/writing-plans

name: writing-plans
description: Creates executable implementation plans that break down a brainstorming design into detailed, unambiguous per-batch tasks for execution.
argument-hint: [design-folder-path]
user-invocable: true
disable-model-invocation: true
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Agent", "Bash(git-agent:*)", "Bash(git:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/lib/seed-checklists.sh:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh:*)"]

Writing Plans

Create executable implementation plans that reduce ambiguity for whoever executes them — substantial Phase 1 → Phase 6 work, run wrapped in `/goal` (see below).

Recommended: run wrapped in `/goal`

**Launch it under Claude Code's built-in `/goal`** (v2.1.139+) so the run continues to a committed plan instead of stopping mid-phase:

/goal "Claude has narrated a successful plan commit (with commit hash) and reported the Phase 4 reflection sub-agent verdicts inline" /superpowers:writing-plans <design-path>

`/goal` is a **user-typed outer wrapper** (a skill cannot enable it for itself mid-run), and its evaluator judges only what Claude narrates in the transcript — phrase the condition against narrated output (the commit hash, the literal Phase 4 reflection summary), never filesystem state. Full semantics and condition phrasing: `../../skills/references/goal-wrapper.md`.

CRITICAL: Bail-Out Check (run first)

**Read `bdd-specs.md` from the resolved design folder. Count `Scenario:` occurrences. Bail out — do NOT decompose tasks — when EITHER:**

• BDD scenarios in `bdd-specs.md` < 3, **OR**
• Total estimated task count < 5 (estimate `2× BDD scenarios + 1 setup task`, or prefer an explicit "Task Estimate" hint in the design `_index.md`)

The OR-gate catches the "2 BDD + many setup tasks" shape an AND-gate lets through.

**Bail-out response (output verbatim):**

> Design too thin for full task-decomposition pipeline (BDD < 3 OR estimated tasks < 5). Drafting a one-page lightweight plan inline instead. To force the full pipeline, re-invoke as `/superpowers:writing-plans --force <design-path>`.

Then write a single `_index.md` (no per-task files, no Phase 4 reflection, no plan evaluator) and exit. The `--force` token (literal in `$ARGUMENTS`, case-sensitive, whole-token match) bypasses this check.

CRITICAL: Justification Check (run after bail-out)

**Read `_index.md` from the resolved design folder. Bail out — do NOT decompose tasks — when grep matches any of:**

grep -nE "STATUS:.*NOT.JUSTIFIED|DESIGN-NOT-YET-JUSTIFIED|DESIGN-CONSIDERED-DEFERRED|DO NOT IMPLEMENT" "<resolved-design-folder>/_index.md"

This catches designs explicitly marked "not approved to advance" (full semantics: `docs/retros/checklists/design-v1.md` JUST-01; inciting case: `docs/retros/2026-05-09-v3-considered-deferred.md`).

**On match, refuse deterministically (the marker is dispositive — do not interpret it away)**:

1. Output a one-line note: `Refusing: <design-path>/_index.md:{N} is marked NOT-JUSTIFIED — '{matched text}'. Re-invoke /superpowers:brainstorming to revise the design, or pass --justify-override to bypass this gate.` 2. Exit without proceeding.

**Override**: Pass `--justify-override` (literal token in `$ARGUMENTS`, case-sensitive, whole-token match) to bypass this refusal and continue to First Action.

**PROHIBITED**: Do NOT conflate `--force` (bypasses the size gate only) with `--justify-override` (bypasses this justification gate only) — they are independent; `--force` on a thin design does not bypass a NOT-JUSTIFIED refusal.

First Action — Resolve Design Path

1. Resolve the design path:

• If `$ARGUMENTS` provides a path (e.g., `docs/plans/YYYY-MM-DD-topic-design/`), use it
• Otherwise, pick the `*-design/` folder whose basename sorts last under `YYYY-MM-DD-*-design/` — highest date prefix in the name, not filesystem mtime: `ls -1d docs/plans/*-design/ 2>/dev/null | sort | tail -1` (NOT `ls -t` — edited old folders outrank fresh ones by mtime). Use the result directly; do NOT pause to confirm.
• If no `*-design/` folder exists in `docs/plans/`, refuse with: `Refusing: no design folder found under docs/plans/. Run /superpowers:brainstorming first, or pass the design folder path explicitly.` Then exit.

2. Proceed to Initialization in the same turn.

Initialization

1. **Design Check**: Verify the folder contains `_index.md` and `bdd-specs.md`. Consult the docs index before drafting: run `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" show <design-path>`. If the status is `expired:`, REFUSE — output a one-line note citing the expired status and exit without creating a plan folder. Then consult memory: run `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind memory --status active` and Read the top topically-relevant matches before Phase 1. 2. **Context**: Read `bdd-specs.md` completely. This is the source of truth for your tasks.

Background Knowledge

**Core Concept**: Explicit over implicit, granular tasks, verification-driven, context independence.

**MANDATORY**: Unit-test tasks require external dependency isolation with test doubles (DB/network/third-party APIs). All other decomposition invariants are enforced by Phase 2 steps 1-7.

Phase 1: Plan Structure

Define goal, architecture, constraints, and context.

1. **Read Specs**: Read `bdd-specs.md` from the design folder. 2. **Draft Structure**: Use `./references/structure-template.md` to outline the plan. 3. **Write Context Section**: Populate `## Context` in `_index.md`: why this work is needed (motivation, constraints, prior incidents); for existing-code changes add a current-state vs target-state comparison table (omit for greenfield work). 4. **Write Global Constraints Section**: Populate the `## Global Constraints` section in `_index.md` — the cross-task invariants every batch and every task must respect (these make parallel batches safe). One invariant per bullet, no prose; omit only when the design carri