ワンクリックで
writing-plans
// Use when you have a spec or requirements for a multi-step task, before touching code
// Use when you have a spec or requirements for a multi-step task, before touching code
| name | writing-plans |
| description | Use when you have a spec or requirements for a multi-step task, before touching code |
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.
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:using-git-worktrees skill at execution time.
Save plans to: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
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.
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.
This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
BEFORE exploring code or writing the plan, you MUST:
TaskList to check for existing tasks from brainstormingTaskCreate as you write each plan taskDo not proceed to exploration until TaskList has been called.
TaskList
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:
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]
---
### 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"
```
Every step must contain the actual content an engineer needs. These are plan failures — never write them:
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.
If the plan contains any task with userGate: true, check whether the user already opted in (scans all 4 standard settings paths — project + user × local + global, missing files silently skipped):
cat .claude/settings.local.json .claude/settings.json ~/.claude/settings.local.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.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.
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
If Parallel Session chosen:
Guide the user to open a new session in the worktree, then invoke: superpowers-extended-cc:executing-plans
Use Claude Code's native task tools (v2.1.16+) to create structured tasks alongside the plan document.
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).
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 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:
"userGate": true."user-gate" to the tags array (create the array if absent).verifyCommand and acceptanceCriteria — done."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
acceptanceCriteriahas 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:
"requireEvidenceTokens": [["baseline","old","iter-0"], ["refactored","new","iter-1"]]) or shortcut ("requireABCompare": true)."requireEvidenceTokens": [["v2","legacy"], ["v3","migrated"]].[["slow","unoptimized","p50=X"], ["fast","optimized","p50=Y"]] — include the literal metric tags you expect the coordinator to post.[["control"], ["variant-a"], ["variant-b"]] — any number of axes.[["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.
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"]}
```
activeForm: "Implementing [Component Name]"
The metadata parameter on TaskCreate is accepted but not returned by TaskGet. Embedding it as a json:metadata code fence in the description ensures:
See skills/shared/task-format-reference.md for the full metadata schema.
After all tasks created, set blockedBy relationships:
TaskUpdate:
taskId: [task-id]
addBlockedBy: [prerequisite-task-ids]
Update task status as work progresses:
TaskUpdate:
taskId: [task-id]
status: in_progress # when starting
TaskUpdate:
taskId: [task-id]
status: completed # when done
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\"]}\n```"
},
{
"id": 1,
"subject": "Task 1: ...",
"status": "pending",
"blockedBy": [0],
"description": "**Goal:** ...\n\n```json:metadata\n{\"files\": [], \"verifyCommand\": \"\", \"acceptanceCriteria\": []}\n```"
}
],
"lastUpdated": "<timestamp>"
}
Both the plan .md and .tasks.json must be co-located in docs/superpowers/plans/.
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.
Use when picking up a user-gate task OR when a hook demands re-validation. Runs the "do I know HOW?" self-check; if the HOW is clear, executes the verification and posts evidence; if not, hands off to specifying-gates. Kept deliberately separate from executing-plans so that without the opt-in hook, the main flow stays untouched.
Use when you have a written implementation plan to execute in a separate session with review checkpoints
Use when a user-gate task has requiresUserSpecification=true OR the agent's "do I know HOW?" self-check returns no. Locks down verification mechanics through a short AskUserQuestion sequence and writes the answers back into the task's metadata. Does NOT run the verification itself.
Use when executing implementation plans with independent tasks in the current session
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions