create-plan

Invocation: User- and model-invocable
Argument hint: [work item reference or description]
Allowed tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/config-*)
Source: skills/planning/create-plan/SKILL.md

Implementation Plan

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-context.sh !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-context.sh create-plan !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-agents.sh

If no “Agent Names” section appears above, use these defaults: accelerator:reviewer, accelerator:codebase-locator, accelerator:codebase-analyser, accelerator:codebase-pattern-finder, accelerator:documents-locator, accelerator:documents-analyser, accelerator:web-search-researcher.

Plans directory: !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-path.sh plans Work items directory: !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-path.sh work

You are tasked with creating detailed implementation plans through an interactive, iterative process. You should be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications.

Initial Response

When this command is invoked:

1. Check if parameters were provided:

• If a file path or work item reference was provided as a parameter, skip the default message
• Immediately read any provided files FULLY
• Begin the research process

2. If no parameters provided, respond with:

I'll help you create a detailed implementation plan. Let me start by understanding what we're building.

Please provide:
1. The task/work item description (or reference to a work item file)
2. Any relevant context, constraints, or specific requirements
3. Links to related research or previous implementations

I'll analyze this information and work with you to create a comprehensive plan.

Tip: You can also invoke this command with a work item file directly: `/create-plan @meta/work/eng-1234.md` (where the work items directory is shown above)
For deeper analysis, try: `/create-plan think deeply about @meta/work/eng-1234.md`

Then wait for the user’s input.

Process Steps

Step 1: Context Gathering & Initial Analysis

1. Read all mentioned files immediately and FULLY:

• Work item files in the configured work items directory
• Research documents
• Related implementation plans
• Any JSON/data files mentioned
• IMPORTANT: Use the Read tool WITHOUT limit/offset parameters to read entire files
• CRITICAL: DO NOT spawn sub-tasks before reading these files yourself in the main context
• NEVER read files partially - if a file is mentioned, read it completely

2. Spawn initial research tasks to gather context: Before asking the user any questions, use specialized agents to research in parallel:

• Use the {codebase locator agent} agent to find all files related to the work item or task
• Use the {codebase analyser agent} agent to understand how the current implementation works
• If relevant, use the {documents locator agent} agent to find any existing documents about this feature

These agents will:

• Find relevant source files, configs, and tests
• Identify the specific directories to focus on
• Trace data flow and key functions
• Return detailed explanations with file:line references

3. Read all files identified by research tasks:

• After research tasks complete, read ALL files they identified as relevant
• Read them FULLY into the main context
• This ensures you have complete understanding before proceeding

4. Analyze and verify understanding:

• Cross-reference the work item requirements with actual code
• Identify any discrepancies or misunderstandings
• Note assumptions that need verification
• Determine true scope based on codebase reality

5. Present informed understanding and focused questions:

   Based on the work item and my research of the codebase, I understand we need to [accurate summary].
   
   I've found that:
   - [Current implementation detail with file:line reference]
   - [Relevant pattern or constraint discovered]
   - [Potential complexity or edge case identified]
   
   Questions that my research couldn't answer:
   - [Specific technical question that requires human judgment]
   - [Business logic clarification]
   - [Design preference that affects implementation]

   Only ask questions that you genuinely cannot answer through code investigation.

Step 2: Research & Discovery

After getting initial clarifications:

1. If the user corrects any misunderstanding:

• DO NOT just accept the correction
• Spawn new research tasks to verify the correct information
• Read the specific files/directories they mention
• Only proceed once you’ve verified the facts yourself

2. Create a research todo list using TodoWrite to track exploration tasks

3. Spawn parallel sub-tasks for comprehensive research:

• Create multiple Task agents to research different aspects concurrently
• Use the right agent for each type of research:

For deeper investigation:

• {codebase locator agent} - To find more specific files (e.g., “find all files that handle [specific component]”)
• {codebase analyser agent} - To understand implementation details (e.g., “analyze how [system] works”)
• {codebase pattern finder agent} - To find similar features we can model after

For historical context:

• {documents locator agent} - To find any research, plans, or decisions about this area
• {documents analyser agent} - To extract key insights from the most relevant documents

Each agent knows how to:

