Skip to main content
command CX Codex

run-plan — Claude Code command: what it does, how to install

run-plan executes a PLAN.md file directly without loading planner skill overhead. It routes tasks to subagents and keeps most of the context window free.

MIT ★ 1,988 updated 2026-04-01

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add glittercowboy/taches-cc-resources
/plugin install taches-cc-resources@taches-cc-resources
Open on GitHub

What run-plan does

The command reads a target plan and picks an execution strategy based on checkpoint tags. If no checkpoints are detected, it spins up a single subagent to complete all tasks, generate SUMMARY.md, and commit the changes under feat({phase}-{plan}): [summary].

When verify-only checkpoints are found, it splits execution into segments and pauses for human confirmation. Total context overhead stays under 30% (5–7k tokens for instructions and 10–15k for project context), reserving 70%+ for code modifications. If the file at plan_path is missing, the command stops immediately with an error.

What it helps with

  • execute a prepared PLAN.md without loading planner prompt context
  • delegate task blocks to subagents to save primary context space
  • produce SUMMARY.md and structured git commits automatically
  • halt automated execution at verification checkpoints for review

Example prompts for the agent

  • /run-plan .planning/phases/07-sidebar/07-01-PLAN.md
  • /run-plan plans/auth-migration-PLAN.md

How to install run-plan

1Plugin marketplace

/plugin marketplace add glittercowboy/taches-cc-resources
/plugin install taches-cc-resources@taches-cc-resources

2Manually: put the files in place

.claude/commands/run-plan.md

Call it with /run-plan. For all projects use ~/.claude/commands/

Questions about run-plan

How to install run-plan in Claude Code?

Add the marketplace source with /plugin marketplace add glittercowboy/taches-cc-resources, then run /plugin install taches-cc-resources@taches-cc-resources. Alternatively, place the file directly at .claude/commands/run-plan.md.

What does run-plan do?

It reads an existing PLAN.md, inspects it for checkpoint tags, and runs the tasks either via autonomous subagents or via segmented execution with human verification.

How does run-plan handle already executed plans?

It looks for a matching SUMMARY.md in the plan directory. If found, it alerts you that the plan ran previously and asks for confirmation before re-running.

Source text

run-plan.md · MIT
---
type: prompt
description: Execute a PLAN.md file directly without loading planning skill context
arguments:
  - name: plan_path
    description: Path to PLAN.md file (e.g., .planning/phases/07-sidebar-reorganization/07-01-PLAN.md)
    required: true
---

Execute the plan at {{plan_path}} using **intelligent segmentation** for optimal quality.

**Process:**

1. **Verify plan exists and is unexecuted:**
   - Read {{plan_path}}
   - Check if corresponding SUMMARY.md exists in same directory
   - If SUMMARY exists: inform user plan already executed, ask if they want to re-run
   - If plan doesn't exist: error and exit

2. **Parse plan and determine execution strategy:**
   - Extract `<objective>`, `<execution_context>`, `<context>`, `<tasks>`, `<verification>`, `<success_criteria>` sections
   - Analyze checkpoint structure: `grep "type=\"checkpoint" {{plan_path}}`
   - Determine routing strategy:

   **Strategy A: Fully Autonomous (no checkpoints)**
   - Spawn single subagent to execute entire plan
   - Subagent reads plan, executes all tasks, creates SUMMARY, commits
   - Main context: Orchestration only (~5% usage)
   - Go to step 3A

   **Strategy B: Segmented Execution (has verify-only checkpoints)**
   - Parse into segments separated by checkpoints
   - Check if checkpoints are verify-only (checkpoint:human-verify)
   - If all checkpoints are verify-only: segment execution enabled
   - Go to step 3B

   **Strategy C: Decision-Dependent (has decision/action checkpoints)**
   - Has checkpoint:decision or checkpoint:human-action checkpoints
   - Following tasks depend on checkpoint outcomes
   - Must execute sequentially in main context
   - Go to step 3C

