claude-planner

name	claude-planner
description	Comprehensive implementation planning for the Claude sub-agent. Use when a complex task requires multi-file changes, architectural analysis, or systematic execution. Triggers when the user asks for a plan, strategy, or implementation roadmap.

Claude Planner

Overview

Claude Planner uses the codebase_investigator sub-agent to perform deep research and then generates a structured implementation plan optimized for the claude sub-agent. It ensures that Claude has all the necessary context, file paths, and specific instructions to execute accurately.

Workflow

1. Research (via Codebase Investigator)

Invoke codebase_investigator with the user's objective. This tool will map dependencies, identify relevant files, and provide architectural insights.

2. Strategy Synthesis & Collaboration

• Analyze Findings: Review the investigator's report to formulate a step-by-step strategy.
• Ask Questions: If the objective is ambiguous or research reveals multiple paths, ask for clarification. Do not assume user intent.
• Make Suggestions: Propose improvements or alternative architectural approaches if they provide better scalability, safety, or performance.
• Validate Assumptions: Explicitly state any assumptions you are making and ask for confirmation unless they are undeniably implied.

3. Plan Generation & Approval

Generate a Markdown plan (see template below). You MUST obtain explicit user approval of the plan before proceeding to the execution phase.

4. Writing the Plan File

Once the plan is approved, write the full content of the plan to a file named PLAN-${SHORT_DESCRIPTOR}.md (e.g., PLAN-add-auth.md). This ensures the plan is persistent and accessible to Claude.

5. Execution (via Claude)

Execute the task using the claude sub-agent, instructing it to read and follow the specific plan file.

• Mode: Run in the foreground (default for run_shell_command without is_background: true).
• Flags: Always use --dangerously-skip-permissions.
• Isolation (Worktree): Instruct Claude to create and use a worktree named ${SHORT_DESCRIPTOR} for all changes.
• Termination: You MUST append Then /exit to the end of the Claude instruction.
• Cleanup: Instruct Claude that its FINAL action before /exit MUST be to delete the PLAN-${SHORT_DESCRIPTOR}.md file to keep the workspace clean.
• Error Handling: Explicitly instruct Claude that if it encounters a major blocker, architectural contradiction, or critical failure, it must document its findings in the PLAN-${SHORT_DESCRIPTOR}.md file and /exit immediately rather than attempting a high-risk workaround.
• Command Pattern:

  claude --dangerously-skip-permissions "Create a worktree named ${SHORT_DESCRIPTOR}. Read and follow PLAN-${SHORT_DESCRIPTOR}.md to [Objective]. Upon success, delete the plan file and /exit. If blocked, document the issue in the plan file and /exit. Then /exit"
  

6. Final Integration (Commit & Push)

Upon Claude's successful completion and termination:

• Merge Worktree: Merge the changes from the worktree back into the main branch.
• Commit: Use a descriptive commit message following the project's convention (e.g., feat: [Objective], fix: [Objective]).
• Push: Push the changes to the remote main branch.
• Cleanup: Remove the Claude worktree.

Output Template

Your response should follow this format:

📋 Implementation Plan: [Feature/Bug Name]

Objective: [Brief description]

🔍 Research & Context

• [Key findings from codebase_investigator]
• [Dependencies or risks identified]

🛠️ Strategy

1. [Task 1]: [Details]
2. [Task 2]: [Details] ...

🧪 Verification Plan

• [Test Case 1]
• [Test Case 2]

---

Wait for user approval before executing the following:

🤖 Claude Execution & Integration

# 1. Write the plan to PLAN-[short-descriptor].md
# 2. Execute Claude task in isolated worktree
claude --dangerously-skip-permissions "Create a worktree named [short-descriptor]. Read and follow PLAN-[short-descriptor].md to [Objective]. Upon success, delete the plan file and /exit. If blocked, document the issue in the plan file and /exit. Then /exit"
# 3. Upon success, merge worktree, commit, and push to main
# git merge [short-descriptor] && git commit -m "[Objective]" && git push origin main && git worktree remove [short-descriptor]

Tips for High-Quality Plans

• Be Surgical: Focus changes on the specific requirement.
• Test-First: Always include reproduction steps for bugs and verification tests for features.
• Atomic Tasks: Break large changes into smaller claude calls if necessary.
• Zero Assumptions: If a path isn't 100% clear, ask the user. It's better to clarify than to misimplement.
• Persistent Plans: Writing to a file allows Claude to use its own tools to reference the plan throughout its entire session.
• Auto-Exit & Cleanup: Ensure /exit is the final command and the plan file is removed on success.
• Fail Gracefully: Claude should stop and report when things go wrong rather than guessing.
• Isolated Changes: Worktrees prevent pollution of the main branch until changes are ready.
• Automated Delivery: Seamlessly merge and push changes once verified by Claude.