• Find the right files and code patterns
• Identify conventions and patterns to follow
• Look for integration points and dependencies
• Return specific file:line references
• Find tests and examples

3. Wait for ALL sub-tasks to complete before proceeding

4. Present findings and design options:

   Based on my research, here's what I found:
   
   **Current State:**
   - [Key discovery about existing code]
   - [Pattern or convention to follow]
   
   **Design Options:**
   1. [Option A] - [pros/cons]
   2. [Option B] - [pros/cons]
   
   **Open Questions:**
   - [Technical uncertainty]
   - [Design decision needed]
   
   Which approach aligns best with your vision?

Step 3: Plan Structure Development

Once aligned on approach:

1. Create initial plan outline:

   Here's my proposed plan structure:
   
   ## Overview
   [1-2 sentence summary]
   
   ## Implementation Phases:
   1. [Phase name] - [what it accomplishes]
   2. [Phase name] - [what it accomplishes]
   3. [Phase name] - [what it accomplishes]
   
   Does this phasing make sense? Should I adjust the order or granularity?

2. Get feedback on structure before writing details

Step 4: Detailed Plan Writing

After structure approval:

1. Write the plan to !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-path.sh plans/YYYY-MM-DD-ENG-XXXX-description.md

• Format: YYYY-MM-DD-ENG-XXXX-description.md where:
  • YYYY-MM-DD is today’s date
  • ENG-XXXX is the work item number (omit if no work item)
  • description is a brief kebab-case description
• Examples:
  • With work item: 2025-01-08-ENG-1478-parent-child-tracking.md
  • Without work item: 2025-01-08-improve-error-handling.md

2. Use this template structure:

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-template.sh plan

Step 5: Populate frontmatter

Before writing the plan file, capture metadata and substitute the unified base fields into the template’s frontmatter block:

1. Invoke ${CLAUDE_PLUGIN_ROOT}/scripts/artifact-derive-metadata.sh to obtain Current Date/Time (UTC):, Current Revision:, and Repository Name:. Run the bare path directly as an executable; never prefix it with bash/sh/env (a wrapper prefix escapes the skill’s allowed-tools permission and forces an unnecessary prompt).

2. Substitute every field below with the indicated value:

   • type: ← plan
   • id: ← the filename stem (the file path computed above without .md), always quoted as a YAML string
   • title: ← the H1 title {Feature/Task Name} Implementation Plan
   • date: ← the Current Date/Time (UTC): value
   • author: ← the author resolved per the standard chain (config → VCS user → prompt)
   • producer: ← create-plan
   • status: ← draft
   • work_item_id: ← the linked work item as a typed-linkage ref "work-item:NNNN". Fill in this form when invoked with a work item argument; otherwise omit the key entirely (do not carry an empty placeholder).
   • revision: ← the Current Revision: value
   • repository: ← the Repository Name: value
   • last_updated: ← the same Current Date/Time (UTC): value
   • last_updated_by: ← the same value resolved for author
   • schema_version: ← 1 (bare integer)

   Optional linkage/lifecycle keys are omit-by-default: the template shows each as ""/[], but write a key into the artifact only when it has a value, and omit it entirely otherwise (do not carry the empty placeholder through). By default a new plan draft names none of them.

   • parent: ← the owning work item as a typed-linkage ref ("work-item:NNNN"). Fill when the plan is owned by a work item; otherwise omit the key.
   • blocks: ← list of typed-linkage refs to plans this plan blocks (["plan:NNNN", ...]). Fill when blocking edges are explicit; otherwise omit the key.
   • blocked_by: ← list of typed-linkage refs to plans that block this one. Prefer writing the canonical blocks: on the other side; emit blocked_by: only when the canonical side cannot be written, and omit it otherwise.
   • derived_from: ← list of typed-linkage refs to research this plan was informed by (["codebase-research:NNNN", ...]). Fill when the plan derives from research; otherwise omit the key.
   • relates_to: ← list of typed-linkage refs to related artifacts. Fill when relationships are explicit; otherwise omit the key.
   • reviewer: ← name/email of the plan reviewer. Leave for review-plan to fill; omit the key on a fresh draft until the plan is reviewed.

3. Write the file with the substituted frontmatter block.

Step 6: Sync and Review

