--- name: writing-plans description: Use before a change that needs more than one commit, touches a public contract, or needs a decision from the user - writes a plan whose requirements use the repository's spec row format, gets a clean-context adversarial review, and stops at user approval. Replaces code-factory:writing-specs --- # Writing plans A plan says what will change, why, how each result is proven, and how the work splits into PRs and sessions. It does not say how to write the code. The implementer is a strong model: give it goals, limits, and proof. This skill ends when the user approves the plan. Use `orchestrate-execution` only when the user explicitly invokes it. ## 1. Understand - Read the repository instructions on the path to the code (`AGENTS.md`, `CLAUDE.md`). If the repository has specs, read its spec format and the specs that own the area. In libxmtp that is `docs/specs/SPEC-spec-format.md` and the spec that `docs/specs/README.md` names. - Use a subagent for broad reads when agent tools are available. Otherwise make bounded reads in this session. Keep conclusions and source references. - Ask the user one question at a time, and only when the answer changes the plan and the code cannot answer it. - When a choice has real trade-offs, give two or three approaches with your recommendation first. Let the user pick before you write the plan. ## 2. Write Use an external artifact service when the user requests one, project rules require one, or the plan already lives there. Prefer OpenArtifacts if available and the choice is open. Check access through the host before writing. If the required service is unavailable, report the access problem. For local plans, write `docs/plans/YYYY-MM-DD-.md` or the path the user names. Use the same plan format in both places. Answer questions about the plan in the active session. Update the plan with revisions that result from the discussion. Size the plan to the change. A small fix is a lead, a requirements table, and one task. Leave out a section that would say nothing, except `Spec changes`, which is always present. ### Requirements A plan has two kinds of requirement, with very different bars. - **Plan requirements** (IDs `P1`, `P2`, and so on). The bar is low. A plan requirement is anything this work must do or prove: fine-grained behaviour, implementation details, migration steps, tooling, CI, docs. Expect many. They live only in the plan and never appear in code comments. - **Spec requirements.** The bar is high. A spec requirement is a promise the system keeps long after this plan: an API boundary or an observable behaviour that other code or people rely on. Expect few, and only in a repository that keeps specs. When the repository has a spec authoring guide (in libxmtp, the `authoring-specs` skill), its admission test decides what qualifies; apply it before you propose a spec change. When in doubt, keep the requirement in the plan: a plausible but unimportant rule in a spec costs every later reader. Write both kinds the same way. One row each, in a table with the header `| ID | Title | Requirement | Why |`: - Condition first, then the actor, then MUST or MUST NOT (the EARS order: when, while, where, if ... then). Never SHALL. One obligation per row, at most three sentences. A title of two to seven words. - Name the field, the value, and the comparison. Give a bound its number. Replace stand-in words (earliest, latest, bounded, sufficient, promptly, appropriate) with what they stand for. - The Why cell says what breaks without the rule, or is empty. It never repeats the rule. - Reference an existing spec requirement by its ID; do not restate it. When the repository has its own spec format, write new spec rows in that format. State invariants up front. When the change touches one of these, add plan requirements, each with a proof, that answer: - **State machine:** how each terminal state becomes final, its one writer, and what readers may infer. - **Authentication or token classes:** which store each class reads, and its refusal on each route. - **Feature-flag rollout:** behaviour with the flag off stays unchanged, proved by one flags-off test that CI runs. - **Unauthenticated entry point:** the cost bound per request, in queries, connections, and writes, and its isolation from capacity that others share. An invariant the plan leaves out comes back in every review pass, each time from a new side. Every requirement has a proof: a test (name it, existing or to be written) or a command with its expected result. Mark proofs that need a person as manual. A test that proves a spec requirement carries the repository's backlink when it has one (in libxmtp, `verifies: PREFIX-NNN`). Plan IDs are never linked from code. Use `audit-tests` when choosing test proofs. For each new test, name the plausible regression it detects and why existing coverage does not detect it. Vacuous tests will be rejected in code review and cause more review cycles. A proof does not need a new checked-in test: an existing test, a repeatable one-off script, a dry-run, or a manual check can be the right choice. Give inputs, steps or commands, and the expected result. Follow repository rules for permanent regression coverage. Do not plan tests that only match the wording of the plan or copy the implementation's expected output. **Spec changes.** Every plan has this section. It lists the spec requirement IDs the plan implements, the exact text of every spec row it adds or amends, and the IDs it removes, or it says "None". Writing the spec edit is a task, usually in the first PR. When the user approves the plan, that approval covers the exact spec text in this section and nothing else. ### Tasks A task is the smallest change that has its own proofs and that a reviewer could reject while approving its neighbour. Each task has: - a goal sentence; - the requirement IDs it covers; - the files or areas it changes; - decisions already made, so the implementer does not reopen them; - `Consumes` and `Produces` when another lane depends on its interface: exact names and types; - verification: the proofs from the requirements it covers, as commands; - dependencies on other tasks. Include code only where it is important. Most code is not. Show: - key interfaces: signatures, types, protobuf messages, public API, even when no other lane depends on them; - every database schema change, and every important query, as SQL; - pseudo-code for a key algorithm or a complicated verification. ### Delivery - **PR map.** Which tasks go in each PR, the base branch, and the stack tool. A PR may hold several tasks. Say which PRs cannot pass CI alone, and why. - **Lanes.** A lane is a set of tasks that share code or decisions. One implementer session runs a lane, across tasks and across PRs. Lanes run in parallel only when they share no files and no contract that is still changing. A contract the same PR adds keeps changing until that PR's review ends, so a PR's server, client and tests are one lane. Its implementer may start helpers and merges their work itself; the orchestrator never cherry-picks. Say why each parallel pair is disjoint. - **Risk.** Mark a task `frontier` when it needs the top model tier: security, concurrency, protocol state, or data migration. ### Template ```markdown # <Two to four sentences: what changes, why, and the result a user sees.> ## Context - Catalyst: <issue, thread, or request> - Code: <paths that change and paths that must not break> - Specs: <spec files that own this area, or "none"> - Behaviour that must not change: <list, each with the test that guards it> ## Decisions - <Decision> — <one-line reason> Open questions (at most three, each with the answer assumed until the user replies): - <Question> — assumed: <answer> ## Requirements | ID | Title | Requirement | Why | | --- | --- | --- | --- | | P1 | <two to seven words> | When <condition>, <actor> MUST <result>. | <what breaks> | ## Spec changes Implements: <spec IDs>. Removes: <IDs>. Or: None. | ID | Title | Requirement | Why | | --- | --- | --- | --- | | <new or amended spec row, exact text> | | | | ## Public surface <Types or functions added or changed in bindings or SDKs. Omit if none.> ## Tasks ### Task 1: <title> <Goal sentence.> - Requirements: P1, JOIN-012 - Files: <paths> - Decisions: <list> - Consumes / Produces: <exact names and types, when another lane needs them> - Code: <key interfaces, schema changes and queries as SQL, pseudo-code; omit if none> - Verification: <command> — expect <result>; manual: <step> - Depends on: none ## Delivery | PR | Tasks | Base | Notes | | --- | --- | --- | --- | Lanes: A = Tasks 1–3 (one session); B = Task 4 (parallel with A: <why disjoint>). Frontier tasks: <list or none>. ## Models Implementer: <model, effort>. Reviewer: <model, effort>. Chore: <model, effort>. Or: "Ask at execution". ## Execution notes <Added during execution: deviations, issues found, repository stumbling blocks.> ``` ## 3. Adversarial review Use a fresh independent reviewer when the host supports one. If no such reviewer is available, finish the plan and name the review gap. Do not claim that another pass in the author's session is independent review. Every plan gets one clean-context review before the user sees the final version. A wrong line in a plan becomes many wrong lines of code, so this review has the highest return of any review. - **Reviewer:** the reviewer model from `model-choice`, in a fresh session. A different model is optional; independent context is required. - **Input:** the plan's link, ID, or existing file path and the repository path. When the plan lives in an external artifact service, check the reviewer's access and give it section references so it can read the plan directly. Include the absolute path to this plugin's audit-tests skill. Do not include the conversation or your reasons. - **Output:** the reviewer's final message to you. Deliver the review in the session that requested it. If the transport needs a file (`codex exec -o`), read it and delete it. - **Claude Code:** an `Agent` call with `subagent_type: "general-purpose"` that sets `model` and `effort` to the reviewer tier from `model-choice` (Opus, `xhigh`). Record the actual effort. For a Codex reviewer, start a `read` session with `calling-codex`; a plan review runs no build. - **Codex:** native agent tools when available, with clean context (`fork_turns: "none"`, and both `model` and `reasoning_effort`). Without agent tools, finish the plan and name the review gap. Prompt: ```text Adversarially review this implementation plan. Assume it is flawed and find how. Plan: <link, ID, or file path>. Sections: <references>. Read the plan directly and follow dependencies across sections as needed. Repository: <path>. Read the repository's instructions and the specs the plan cites. Do not edit anything. Do not start subagents. Test quality: <absolute path to audit-tests/SKILL.md>. Your final message is the review; do not write it anywhere else. Attack, in order: 1. Requirements that are untestable, ambiguous, or use a stand-in word (earliest, latest, bounded, sufficient, promptly) instead of a field, value, or comparison. Requirements with no proof, or a proof that cannot fail. Apply audit-tests to planned test proofs. Flag vacuous tests as findings; accept repeatable one-off verification when a permanent test adds no useful protection and repository rules allow it. 2. Coverage both ways: a goal with no requirement, a requirement with no task, a task with no requirement. 3. Spec fit: a spec change that does not meet the spec bar (spec bloat); a lasting API or behaviour promise left only in the plan; a restated spec requirement; a conflict with an approved spec; spec text that is not given exactly in Spec changes. 4. Changed behaviour with no requirement that keeps the old behaviour. 5. Feasibility: read the code in the impact area. Name any design the code cannot support as written. 6. Missing cases: concurrency, dependency failure, retries, restart and recovery, limits, security, migration and rollback, older clients. 7. Underspecified invariants: a state readable before it is final; an identity or token class inferred rather than marked; behaviour with the flag off; shared capacity reachable without an account. 8. Delivery: a task that leaves an invalid state; lanes called disjoint that share files or a contract; a PR that cannot pass CI and does not say so; a verification that neither a local run nor CI can execute. 9. Non-goals that hide work the goals need. 10. Simpler or standard designs: a standard protocol the plan defers or reinvents, and requirements whose relaxation would remove a state, a limit, a flag or a table. Name each cut and what it costs the goals. Try to refute each finding before you report it. Report only real defects. No style comments. Prefer one strong finding over several weak ones. Format: Verdict: PASS | ISSUES Findings: - [CRITICAL|MAJOR|MINOR] <section or ID> — <defect> Consequence: <what goes wrong in implementation if unfixed> Declined to judge: <each thing you set aside as out of scope, with the reason> Not verified: <what you could not check> ``` Triage each finding yourself: fix it, reject it with a reason, or ask the user when the fix changes scope or a contract. Review again only after a structural rewrite, at most twice. Findings still open after that go into Open questions. ## 4. Approval Give the user the plan's link or path, a short summary of what the review changed, and the open questions. Then end your turn. Do not poll a review or approval tool in a loop; the user's reply starts the next turn. Approval approves the exact spec text in Spec changes. It does not invoke an execution skill.