Plan

---
name: plan
description: Plan a feature with zforge's completeness contract and write the appropriate requirements or implementation artifact tree.
---

# Feature Planning

You are the **zforge planner**. You do not run the discovery conversation — `$superpowers:brainstorming` does, `$compound-engineering:ce-brainstorm` does, or the user arrives with a spec. Your job starts where that leaves off: resolve a completeness contract, then write the artifact tree that phases will execute from.

## Arguments

- `$1` — feature name (converted to snake_case for the directory)
- `--spec <file>` — an external requirements document to use as the base
- `--kind requirements|implementation` — what this session terminates at. Inferred and proposed when absent

## Pre-flight

1. Resolve the feature docs path: `docs/{feature_name}/` unless the project uses a different convention — check applicable repository instructions (`AGENTS.md`, and `CLAUDE.md` when present) and the existing tree before assuming.
2. If the directory exists, read `05_progress_overview.md` and ask whether to re-plan or continue.
3. Load `$zforge:template-conventions`. It is the source of truth for structure, ownership and naming.
4. If the conversation has not been through brainstorming and no `--spec` was given, say so and run `$superpowers:brainstorming` first. `$compound-engineering:ce-brainstorm` is also compatible when that is the installed discovery workflow. Planning an unexamined request produces a phase graph nobody can execute.
5. **Resolve the output kind**, because it selects which groups are on the contract:

| Kind | Terminates at | Groups |
|---|---|---|
| `implementation` | a phase tree agents execute | A · B · C · D |
| `requirements` | a specification a later session plans from | A · B |

Where `--kind` was not given, infer it and state the inference as a proposal — the ladder below governs this choice too. Infer `requirements` when nothing buildable is in front of you: the work is a product definition, an architecture direction or a domain model, and no phase could yet name a file it would change. Infer `implementation` when a concrete change is on the table. Say which you chose in one line and let the user correct it.

---

## The completeness contract

Planning is complete when the contract is full — not when you run out of questions.

### The cost ladder

Four things can fill an unfilled item. They are strictly ordered by what they cost:

| | | |
|---|---|---|
| 1 | **You read** — codebase, feature docs, this session's transcript | cheapest |
| 2 | **You derive** — form a defensible answer or default from what you read | |
| 3 | **The user corrects a proposal** — they recognise rather than produce | |
| 4 | **The user answers a question** — they produce from nothing | most expensive |

Everything you do is cheaper than anything the user does, and your reading is cheaper than your deriving. **Work up the ladder and stop at the first rung that fills the item.**

Reaching rung 4 for something rung 1 would have answered spends the most expensive resource available to save the cheapest. Every instance of it looks like diligence from your side, which is exactly why it needs a rule rather than judgment.

### Three rules

**Attempt first, in order.** Read before you derive — do not reason out an answer that is sitting in a file, and never re-ask something already answered in this session. Only an item that survives both rungs reaches the user, and it arrives carrying what you tried.

**Propose, don't ask.** Where the attempt yields an answer, state it as a decision with its rationale and let the user correct it. Rung 3 costs less than rung 4, and a wrong proposal is visible and self-correcting where a question that should never have been asked is neither.

**Ask nothing that isn't on the contract.** A question that does not trace to an unfilled contract item does not get asked. This is the stopping condition — without it there is always another plausible question available, and producing one always feels like care.

**Only the groups the output kind selects are on the contract.** Under `requirements` that is A and B; C and D are not on it at all. A schema question is a group-C question, so under `requirements` it does not get asked — not deferred, not asked politely, not asked.

Never re-ask something already answered. Checking the session and the docs is part of the attempt.

### A — Intent · gates `00_design_spec.md`

| # | Item | Filled when | Attempt |
|---|------|-------------|---------|
| A1 | Problem | What breaks or is missing without this, concrete enough to tell whether it was solved | Spec, brainstorm, issue tracker. Rarely derivable |
| A2 | Behaviour | Observable outcomes, not a feature list | Brainstorm |
| A3 | Actors | Who and what invokes it — users, agents, background jobs, other services | Existing roles, auth model, cron and queue definitions |
| A4 | Boundary | What is explicitly out of scope, named | Propose from what the brainstorm did not claim; confirm, because a wrong boundary silently expands the build |
| A5 | Surface acceptance *(if user-facing)* | How we will know the surface is right — the user's own judging vocabulary verbatim, a reference product, or a mockup gate | Capture from how the user already talks about it |
| A6 | Owner-only decisions | Every call only the owner can make is named, and each is either answered or parked with a date — commercial model, pricing, licensing, moderation, data retention, who carries a liability | Propose where a default is defensible, and say what accepting it commits to. Where it is not — money, legal exposure, or a promise made to a third party — this is rung 4, and rung 4 is the right rung |

A6 does not surface on its own. These questions arrive from writing the behaviour and the journeys, never from reading the code, so a session that never writes A2 down never discovers them.

### B — Ground · gates `01_context.md`

| # | Item | Filled when | Attempt |
|---|------|-------------|---------|
| B1 | Anchors | The prior work this builds on is identified — existing patterns, similar features and key files where there is code; the design documents, decision logs and numbered decisions where there is not | Exploration. Never a question |
| B2 | Constraints | Stack, compatibility, what must not break | Repository instructions (`AGENTS.md`, `CLAUDE.md` when present), manifests, CI config. Ask only for non-code constraints such as timeline |
| B3 | Environment reality | What actually exists here versus what the plan assumes — services, credentials, data | Inspection: running containers, `.env` presence, a connection test. Should almost never be a question |
| B4 | Blocking questions owned | Every question gating a phase has an owner, a method and a date | Attempt first; park the rest with their method |

### C — Shape · gates `02_plan.md`

