@blundergoat/goat-flow/workflow/skills/goat-plan/SKILL.md

AI coding agent harness and local dashboard for Claude Code, OpenAI Codex, Google Antigravity, and GitHub Copilot - setup audits, guardrails, structured skills, deny hooks, and persistent learning loops.

---
name: goat-plan
description: "Use when starting a non-trivial implementation that needs structured task breakdown with progress tracking."
goat-flow-skill-version: "1.12.1"
---
# /goat-plan

## Shared Conventions

Read `.goat-flow/skill-docs/skill-preamble.md` for shared conventions.
On full-depth, also read `.goat-flow/skill-docs/skill-conventions.md`.

## When to Use

Use when work needs milestone tracking. goat-plan manages gitignored coordination files in `.goat-flow/plans/<active>/`.

Use for milestones, replans, rescope, resume-from-plan. **NOT this skill:** tests → run them; debug → /goat-debug; review → /goat-review; security → /goat-security; gaps → /goat-qa; critique → /goat-critique; question → answer directly.

| 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. |

## Step 0 - Intake

**Path-only guard runs first.** If the user message is only a task/milestone path, or an ambiguous context phrase such as "look at this task directory", choose **Path-Only Intake / Read-Only Orientation**. Read only minimal index/status files. Do NOT update `.active`, milestone status fields, task checkboxes, or code. If `.active` points elsewhere, mention it and offer to switch only on approval. Implementation requires "start", "implement", "resume", "mark in progress and begin", or "fix code". Plan-file writes require "update", "rewrite", "write", "create", or "fix" tied to the plan file. Before any write after an ambiguous path, checkpoint and stop.

**Check for existing milestones first:**
- Treat `.goat-flow/plans/.active` as an advisory local pointer (one-line file naming a subdir), not a setup invariant.
- If `.active` exists and names an existing subdir, scan only that subdir for milestone files.
- If `.active` is missing or names a missing subdir, treat as normal local churn. List top-level entries in `.goat-flow/plans/` excluding archives, prefer dirs with recent `M*.md` files, ask which is current, and offer to write/update `.active`. Do NOT report a stale/missing `.active` as setup failure.
- If milestones exist and the user hasn't given an explicit action verb: "Milestone files exist for [feature]. Resume from here, update milestones, or start fresh?"
- If the selected plan appears stale: flag whether code moved on but milestones didn't. Note: task files are gitignored, so `git log` won't track them - check file modification dates instead.
- Also check for legacy milestone files outside `.goat-flow/plans/` (e.g. `milestones/`, `tasks/`). Sibling-version subdirs hold deferred/completed work, NOT scanned unless `.active` is missing or points nowhere. Note any found.

**If starting fresh:** identify what is being built, the riskiest part, kill criteria, and run the preamble's learning-loop retrieval for the target area.

**Pick exactly one mode.** Apply these signals in order - stop at the first that matches:

0. **Path-Only Intake / Read-Only Orientation** - path-only or ambiguous task path. Summarize status, ask next action, stop.
1. **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.
2. **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.
3. **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>/`.
4. **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 (all other modes):** "Mode: [Named-File Update | Read-Only Analysis | Small File-Write | File-Write]. Creating milestones for [feature]. Riskiest part: [risk]. Kill criteria: [criteria]. Proceeding to milestone breakdown."

## Phase 1 - Milestone Breakdown

Structure work into milestones using these archetypes. Adapt the count - small features might need 2, large ones 5+.

### Milestone Archetypes

1. **Prove It Works** - Validate the riskiest assumption.
2. **Make It Real** - End-to-end flow works with real data.
3. **Make It Solid** - Edge cases, errors, security, UX, and feedback are handled.
4. **Make It Shine** - Optional polish, performance, docs, or open-source prep.

**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.

### For each milestone, produce:

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`.

### Risk-weighted task ordering

Tag every task within a milestone:

- **[RISKY]** - Unknowns, integrations, unproven assumptions. Includes spikes.
- **[CORE]** - Essential logic without unknowns. The bulk of most milestones.
- **[SAFE]** - Straightforward, well-understood. Documentation, polish, cosmetic.

**Ordering rule:** All [RISKY] first, then [CORE], then [SAFE] within each milestone.

**Structural check:** If a milestone has no [RISKY] tasks but contains uncertainty, the plan is wrong - revise the milestone.

### Testing gate format

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.

### Quality rules

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.

**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.

### Assumption tracking

Assumptions are beliefs about the system, not tasks. Tick with evidence when validated. If invalidated, update the plan immediately. See `references/milestone-examples.md` for format and examples.

**CHECKPOINT:** Read-Only Analysis presents milestones inline and stops. Write modes go to Phase 2 to write files; no Phase 1 approval pause.

## Phase 2 - Deliver Milestones

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.

### Mode 0: Path-Only Intake / Read-Only Orientation

