writing-plans

name	writing-plans
description	Create detailed step-by-step implementation plans

Writing Plans

Purpose

Create comprehensive implementation plans with bite-sized tasks (2-5 minutes each), exact file paths, complete code snippets, and expected output. Plans assume the implementer has zero context and needs mechanical instructions.

When to Use

• After completing a design with brainstorming skill
• When user requests an implementation plan
• Before beginning implementation of any non-trivial feature

Required argument: Path to design doc (e.g., docs/plans/2026-01-29-feature-design.md)

Do NOT execute any plan tasks, write implementation code, or make non-docs changes during plan writing. Your job is to create a complete, mechanical plan document — not to start implementing it. The executing-plans skill handles implementation.

Common Rationalizations (all wrong)

Rationalization	Why it's wrong
"I'll just implement this one thing while planning"	Implementation belongs in executing-plans. Stay in your lane.
"The plan is obvious, I don't need to write it down"	Plans catch missing steps. "Obvious" plans miss edge cases.
"Let me test if this approach works first"	That's prototyping, not planning. Design validates approach.
"This task is too small for a full plan"	Small tasks get the same plan structure. No exceptions.
"The deployed build is obviously just the repo"	Both clients cache; a local marketplace still runs from cache. Check the wrapper log for the path that actually executed.
"Empty output means there were no matches"	It may mean the command failed, the glob aborted, or a head truncated it away. Make absence provable.

Mandatory Direct Transition Preflight

Before every direct workflow-transition MCP call:

1. Call get_resume_state and validate that its session identity is the provider-native root session for the active task. Missing or mismatched identity: fail closed; stop and report the mismatch.
2. Compare its current workflow stage to the requested target. On an equal-target result, skip the transition call and preserve all state.
3. Make one different-target call only and require returned changed:true. If the call errors or returns unexpected changed:false, stop and report it; do not retry without a fresh get_resume_state read. No blind retry.

Process

Announce professional mode status:

Using writing-plans skill. Professional mode is ACTIVE - architect mode enforced (no code changes).

Before You Begin: Episodic Memory Search

Episodic memory search is REQUIRED before plan writing (see Step 0.5). Relevant when:

• Design relates to past work in this project
• Similar features were implemented before
• User references "last time", "like we did before"
• Context feels incomplete (after compaction)

To search: dispatch the ironclaude:search-conversations agent with relevant query.

Phase 0: Validate Design Doc Argument

Step 0: Check for required design doc path argument

If no design doc path is provided, display:

BLOCKED: Design doc path required.

Usage: /writing-plans docs/plans/YYYY-MM-DD-feature-design.md

The design file must:
- Exist at the specified path
- End with -design.md

Then STOP. Do not proceed without a valid design doc path.

If design doc path is provided:

1. Verify file exists
2. Verify it ends with -design.md
3. Read the design doc for context
4. Proceed to Phase 1

Step 0.5: Search Episodic Memory (REQUIRED)

Before creating the implementation plan:

1. Dispatch ironclaude:search-conversations agent with query based on design topic
2. Look for:
   • Similar implementations done before
   • Patterns that worked or failed
   • Integration gotchas
3. Incorporate relevant learnings into plan

This is REQUIRED, not optional. Do not skip.

Phase 1: Read Design Document

Step 1: Locate design document

Check docs/plans/ for the most recent design:

