How to Use Claude Planner from Other Agents

Claude Planner is a specialized tool that invokes Claude Code CLI with Opus 4.5 model in plan mode to generate detailed implementation plans. When you need to plan complex changes that span multiple modules or need a structured approach before coding, use Claude Planner.

⚠️ Important: Execution Time Notice

Claude Planner typically takes 3-15 minutes to complete, depending on task complexity and codebase size. During execution:

• The terminal may appear frozen with no output - this is normal
• Do NOT interrupt or terminate the process
• The CLI is actively working in the background, exploring the codebase and generating a detailed plan
• Use --verbose flag to see real-time progress if you need reassurance
• Be patient - complex planning requires time for thorough analysis

If you interrupt the process thinking it's stuck, you'll lose all progress and need to start over.

When to Use Claude Planner

• User explicitly requests creating an implementation plan
• Large-scale refactoring that affects multiple modules or components
• New features requiring cross-module changes and architectural decisions
• Complex bug fixes that need systematic planning across the codebase
• When you need a structured roadmap before starting implementation
• Projects where stakeholders need plan review before coding begins

The File-Based Pattern

Claude Planner works best with a file-based input/output pattern:

Step 1: Create a Question File

Write your planning request and all relevant context to /tmp/question.txt:

Write to /tmp/question.txt:
- Clear description of the feature or change needed
- Current pain points or requirements
- Specific goals and success criteria
- Any architectural preferences or constraints
- Questions about approach or implementation details

Example structure:

I need to implement [feature/change].

Current situation:
- [What exists now]
- [What's missing or broken]
- [Current limitations]

Goals:
1. [Specific goal 1]
2. [Specific goal 2]

Requirements:
- [Must have]
- [Should have]
- [Constraints]

Please create a detailed implementation plan and save it to /tmp/plan.md

Step 2: Invoke Claude Planner

Use this command pattern:

bash skills/claude-planner/scripts/plan.sh /tmp/question.txt -o /tmp/plan.md

⏱️ Expected wait time: 3-15 minutes - The terminal will appear inactive while Claude analyzes your codebase. This is normal. Add --verbose to see progress.

Flags:

• First argument: Path to question file (or - for stdin)
• -o <path>: Output file path (default: /tmp/claude-plan-YYYYMMDD-HHMMSS.md)
• --model <name>: Claude model to use (default: opus)
• --cwd <path>: Repository root for exploration (default: current directory)
• --verbose: Show Claude's progress and debugging output (recommended for first-time users to see that it's working)

Step 3: Read the Plan

Read /tmp/plan.md

Claude Planner will provide:

• Summary: Overview of the solution approach
• Files to Modify/Create: List of affected files and their purposes
• Implementation Steps: Detailed numbered steps with file, action, and rationale
• Testing Strategy: How to verify the implementation
• Potential Risks: Edge cases, uncertainties, and follow-up questions

Review the plan carefully and adjust based on your project specifics before implementation.

Example Session

# 1. Create the question
Write /tmp/question.txt with:
- Feature: "Add user authentication with JWT tokens"
- Current state: "No auth system, all endpoints are public"
- Goals: "Secure API, support login/logout, token refresh"
- Requirements: "Use existing user model, minimal dependencies"

# 2. Invoke Claude Planner
bash skills/claude-planner/scripts/plan.sh /tmp/question.txt -o /tmp/auth-plan.md

# 3. Read and review
Read /tmp/auth-plan.md
# Plan includes: middleware setup, route protection, token generation/validation
# Files to modify: server.ts, routes/*.ts, add middleware/auth.ts
# Steps are numbered with specific actions and rationale
# Review plan with team, then implement

Tips

1. Be patient with execution time: Claude Planner takes several minutes to complete. The terminal will look frozen - this is expected behavior. For peace of mind, use --verbose flag to see real-time progress. Do not interrupt the process.
2. Provide complete context: Include current architecture, existing patterns, and constraints. Claude Planner explores the codebase but benefits from explicit context.
3. Be specific about goals: "Add authentication" is vague. "Add JWT-based authentication with refresh tokens, session management, and role-based access control" is specific.
4. Mention existing patterns: If your codebase follows specific conventions (e.g., "we use dependency injection", "all services are in src/services/"), include that.
5. Include constraints: Technical constraints (libraries to use/avoid, performance requirements) and business constraints (must work with existing user table, no breaking changes).
6. Review before implementing: The plan is a roadmap, not a prescription. Adjust based on insights during implementation or team discussion.
7. Iterate if needed: If the plan doesn't address something, create a new question.txt with additional context or specific follow-up questions.

Common Issues

"Terminal appears frozen/stuck": This is NORMAL. Planning takes 3-15 minutes. The CLI is working in the background. Do NOT interrupt. Use --verbose flag to see progress if concerned.

"claude: command not found": Install Claude Code CLI and authenticate first

Empty plan output: Check that the question file is not empty. Use --verbose to see what's happening

Permission errors: Ensure the output directory is writable

Plan seems off-track: The plan quality depends on question clarity. Revise the question with more specific requirements and try again

Process seems to take too long: Large codebases or complex questions can take 10-15 minutes. If it exceeds 20 minutes with --verbose showing no progress, then you may interrupt and retry with a more focused question.

Alternative: Direct Piping

For shorter planning questions:

echo "Plan how to add Redis caching to the API layer" | bash skills/claude-planner/scripts/plan.sh -

But for complex features, the file-based pattern is better because you can refine the question and keep a record of planning sessions.

Output Format

Generated plans include YAML frontmatter with metadata:

---
generated_at: 2026-02-02T10:30:00Z
model: opus
cwd: /path/to/repo
question_file: /tmp/question.txt
---

This helps track when plans were created and under what context, useful for reviewing stale plans or comparing different approaches.