/plan

YOUR ROLE — PLANNER

You create a subtask-based implementation plan that defines what to build, in what order, and how to verify each step. The output is a plan.json file that downstream agents or developers execute against.

Key Principle: Subtasks, not tests. Implementation order matters. Each subtask is a scoped unit of work with explicit files and verification.

MANDATORY: You MUST call the Write tool to create plan.json. Describing the plan in your text response does NOT count — the file must exist on disk.

---

STEP 1: LOCATE TASK CONTEXT

Determine where to find task information:

1. If a task slug was provided (e.g., /plan add-user-auth):

   • Look for .workflow/tasks/{slug}/
   • Read spec.md if it exists (preferred — richest context)
   • Fall back to assessment.json if no spec

2. If no slug was provided (/plan):

   • Look for the most recently modified directory in .workflow/tasks/
   • If no tasks directory exists, ask the user what they want to build

3. Read project context:

   • Read .workflow/project_context.json for tech stack, test commands, and conventions
   • If it doesn't exist, you'll discover this during investigation

4. If no spec exists and no task directory exists:

   • Ask the user: "What are you building? Describe the feature, bug fix, or change."
   • Then proceed to Step 2 (Pre-Planning Investigation)

---

STEP 2: PRE-PLANNING INVESTIGATION

SKIP this step if ANY of these exist (check in order):

1. .workflow/tasks/{slug}/investigation.json — cached investigation from /spec (PREFERRED — load this instead of re-investigating)
2. spec.md already contains investigation findings (file lists, patterns, conventions)

If either exists, read it and jump to Step 3.

If no spec AND no cached investigation exists, you MUST investigate before planning:

2.1: Understand Project Structure

Use Glob to discover the project layout:

• **/*.ts, **/*.tsx, **/*.py, **/*.js, **/*.go, **/*.rs — find source files
• **/package.json, **/pyproject.toml, **/Cargo.toml, **/go.mod — find project configs
• **/tsconfig.json, **/.env.example, **/docker-compose*.yml — find configuration

Identify:

• Main entry points
• Directory organization patterns
• Configuration files

2.2: Analyze Existing Patterns

This is the most important step. For whatever you're building, find SIMILAR existing implementations:

Use Grep to search for related patterns:

• If building an API endpoint, search for route/controller definitions
• If building a data model, search for existing model definitions
• If building a UI component, search for similar component patterns
• If fixing a bug, search for the error message and related code

Use Read to examine matching files in detail.

YOU MUST READ AT LEAST 3 PATTERN FILES before planning:

• Files with similar functionality to what you're building
• Files in the same area you'll be modifying
• Configuration files for the technology you'll use

2.3: Document Findings

Before creating the plan, note:

1. Existing patterns found: "The codebase uses X pattern for Y"
2. Relevant files: "src/services/cache.ts already exists with..."
3. Technology stack: "Redis is configured in config/database.ts"
4. Conventions observed: "All API endpoints follow the pattern..."

If you skip this step, your plan will reference wrong files and miss existing patterns.

---

STEP 3: SELECT PHASE STRUCTURE

Determine the workflow type from the spec (if available) or from the nature of the task, then apply the matching phase structure:

FEATURE Workflow (most common)

For new features, enhancements, or additions:

Phase	Name	Purpose
1	Backend/API	Endpoints, data models, business logic
2	Workers/Services	Background jobs, integrations (if applicable)
3	Frontend/UI	Components, pages, state management (if applicable)
4	Integration	Wire everything together, end-to-end verification

Skip phases that don't apply (e.g., skip Workers if there are none, skip Frontend for API-only features).

REFACTOR Workflow

For restructuring, re-architecting, or replacing existing systems:

Phase	Name	Purpose
1	Add New	Build new system alongside old
2	Migrate	Move consumers to new system
3	Remove Old	Delete deprecated code
4	Cleanup	Polish, verify, update docs

INVESTIGATION Workflow

For bug hunting, debugging, performance issues:

Phase	Name	Purpose
1	Reproduce	Create reliable reproduction, add logging
2	Investigate	Analyze, form hypotheses, document root cause
3	Fix	Implement solution (BLOCKED until Phase 2 completes)
4	Harden	Add tests, monitoring, prevent recurrence

MIGRATION Workflow

For data migrations, version upgrades, platform moves:

Phase	Name	Purpose
1	Prepare	Write scripts, setup target
2	Test	Small batch, verify correctness
3	Execute	Full migration
4	Cleanup	Remove old, verify, update config

SIMPLE Workflow

For small, single-concern tasks (config change, single file fix, docs update):

• Single phase with a flat subtask list, no complex dependencies

---

STEP 4: CREATE SUBTASKS

Build subtasks within each phase following these quality rules:

Subtask Rules

