holocron/docs/prd/chunk-2-instructions.md

PRD: Chunk 2 — Core Instructions

Problem Statement

Claude Code runs without any domain conventions or coding standards — every session starts from scratch. The placeholder core/instructions/global.md exists but contains no content. providers/claude-code/CLAUDE.md has only one rule and no communication or behavior guidelines. There are no rules about how code should be written, how commits should be structured, or how tests should be approached. The agent has no basis for challenging bad ideas, explaining decisions, or behaving consistently across sessions.

Separately, docs/ has no consistent naming convention. As workflow artifacts accumulate (PRDs, ARDs, Bug Briefs), there is no predictable place to find them.

Solution

Write three topic-specific instruction files (coding.md, git.md, testing.md) that the agent reads on demand. Update providers/claude-code/CLAUDE.md with a proper always-on section covering communication style and behavior rules. Retire the placeholder global.md. Establish the subdirectory-by-type naming convention for docs/ and migrate the existing PRD into it.

This gives the agent real conventions to follow from every session forward, and gives humans a clean, navigable document structure as the repo grows.

User Stories

1. As a developer, I want the agent to follow consistent coding conventions, so that code quality is predictable across sessions without repeating instructions.
2. As a developer, I want coding conventions loaded on demand rather than always, so that every session does not pay a context cost for rules that may not be relevant.
3. As a developer, I want the agent to follow conventional commits format, so that git history is machine-readable and changelog automation is possible in Chunk 3.
4. As a developer, I want git safety rules available whenever I do git operations, so that I never accidentally bypass hooks or force-push main.
5. As a developer, I want the agent to require my approval before writing or editing files, so that I stay in control and understand what is changing.
6. As a developer, I want the agent to proceed freely with reads and exploration, so that information-gathering does not require constant approval.
7. As a developer, I want the agent to always require explicit confirmation for irreversible or shared-state operations, so that I never accidentally push, drop, or publish something unintended.
8. As a developer, I want the agent to challenge my ideas with industry standards rather than validate them, so that I make better decisions rather than hearing what I want to hear.
9. As a developer, I want the agent to explain the why behind pushback and decisions, so that I build domain knowledge and can generalise to future situations.
10. As a developer, I want the agent to answer directly first and give context only when it changes the answer, so that responses are efficient and signal-dense.
11. As a developer, I want the agent never to soften disagreement into a suggestion, so that I can trust the agent is giving me its actual assessment.
12. As a developer, I want the agent to prefer integration tests over mocks, so that tests catch real divergences between code and production systems.
13. As a developer, I want manual testing reserved for nuanced UI/UX or agent interaction behaviour, so that automation handles everything that can be automated.
14. As a developer, I want the agent to test observable end-state rather than implementation internals, so that tests survive refactoring without needing to be rewritten.
15. As a developer, I want a consistent subdirectory-by-type naming convention for docs/, so that I can navigate artifacts without guessing where they live.
16. As a developer, I want existing docs migrated to the new convention, so that the repo is consistent from the start rather than accumulating two naming patterns.
17. As a developer, I want global.md retired, so that there is no ambiguity about where instruction content lives.
18. As a developer, I want the content index in CLAUDE.md to include a load trigger for each file, so that the agent knows when to read each instruction file without requiring frontmatter.
19. As a developer, I want acceptance criteria on each issue that I can verify in a new Claude session, so that I can confirm conventions are actually being applied and not just written.
20. As a developer, I want instruction files to use plain markdown with no schema or frontmatter, so that they are readable by both humans and agents without tooling.

Implementation Decisions

Module 1 — providers/claude-code/CLAUDE.md (rewrite)

The source file deployed to ~/.claude/CLAUDE.md via install.sh. Rewritten with two top-level sections replacing the current sparse content.

Always-on / Communication:

• Answer directly first; context only if it changes the answer
• Challenge bad ideas explicitly — name the problem, cite the industry standard or first principle, then implement if the user proceeds
• Never validate an approach because the user seems confident about it
• When disagreeing, say so clearly — do not soften into a suggestion
• For exploratory questions: one recommendation, one tradeoff, 2–3 sentences
• Never say "it depends" without immediately stating what it depends on
• Explain the why behind decisions — assume the user is learning, not just executing

Always-on / Behavior:

• Reads, searches, exploration: proceed without asking
• Writes, edits, deletes, git operations: state what you are about to do and why in one sentence; wait for approval before proceeding
• Irreversible or shared-state operations (push, force-push, drop, publish): require explicit confirmation every time, regardless of prior context

On-demand content index (inline load triggers to guide agent judgment):

• Coding conventions — when writing, editing, or reviewing code
• Git conventions — when doing git operations
• Testing conventions — when writing or running tests
• Workflows / agents / prompts — read from ~/.claude/core/ when invoked

Module 2 — core/instructions/coding.md (new, thin draft)

