writing-plans

name	writing-plans
description	Use when you have a spec or requirements for a multi-step task, before touching code

Writing Plans

CRITICAL CONSTRAINTS — Read Before Anything Else

You MUST NOT call EnterPlanMode or ExitPlanMode at any point during this skill. This skill operates in normal mode and manages its own completion flow via AskUserQuestion. Calling EnterPlanMode traps the session in plan mode where Write/Edit are restricted. Calling ExitPlanMode breaks the workflow and skips the user's execution choice. If you feel the urge to call either, STOP — follow this skill's instructions instead.

Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

Announce at start: "I'm using the writing-plans skill to create the implementation plan."

Context: If working in an isolated worktree, it should have been created via the superpowers-extended-cc:using-git-worktrees skill at execution time.

Save plans to: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

• (User preferences for plan location override this default)

Scope Check

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

File Structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

• Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
• You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
• Files that change together should live together. Split by responsibility, not by technical layer.
• In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

REQUIRED FIRST STEP: Initialize Task Tracking

BEFORE exploring code or writing the plan, you MUST:

1. Call TaskList to check for existing tasks from brainstorming
2. If tasks exist: you will enhance them with implementation details as you write the plan
3. If no tasks: you will create them with TaskCreate as you write each plan task

Do not proceed to exploration until TaskList has been called.

TaskList

Task Granularity

Each task is a coherent unit of work that produces a testable, committable outcome.

See skills/shared/task-format-reference.md for the full granularity guide.

Key principle: TDD cycles happen WITHIN tasks, not as separate tasks. A task is "Implement X with tests" — the red-green-refactor steps are execution detail inside the task, not task boundaries.

Scope test:

1. Can it be verified independently? (if no → too small)
2. Does it touch more than one concern? (if yes → too big)
3. Would it get its own commit? (if no → merge with adjacent task)

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:subagent-driven-development (recommended) or superpowers-extended-cc:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**User decisions (already made):** [One line per decision the user made during brainstorming/planning, quotable. "none" if none.]

---

Deferred decisions

If the plan schedules questions for the user (a DECIDE list, an AskUserQuestion step), each question MUST:

• Cite why it is still open despite the header decisions. If a recorded decision answers it, answer from the record — do not re-ask.
• Carry the facts needed to answer it in the option descriptions: name the artifact AND its role/state (e.g. "stale GitHub mirror, last push 2026-03-25 — separate from your local-tools dev home"), and state what does NOT change under each option.
• Recommend nothing that contradicts a recorded decision. That is a plan failure (same severity as No Placeholders).

Task Structure

### Task N: [Component Name]

**Goal:** [One sentence — what this task produces]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

**Acceptance Criteria:**
- [ ] [Concrete, testable criterion]
- [ ] [Another criterion]

**Verify:** `exact test command` → expected output

**Steps:**

- [ ] **Step 1: Write the failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

- [ ] **Step 3: Write minimal implementation**

```python
def function(input):
    return expected
```

- [ ] **Step 4: Run test to verify it passes**

Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

No Placeholders

Every step must contain the actual content an engineer needs. These are plan failures — never write them:

• "TBD", "TODO", "implement later", "fill in details"
• "Add appropriate error handling" / "add validation" / "handle edge cases"
• "Write tests for the above" (without actual test code)
• "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
• Steps that describe what to do without showing how (code blocks required for code steps)
• References to types, functions, or methods not defined in any task

Remember

• Exact file paths always
• Complete code in every step — if a step changes code, show the code
• Exact commands with expected output
• DRY, YAGNI, TDD, frequent commits

Self-Review

After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.

1. Spec coverage: Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.

2. Placeholder scan: Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.

3. Type consistency: Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug.

If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.

Gate enforcement note (only when user-gate tasks were tagged AND hooks not yet registered)

If the plan contains any task with userGate: true, check whether the user already opted in (scans the three user-editable settings files Claude Code merges — project settings.local.json + settings.json, and user ~/.claude/settings.json; missing files silently skipped):

cat .claude/settings.local.json .claude/settings.json ~/.claude/settings.json 2>/dev/null | grep -q "post-task-complete-revalidate.sh"