1. Present the draft plan location:

   I've created the initial implementation plan at:
   `{configured plans directory}/YYYY-MM-DD-ENG-XXXX-description.md`
   
   Please review it and let me know:
   - Are the phases properly scoped?
   - Are the success criteria specific enough?
   - Any technical details that need adjustment?
   - Missing edge cases or considerations?

2. Iterate based on feedback - be ready to:

• Add missing phases
• Adjust technical approach
• Clarify success criteria (both automated and manual)
• Add/remove scope items

3. Continue refining until the user is satisfied

Important Guidelines

1. Be Skeptical:

• Question vague requirements
• Identify potential issues early
• Ask “why” and “what about”
• Don’t assume - verify with code

2. Be Interactive:

• Don’t write the full plan in one shot
• Get buy-in at each major step
• Allow course corrections
• Work collaboratively

3. Be Thorough:

• Read all context files COMPLETELY before planning
• Research actual code patterns using parallel sub-tasks
• Include specific file paths and line numbers
• Write measurable success criteria with clear automated vs manual distinction
• automated steps should use make whenever possible

4. Be Practical:

• Focus on incremental, testable changes
• Consider migration and rollback
• Think about edge cases
• Include “what we’re NOT doing”

5. Track Progress:

• Use TodoWrite to track planning tasks
• Update todos as you complete research
• Mark planning tasks complete when done

6. No Open Questions in Final Plan:

• If you encounter open questions during planning, STOP
• Research or ask for clarification immediately
• Do NOT write the plan with unresolved questions
• The implementation plan must be complete and actionable
• Every decision must be made before finalizing the plan

Success Criteria Guidelines

Always separate success criteria into two categories:

1. Automated Verification (can be run by execution agents):

• Commands that can be run: make test, npm run lint, etc.
• Specific files that should exist
• Code compilation/type checking
• Automated test suites

2. Manual Verification (requires human testing):

• UI/UX functionality
• Performance under real conditions
• Edge cases that are hard to automate
• User acceptance criteria

Format example:

### Success Criteria:

#### Automated Verification:

- [ ] Database migration runs successfully: `make migrate`
- [ ] All unit tests pass: `go test ./...`
- [ ] No linting errors: `golangci-lint run`
- [ ] API endpoint returns 200: `curl localhost:8080/api/new-endpoint`

#### Manual Verification:

- [ ] New feature appears correctly in the UI
- [ ] Performance is acceptable with 1000+ items
- [ ] Error messages are user-friendly
- [ ] Feature works correctly on mobile devices

Common Patterns

For Database Changes:

• Start with schema/migration
• Add store methods
• Update business logic
• Expose via API
• Update clients

For New Features:

• Research existing patterns first
• Start with data model
• Build backend logic
• Add API endpoints
• Implement UI last

For Refactoring:

• Document current behavior
• Plan incremental changes
• Maintain backwards compatibility
• Include migration strategy

Sub-task Spawning Best Practices

When spawning research sub-tasks:

1. Spawn multiple tasks in parallel for efficiency
2. Each task should be focused on a specific area
3. Provide detailed instructions including:

• Exactly what to search for
• Which directories to focus on
• What information to extract
• Expected output format

4. Be EXTREMELY specific about directories:

• Include the full path context in your prompts

5. Specify read-only tools to use
6. Request specific file:line references in responses
7. Wait for all tasks to complete before synthesizing
8. Verify sub-task results:

• If a sub-task returns unexpected results, spawn follow-up tasks
• Cross-check findings against the actual codebase
• Don’t accept results that seem incorrect

Example of spawning multiple tasks:

# Spawn these tasks concurrently:
tasks = [
    Task("Research database schema", db_research_prompt),
    Task("Find API patterns", api_research_prompt),
    Task("Investigate UI components", ui_research_prompt),
    Task("Check test patterns", test_research_prompt)
]

Example Interaction Flow

User: /create-plan
Assistant: I'll help you create a detailed implementation plan...

User: We need to add parent-child tracking for Claude sub-tasks. See {work_dir}/eng-1478.md
Assistant: Let me read that work item file completely first...

[Reads file fully]

Based on the work item, I understand we need to track parent-child relationships for events in the webhook daemon. Before I start planning, I have some questions...

[Interactive process continues...]

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-instructions.sh create-plan