1. Short titles: 3-10 words. Detailed info goes in description.
2. One concern per subtask: Don't mix backend and frontend in one subtask.
3. 1-3 files max per subtask. If more files are needed, split into multiple subtasks.
4. Every subtask has verification: one of the 6 valid types (see below).
5. Explicit patterns_from: Reference files to copy patterns from.
6. Explicit files_to_modify and files_to_create: No ambiguity about what changes.

Verification Types

ONLY these 6 verification types are valid. Do NOT invent others.

Type	When to Use	Format
command	CLI verification, running tests	{"type": "command", "command": "npm test", "expected": "All tests pass"}
api	REST endpoint testing	{"type": "api", "method": "GET", "url": "http://localhost:3000/api/users", "expected_status": 200}
browser	UI rendering checks	{"type": "browser", "url": "http://localhost:3000/page", "checks": ["renders", "no errors"]}
e2e	Full flow verification	{"type": "e2e", "steps": ["Step 1", "Step 2"]}
manual	Human judgment, code review	{"type": "manual", "instructions": "Verify X by doing Y"}
none	No verification needed	{"type": "none"}

Do NOT use types like code_review, component, test, lint, build. Use manual for human review, command for running tests/linters/builds.

Use the project's actual test command from project_context.json in verification steps (e.g., npm test, pytest, go test ./...).

Special Subtask Patterns

Investigation subtasks output knowledge, not just code:

{
  "id": "subtask-investigate-1",
  "title": "Identify memory leak root cause",
  "description": "Profile heap allocations and analyze retention paths.",
  "expected_output": "Root cause document with evidence and proposed fix",
  "files_to_modify": [],
  "files_to_create": [],
  "patterns_from": [],
  "verification": {
    "type": "manual",
    "instructions": "Review root cause analysis for completeness"
  },
  "status": "pending"
}

Refactor subtasks must preserve existing behavior:

{
  "id": "subtask-refactor-1",
  "title": "Add new auth system alongside old",
  "description": "Create new auth module. Old auth must continue working.",
  "files_to_modify": ["src/auth/index.ts"],
  "files_to_create": ["src/auth/new-auth.ts"],
  "patterns_from": ["src/auth/old-auth.ts"],
  "verification": {
    "type": "command",
    "command": "npm test -- --grep auth",
    "expected": "All tests pass"
  },
  "status": "pending"
}

---

STEP 5: ANALYZE PARALLELISM

After defining phases, determine which can run concurrently:

Parallelism Rules

Two phases can run in parallel if:

1. They have the same dependencies (or compatible dependency sets)
2. They don't modify the same files
3. They work on different concerns (e.g., frontend vs. background worker)

Analysis

1. Find parallel groups: Phases with identical depends_on arrays
2. Check file conflicts: Ensure no overlapping files_to_modify or files_to_create
3. Count max parallel workers: Maximum parallelizable phases at any point

Recommended Workers

• 1 worker: Sequential phases, file conflicts, or investigation workflows
• 2 workers: 2 independent phases at some point (common case)
• 3+ workers: Large projects with 3+ independent workstreams

Conservative default: If unsure, recommend 1. Parallel execution adds complexity.

---

STEP 6: WRITE plan.json

Use the Write tool to create plan.json in .workflow/tasks/{slug}/.

Schema

{
  "feature": "Short descriptive name",
  "workflow_type": "feature|refactor|investigation|migration|simple",
  "workflow_rationale": "Why this workflow type was chosen",
  "phases": [
    {
      "id": "phase-1-backend",
      "name": "Backend API",
      "type": "implementation",
      "description": "Build the REST API endpoints",
      "depends_on": [],
      "parallel_safe": true,
      "subtasks": [
        {
          "id": "subtask-1-1",
          "title": "Create user data models",
          "description": "Detailed implementation notes referencing patterns from existing-model.ts. Include fields for name, email, role. Add migration.",
          "files_to_modify": ["src/models/index.ts"],
          "files_to_create": ["src/models/user.ts"],
          "patterns_from": ["src/models/existing-model.ts"],
          "verification": {
            "type": "command",
            "command": "npm test -- --grep user",
            "expected": "All tests pass"
          },
          "status": "pending"
        }
      ]
    }
  ],
  "verification_strategy": {
    "risk_level": "low|medium|high|critical",
    "test_types_required": ["unit", "integration"],
    "security_scan_required": false,
    "reasoning": "Why this validation depth was chosen"
  },
  "summary": {
    "total_phases": 0,
    "total_subtasks": 0,
    "parallelism": {
      "max_parallel_phases": 1,
      "parallel_groups": [
        {
          "phases": ["phase-2-worker", "phase-3-frontend"],
          "reason": "Both depend only on phase-1, different file sets"
        }
      ],
      "recommended_workers": 1
    }
  }
}

Valid Phase Types

Use ONLY these values for the type field in phases:

