claude-planner-kit

Claude Code slash commands that pair a deep-reading planner with a guarded implementor so JavaScript/TypeScript teams can move from idea to diff without micromanaging an agent.

Table of Contents

• Installation
• What it does
• Quick Start
• Available Commands
• Security
• Best Practices
• License

Installation

This package provides two slash commands for Claude Code:

Option 1: Project-specific installation (recommended)

# In your project directory
mkdir -p .claude/commands
cp path/to/claude-planner-kit/commands/* .claude/commands/

Option 2: User-wide installation

# Install for all your projects
mkdir -p ~/.claude/commands
cp path/to/claude-planner-kit/commands/* ~/.claude/commands/

That's it! Claude Code automatically detects markdown files in .claude/commands/ directories. No restart needed - the commands become available immediately when you type / in Claude Code.

Required: Context7 MCP Setup

The planner uses Context7 for up-to-date documentation lookups. Install it by following the instructions at:

Context7

Note: Context7 is essential for the planner's accuracy with external APIs and frameworks.

What it does

• Plans from real context — The planner fingerprints package manager, TypeScript usage, and runtime signals before it writes anything
• Verifies assumptions — Context7 docs lookups and targeted web searches trigger only when an external API or framework nuance needs confirmation
• Produces deterministic worklists — Each plan follows the shared implementor.v1 schema with stable IDs, checkbox leaves, approvals, and clearly spelled-out acceptance criteria
• Executes safely — The implementor applies ≤150-line diffs, runs type-check or lint gates, and pauses automatically when blockers or questions appear
• Keeps receipts — State, questions, design notes, and doc snippets live under .planner/implement/ so every run is auditable and easy to reset

Quick Start

1. Open your project in Claude Code

2. Create a plan:

   /create-plan "Your goal here"
   

   → Writes .planner/plan.md (auto-creates folder; makes a timestamped backup if overwriting)

3. Edit the plan (optional): Add APPROVED: lines if dependency changes are desired

4. Implement:

   /implement-plan
   

   → Parses the plan, edits the repo in micro-steps, and updates .planner/implement/* state

5. Use options:

   /implement-plan --dry-run     # Preview diffs
   /implement-plan --task T-2    # Focus on specific task
   

Available Commands

Command	Description
/create-plan	Reads repo signals and your prompt; outputs a deterministic plan (implementor.v1) with stable IDs, leaf checkboxes, constraints, acceptance, and optional approvals
/implement-plan	Executes the plan with ≤150-line patches per step, runs lint/test/tsc gates when available, and auto-continues until done or blocked. No git commits are made

Command Options

• --dry-run — Preview changes without applying them
• --task T-X — Focus on a specific task ID
• --max-lines N — Cap each micro-diff at roughly N unified diff lines (default 150)
• --max-steps K — Allow at most K micro-steps before auto-extending (default 500)
• --stop-when-questions — Stop immediately if a blocking question is logged

Security

Warning: Autonomous with broad permissions — Read this before running on untrusted repos.

What runs

• /implement-plan may run repo scripts (e.g., npm run lint, pnpm test) and tools (tsc --noEmit)
• No git commits — writes stay in your working tree and .planner/**

What leaves your machine

• External lookups never send code, logs, or env values — only library names, versions, and public API symbols
• If unsure, the lookup is skipped and an open question is recorded

Secrets and logs

• Diagnostics are redacted for sensitive values; uncertain lines are omitted
• Provide minimal env vars and avoid long-lived tokens

Dependencies

• No package installs/updates occur unless your plan includes explicit APPROVED: entries

Supply chain

• Treat repo scripts and tools as untrusted
• Prefer a disposable container/VM or CI runner for third-party code

On-disk data

• Runtime state lives in .planner/
• Add it to .gitignore and delete it to reset

Best Practices

• Start with --dry-run on new or third-party repos
• Run in an ephemeral environment for untrusted projects
• Review and commit changes yourself to keep human control over merges
• Use project-specific installation for team consistency
• Add .planner/ to .gitignore

License

MIT — see LICENSE