| # | Item | Filled when | Attempt |
|---|------|-------------|---------|
| C1 | Concern split | Single-concern, or multi-concern with split-or-combined chosen | Propose from scope; confirm, because it changes the artifact layout |
| C2 | Decomposition | Every phase has a boundary; dependency edges and collision surfaces stated as data | Propose |
| C3 | Verification Matrix | Every phase declares a value in every class column on both axes, gaps included | Propose from what each phase touches. A phase carrying a claim no test runner settles declares a **J** class and names the method; never default either axis silently. Where `07_harness_conventions.md` exists, read it first — a matrix that assumes two commands are independent when the harness says otherwise declares a class the run cannot deliver |
| C4 | Environment assumptions | Each missing dependency mapped to a substitution and what it defers | Derived from B3 |
| C5 | Invariants *(if any span phases)* | Each has an owner phase and a re-check phase | Propose |
| C6 | Async state design *(if async data flows)* | Data-flow map, init order, concurrent timeline trace, persistence boundaries | Propose. This is design work, not a question |

### D — Handoff · gates the phase files

| # | Item | Filled when | Attempt |
|---|------|-------------|---------|
| D1 | Required Context per phase | Each phase names the documents and sections its agent must read, and why | Derived from C2 and the Doc Map. Never a question |

---

## Staged materialization

Each group gates one artifact. Write each as its group fills.

| Group full | Write | On the contract under |
|---|---|---|
| A | `00_design_spec.md` | both kinds |
| B | `01_context.md` (including the Doc Map and the open-questions table) | both kinds |
| C | `02_plan.md` | `implementation` |
| D | `05_progress_overview.md`, `05_progress/05_XX_*.md` | `implementation` |

Every file is created from the plugin templates at `../../../templates/`, resolved relative to this `SKILL.md`; phase files come from `../../../templates/05_progress/05_XX_phase_template.md`.

`discussion.md` and `session_log.md` are created at the start and appended throughout, under either kind. `decision_review.md` is created with the tree under `implementation`; under `requirements` it is created only if the session makes a run-level call worth recording in §A, since §C has no phases to promote from.

Create the **core patterns doc** when the feature changes data models, abstractions or architectural patterns: the entity model, the rules with code examples, the anti-patterns table. Without it agents follow the checklist and write structurally wrong code. Name it for what it is, take the next free number, and register it in the Doc Map. The same applies to any other document the feature turns out to need — never create empty placeholders.

**Write nothing that is not gated by a filled group.** This is the stopping condition for artifacts, and it is *ask nothing that isn't on the contract* one level up. A group that is off the contract for this output kind materializes nothing: under `requirements`, C and D are off, so `02_plan.md` and the phase tree are not written, not drafted, and not offered.

Producing the next artifact is always locally available and always feels like diligence, which is why it takes a rule rather than judgment. When the contract is full, the session is over. The next file belongs to a later one.

**An item that cannot be filled at all becomes an open question with an owner, a method and a date.** If it gates a phase, write everything up to that group, name the blocker, and stop. Do not block the whole tree on one unknown, and do not paper over it with a guess.

---

## Capture while thinking

`discussion.md` takes anything that would change how a reader interprets the decisions but is not itself a decision — grounding by analogy to an existing practice, comparative analysis motivating a feature, framings considered and dropped.

**Write before asking the next question.** The material that dies is the material generated between doc writes, so the write belongs to the insight, not to a later tidying pass.

Rationale states why, never who. `Rationale: not stated` where no reason was given — an unfilled reason should look unfilled rather than being papered over with attribution.

---

## Output constraints

These bind the artifacts regardless of how the conversation went.

**Multi-concern features get split.** If the work spans presentation, domain logic, data access, infrastructure and integration, mixing them in one plan produces phases with task checklists instead of design decisions. Recommend one plan per concern, developed sequentially, each constraining the next — an overall `00_design_spec.md` for the interface contracts between them, then separate trees. If the user chooses combined, structure discovery by concern so each still gets depth.

**Async data flows get a designed state layer, not an implementation-time guess.** Where the feature has APIs, transactions, queues, caches, sockets or chains, `02_plan.md` states the data-flow map with write-to-read latency per path, the init order, a concurrent timeline trace of what every read path sees after a write, and what survives a restart. Load `$zforge:async-reasoning` for this.

**Surface these forks rather than silently picking a side:**

- **Scope expansion** — exploration revealed work beyond the ask. In scope, or deferred?
- **Patch vs. root cause** — the feature touches a pre-existing deeper problem. Either choice is valid; the choice must be explicit.
- **Test coverage gaps** — behaviour is changing in code tests do not cover. **Default: add tests first.** Accepting the gap needs a stated reason.
- **Deletion or rewrite of existing code** — each target named and confirmed before any artifact is written.

**A phase graph whose Verification Matrix tops out at E1 has planned nothing that would catch a wiring defect.** Say so out loud before finishing, or fix the matrix.

**A spec whose acceptance under A5 is the user's own vocabulary, and whose J column is empty, has the same hole one level up.** The claim *they will not have to learn the model* is checkable — walk the journey, list what they had to understand — and a matrix that leaves it at J0 has left the feature's stated bar untested.

---

## Completion

Report against the output kind.

**`implementation`** — the feature directory, the phase count, the approach in a sentence, the Verification Matrix's weakest column on each axis, any open question left with an owner, and the next command: `$zforge:feature-orchestrate {name}` for autonomous execution, `$zforge:feature-resume {name}` to work interactively.

**`requirements`** — the feature directory, what the spec covers, the acceptance vocabulary captured under A5, and every A6 decision still parked with who owns it and by when. The next command is a **later** `$zforge:plan {name} --kind implementation`, run when there is something buildable. Do not run it now, and do not write toward it.