Plain markdown. On-demand. Read when writing, editing, or reviewing code.

Key rules for the thin draft:

• Automate anything repeatable — if done manually twice, it belongs in a script, hook, or pipeline step
• No comments unless the why is genuinely non-obvious — names carry meaning, git history carries context
• No defensive code at internal boundaries — validate only at system edges (user input, external APIs, git hooks)
• Prefer explicit over implicit — agents reading code must not need to infer intent from convention
• No abstractions, features, or cleanup beyond what the task requires

Module 3 — core/instructions/git.md (new, thin draft)

Plain markdown. On-demand. Read when doing git operations. Includes conventional commits convention.

Key rules for the thin draft:

• Never skip hooks (--no-verify) — hooks are the automated QA gate; bypassing them breaks the pipeline
• Never force-push main or master
• Commit messages explain why, not what — written for both humans and changelog generators
• Never commit secrets, credentials, or environment-specific config
• Conventional commits categories: feat:, fix:, docs:, chore:, refactor:, test:

Module 4 — core/instructions/testing.md (new, thin draft)

Plain markdown. On-demand. Read when writing or running tests.

Key rules for the thin draft:

• Prefer integration tests over mocks — mocks mask production divergence; real systems catch real failures
• Automate everything automatable — manual testing only for nuanced UI/UX or agent interaction behaviour requiring human judgment
• Test observable end-state, not implementation internals — tests must survive refactoring
• No test is better than a wrong test — a passing mock that masks a real failure is actively harmful

Module 5 — core/instructions/global.md (retire)

Delete this file. It is a placeholder stub with no content. The content index in providers/claude-code/CLAUDE.md will be updated to point to the three topic files instead. install.sh copies core/ wholesale, so deletion automatically removes the deployed file on next install.

Module 6 — docs/ restructure

Create subdirectories by artifact type. Migrate the one existing PRD.

New structure:

docs/
├── prd/          ← PRDs (this PRD is the first)
├── ard/          ← Architecture Requirements Documents
├── bug/          ← Bug Briefs
├── notes/        ← Exploration Notes
├── adr/          ← Architecture Decision Records (NNNN-slug)
├── issues/       ← Issues (NNNN-slug, already correct)
└── VISION.md     ← stays at root of docs/

Migration: docs/prd-chunk-1.md → docs/prd/chunk-1.md. No other files need moving.

install.sh

No changes required. It copies core/ wholesale and deploys providers/claude-code/CLAUDE.md verbatim. Adding new files to core/instructions/ and deleting global.md takes effect automatically on next install run.

Testing Decisions

Instruction files and CLAUDE.md content cannot be unit tested. A well-formed file is not the same as an effective file — the test is whether the agent actually follows the rule in a real session.

Approach: Each issue carries a short acceptance criteria checklist. After committing the issue, the developer opens a new Claude session and exercises the relevant behaviour. The issue is closed only when the behaviour is confirmed.

What a good test looks like:

• Trigger the scenario the rule covers (e.g. ask Claude to implement something with unnecessary complexity; expect pushback citing the rule)
• Confirm the agent's response matches the intended behaviour
• Do not test that the file was written correctly — test that the behaviour changed

Prior art: Chunk 1 used the same approach — manual smoke test in a new session to verify the always-on rule was in effect. Chunk 2 formalises this as per-issue acceptance criteria.

No automated tests for this chunk. Automated QA applies to tooling (scripts, hooks); behavioural QA for content is always human-executed.

Out of Scope

• Changelog tooling (Chunk 3 follow-on to the conventional commits convention)
• Frontmatter or load-trigger hints in instruction files themselves — deferred until there is evidence agents are loading the wrong files in practice (Chunk 2 Phase 2 refinement)
• Security floor, scope discipline, tool preference in the always-on CLAUDE.md section — separate future workstream with its own grill and PRD
• Loosening the agent behavior confirmation model for automation — deferred to post Chunk 4 once skills and workflows are proven
• Additional instruction categories beyond coding, git, and testing — Phase 2 refinement, triggered by real friction
• The docs/VISION.md file path does not change — it stays at docs/VISION.md, not moved into a subdirectory

Further Notes

• install.sh copies core/ wholesale — adding or removing files in core/instructions/ automatically affects what is deployed on the next install run. No install script changes are needed for this chunk.
• This PRD is itself the first artifact written under the new docs/prd/ convention. The migration of docs/prd-chunk-1.md is a Chunk 2 deliverable, not a precondition for writing this PRD.
• The behavior confirmation model (writes require stating intent and approval) is intentionally conservative. It reflects the current context: a junior developer interacting directly with the agent. It will loosen post Chunk 4 when automated agents replace direct interaction for routine tasks.
• The inline load triggers in the content index ("when writing, editing, or reviewing code") are a lightweight substitute for frontmatter. They are noted as a known interim approach and will be revisited if agents load wrong files in practice.