# Instruction File Sections These sections go in the project's instruction file. Target: under 125 lines. Hard limit: 150. --- ## Required Sections a) Project identity + version header - Start with 1-2 lines: project name, domain, core technology, and primary invariant. - Include the five-concerns framing when installing goat-flow itself or when the target project needs a concise harness identity: Context, Constraints, Verification, Recovery, Feedback loop. - Set the version header to the current goat-flow release version (match installed skill frontmatter). b) Truth Order - User's explicit instruction for this session. - This instruction file. - Architecture (`.goat-flow/architecture.md`). - Skills/templates loaded on demand. c) Autonomy Tiers - Always: read files, run validation, edit within declared scope, and write continuity notes only when useful. - Ask First: before touching risky boundaries, ask and wait for approval; include boundary touched, related code read, footgun checked, local instruction checked, and rollback command. - Never: freeze writes first if interrupted or told no changes; do not edit secrets; do not push/commit unless asked; do not overwrite without checking destination. - Group Ask First boundaries by category: instruction files, workflow/templates, architecture, skill reference, skill playbooks, runtime code, agent configs, CI/hooks, add/remove/rename, and 3+ docs/scripts. - New Never/Ask First rules must trace to a real incident, current file evidence, or a documented footgun/lesson - not hypothetical best practices. d) Hard Rules - If file exists, modify in place. Never create `_modified`, `_new`, `_backup`, or `_v2` variants. - Severity order: SECURITY > CORRECTNESS > INTEGRATION > PERFORMANCE > STYLE. - Maintain cross-file consistency for the same concept. - Preserve file evidence with semantic anchors, not stale line numbers. - Use real incidents, never hypothetical examples. - Sub-agents get one objective, structured return, and a 5-call budget. - No features, abstractions, or error handling beyond what was asked. - Ambiguous requirements: present interpretations; do not pick silently. e) Commit Messages - Summarise the project's commit conventions: subject format, any branch/issue prefix rule, and the weak-verb ban. - Point to the full reference at `docs/coding-standards/git-commit.md`; the detector seeds that doc from git history (Step 02). f) Key Resources - **Learning loop** (grep before every change): `.goat-flow/learning-loop/footguns/`, `.goat-flow/learning-loop/lessons/`, `.goat-flow/learning-loop/patterns/`, `.goat-flow/learning-loop/decisions/`. - **Tool playbooks**: `.goat-flow/skill-docs/playbooks/README.md` is the full index (examples: `.goat-flow/skill-docs/playbooks/browser-use.md`, `.goat-flow/skill-docs/playbooks/page-capture.md`) - read BEFORE declaring a tool unavailable. - Add only first-action resources here. The Router Table remains exhaustive. g) Essential Commands - Include exact commands for lint, syntax/type checks, tests, release/preflight checks, and agent hook self-tests. - Keep common checks in a short code block; route situational checks to one terse line. h) Execution Loop: READ -> SCOPE -> ACT -> VERIFY When a goat-* skill is active, the skill's Step 0 replaces READ and selects the skill's mode/depth. SCOPE still applies before writes: a skill may write when its selected mode permits writes or the user explicitly approves them. `/goat-plan` File-Write may create gitignored milestone files without a separate approval gate; `/goat-debug` D3 still requires approval before fixes. Resume at ACT after Step 0 output or when a blocking gate releases. ### READ MUST read relevant files before changes. Never fabricate codebase facts. Check browser evidence first for URL, local HTML, localhost, screenshot, rendered UI, or browser-visible behaviour. Use grep-first retrieval across learning-loop dirs; include decisions for architecture, policy, or setup work. Before declaring any tool or capability unavailable, read the matching playbook in `.goat-flow/skill-docs/playbooks/` (e.g. `browser-use.md`, `page-capture.md`) and run that doc's "Availability Check" section verbatim - project-local CLI tools at `~/.local/bin/` are valid; do not conflate "no harness/MCP tool" with "no tool". ### SCOPE Declare intent, complexity tier, mode, files allowed to change, non-goals, and blast radius. Expanding beyond scope means stop and re-scope. ### ACT Declare `State: [MODE] | Goal: [one line] | Exit: [condition]`. Mode must be Plan, Implement, Explain, Debug, or Review. ### VERIFY Run required checks for changed files. Check cross-references after renames. Tick milestone checkboxes immediately. Do not claim checks passed without the literal pass/fail line from this session. Stop the line when tests break, builds fail, or behaviour regresses. If VERIFY caught a failure or you corrected course, update the learning loop before DoD. i) Definition of Done MUST confirm all six gates: lint/typecheck passes on changed files; no broken cross-references; no unapproved boundary changes; logs updated if tripped; working notes current; grep old pattern after renames. j) Artifact Routing Map "add a footgun/lesson/decision/pattern" to `.goat-flow/learning-loop/footguns/`, `.goat-flow/learning-loop/lessons/`, `.goat-flow/learning-loop/decisions/`, or `.goat-flow/learning-loop/patterns/`. These are documentation artifacts, not runtime code. Read the target directory's `README.md` before editing. k) Router Table MUST be the final section. Include at minimum: - Learning loop dirs (`.goat-flow/learning-loop/footguns/`, `.goat-flow/learning-loop/lessons/`, `.goat-flow/learning-loop/patterns/`, `.goat-flow/learning-loop/decisions/`) - Skill reference (meta) (`.goat-flow/skill-docs/`) - Tool playbooks (`.goat-flow/skill-docs/playbooks/`) - Orientation docs (`.goat-flow/code-map.md`, `.goat-flow/glossary.md`) when present - Architecture doc (`.goat-flow/architecture.md`) - Agent skills directory (`.claude/skills/`, `.agents/skills/`, or `.github/skills/`) - Workflow/setup source if present - Source, scripts, config, docs, and workspace/session paths - Peer instruction files present in the project ## Quality Bar Every line in the hot-path instruction file must be one of: behavioral rule, scope boundary, exact command, verification gate, router pointer, or composition rule. Domain knowledge, project history, API docs, and glossary entries belong in cold-path files. For strict Never/MUST constraints, state whether the constraint is prose-only or mechanically enforced when that distinction matters. If you must weaken a MUST to meet the line target, the target is wrong - raise it, do not weaken the rule.