If the pipeline exits 0 (the canonical user-gate hook is registered in any of those files) → suppress the heads-up entirely. They already enabled it.

Otherwise, show this short heads-up before the Execution Handoff (substitute {N} and the task numbers):

Heads up — I tagged {N} task(s) as user-gate (Tasks #X, #Y, …). The plan runs end-to-end as-is. If you'd like automatic close-time enforcement, the JSON snippets are in README.md — paste them into .claude/settings.json (or settings.local.json). Happy to walk you through it; just say the word.

Internal reference (do NOT show): README sections #force-re-validation-on-user-thrown-gate-close + #re-validate-gates-on-plan-complete-claims in ~/.claude/plugins/marketplaces/superpowers-extended-cc-marketplace/README.md. Hooks: hooks/examples/{post-task-complete-revalidate,stop-revalidate-user-gates}.sh. Design doc: docs/user-gate-flow.md.

Suppress entirely if no user-gate tasks were tagged. Do NOT turn this into an AskUserQuestion.

Execution Handoff

STOP. You are about to complete the plan. DO NOT call EnterPlanMode or ExitPlanMode. You MUST call AskUserQuestion below. Both are FORBIDDEN — EnterPlanMode traps the session, ExitPlanMode skips the user's execution choice.

Your ONLY permitted next action is calling AskUserQuestion with this EXACT structure:

AskUserQuestion:
  question: "Plan complete and saved to docs/superpowers/plans/<filename>.md. How would you like to execute it?"
  header: "Execution"
  options:
    - label: "Subagent-Driven (this session)"
      description: "I dispatch fresh subagent per task, review between tasks, fast iteration"
    - label: "Parallel Session (separate)"
      description: "Open new session in worktree with executing-plans, batch execution with checkpoints"

If you are about to call ExitPlanMode, STOP — call AskUserQuestion instead.

STOP. The user has chosen an execution method. You MUST invoke the corresponding skill using the Skill tool NOW. Do NOT implement tasks yourself — do NOT read files, make edits, or update task statuses. Your ONLY permitted action is invoking the skill below.

If Subagent-Driven chosen: Invoke the Skill tool: superpowers-extended-cc:subagent-driven-development

• The skill handles everything: subagent dispatch, review, task tracking
• You stay in this session as the coordinator
• Do NOT start working on tasks directly

If Parallel Session chosen: Guide the user to open a new session in the worktree, then invoke: superpowers-extended-cc:executing-plans

---

Native Task Integration Reference

Use Claude Code's native task tools (v2.1.16+) to create structured tasks alongside the plan document.

Creating Native Tasks

For each task in the plan, create a corresponding native task. Embed metadata as a json:metadata code fence at the end of the description — this is the only way to ensure metadata survives TaskGet (the metadata parameter on TaskCreate is accepted but not returned by TaskGet).

User-Thrown Gates — Mechanical Detection + Tagging

You MUST run this check for EVERY task you create. It takes seconds and is the cheapest part of the whole user-gate flow.

Step 1 — Scan for gate-language. For each of these, search the user's brief AND the task's Goal/Acceptance Criteria, case-insensitive, whole-word where reasonable:

Bucket	Keywords / patterns
Verbs	verify, prove, validate, confirm, ensure, check, gate
Nouns	verification gate, acceptance test, smoke test, end-to-end, E2E
Scope	first on one, then all, one before the rest, before proceeding, don't continue until
Proof	prove it works, make sure, demonstrate, show that

Trigger rule — a task is a user-thrown gate ONLY if:

• a Nouns match is found (these phrases are unambiguous gate nouns), OR
• a Scope match is found (commitment to ordering is a gate by itself), OR
• a Verbs match co-occurs with EITHER a Scope or a Proof match.

A Verbs match ALONE is not enough. Normal work briefs routinely say "validate the output" or "check that imports work" without asking for a gate. If the user wanted a gate, they committed to ordering ("do X before Y", "first on one"), named the artifact ("smoke test", "acceptance test"), or demanded proof ("prove it works", "show that"). One of those MUST be present in addition to the verb.

If no bucket matches, or only Verbs match → regular task, no tagging needed.

Step 2 — Tag the task. In the task's json:metadata fence:

1. Set "userGate": true.
2. Append "user-gate" to the tags array (create the array if absent).
3. If the user's brief specified the HOW concretely (named a command, entity, subagent, or observable), put it straight into verifyCommand and acceptanceCriteria — done.
4. If HOW is vague, set "requiresUserSpecification": true only when the verification sentence names no testable noun (function, command, entity, endpoint, file, log pattern) AND no concrete value (expected result, threshold, example input/output). One foothold — e.g. "verify each op with real inputs" — is enough for the agent to self-solve. The flag is for pure adjectives ("solid", "works", "good", "proper") where any guess is a shot in the dark.

Step 3 — Add the prose banner (mandatory whenever userGate: true). Near the top of the task description, right under Goal:, include verbatim:

USER-ORDERED GATE — NON-SKIPPABLE. This task was requested by the user in the current conversation. It MUST NOT be closed by walking around it, by declaring it "verified inline", or by substituting a cheaper check. Close only after every item in acceptanceCriteria has been re-validated independently, with output captured.

Tasks with declared evidence axes — set requireEvidenceTokens. When a task's close is meaningful only if the coordinator has actually observed two (or more) labeled states, declare the axes in metadata. The post-task-complete-revalidate hook refuses the close unless at least one token from each axis appears in the close window. Examples:

• Empirical refactor / A/B: either explicit ("requireEvidenceTokens": [["baseline","old","iter-0"], ["refactored","new","iter-1"]]) or shortcut ("requireABCompare": true).
• v2→v3 migration verification: "requireEvidenceTokens": [["v2","legacy"], ["v3","migrated"]].
• Perf before/after: [["slow","unoptimized","p50=X"], ["fast","optimized","p50=Y"]] — include the literal metric tags you expect the coordinator to post.
• Multi-arm experiment: [["control"], ["variant-a"], ["variant-b"]] — any number of axes.
• Security pre/post fix: [["vulnerable","CVE-","before-patch"], ["patched","after-patch","hardened"]].

Without the axes, "looks good, keep going" closes are legal; with axes, the coordinator must produce evidence from each declared side. Pair with a concrete verifyCommand that actually runs both sides when possible (e.g. diff <(old-cmd) <(new-cmd)).

Banner ↔ metadata invariant — both paths must agree. The banner goes inside the SAME TaskCreate description string as the json:metadata fence, not only in the plan .md. If you are writing both a plan document AND creating native tasks, the banner must appear in BOTH places for the same task, OR in NEITHER. Self-check before moving on: for each task, the plan doc section and the TaskCreate description must both either have userGate: true + banner + fence, or have none of them.

Step 4 — Check acceptance criteria operational specificity. Each criterion MUST name an observable. Vague ("integration works", "it passes") is not acceptable — rewrite to "sensor X reports idle", "HTTP 200 from /health", "setup.done file present", etc. If you cannot make a criterion operational, set requiresUserSpecification: true and let /specify-gate collect the real answer.

Step 5 — Per-task isolation self-check. For every task where you set userGate: true and DIDN'T set requiresUserSpecification: true, re-read ONLY that task's Goal sentence in isolation — pretend no other task exists. Does that sentence alone name an observable, a capture method, AND a pass/fail value? If no to any of the three, set requiresUserSpecification: true even if you already filled in a verifyCommand from context. Borrowing concreteness from sibling tasks is the failure mode this catches. Example: a plan with per-op tasks saying "verify add(3,2)==5" (concrete) and a final task saying "make sure the whole thing works" (vague) — the per-op tasks anchor; the final task fails this check and MUST carry requiresUserSpecification: true.

Tag liberally when a real gate signal is present. The three shades of gate (strict user gate / strict agent gate / gray in-between) all get the same tag — if the trigger rule above matches, err on the side of tagging. But do not read a gate into normal verbs: "validate", "check", "verify" on their own describe routine work, not user-thrown gates. Over-tagging on real signals is harmless (extra metadata). Over-tagging on bare verbs produces the banner flood that makes every task look high-ceremony and drowns the real gates.

Do NOT ask the user questions during write-plan. The opinionated default is "tag it and move on". Users who wanted questions said "brainstorm". If the user's brief is vague about a gate's HOW, the flag requiresUserSpecification: true routes the question to execute time where /specify-gate handles it in 3-5 short multiple-choice prompts.

See skills/shared/task-format-reference.md → "User-Thrown Gates" for the full metadata schema with all six gate-related keys (userGate, tags, requiresUserSpecification, gateScope, failurePolicy, subagentBrief), and docs/user-gate-flow.md for the end-to-end flow.

TaskCreate description — full structured body, not a summary

Hard rule. Every TaskCreate description MUST contain, verbatim, the same Goal / Files / Acceptance Criteria / Verify sections you wrote into the plan .md for that task. Do NOT condense into a one-sentence summary. Do NOT move the AC to "see the plan doc". Do NOT omit **Verify:**. The description MUST end with the json:metadata code fence.

Why it matters. Both execution paths (executing-plans and subagent-driven-development) read the task description via TaskGet and pass it to the implementing subagent. A one-sentence description makes the subagent improvise AC. The plan .md is not a fallback — TaskGet does not read it.

Self-check before finishing the skill. After TaskCreate for every task, open the task description (via TaskGet or by reading <plan>.tasks.json) and confirm all four section headers (**Goal:**, **Files:**, **Acceptance Criteria:**, **Verify:**) AND the json:metadata fence are present. If any section is missing → TaskUpdate the description to the full block.

TaskCreate:
  subject: "Task N: [Component Name]"
  description: |
    **Goal:** [From task's Goal line]

    **Files:**
    [From task's Files section]

    **Acceptance Criteria:**
    [From task's Acceptance Criteria]

    **Verify:** [From task's Verify line]

    **Steps:**
    [Key actions from task's Steps — abbreviated]

    ```json:metadata
    {"files": ["path/to/file1.py"], "verifyCommand": "pytest tests/path/ -v", "acceptanceCriteria": ["criterion 1", "criterion 2"], "modelTier": "mechanical"}
    ```
  activeForm: "Implementing [Component Name]"

Why Embedded Metadata

The metadata parameter on TaskCreate is accepted but not returned by TaskGet. Embedding it as a json:metadata code fence in the description ensures:

• TaskGet returns the full metadata (it's part of the description)
• Cross-session resume can parse it from .tasks.json
• Subagent dispatch can extract it for implementer prompts

See skills/shared/task-format-reference.md for the full metadata schema.

Setting Dependencies

After all tasks created, set blockedBy relationships:

TaskUpdate:
  taskId: [task-id]
  addBlockedBy: [prerequisite-task-ids]

During Execution

Update task status as work progresses:

TaskUpdate:
  taskId: [task-id]
  status: in_progress  # when starting

TaskUpdate:
  taskId: [task-id]
  status: completed    # when done

---

Task Persistence

At plan completion, write the task persistence file in the same directory as the plan document.

If the plan is saved to docs/superpowers/plans/2026-01-15-feature.md, the tasks file MUST be saved to docs/superpowers/plans/2026-01-15-feature.md.tasks.json.

{
  "planPath": "docs/superpowers/plans/2026-01-15-feature.md",
  "tasks": [
    {
      "id": 0,
      "subject": "Task 0: ...",
      "status": "pending",
      "description": "**Goal:** ...\n\n**Files:**\n...\n\n```json:metadata\n{\"files\": [\"path/to/file.py\"], \"verifyCommand\": \"pytest tests/ -v\", \"acceptanceCriteria\": [\"criterion 1\"], \"modelTier\": \"mechanical\"}\n```"
    },
    {
      "id": 1,
      "subject": "Task 1: ...",
      "status": "pending",
      "blockedBy": [0],
      "description": "**Goal:** ...\n\n```json:metadata\n{\"files\": [], \"verifyCommand\": \"\", \"acceptanceCriteria\": [], \"modelTier\": \"standard\"}\n```"
    }
  ],
  "lastUpdated": "<timestamp>"
}

Both the plan .md and .tasks.json must be co-located in docs/superpowers/plans/.

Resuming Work

Any new session can resume by running:

/superpowers-extended-cc:executing-plans <plan-path>

The skill reads the .tasks.json file and continues from where it left off.