3. **Execute based on strategy:**

   **3A: Fully Autonomous Execution**
   ```
   Spawn Task tool (subagent_type="general-purpose"):

   Prompt: "Execute plan at {{plan_path}}

   This is a fully autonomous plan (no checkpoints).

   - Read the plan for full objective, context, and tasks
   - Execute ALL tasks sequentially
   - Follow all deviation rules and authentication gate protocols
   - Create SUMMARY.md in same directory as PLAN.md
   - Update ROADMAP.md plan count
   - Commit with format: feat({phase}-{plan}): [summary]
   - Report: tasks completed, files modified, commit hash"

   Wait for completion → Done
   ```

   **3B: Segmented Execution (verify-only checkpoints)**
   ```
   For each segment (autonomous block between checkpoints):

     IF segment is autonomous:
       Spawn subagent:
         "Execute tasks [X-Y] from {{plan_path}}
          Read plan for context and deviation rules.
          DO NOT create SUMMARY or commit.
          Report: tasks done, files modified, deviations"

       Wait for subagent completion
       Capture results

     ELSE IF task is checkpoint:
       Execute in main context:
         - Load checkpoint task details
         - Present checkpoint to user (action/verify/decision)
         - Wait for user response
         - Continue to next segment

   After all segments complete:
     - Aggregate results from all segments
     - Create SUMMARY.md with aggregated data
     - Update ROADMAP.md
     - Commit all changes
     - Done
   ```

   **3C: Decision-Dependent Execution**
   ```
   Execute in main context:

   Read execution context from plan <execution_context> section
   Read domain context from plan <context> section

   For each task in <tasks>:
     IF type="auto": execute in main, track deviations
     IF type="checkpoint:*": execute in main, wait for user

   After all tasks:
     - Create SUMMARY.md
     - Update ROADMAP.md
     - Commit
     - Done
   ```

4. **Summary and completion:**
   - Verify SUMMARY.md created
   - Verify commit successful
   - Present completion message with next steps

**Critical Rules:**

- **Read execution_context first:** Always load files from `<execution_context>` section before executing
- **Minimal context loading:** Only read files explicitly mentioned in `<execution_context>` and `<context>` sections
- **No skill invocation:** Execute directly using native tools - don't invoke create-plans skill
- **All deviations tracked:** Apply deviation rules from execute-phase.md, document everything in Summary
- **Checkpoints are blocking:** Never skip user interaction for checkpoint tasks
- **Verification is mandatory:** Don't mark complete without running verification checks
- **Follow execute-phase.md protocol:** Loaded context contains all execution instructions

**Context Efficiency Target:**
- Execution context: ~5-7k tokens (execute-phase.md, summary.md, checkpoints.md if needed)
- Domain context: ~10-15k tokens (BRIEF, ROADMAP, codebase files)
- Total overhead: <30% context, reserving 70%+ for workspace and implementation

© Lex Christopherson · MIT · glittercowboy/taches-cc-resources

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set48

The whole set →
heal-skill heal-skill — a command to update skill documentation based on errors discovered during execution. Shows proposed changes, waits for approval, then applies edits with optional commit. CX Codex +1 ★ 1,988repo stars whats-next whats-next analyzes the current conversation and writes a detailed handoff document to resume work in a fresh context. CX Codex +1 ★ 1,988repo stars the-pirate-bay Search The Pirate Bay through its JSON API and retrieve magnet links. Use it to find torrents, browse popular uploads, or check seed counts. CX Codex +1 ★ 1,988repo stars setup-ralph setup-ralph lays out Geoffrey Huntley's Ralph Wiggum loop in a directory: file structure, planning and build prompts, and gates that reject bad work. CX Codex +1 ★ 1,988repo stars build-macos-apps build-macos-apps is a Claude Code skill for building native macOS apps with SwiftUI and AppKit. It routes work on new apps, bugs, tests, performance, and releases to a matching workflow. CX Codex +1 ★ 1,988repo stars options A command to evaluate multiple options side-by-side: tools, approaches, architectures. It asks clarifying questions, builds a comparison matrix, and recommends the best choice with reasoning. CX Codex +1 ★ 1,988repo stars competitive competitive researches competitors for any feature or product, maps market gaps, and saves a markdown report to your project. CX Codex +1 ★ 1,988repo stars deep-dive deep-dive — a slash command that investigates a topic from several angles and writes a structured report into artifacts/research/ inside your project. CX Codex +1 ★ 1,988repo stars

Project sponsors

Companies that keep this analytics open