Use the Glob tool with pattern docs/plans/*-design.md to find design documents.

Read the design document completely to understand:

• Architecture
• Components to build
• Data flow
• Testing strategy

Identify the operator-approved requirements artifact used to approve the design. If none exists, STOP and return to brainstorming to document and approve the requirements. Record this path as requirements_file in the human plan and machine plan; a professional blind review must evaluate original requirements, not only the author's design interpretation.

Step 1.6: Ground every plan fact in live source (REQUIRED)

Before writing any task, inspect the current implementation, tests, schemas, and call sites that constrain it. Every file path, function name, signature, DB column, config key, and command the plan asserts MUST be verified against current source — read it, do not infer it from design prose, an earlier plan, or a summary. A symbol you did not open does not exist for planning purposes. Speculative replacement snippets are not implementation authority; any indispensable code fragment must be derived from and checked against the current source contract.

This is verified rather than inferred: if a plan names foo() at bar.py:42, open bar.py:42 and confirm foo is there with the signature the plan assumes.

Verify the artifact that RAN, not the one you expect. Before asserting what a deployed component does, establish which file actually executed. Do not reason from install layout: "local marketplace" does NOT imply run-from-source, and both clients cache. Use the evidence:

• ~/.claude/ironclaude-mcp-state-manager.log — the wrapper logs Starting state-manager wrapper (PID=…, PPID=…) then Launching MCP server: <absolute path> on every start. Match your process's PPID to get the exact path that executed.
• runtime-fingerprint — plugin_root, plugin_version, manifest_sha256, bundle_path, bundle_sha256.

Beware a dist/<module>.js sibling: when the entrypoint is a bundle, that file may be an inert build leftover that never runs, and the bundle itself may be stale.

Absence is not evidence. Before calling missing code a defect, run git log -S "<the exact line>" --oneline --all — it may have been removed on purpose, and "restoring" it would regress an intentional fix. Before concluding a capability is absent, require a positive control proving the mechanism was exercised at all; a null result with no control is UNCERTAIN, not a finding.

Step 1.7: Execution invariants (carry these into the plan)

Every command you author must satisfy these, and the plan document MUST state them so the blind reviewer can check the commands against a declared standard:

• Shell state does NOT persist between steps. Each step is its own invocation — use literal absolute paths; never rely on a variable exported by an earlier step (an empty variable can make a guard fail OPEN).
• Bash cwd is commander/, not the repo root. Use git -C <repo-root> and absolute paths for writes; a bare git add docs/… silently resolves to commander/docs/….
• zsh has nomatch. Quote globs ('--include=*.py'); an unquoted zero-match glob aborts the command before it runs.
• Foreground sleep is blocked. Split waits across steps and re-verify instead.
• docs/ is gitignored — plan and findings artifacts need git add -f.
• An empty result must be distinguishable from a failed command. No 2>/dev/null on evidence commands; list names, not counts; never head-truncate a grep whose purpose is proving absence or completeness; give a decisive term its own uncapped search so a broad alternation branch cannot bury it.
• Evidence outlives cleanup. Author the deliverable BEFORE deleting what it quotes; give each run its own log so a later run cannot clobber an earlier one's evidence.
• Enumerate; never hard-code the answer a discovery step is meant to find.

Phase 2: Break Down Into Tasks

Step 2: Identify major components

List the major components that need to be built:

• What files need to be created?
• What files need to be modified?
• What tests need to be written?
• What integrations are required?

Step 3: Order tasks by dependencies

Arrange tasks so:

• Foundation components come first
• Dependent components come after dependencies
• Tests come after the code they test
• Integration comes after individual components

Phase 3: Write Bite-Sized Steps

Step 4: Break each task into 2-5 minute steps

For each task, create steps that are ONE action each:

Example breakdown:

Task: Add user authentication

Step 1: Write test for authentication function (2 min)
Step 2: Run test to verify it fails (1 min)
Step 3: Implement minimal authentication function (3 min)
Step 4: Run test to verify it passes (1 min)
Step 5: Stage changes (1 min)

Each step must include:

• Exact command to run (if applicable)
• Expected output
• Exact file path
• Complete code snippet (not "add validation" - show the actual code)

TDD requirement: When a task involves creating or modifying executable code (not config files, documentation, or version bumps), the steps MUST follow this structure:

1. Write or modify the test (RED)
2. Run the test — verify it fails with expected failure
3. Write the implementation (GREEN)
4. Run the test — verify it passes
5. Stage changes

If a task genuinely does not need tests (pure config, documentation, version bump, hook script with no test framework), document why: "No tests required: [reason]" in the task description.

Phase 4: Write Plan Document

Step 5: Create plan document

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

# <Feature Name> Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use ironclaude:executing-plans to implement this plan task-by-task.

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

**Requirements:** [Path to operator-approved requirements artifact]

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

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

---

## Task 1: [Component Name]

**Files:** (MUST be explicit paths — never use glob patterns like `**/*.py`)
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

**Step 1: [Action]**

[If writing code, include complete snippet]
[If running command, include exact command and expected output]

Example:
```python
def authenticate(username, password):
    # TODO: implement
    pass

Run:

pytest tests/auth/test_authentication.py -v

Expected: FAIL with "function not defined"

Step 2: [Next action]

[Continue with exact steps...]

Step 5: Stage changes

Run:

git add src/auth/authentication.py tests/auth/test_authentication.py

Expected: Changes staged (professional mode blocks commit)

---

Task 2: [Next Component]

[Repeat structure...]

**Step 5.5: Create machine-readable plan JSON**

After creating the markdown plan, also create `docs/plans/YYYY-MM-DD-<feature-name>.plan.json`:

