claude-planner

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.

• 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

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

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 : Output file path (default: /tmp/claude-plan-YYYYMMDD-HHMMSS.md)
• --model : Claude model to use (default: opus)
• --cwd : 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

```bash

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.

```

# 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

```

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.

1. Provide complete context: Include current architecture, existing patterns, and constraints. Claude Planner explores the codebase but benefits from explicit context.

1. Be specific about goals: "Add authentication" is vague. "Add JWT-based authentication with refresh tokens, session management, and role-based access control" is specific.

1. Mention existing patterns: If your codebase follows specific conventions (e.g., "we use dependency injection", "all services are in src/services/"), include that.

1. Include constraints: Technical constraints (libraries to use/avoid, performance requirements) and business constraints (must work with existing user table, no breaking changes).

1. Review before implementing: The plan is a roadmap, not a prescription. Adjust based on insights during implementation or team discussion.

1. Iterate if needed: If the plan doesn't address something, create a new question.txt with additional context or specific follow-up questions.

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

For shorter planning questions:

```bash

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.

Generated plans include YAML frontmatter with metadata:

```yaml

---

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.