# Writing Plans > Creates executable implementation plans that break down designs into detailed tasks. This skill should be used when the user has completed a brainstorming design and asks to "write an implementation plan" or "create step-by-step tasks" for execution. - Skill: `tuyv/writing-plans` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add tuyv/writing-plans` - Raw SKILL.md: https://api.skillmd.com/api/skills/tuyv/writing-plans/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tuyv (https://skillmd.com/u/tuyv) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tuyv/writing-plans --- # Writing Plans Create executable implementation plans that reduce ambiguity for whoever executes them using Superpower Loop for continuous iteration. ## CRITICAL: First Action - Start Superpower Loop NOW **Resolve the design path and start the loop immediately — do NOT read design files, explore the codebase, or do anything else first.** 1. Resolve the design path: - If `$ARGUMENTS` provides a path (e.g., `docs/plans/YYYY-MM-DD-topic-design/`), use it - Otherwise, search `docs/plans/` for the most recent `*-design/` folder matching `YYYY-MM-DD-*-design/` - If found without explicit argument, confirm with user: "Use this design: [path]?" - If not found or user declines, ask the user for the design folder path 2. Immediately run: ```bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup-superpower-loop.sh" "Write an implementation plan for: . Continue progressing through the superpowers:writing-plans skill phases: Phase 1 (Plan Structure) → Phase 2 (Task Decomposition) → Phase 3 (Validation) → Phase 4 (Plan Reflection) → Phase 5 (Git Commit) → Phase 6 (Transition)." --completion-promise "PLAN_COMPLETE" --max-iterations 50 ``` 3. Only after the loop is running, proceed with Initialization below **The loop enables self-referential iteration throughout the planning process.** ## Superpower Loop Integration This skill uses Superpower Loop to enable self-referential iteration throughout the planning process. **CRITICAL**: Throughout the process, you MUST output `PLAN_COMPLETE` only when: - Phase 1-4 (Plan Structure, Task Decomposition, Validation, Plan Reflection) are all complete - Plan folder created with all task files - User approval received in Phase 3 - Git commit completed Do NOT output the promise until ALL conditions are genuinely TRUE. **ABSOLUTE LAST OUTPUT RULE**: The promise tag MUST be the very last text you output. Output any transition messages or instructions to the user BEFORE the promise tag. Nothing may follow `PLAN_COMPLETE`. ## Initialization (The Superpower Loop and design path were resolved in the first action above — do NOT start the loop again) 1. **Design Check**: Verify the folder contains `_index.md` and `bdd-specs.md`. 2. **Context**: Read `bdd-specs.md` completely. This is the source of truth for your tasks. The loop will continue through all phases until `PLAN_COMPLETE` is output. ## Background Knowledge **Core Concept**: Explicit over implicit, granular tasks, verification-driven, context independence. **PROHIBITED**: Do not generate implementation bodies — no function logic, no algorithm code. **ALLOWED**: Interface signatures and type definitions that define the contract. - **MANDATORY**: Tasks must be driven by BDD scenarios (Given/When/Then). - **MANDATORY**: Test-First (Red-Green) workflow. Verification tasks must precede implementation tasks. - **MANDATORY**: When plans include unit tests, require external dependency isolation with test doubles (DB/network/third-party APIs). - **PROHIBITED**: Do not generate implementation bodies — no function logic, no algorithm code. - **ALLOWED**: Interface signatures, type definitions, and function signatures that define the contract (e.g., `async function improve(params: ImproveParams): Promise`). - **MANDATORY**: One task per file. Each task gets its own `.md` file. - **MANDATORY**: _index.md contains overview and references to all task files. ## Phase 1: Plan Structure Define goal, architecture, constraints, and context. 1. **Read Specs**: Read `bdd-specs.md` from the design folder (generated by `superpowers:brainstorming`). 2. **Draft Structure**: Use `./references/plan-structure-template.md` to outline the plan. 3. **Write Context Section**: Populate the `## Context` section in `_index.md`: - State why this work is needed (motivation, constraints, prior incidents). - If modifying existing code, add a current-state vs target-state comparison table covering key dimensions (module structure, API shape, behavior, etc.). Omit the table for greenfield work. ## Phase 2: Task Decomposition Break into small tasks mapped to specific BDD scenarios. 1. **Reference Scenarios**: **CRITICAL**: Every task must explicitly include the full BDD Scenario content in the task file using Gherkin syntax. For example: ```gherkin ## BDD Scenario Scenario: [concise scenario title] Given [context or precondition] When [action or event occurs] Then [expected outcome] And [additional conditions or outcomes] ``` The scenario content should be self-contained in the task file, not just a reference to `bdd-specs.md`. This allows the executor to see the complete scenario without switching files. 2. **Define Verification**: **CRITICAL**: Verification steps must run the BDD specs (e.g., `npm test tests/login.spec.ts`). 3. **Enforce Ordering**: For each feature NNN, the test task (`task-NNN--test`) must precede its paired impl task (`task-NNN--impl`) via `depends-on`. 4. **Declare Dependencies**: **MANDATORY**: Each task file must include a `**depends-on**` field listing only **true technical prerequisites** — tasks whose output is required before this task can start. Rules: - A test task (Red) for feature X has no dependency on test tasks for other features - An implementation task (Green) depends only on its paired test task (Red), not on other features' implementations - Tasks that touch different files and test different scenarios are independent by default - **PROHIBITED**: Do not chain tasks sequentially just to impose execution order — use `depends-on` only when there is a real technical reason (e.g., "implement auth middleware" must precede "implement protected route test") 5. **Create Task Files**: **MANDATORY**: Create one `.md` file per task. Filename pattern: `task---.md`. - Example: `task-001-setup.md`, `task-002-feature-test.md`, `task-002-feature-impl.md` - ``: Sequential number (001, 002, ...) - ``: Feature identifier (e.g., auth-handler, user-profile) - ``: Type (test, impl, config, refactor) - **Test and implementation tasks for the same feature share the same NN prefix**, e.g., `002-feature-test` and `002-feature-impl` 6. **Describe What, Not How**: **PROHIBITED**: Do not generate implementation bodies. Describe what to implement (e.g., "Create a function that validates user credentials"). **ALLOWED**: Include interface signatures to define contracts (e.g., `def validate_credentials(username: str, password: str) -> bool: ...`), but never the body logic. ## Phase 3: Validation & Documentation Verify completeness, confirm with user, and save. 1. **Verify**: Check for valid commit boundaries and no vague tasks. 2. **Confirm**: Use AskUserQuestion to get user approval on the plan. AskUserQuestion pauses within the turn, ensuring the user can respond before the loop re-injects. 3. **Save**: Write to `docs/plans/YYYY-MM-DD--plan/` folder. - **CRITICAL**: `_index.md` MUST include "Execution Plan" section with **inline YAML metadata** (see template in `./references/plan-structure-template.md`) - **CRITICAL**: `_index.md` MUST include "Task File References" section with links to full task files for detailed BDD scenarios - **CRITICAL**: `_index.md` MUST include "BDD Coverage" section confirming all scenarios are covered - **CRITICAL**: `_index.md` MUST include "Dependency Chain" section with visual dependency graph (will be populated in Phase 4) - Example YAML metadata: ```yaml tasks: - id: "001" subject: "Setup project structure" slug: "setup-project-structure" type: "setup" depends-on: [] - id: "002" subject: "Whale Discovery Test" slug: "whale-discovery-test" type: "test" depends-on: ["001"] - id: "003" subject: "Whale Discovery Impl" slug: "whale-discovery-impl" type: "impl" depends-on: ["002"] ``` - Example file reference: `- [Task 002: Whale Discovery Test](./task-002-whale-discovery-test.md)` ## Phase 4: Plan Reflection Before committing, verify plan quality. Scale reflection based on plan size. **Small plans (up to 6 tasks)**: Main agent performs a single review pass — check BDD coverage, dependency graph, and task completeness sequentially. No sub-agents needed. **Medium plans (7-15 tasks, 2 sub-agents)**: **Sub-agent 1: BDD Coverage & Completeness Review** - Focus: Verify BDD scenario coverage AND task structure completeness - Output: Coverage matrix, incomplete tasks, missing sections **Sub-agent 2: Dependency Graph Review** - Focus: Verify depends-on fields, check for cycles, identify missing dependencies - Output: Dependency graph, cycle detection, incorrect dependencies **Large plans (16+ tasks, 3+ sub-agents)**: **Sub-agent 1: BDD Coverage Review** - Focus: Verify every BDD scenario from design has corresponding tasks - Output: Coverage matrix, orphaned scenarios, extra tasks without scenarios **Sub-agent 2: Dependency Graph Review** - Focus: Verify depends-on fields are correct, check for cycles, identify missing dependencies - Output: Dependency graph, cycle detection, incorrect dependencies **Sub-agent 3: Task Completeness Review** - Focus: Verify each task has required structure (BDD scenario, files, steps, verification) - Output: Incomplete tasks list, missing sections by task **Additional sub-agents (launch as needed)**: Red-Green Pairing Review, File Conflict Review. **Integrate and Update**: 1. Collect all sub-agent findings 2. Prioritize issues by impact 3. Update plan files to fix issues 4. **MANDATORY**: Add dependency graph from Sub-agent 2 to `_index.md` in "Dependency Chain" section 5. Re-verify updated sections 6. **Confirm with user**: Use AskUserQuestion to present the reflection summary and get approval before committing **Output**: Updated plan with issues resolved, dependency graph included in `_index.md`, and user approval received. See `./references/plan-reflection.md` for sub-agent prompts and integration workflow. ## Phase 5: Git Commit Commit the plan folder using git-agent (with git fallback). **Actions**: 1. Stage the entire folder: `git add docs/plans/YYYY-MM-DD--plan/` 2. Run: `git-agent commit --no-stage --intent "add implementation plan for " --co-author "Claude "` 3. On auth error, retry with `--free` flag 4. **Fallback**: If git-agent is unavailable or fails, use `git commit -m "docs: add implementation plan for ..."` with conventional format See `../../skills/references/git-commit.md` for detailed patterns. ## Phase 6: Transition to Execution Prompt the user to use `superpowers:executing-plans`, then output the promise as the absolute last line. Output in this exact order: 1. Transition message: "Plan complete. To execute this plan, use `/superpowers:executing-plans`." 2. `PLAN_COMPLETE` — nothing after this **PROHIBITED**: Do NOT offer to start implementation directly. Do NOT output any text after the promise tag. ## Exit Criteria Plan created with clear goal/constraints, decomposed tasks with file lists and verification, BDD steps, commit boundaries, no vague tasks, reflection completed, user approval. ## References - `./references/plan-structure-template.md` - Template for plan structure - `./references/task-granularity-and-verification.md` - Guide for task breakdown and verification - `./references/plan-reflection.md` - Sub-agent prompts for plan reflection - `../../skills/references/git-commit.md` - Git commit patterns and requirements - `../../skills/references/loop-patterns.md` - Completion promise design, prompt patterns, and safety nets