The JSON must follow this exact schema:
```json
{
  "name": "Feature Name",
  "goal": "One sentence describing what this builds",
  "requirements_file": "docs/plans/YYYY-MM-DD-requirements.md",
  "design_file": "docs/plans/YYYY-MM-DD-<feature-name>-design.md",
  "tasks": [
    {
      "id": 1,
      "name": "Task Name",
      "description": "What this task does",
      "allowed_files": ["exact/path/to/file.py", "exact/path/to/other.py"],
      "depends_on": [],
      "steps": [
        {
          "description": "Step description",
          "command": "optional shell command",
          "expected": "optional expected output"
        }
      ]
    }
  ]
}

Rules:

• id must be positive integers, unique across all tasks
• depends_on references other task IDs (must exist, no circular deps)
• allowed_files must be exact paths (no globs) — these are the only files the MCP will permit editing during that task
• The JSON is the source of truth for the MCP server; the markdown is for human review
• requirements_file must name the same operator-approved requirements artifact shown in the human plan
• The MCP validates schema, dependency integrity, and cycle-freedom before accepting

Stage the JSON file alongside the markdown:

git add docs/plans/YYYY-MM-DD-<feature-name>.plan.json

Step 5.6: Requirements → design → plan parity audit

Before calling mark_plan_ready, audit the complete plan as one coherent candidate. Verify the human and machine plans express the same:

• operator requirements and design coverage;
• task IDs and depends_on relationships;
• exact allowed_files lists;
• ordered steps and commands;
• tests and expected results.

If any item differs or any requirement/design decision is missing, regenerate the plan coherently before proceeding. Do not patch one representation independently.

Step 5.7: Signal plan files written

Run Mandatory Direct Transition Preflight for target plan_ready. Only after a different-target result, call MCP mcp__plugin_ironclaude_state-manager__mark_plan_ready once to transition the session to plan_ready. The statusline will show orange "plan_ready" until executing-plans is invoked.

If mcp__plugin_ironclaude_state-manager__mark_plan_ready returns an error (wrong stage), display the error to the user. Do NOT proceed to Phase 5 until it succeeds.

Note: Do NOT call mcp__plugin_ironclaude_state-manager__create_plan here. That is called by executing-plans.

Note: The higher-model plan review has been RELOCATED to the executing-plans skill (it now runs after create_plan loads the plan, gated by tier_up_review_policy). It is no longer part of writing-plans.

Phase 5: Offer Execution Options

Step 6: Stage plan document

Run:

git add docs/plans/YYYY-MM-DD-<feature-name>.md

Step 7: Present execution options with recommendation

Before presenting options, analyze the plan to determine the recommended execution strategy:

Recommend inline (option 3) when:

• Total tasks ≤ 2
• Any task has complex or ambiguous steps requiring judgment
• Tasks require reading large portions of the codebase

Recommend subagent-parallel (option 2) when:

• Wave 1 has 3+ independent tasks
• Tasks are self-contained file edits with clear, mechanical steps
• No task requires broad codebase context

Recommend subagent-sequential (option 1) when:

• Moderate task count (3-5) with mixed complexity
• Tasks have subtle inter-dependencies beyond what depends_on captures
• Default choice when neither inline nor parallel is clearly better

Display with recommendation:

Plan complete and saved to:
- docs/plans/YYYY-MM-DD-<feature-name>.md (human-readable)
- docs/plans/YYYY-MM-DD-<feature-name>.plan.json (machine-readable)

Professional mode is ACTIVE - plan staged for your review.

The MCP server releases tasks in dependency-computed waves:
- Wave 1: All tasks with no dependencies
- Wave 2: Tasks whose dependencies are all in Wave 1 (released after Wave 1 review passes)
- And so on until all tasks complete

Recommended: Option N ([mode name])
Rationale: [one sentence explaining why based on plan characteristics]

Three execution options:

1. Subagent tasks, sequential
   - MCP releases one wave at a time
   - Subagent per task, sequential within each wave
   - Code review after each task

2. Subagent tasks, parallel
   - MCP releases one wave at a time
   - Independent tasks within a wave run in parallel
   - Code review as each completes

3. No subagents, main session
   - Execute all tasks in this session
   - Maximum control, no subagent drift possible

Which approach? (1/2/3)

SUGGESTED_NEXT_ACTION: Skill(skill="ironclaude:executing-plans", args="docs/plans/YYYY-MM-DD-<feature-name>.plan.json --mode=inline")

(Move the "(Recommended)" label to whichever option is recommended for this specific plan.)

Wait for user choice.

If option 1 chosen (subagent tasks, sequential):

Invoke executing-plans skill: [Use Skill tool: skill="ironclaude:executing-plans", args=" --mode=subagent-sequential"]

If option 2 chosen (subagent tasks, parallel):

Invoke executing-plans skill: [Use Skill tool: skill="ironclaude:executing-plans", args=" --mode=subagent-parallel"]

If option 3 chosen (no subagents, main session):

Invoke executing-plans skill: [Use Skill tool: skill="ironclaude:executing-plans", args=" --mode=inline"]

Key Principles

• Bite-sized tasks: Every step is 2-5 minutes maximum
• Exact paths: No ambiguity about what file to touch. NEVER use glob patterns (**/*.py, src/*). Every file must be listed by its full relative path.
• Complete code: Show the actual code, not "add validation"
• Exact commands: Full command with all flags and expected output
• TDD cycle: Write test → run to fail → implement → run to pass → stage
• Professional mode aware: All steps use "git add" to stage, never commit
• Explicit skill invocation: Use Skill tool for executing-plans
• No review history in plan artifacts: A plan (human or machine) MUST NOT contain prior-review findings, verdicts, fix rationale, reviewer-drift audits, or round-by-round obligation tables. Because the human plan is a mandatory blind-reviewer input, any such content reaches the reviewer and breaks blind review (MP-W02, MP-R07). This content already has durable homes — tier_up_reviews rows, retreat reasons, and workflow-private session state. Never record it in the plan.