writing-plans

Writing Plans

Contents

• Writing Plans
  • Contents
  • Overview
  • Protocol Threshold (Required)
  • Bite-Sized Task Granularity
  • Plan Document Header
  • Task Structure
  • Execution Handoff

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.

Protocol Threshold (Required)

Follow the [CP Protocol Threshold] injected by hooks:

• Before the first Task call: output a standalone [CP1 Assessment] block (the block itself must not include tool calls; tool calls may follow in the same reply)
• Before claiming the plan is complete / ready for execution handoff: output a standalone [CP3 Assessment] block (the block itself must not include tool calls; the claim may follow in the same reply)

If unmet -> immediately perform the CP assessment, then continue the flow right away; do not stop or interrupt.

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."

Hard reminder: before your first Task tool call, you must output a standalone 【CP1 Assessment】 block (fixed format with fields).

► Checkpoint 1 (Task Analysis): Before writing the plan, apply checkpoint logic from coordinating-multi-model-work/checkpoints.md:

• Collect: overall scope, files involved, tech stack, complexity
• Check critical task conditions → Match: invoke expert model for architecture review
• Evaluate general task signals → Positive: invoke for plan quality assessment

Context: This should be run in a dedicated worktree (created by brainstorming skill).

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

Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

• "Write the failing test" - step
• "Run it to make sure it fails" - step
• "Implement the minimal code to make the test pass" - step
• "Run the tests and make sure they pass" - step
• "Commit" - step

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

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

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

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

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

---

Task Structure

### Task N: [Component Name]

**Files:**

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

**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

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

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

## Remember
- Exact file paths always
- Complete code in plan (not "add validation")
- Exact commands with expected output
- Reference relevant skills with @ syntax
- DRY, YAGNI, TDD, frequent commits

## Multi-Model Task Routing

**Related skill:** superpowers:coordinating-multi-model-work

When writing plans, you can optionally annotate tasks with model hints to guide execution. However, these hints are **suggestions only** - actual execution uses semantic analysis.

**Task annotation format (optional):**

```markdown
### Task N: [Component Name]
**Model hint:** `auto` | `codex` | `gemini` | `cross-validation`

**Files:**
- Create: `exact/path/to/file.py`
...

Routing hint meanings:

• auto - Executor determines routing through semantic analysis (default)
• codex - Suggests backend focus (API, database, algorithms)
• gemini - Suggests frontend focus (components, styles, interactions)
• cross-validation - Suggests critical task needing dual-model verification

How execution handles hints:

During plan execution (via executing-plans or developing-with-subagents):

1. Executor reads the Model hint if present

2. Applies semantic routing using coordinating-multi-model-work/routing-decision.md:

   • Collects task information (files, description, tech stack)
   • Analyzes task domain, complexity, and uncertainty
   • Makes routing decision based on semantic understanding
   • Uses hint as guidance, not strict rule

3. Routes task to optimal model (MCP tools):

   • Frontend → GEMINI (Gemini MCP mcp__gemini__gemini)
   • Backend → CODEX (Codex MCP mcp__codex__codex)
   • Full-stack/uncertain → CROSS_VALIDATION (call both MCP tools)
   • Simple → CLAUDE (no MCP call)

Example with hints:

### Task 1: Create API endpoint

**Model hint:** `codex`

**Files:**

- Create: `server/api/users.go`
- Test: `server/api/users_test.go`
  ...

### Task 2: Create user profile component

**Model hint:** `gemini`

**Files:**

- Create: `src/components/UserProfile.tsx`
- Create: `src/components/UserProfile.css`
  ...

### Task 3: Integrate API with component

**Model hint:** `cross-validation`

**Files:**

- Modify: `src/components/UserProfile.tsx`
- Modify: `server/api/users.go`
  ...

Important notes:

• Model hints are optional - executor can always succeed without them
• Hints are suggestions - executor may route differently based on semantic analysis
• Missing or auto hint → Executor performs full semantic analysis
• Plan author doesn't need to understand routing logic deeply
• Focus on clear task descriptions and file paths; routing is handled automatically

Execution Handoff

Hard reminder: before claiming the plan is complete/ready to hand off for execution, you must output a standalone 【CP3 Assessment】 block (fixed format with fields).

► Checkpoint 3 (Quality Gate): Before handoff, apply checkpoint logic from coordinating-multi-model-work/checkpoints.md:

• Plan complete and ready for execution → invoke domain expert for final review
• Critical tasks identified in plan → invoke cross-validation for architecture verification

After saving the plan, offer execution choice:

"Plan complete and saved to docs/plans/<filename>.md. Two execution options:

1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration

2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints

Which approach?"

If Subagent-Driven chosen:

• REQUIRED SUB-SKILL: Use superpowers:developing-with-subagents
• Stay in this session
• Fresh subagent per task + code review

If Parallel Session chosen:

• Guide them to open new session in worktree
• REQUIRED SUB-SKILL: New session uses superpowers:executing-plans