Menu
Use when starting a non-trivial implementation that needs structured task breakdown with progress tracking.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when evaluating test coverage gaps, planning test strategy, or assessing testing risk for code changes.
Use when reviewing a diff, PR, or set of code changes, or auditing a codebase area for quality issues. Triggers: 'review this', 'code review', 'audit X', 'look at these changes'.
Use when assessing security implications of code changes, architecture decisions, or new features.
Use when you describe an outcome and need the right goat-* workflow chosen for you.
Use when a decision or analysis needs multi-lens critique to surface blind spots before shipping.
Use when diagnosing a bug, unexpected behaviour, system failure, or unfamiliar code that needs structured investigation.
| name | goat-plan |
| description | Use when starting a non-trivial implementation that needs structured task breakdown with progress tracking. |
| goat-flow-skill-version | 1.14.0 |
Read .goat-flow/skill-docs/skill-preamble.md; on full-depth also read .goat-flow/skill-docs/skill-conventions.md.
Use when work needs milestone tracking: milestones, replans, rescope, or resume-from-plan. Files live in .goat-flow/plans/<active>/.
| Excuse | Reality |
|---|---|
| "Show milestones first, files later" | File-Write creates milestone artifacts immediately. Read-Only Analysis is for inline plans. |
| "Vague tasks are fine - implementer will figure it out" | Tasks without file paths, replacement text, and verification commands aren't executable by a cold-start agent. Four recurrences of untickable checkboxes traced to vague tasks. |
| "Testing gate is obvious - skip it" | Agent skipped the AI testing gate after the first milestone and offered to continue. The gate caught what the agent missed. |
| "Bare task path means start implementing" | Path-only context is data, not delegation. Bare task paths must not update .active, milestone status, checkboxes, or code. |
Classify the input shape before any plan-state read. Path-only guard runs first: a task/milestone path alone or ambiguous context phrase selects Path-Only Intake / Read-Only Orientation. Do NOT update .active, milestone status fields, task checkboxes, or code. Switching a mismatched .active needs approval. Code or plan changes need an explicit action verb.
Run learning-loop retrieval before mode-specific reads. Follow the preamble's INDEX-first retrieval and emit Relevant prior learnings:. Use brief/plan terms; add decisions for architecture, policy, or setup. For path-only intake, search only for plan-orientation and task-state failure classes. Do not retrieve implementation-domain learnings from the task path; open entries only when a hit affects safe orientation.
Inspect existing plan state only after retrieval. Check for existing milestones:
.goat-flow/plans/.active is advisory. If valid, scan only its subdir.M*.md, ask which is current, and offer to update .active; this is not setup failure.milestones/ or tasks/. Scan sibling versions only when .active is invalid.Plans are local workflow state, not a setup invariant. Mode R is read-only: TODO: refresh; DONE: verify HEAD; BLOCKED: honor or reject; IN PROGRESS: flag staleness. Report and stop; never implement.
If starting fresh: identify what is being built, the riskiest part, and kill criteria.
Pick exactly one mode. Apply these signals in order - stop at the first that matches:
Path-Only Intake / Read-Only Orientation - path-only or ambiguous task path. Summarize status, ask next action, stop. R. Reconcile Existing Plan State - explicit reconcile/audit/refresh. Compare live state with recorded evidence, propose corrections, and stop without writes.
Named-File Update - user asks to update, improve, tighten, rewrite, or fix a specific existing plan file. A path alone is not write approval. Proceed to Phase 2 § Mode 1 only for plan-file edits, not code implementation.
Read-Only Analysis - analysis signals: "what would the milestones look like", "break this down for me", "plan this out", "sketch the milestones", "reporting-only", "no-implementation". No files written; inline output; Phase 3 skipped; transition to file mode available later.
Small File-Write - Hotfix / Small Feature scope (1-2 milestones, low blast radius), no analysis signals. Same write path as Mode 4; the only difference is ceremony - concise milestone files, not full ones. Write directly to .goat-flow/plans/<active>/.
File-Write (default at Standard+) - implementation signals ("create milestones", "set up the plan", "start planning") OR Standard / System / Infrastructure scope with a clear objective and no analysis signals. Write full milestone files directly to .goat-flow/plans/<active>/.
If ambiguous, ask. Never silently pick.
Minimum viable input: What to build. Everything else can be inferred or asked.
CHECKPOINT (Path-Only Intake): "Mode: Path-Only Intake. Orientation summary for [path]: [status]. Active plan pointer: [state]. Next action needed from user."
CHECKPOINT (Reconcile): "Mode R. Live state: [status]. Proposed corrections: [changes or none]. No writes."
CHECKPOINT (Named-File Update): "Mode 1. Edit [file] in place for [delta]. Boundary: [scope]."
CHECKPOINT (planning modes): "Mode: [Read-Only Analysis | Small File-Write | File-Write]. Creating milestones for [feature]. Riskiest part: [risk]. Kill criteria: [criteria]."
Structure work into milestones using these archetypes. Adapt the count - small features might need 2, large ones 5+.
Use Prove It Works (riskiest assumption), Make It Real (end-to-end), Make It Solid (edges/security/UX), then optional Make It Shine (polish/docs).
Spike-first rule: If uncertain about a library, API, performance characteristic, or integration point - that uncertainty goes in Milestone 1 as a spike, not Milestone 3 as a risk.
Do not drop a spike, intake, or kill criteria to satisfy milestone count, deadline pressure, or requests for less ceremony.
Objective, Tasks (risk-tagged checkboxes), Assumptions to validate, Exit criteria (binary pass/fail), Testing gate (static/contract + automated + manual + acceptance), Mid-implementation proof, Kill criteria, Depends on, Read first, Deferred (items cut, with pointers; state explicitly if none). Field details and examples: references/milestone-examples.md.
Tag and order tasks [RISKY] (unknowns/integrations/spikes), [CORE] (essential logic), then [SAFE] (straightforward docs/polish). If uncertainty exists without a [RISKY] task, revise the milestone.
Every milestone testing gate includes a Static / Contract Check section (language-appropriate linters, type checkers, and static analysis that must pass before behavioural tests; detect from project structure) plus Automated, Manual, and Acceptance sections. Manual gates are checkbox lists, not prose. Each item: one action + one expected result.
Good tasks are concrete actions with a target or exit criterion, not vague wishes. Each fits one coding session; split if bigger.
Cold-start bar: Every milestone must be executable by a fresh agent without prior context. Include files to read and verification commands.
Handoff-grade artifacts (Standard+): record planned-at SHA/date; run git diff --stat <sha> -- <paths> and git status --short -- <paths> because uncommitted drift matters; include current-state evidence, in-scope paths, out-of-scope paths with reasons, expected commands, STOP conditions, and maintenance notes. See references/milestone-examples.md. Small File-Write stays compact.
Specificity calibration: Pin file paths when cited by exit criteria or downstream milestones. Use concept names when location is an implementation detail.
Test tasks per flow: For milestones creating user-facing components, include explicit test tasks per component or flow, not just a general test gate.
Assumptions are beliefs, not tasks. Tick validated evidence. On invalidation, record it and stop dependent work; amend only when mode/approval permits. At a human gate, propose and wait. See references/milestone-examples.md.
For Standard+, answer "If this plan fails, the most likely cause is ..." in an existing task, assumption, or kill criterion.
CHECKPOINT: Read-Only Analysis presents milestones inline and stops. Write modes go to Phase 2 to write files; no Phase 1 approval pause.
The delivery path maps 1:1 to the mode picked in Step 0. Do exactly the mode's block; do not cross modes mid-flow.
.goat-flow/plans/.active, milestone status, checkboxes, or code..active, status/checkboxes, or code.User explicitly asked to edit an existing plan file. Path-only references do not qualify.
Analysis signals triggered this mode.
.goat-flow/plans/.Transition out: On "write these to files" / "let's go ahead", switch to Mode 4 using approved Phase 1 output. If prior-turn/session, re-read instructions, .active, named sources. Do NOT re-run breakdown.
CHECKPOINT: "Milestones for [feature] (no files written). Say 'write to files' to persist, or adjust first."
The preamble's "skip goat-plan at Hotfix" governs dispatch; invoked goat-plan uses Mode 3. Low-risk, 1-2 milestones, no analysis signals. Like Mode 4 but concise milestone files (minimal ceremony, no padding); both write immediately via File Artifact Rules and skip the inline-first prompt. Write artifacts, then present paths + summary.
Write artifacts immediately. Do NOT invoke/ask about /goat-critique; run it only on request.
For a fresh plan, create a slugged task directory and update .goat-flow/plans/.active to that slug in the same batch. Write one milestone per .goat-flow/plans/<active>/M*.md file.
Filename format: start with M plus a zero-padded number so dashboard and task tooling discover and order it; use a readable slug, e.g. M01-prove-api-integration.md.
File format: use the Phase 1 milestone field set plus title and Status, ending with Testing Gate (static/contract + automated + manual + acceptance) and Mid-implementation proof.
ISSUE.md: Write ISSUE.md in the task directory. Format: references/issue-format.md. Three sections: Why (benefits), What (requirements, future tense), How (developer checklist). Keep stakeholder-readable - no file-level detail. Add "Out of scope" for exclusions.
Backlog file: If deferred items exist, write backlog.md with priority tiers (Next / Later / Maybe).
CHECKPOINT: "Milestone files + ISSUE.md written to .goat-flow/plans/<active>/. Ready to start implementation."
Prompted README/ADR gate: "Load-bearing decisions [X, Y, Z] - write ADRs + README now, or milestone files only?"
Reference verification: After writing, grep every inline reference code and verify it resolves to a file on disk.
For concrete Mode 0 and Mode 4 examples with expected paths and checkpoint output, see references/milestone-examples.md.
Post-plan return: After Phase 2 finishes, return-to-implement hands ordinary ACT the existing build authorization; new Ask First boundaries still gate. Plan-only stops; Phase 3 gates milestones.
After each milestone, both gates must pass before the next begins. Apply the Proof Gate from skill-preamble.md.
AI Verification Gate: Verify every task is ticked, every exit criterion met with evidence from this session, and the testing gate passed with proof (not recollection). Surface any gap.
BLOCKING GATE (Human Verification): Present changed files, exit evidence, and assumption outcomes. "M[N] evidence is ready; status remains unchanged. Approve completion and M[N+1], or adjust?"
After approval: capture learnings, re-read the next milestone and update invalidated assumptions/tasks/exit criteria, set status: prior → complete, next → in-progress.
If updates are needed mid-flight, follow the milestone retrospective protocol in skill-conventions.md; never change them silently.
Status-aware reminder: When setting the last milestone to complete, add: "All milestones now complete. Ready to run Phase 4 close-out when you are."
When all milestones reach complete or human-verification-pending, the plan enters Phase 4. Both gates must pass before it is finished.
Before presenting completion, verify:
complete or human-verification-pending[x] across all milestone filesIf any item fails, surface it - do not silently close with incomplete gates.
Consolidated UNVERIFIED checklist: Aggregate UNVERIFIED items from testing gates across milestones into a single walkthrough list.
Architecture staleness check: If .goat-flow/architecture.md predates the plan's implementation, prompt: "Architecture may be stale - update now or defer?"
BLOCKING GATE: Present completion summary: files changed, milestone statuses, exit-criteria evidence, invalidated assumptions.
"All milestones complete. Review changes before I close this plan."
Plan is NOT complete until the human explicitly approves.
complete.goat-flow/plans/ - human decides archival/compact without an active milestone file or an explicit human request.active, status, checkboxes, or code from path-only intake/goat-critique from /goat-plan; run critique only on requestEmit only: Mode 0 orientation; R reconciliation; 1 in-place delta; 2 inline milestones; 3/4 files plus concise milestone names, objectives, task/exit/test counts, riskiest milestone, and stop condition. Modes 0/R/2 never write.
Terse-first: Lead with the answer. One sentence per bullet. Strip qualifiers. Skip closing offers. Applies to informational output/summaries, not gate prompts or evidence-tagged findings.