- Read task directory README/index and milestone filenames/status fields only.
- Do NOT mutate `.goat-flow/plans/.active`, milestone status, checkboxes, or code.
- Present: active marker, plan reference, milestone list/status, current in-progress item.
- Ask: "Summary, status check, plan update, or start a specific milestone?"
- Stop until the user answers with an explicit action.

### Mode 1: Named-File Update (edit in place)

User explicitly asked to edit an existing plan file. Path-only references do not qualify.

- Edit in place. Do NOT create a parallel inline plan.
- Preserve title/status metadata unless the change requires updating them.
- Present updated content or concise delta. Ask if scope spills beyond named file.

### Mode 2: Read-Only Analysis (no files)

Analysis signals triggered this mode.

- Run Phase 1. Present milestones. Do NOT write files or modify `.goat-flow/plans/`.
- Skip Phase 3. Include summary format.

**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."

### Mode 3: Small File-Write (Hotfix / Small Feature)

The preamble's "skip goat-plan at Hotfix" is dispatcher routing; once goat-plan is invoked, Mode 3 is the Hotfix path. Low blast radius, 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.

### Mode 4: File-Write (Standard+ or explicit file request)

Write artifacts immediately. Do NOT invoke/ask about `/goat-critique`; run it only on request.

### File Artifact Rules (Modes 3 and 4)

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` so dashboard and task tooling discover it; use a readable slug, e.g. `Milestone-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`.

## Phase 3 - Between 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 files changed, exit criteria with evidence, and assumptions validated or invalidated. "M[N] complete. Approve to proceed with 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."

## Phase 4 - Plan Complete

When all milestones reach `complete` or `human-verification-pending`, the plan enters Phase 4. Both gates must pass before it is finished.

### AI Verification Gate

Before presenting completion, verify:

1. Every milestone status shows `complete` or `human-verification-pending`
2. Every task checkbox ticked `[x]` across all milestone files
3. Every exit criterion met with evidence cited in this session
4. Every testing gate passed with proof (not recollection)
5. Every assumption validated or explicitly invalidated with plan updates
6. Learning loop checked: footguns/lessons/patterns updated if warranted
7. ISSUE.md reviewed and revised - What section updated to past tense (requirements met), How checkboxes ticked

If 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?"

### Human Verification Gate

**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.

### After Human Approval

- Confirm all statuses are `complete`
- Plan files remain in `.goat-flow/plans/` - human decides archival
- Write a session log if the plan spanned multiple sessions

## Constraints

- MUST pick exactly one Step 0 mode and stay in it through Phase 2.
- MUST check for existing milestone files before creating new ones
- MUST treat bare task paths as read-only context, not implementation permission
- MUST NOT update `.active`, status, checkboxes, or code from path-only intake
- MUST default to Mode 1 only on explicit plan-file edit verb
- MUST include a testing gate on every milestone and mid-implementation proof for long milestones (run before switching modules or after a bounded edit batch)
- MUST re-read and update the next milestone after completing each one
- MUST check kill criteria between milestones - triggered = BLOCKING GATE
- MUST tick assumption checkboxes with evidence when validated or invalidated
- MUST present milestone updates to human for approval - never silently change
- MUST order tasks riskiest-first within each milestone
- MUST NOT invoke or prompt for `/goat-critique` from `/goat-plan`; run critique only on request
- MUST ensure each task fits one coding session - split if not
- MUST NOT create vague tasks ("set up backend", "make it work", "research options")
- MUST NOT skip per-milestone AI + human verification gates
- Universal constraints from skill-preamble.md apply.
- MUST NOT continue building on an invalidated assumption - update the plan first
- MUST NOT include self-destruct instructions in plan artifacts. Cleanup is the human's decision.
- MUST NOT delete or remove plan/milestone files without explicit human approval
- MUST require both AI verification and human sign-off before plan completion (Phase 4)
- Status tracking: update status only after explicit start/resume/implement/update approval

## Output Format

The output depends on the mode picked in Step 0:
- **Mode 0 (Path-Only Intake):** status/orientation summary plus next-action question. No files.
- **Mode 1 (Named-File Update):** the edited milestone file plus a concise delta shown to the user.
- **Mode 2 (Read-Only Analysis):** the inline milestone breakdown in the response. No files.
- **Mode 3 (Small File-Write):** milestone files in `.goat-flow/plans/<active>/` plus a concise summary.
- **Mode 4 (File-Write):** the milestone files in `.goat-flow/plans/<active>/`.

Summary format for presentation:

```markdown
## Milestones for [feature]

### Milestone 01: [name] - [archetype]
**Objective:** [1-2 sentences]
**Tasks:** [N] | **Exit criteria:** [N] | **Testing gate:** [auto + manual + acceptance]
**Kill criteria:** [condition]

### Milestone 02: [name] - [archetype]
...

**Total milestones:** [N] | **Estimated sessions:** [rough guess]
**Riskiest milestone:** M[N] because [reason]
**Kill criteria summary:** [what would stop the entire effort]
```

**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.