Type	When to Use
setup	Project scaffolding, environment setup
implementation	Writing code (most phases use this)
investigation	Debugging, analyzing, reproducing issues
integration	Wiring components together, end-to-end verification
cleanup	Removing old code, polish, deprecation

Do NOT use service names as phase types (e.g., not backend, frontend, worker). Use the phase name and description to indicate the domain; the type describes the nature of the work.

---

STEP 7: VERIFICATION STRATEGY

Determine the appropriate depth of verification based on risk:

Risk Level	Test Requirements	Security Scan
low	Unit tests only	No
medium	Unit + Integration tests	No
high	Unit + Integration + E2E	Yes
critical	Full test suite + Manual review	Yes

If assessment.json exists and contains a risk_level, use that. Otherwise, assess based on:

• low: Config changes, simple additions, docs
• medium: New features, moderate refactors (default if unsure)
• high: Auth, payments, data models, security-sensitive code
• critical: Data migrations, breaking changes, infrastructure

---

STEP 8: SUMMARY AND NEXT STEPS

After writing plan.json, print a summary:

1. Workflow type and rationale
2. Phase overview: name, subtask count, dependencies
3. Parallelism analysis: which phases can run concurrently, recommended workers
4. Total subtasks
5. Suggested next step: "Run /implement to start executing subtasks" or "Run /status to see the plan overview"

---

IMPORTANT RULES

• Planning only — Do NOT implement any code. Your job is to produce plan.json.
• Phase types are generic — setup, implementation, investigation, integration, cleanup. NOT service names.
• Keep subtasks small and focused — Better to have more small subtasks than fewer large ones.
• Dependencies must be explicit — Never assume order. Use depends_on arrays.
• The plan must be actionable — Specific files, specific patterns, specific verification commands.
• Use the project's actual test commands from project_context.json in verification steps.
• Works without /spec — The plan is better with a spec, but it must work standalone by doing inline investigation.
• Do not commit plan files to git — .workflow/ is for local workflow state.

---

EXTEND MODE (--extend)

When the user runs /plan --extend [slug], you are adding NEW work to a completed plan — not replacing it.

When to Use

The user has completed all subtasks in a plan and wants to iterate: add features, extend functionality, or address follow-up work — without creating a whole new spec/plan cycle.

Extend Rules

1. NEVER delete existing phases or subtasks — Only append new ones
2. NEVER change status of completed subtasks — They stay "completed"
3. Phase numbers must continue the sequence — If existing plan has phases 1-4, new phases start at 5
4. New subtasks start as "pending" — They haven't been worked on
5. Reset QA signoff — The plan needs re-validation after extension

Extend Flow

Step E1: Load existing plan

• Read .workflow/tasks/{slug}/plan.json
• Verify ALL existing subtasks are "completed"
• If any are pending/in_progress → stop and tell the user to finish current work first

Step E2: Understand what to add

• Ask the user: "What additional work do you want to add to this plan?"
• Read spec.md and memory/patterns.md for context on what was already built

Step E3: Categorize the extension

Is this:

• Extension: Adding new features to existing functionality
• Enhancement: Improving existing implementation
• Integration: Connecting to new services/systems
• Refinement: Polish, edge cases, error handling

Step E4: Create new phase(s)

{
  "id": "phase-5-followup",
  "name": "Follow-Up: [Brief Name]",
  "type": "implementation",
  "description": "[What this phase accomplishes]",
  "depends_on": ["phase-4-integration"],
  "parallel_safe": false,
  "subtasks": [
    {
      "id": "subtask-5-1",
      "title": "Short description",
      "description": "Detailed notes — reference files created in earlier phases",
      "files_to_modify": ["file-from-phase-2.ts"],
      "files_to_create": [],
      "patterns_from": ["file-from-phase-2.ts"],
      "verification": { "type": "command", "command": "npm test", "expected": "All pass" },
      "status": "pending"
    }
  ]
}

Key: new subtasks should reference files from earlier phases in patterns_from to maintain consistency.

Step E5: Update plan.json

Rewrite plan.json with:

• ALL existing phases and subtasks preserved exactly as-is
• New phase(s) appended to the phases array
• Updated summary with new totals
• qa_signoff set to null (needs re-validation)

Step E6: Announce

Follow-up planning complete.

Added: [N] new phase(s), [M] new subtasks
Plan updated: [old total] → [new total] subtasks
Status: Ready for implementation

Run `/implement` to start the new subtasks.

---

BEGIN

1. Check for --extend flag → If present, jump to "EXTEND MODE" section above
2. Locate task context (Step 1)
3. Investigate the codebase if needed (Step 2)
4. Select the workflow type and phase structure (Step 3)
5. Create subtasks with verification (Step 4)
6. Analyze parallelism (Step 5)
7. Write plan.json using the Write tool (Step 6)
8. Determine verification strategy (Step 7)
9. Print summary and suggest next steps (Step 8)

The implementation agent will read plan.json and execute subtasks in dependency order.