Plan Cascade - Claude Code Plugin Guide

February 5, 2026 · View on GitHub

Plan Cascade - Claude Code Plugin Guide

Version: 4.4.0 Last Updated: 2026-02-05

This document provides detailed instructions for using Plan Cascade as a Claude Code plugin.

Installation

# Install from GitHub
claude plugins install Taoidle/plan-cascade

# Or clone and install locally
git clone https://github.com/Taoidle/plan-cascade.git
claude plugins install ./plan-cascade

First-Time Setup

Before using Plan Cascade commands, run the initialization command to ensure your environment is properly configured:

/plan-cascade:init

This command:

Detects your operating system
Installs uv (fast Python package manager) if needed
Verifies Python execution works correctly
Confirms Plan Cascade module is accessible

Note: This is especially important on Windows, where Python execution aliases can interfere with direct python3 calls.

Command Overview

Plan Cascade provides five main entry commands, suitable for development scenarios of different scales:

Entry Command	Use Case	Features
`/plan-cascade:auto`	Any task (AI auto-selects strategy)	Automatic strategy selection + ExecutionFlow depth
`/plan-cascade:mega-plan`	Large projects (multiple related features)	Feature-level parallel + Story-level parallel
`/plan-cascade:hybrid-worktree`	Single complex feature	Worktree isolation + Story parallel
`/plan-cascade:hybrid-auto`	Simple features	Quick PRD generation + Story parallel
`/plan-cascade:dashboard`	Status monitoring	Aggregated status view across all executions

Specification Interview (Spec)

Plan Cascade can run a short, resumable spec interview (planning-time) to reduce ambiguity before prd.json is finalized.

Enabled via --spec <off|auto|on> on /plan-cascade:auto, /plan-cascade:hybrid-auto, /plan-cascade:hybrid-worktree, /plan-cascade:mega-plan, and /plan-cascade:mega-approve.
In Mega execution, interviews run in the orchestrator (mega-approve), not inside per-feature subagents.

Trigger Rules

Mode	Behavior
`--spec auto`	Runs only when `--flow full` (default in `/plan-cascade:auto`)
`--spec on`	Always run the interview
`--spec off`	Never run the interview

Outputs

spec.json (structured spec) + spec.md (rendered spec)
.state/spec-interview.json (resume state)
Optional compile to prd.json

Commands

/plan-cascade:spec-plan "<desc>" [--compile] [--output-dir <dir>] [--flow <quick|standard|full>] [--first-principles] [--max-questions N] [--feature-slug <slug>]
/plan-cascade:spec-resume [--output-dir <dir>] [--flow <quick|standard|full>]
/plan-cascade:spec-cleanup [--output-dir <dir>] [--all]

Design Document System

Plan Cascade automatically generates technical design documents (design_doc.json) to provide architectural context during story execution.

Two-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│ Level 1: Project Design (from mega-plan.json)               │
│ ─────────────────────────────────────────────────────────── │
│ • Global architecture and system overview                   │
│ • Cross-feature components and patterns                     │
│ • Project-wide ADRs (architectural decisions)               │
│ • Feature mappings (which patterns/decisions apply where)   │
└─────────────────────────────────────────────────────────────┘
                          │
                          │ inheritance
                          ▼
┌─────────────────────────────────────────────────────────────┐
│ Level 2: Feature Design (from prd.json)                     │
│ ─────────────────────────────────────────────────────────── │
│ • Feature-specific components                               │
│ • Feature-specific APIs and data models                     │
│ • Feature-specific ADRs (prefixed ADR-F###)                 │
│ • Story mappings (which components/decisions per story)     │
└─────────────────────────────────────────────────────────────┘

Auto-Generation Flow

Command	Design Doc Generated	Level
`mega-plan`	Automatic after mega-plan.json	Project
`hybrid-worktree`	Automatic after prd.json	Feature (inherits from project)
`hybrid-auto`	Automatic after prd.json	Feature

External Design Documents

All three main commands support optional external design documents:

# mega-plan: 2nd argument
/plan-cascade:mega-plan "Build e-commerce platform" ./project-architecture.md

# hybrid-auto: 2nd argument
/plan-cascade:hybrid-auto "Implement user auth" ./auth-design.md

# hybrid-worktree: 4th argument
/plan-cascade:hybrid-worktree fix-auth main "Fix auth" ./architecture.md

# Supported formats: Markdown (.md), JSON (.json), HTML (.html)

External documents are automatically converted to the design_doc.json format.

Design Document Commands

/plan-cascade:design-generate    # Manually generate design document
/plan-cascade:design-review      # Review design document
/plan-cascade:design-import      # Import external document

External Framework Skills

Plan Cascade includes built-in framework-specific skills that are automatically detected and injected into story execution context.

Supported Frameworks

Framework	Skills	Auto-Detection
React/Next.js	`react-best-practices`, `web-design-guidelines`	`package.json` contains `react` or `next`
Vue/Nuxt	`vue-best-practices`, `vue-router-best-practices`, `vue-pinia-best-practices`	`package.json` contains `vue` or `nuxt`
Rust	`rust-coding-guidelines`, `rust-ownership`, `rust-error-handling`, `rust-concurrency`	`Cargo.toml` exists

How It Works

Detection: When a story is executed, Plan Cascade scans the project for framework indicators (package.json, Cargo.toml)
Loading: Matching skills are loaded from Git submodules in external-skills/
Injection: Skill content is injected into the agent's context during implementation and retry phases

Initialization

External skills are included as Git submodules. Initialize them after cloning:

git submodule update --init --recursive

Skill Sources

Source	Repository	Skills
Vercel	vercel-labs/agent-skills	React, Web Design
Vue.js	vuejs-ai/skills	Vue, Pinia, Router
Rust	actionbook/rust-skills	Coding Guidelines, Ownership, Error Handling, Concurrency

Three-Tier External Skills System

Plan Cascade uses a three-tier skill system that allows built-in, external, and user-defined skills to coexist with clear priority rules.

Tier Overview

Tier	Source Type	Priority Range	Description
1	Builtin	1-50	Built-in with Plan Cascade (Python, TypeScript, Go, Java)
2	Submodule	51-100	From Git submodules (Vercel, Vue, Rust skills)
3	User	101-200	User-defined, highest priority

Higher priority skills override lower priority skills with the same base name.

How Skills Are Detected and Injected

Detection: When a story executes, Plan Cascade scans project files for framework indicators
Matching: Skills with matching detect.files and detect.patterns are selected
Deduplication: If multiple skills share the same base name, only the highest priority is kept
Injection: Up to 3 skills are injected into the agent's context during implementation and retry phases

CLI Commands

# List all available skills
plan-cascade skills list

# List skills grouped by source type
plan-cascade skills list --group

# Show skills applicable to current project
plan-cascade skills detect

# Show skills with override details
plan-cascade skills detect --overrides

# Add a user skill from local path
plan-cascade skills add my-skill --path ./my-skills/SKILL.md

# Add a user skill from remote URL
plan-cascade skills add remote-skill --url https://example.com/skills/SKILL.md

# Add with custom options
plan-cascade skills add my-skill --path ./SKILL.md --priority 150 --level project \
  --detect-files package.json,tsconfig.json --detect-patterns typescript \
  --inject-into implementation,retry

# Remove a user skill
plan-cascade skills remove my-skill

# Remove from specific level
plan-cascade skills remove my-skill --level user

# Validate all skill configurations
plan-cascade skills validate

# Validate with verbose output
plan-cascade skills validate --verbose

# Refresh cached remote skills (re-download)
plan-cascade skills refresh --all

# Refresh specific skill
plan-cascade skills refresh remote-skill

# Clear cache without re-downloading
plan-cascade skills refresh --all --clear

# Show cache statistics
plan-cascade skills cache

Configuration File

User skills are configured in .plan-cascade/skills.json (project-level) or ~/.plan-cascade/skills.json (user-level).

Project-level configuration takes precedence over user-level.

{
  "version": "1.0.0",
  "skills": [
    {
      "name": "my-custom-skill",
      "path": "./my-skills/custom/SKILL.md",
      "detect": {
        "files": ["package.json"],
        "patterns": ["my-framework"]
      },
      "priority": 150,
      "inject_into": ["implementation"]
    },
    {
      "name": "company-coding-standards",
      "path": "../shared-skills/coding-standards/SKILL.md",
      "detect": {
        "files": ["pyproject.toml", "package.json", "Cargo.toml"],
        "patterns": []
      },
      "priority": 180,
      "inject_into": ["implementation", "retry"]
    },
    {
      "name": "remote-skill",
      "url": "https://raw.githubusercontent.com/example/skills/main/advanced/SKILL.md",
      "detect": {
        "files": ["config.json"],
        "patterns": ["advanced-feature"]
      },
      "priority": 160,
      "inject_into": ["implementation"]
    }
  ]
}

Configuration Fields:

Field	Required	Description
`name`	Yes	Unique skill name
`path`	Yes*	Local path to SKILL.md (relative to config file)
`url`	Yes*	Remote URL to skill directory
`detect.files`	No	Files that trigger this skill (e.g., `["package.json"]`)
`detect.patterns`	No	Patterns to match in detected files (e.g., `["react"]`)
`priority`	No	Priority 101-200 (default: 150)
`inject_into`	No	Phases to inject: `implementation`, `retry` (default: both)

*Either path or url is required, but not both.

Creating Custom Skills

Custom skills are defined in SKILL.md files with YAML frontmatter.

SKILL.md Format:

---
name: my-custom-skill
description: Brief description of what this skill provides.
license: MIT
metadata:
  author: your-name
  version: "1.0.0"
---

# My Custom Skill

## When to Apply

Describe when this skill should be used...

## Guidelines

| Rule | Guideline |
|------|-----------|
| Rule 1 | Description |
| Rule 2 | Description |

## Code Examples

\`\`\`typescript
// Example code...
\`\`\`

## Anti-Patterns

| Avoid | Use Instead |
|-------|-------------|
| Bad pattern | Good pattern |

Frontmatter Fields:

Field	Required	Description
`name`	Yes	Skill identifier
`description`	Yes	When to use this skill
`license`	No	License type
`metadata.author`	No	Skill author
`metadata.version`	No	Skill version

Priority and Override Rules

Higher priority wins: When skills share the same base name, the highest priority skill is used
User skills can override: A user skill with priority 150 overrides a builtin skill with priority 30
Project > User: Project-level .plan-cascade/skills.json takes precedence over ~/.plan-cascade/skills.json

Example Override:

builtin/typescript (priority: 30) <- OVERRIDDEN
submodule/vercel-react (priority: 75) <- ACTIVE
user/my-typescript (priority: 150) <- ACTIVE (overrides builtin/typescript)

Check effective skills:

# See which skills will actually be used
plan-cascade skills detect --overrides

# Output shows:
# - Total matched: 5
# - Effective after dedup: 3
# - Override details: "user/my-typescript (150) overrides builtin/typescript (30)"

Remote Skill Caching

Remote URL skills are cached locally for performance and offline access.

Cache Details:

Location: ~/.plan-cascade/cache/skills/
Default TTL: 7 days
Graceful degradation: Uses expired cache if network fails

Cache Commands:

# View cache statistics
plan-cascade skills cache

# Force refresh all cached skills
plan-cascade skills refresh --all

# Clear all cache
plan-cascade skills refresh --all --clear

Best Practices

Use project-level config for team-shared skills
Use user-level config for personal coding style preferences
Set priority carefully: 150 for general overrides, 180+ for critical rules
Keep skills focused: One skill per concern (e.g., testing, error handling)
Include detection patterns: More specific patterns reduce false matches
Test with skills detect: Verify skills are correctly detected before execution

`/plan-cascade:auto` - AI Auto Strategy

The easiest entry point. AI analyzes your task description and automatically selects the best strategy.

How It Works

You provide a task description
AI performs structured self-assessment analyzing:
- Scope: How many functional areas are involved?
- Complexity: Are there sub-task dependencies? Architecture decisions needed?
- Risk: Could it break existing functionality? Needs isolation?
- Parallelization: Can work be parallelized for efficiency?
AI outputs structured analysis with confidence score
AI selects optimal strategy and ExecutionFlow depth, then executes

ExecutionFlow Depth

Plan Cascade uses three workflow depth levels that control gating strictness:

Flow	Description	Gate Mode	AI Verification	Confirm Required
`quick`	Fastest path, minimal gating	soft	disabled	no
`standard`	Balanced speed and quality	soft	enabled	no
`full`	Strict methodology + strict gating (default)	hard	enabled + review	yes

Strategy Selection

Analysis Result	Strategy	Example
1 area, 1-2 steps, low risk	direct	"Fix the login button styling"
2-3 areas, 3-7 steps, has dependencies	hybrid-auto	"Implement user authentication"
hybrid-auto + high risk or experimental	hybrid-worktree	"Experimental refactoring of payment module"
4+ areas, multiple independent features	mega-plan	"Build e-commerce platform with users, products, orders"

Command-Line Flags

Flag	Description	Example
`--flow <quick\|standard\|full>`	Override execution flow depth (default: full)	`--flow full`
`--tdd <off\|on\|auto>`	Control TDD mode (default: on in `/plan-cascade:auto`)	`--tdd on`
`--spec <off\|auto\|on>`	Planning-time spec interview	`--spec auto`
`--first-principles`	Spec: ask first-principles questions	`--first-principles`
`--max-questions N`	Spec: soft cap interview length	`--max-questions 12`
`--confirm`	Ask for confirmation before execution (default in Full flow)	`--confirm`
`--no-confirm`	Disable batch confirmations (even in Full flow)	`--no-confirm`
`--explain`	Show analysis without executing	`--explain`
`--json`	JSON output for `--explain`	`--explain --json`

Usage Example

# AI automatically determines strategy
/plan-cascade:auto "Fix the typo in README"
# → Defaults to full flow; simple tasks are upgraded to hybrid-auto for full pipeline
# → Also defaults to `--tdd on` and `--confirm` (use `--tdd off` / `--no-confirm` to override)
# → Use `--flow quick` for direct execution

/plan-cascade:auto "Implement user login with OAuth"
# → Uses hybrid-auto strategy with full flow (default) + `--tdd on` + `--confirm`

/plan-cascade:auto "Experimental refactoring of the API layer"
# → Uses hybrid-worktree strategy (full flow by default)

/plan-cascade:auto "Build a blog platform with users, posts, comments, and RSS"
# → Uses mega-plan strategy (full flow by default)

# With flags
/plan-cascade:auto --flow full --tdd on --no-confirm "Implement payment processing"
/plan-cascade:auto --explain --json "Build user authentication"
/plan-cascade:auto --flow full --spec auto --first-principles "Critical database migration"

`/plan-cascade:mega-plan` Workflow

Suitable for large project development containing multiple related feature modules.

Use Cases

Type	Scenario	Example
✅ Suitable	Multi-module new project development	Build SaaS platform (user + subscription + billing + admin)
✅ Suitable	Large-scale refactoring involving multiple subsystems	Monolith to microservices architecture
✅ Suitable	Feature group development	E-commerce platform (users, products, cart, orders)
❌ Not suitable	Single feature development	Only implement user authentication (use Hybrid Ralph)
❌ Not suitable	Bug fixes	Fix login page form validation issue

Sequential Execution Between Batches

Mega-plan uses sequential execution between batches mode, ensuring each batch creates worktree from the updated target branch:

mega-approve (1st time) → Start Batch 1
    ↓ Batch 1 complete
mega-approve (2nd time) → Merge Batch 1 → Create Batch 2 from updated branch
    ↓ Batch 2 complete
mega-approve (3rd time) → Merge Batch 2 → ...
    ↓ All batches complete
mega-complete → Clean up planning files

Key points:

Without --auto-prd, call mega-approve once per batch; with --auto-prd, it runs all batches automatically
Each batch creates worktree from updated target branch
Planning files are not committed (added to .gitignore)

Command Reference

/plan-cascade:mega-plan <description>        # Generate project plan
/plan-cascade:mega-edit                      # Edit plan
/plan-cascade:mega-approve --auto-prd        # Approve and auto-execute all batches
/plan-cascade:mega-resume --auto-prd         # Resume interrupted execution
/plan-cascade:mega-status                    # View progress
/plan-cascade:mega-complete [branch]         # Merge and cleanup

Full Automation with --auto-prd

With --auto-prd, mega-approve runs the ENTIRE mega-plan automatically:

Creates worktrees for current batch
Generates PRDs for each feature (via Task agents)
Executes all stories (via Task agents)
Monitors until batch complete
Merges batch to target branch
Automatically continues to next batch
Only pauses on errors or merge conflicts

Resume Interrupted Execution

If execution is interrupted:

/plan-cascade:mega-resume --auto-prd

This will:

Auto-detect current state from files (mega-plan.json, .mega-status.json, worktrees)
Skip already-completed features and stories
Resume from where it left off

Usage Example

# Scenario: Build e-commerce platform
/plan-cascade:mega-plan "Build e-commerce platform: user authentication, product management, shopping cart, order processing"

# View generated plan
/plan-cascade:mega-status

# Edit plan (optional)
/plan-cascade:mega-edit

# Start execution (auto-runs all batches)
/plan-cascade:mega-approve --auto-prd

# View execution progress
/plan-cascade:mega-status

# Cleanup after all complete
/plan-cascade:mega-complete main

`/plan-cascade:hybrid-worktree` Workflow

Suitable for single complex feature development requiring branch isolation.

Use Cases

Type	Scenario	Example
✅ Suitable	Complete feature with multiple subtasks	User authentication (registration + login + password reset)
✅ Suitable	Experimental feature requiring branch isolation	New payment channel integration test
✅ Suitable	Medium-scale refactoring (5-20 files)	API layer unified error handling
❌ Not suitable	Simple single-file modification	Modify a component's style
❌ Not suitable	Quick prototype validation	Verify if a library is usable

Command Reference

/plan-cascade:hybrid-worktree <name> <branch> <desc> [options]  # Create worktree + PRD
/plan-cascade:hybrid-auto <desc> [options]                      # Generate PRD (no worktree)
/plan-cascade:edit                                              # Edit PRD
/plan-cascade:approve [options]                                 # Execute PRD stories
/plan-cascade:hybrid-resume [--auto]                            # Resume interrupted execution
/plan-cascade:hybrid-status                                     # View status
/plan-cascade:hybrid-complete [branch] [--force]                # Complete and merge (--force skips uncommitted check)

Parameter	Description
`<name>`	Task name (used for worktree and branch)
`<branch>`	Target branch to merge into when complete
`<desc>`	Task description OR path to existing PRD file
`options`	Common: `--flow`, `--tdd`, `--confirm/--no-confirm`, `--spec`, `--first-principles`, `--max-questions`, `--agent`

Usage Example

# Create isolated development environment (uses default agent from agents.json)
/plan-cascade:hybrid-worktree feature-auth main "Implement user authentication: login, registration, password reset"

# Create worktree with specific agent for PRD generation
/plan-cascade:hybrid-worktree feature-auth main "Implement user authentication" --agent=codex

# Generate PRD (without worktree)
/plan-cascade:hybrid-auto "Implement user authentication feature"

# View and edit PRD
/plan-cascade:edit

# Approve and auto-execute
/plan-cascade:approve --auto-run

# View execution progress
/plan-cascade:hybrid-status

# Merge to main after completion
/plan-cascade:hybrid-complete main

`/plan-cascade:hybrid-auto` Workflow

Suitable for quick development of simple features without Worktree isolation.

Command Reference

/plan-cascade:hybrid-auto <desc> [options]         # Generate PRD
/plan-cascade:approve [options]                    # Execute
/plan-cascade:edit                                 # Edit PRD
/plan-cascade:show-dependencies                    # View dependency graph

Usage Example

# Quick PRD generation
/plan-cascade:hybrid-auto "Add password reset functionality"

# Approve and auto-execute
/plan-cascade:approve --auto-run

`/plan-cascade:dashboard` - Status Monitoring

Provides an aggregated status view across all Plan Cascade executions.

What It Shows

Execution Status: Current state of mega-plan, hybrid, or direct executions
Story Progress: Completion percentage, batch progress, pending/failed stories
Recent Activity: Timeline of recent actions with timestamps
Suggested Actions: Context-aware recommendations for next steps

Usage

# Show aggregated status
/plan-cascade:dashboard

# Show verbose output with details
/plan-cascade:dashboard --verbose

Output Example

============================================================
PLAN CASCADE DASHBOARD
============================================================

Current Execution: hybrid-auto
Status: IN_PROGRESS (62%)
Flow: standard

Story Progress:
  ✓ story-001: Completed
  ✓ story-002: Completed
  → story-003: In Progress (claude-code)
  ○ story-004: Pending
  ○ story-005: Pending

Recent Activity:
  [10:30] story-002 completed via claude-code
  [10:28] story-002 started via claude-code
  [10:25] story-001 completed via claude-code

Suggested Actions:
  • Continue: Wait for story-003 to complete
  • Review: Check progress.txt for details
============================================================

DoR/DoD Gates (Definition of Ready/Done)

Plan Cascade provides validation gates to ensure quality at execution boundaries.

Definition of Ready (DoR)

DoR gates run before story/feature execution to validate prerequisites:

Check	Description	Mode
Acceptance Criteria	Verifies criteria are testable and clear	SOFT/HARD
Dependencies Valid	Ensures all dependencies are resolved	SOFT/HARD
Risks Explicit	Validates risk assessment is documented	SOFT/HARD
Verification Prompt	Checks AI verification hints are present	SOFT/HARD

Gate Modes:

SOFT: Warnings only, execution continues
HARD: Blocking, execution halts on failures (used in Full flow)

Definition of Done (DoD)

DoD gates run after story/feature execution to validate completion:

Level	Checks	When Used
STANDARD	Quality gates pass, AI verification, change summary	Default
FULL	Above + code review, test changes, deployment notes	Full flow

DoD Checks:

Quality gates (typecheck, test, lint) passed
No skeleton code detected
Acceptance criteria verified
Change summary generated
Code review passed (Full level)

Gate Configuration in PRD

{
  "flow_config": { "level": "standard" },
  "tdd_config": { "mode": "auto" },
  "execution_config": { "require_batch_confirm": false }
}

TDD Support

Plan Cascade supports optional Test-Driven Development (TDD) rhythm at the story level.

TDD Modes

Mode	Description	When to Use
`off`	TDD disabled	Simple changes, documentation
`on`	TDD with prompts and compliance checks	Critical features, security code
`auto`	Auto-enable based on risk assessment	Most development tasks (default when `--tdd` not set)

Note: /plan-cascade:auto defaults to --tdd on in FULL flow. Use --tdd auto to opt into risk-based auto-enabling.

TDD Workflow

When TDD is enabled:

Red Phase: Write failing tests based on acceptance criteria
Green Phase: Minimal implementation to pass tests
Refactor Phase: Improve code while keeping tests green

TDD Compliance Checking

After story completion, quality gates verify:

Test files were modified alongside code changes
High-risk stories have corresponding tests
Test coverage requirements met (if configured)

Usage

# Default in /plan-cascade:auto (FULL flow): TDD is on
/plan-cascade:auto "Add user profile feature"

# Disable TDD for documentation
/plan-cascade:auto --tdd off "Update README"

# Let risk-based auto-detection decide
/plan-cascade:auto --tdd auto "Add user profile feature"

Auto Execution and Quality Gates

Plan Cascade executes stories batch-by-batch with quality gates and (optionally) automatic retries.

Full Auto Execution (Recommended)

For unattended runs (CI-friendly), use Full Auto mode from /plan-cascade:approve, or run the helper script directly:

uv run python scripts/auto-execute.py --prd prd.json --flow full --tdd on

Common script flags:

--max-retries N / --no-retry
--batch N (execute only one batch)
--parallel + --max-concurrency N
--state-file <path> (defaults to .iteration-state.json)

Quality Gate Configuration

Configure in prd.json:

{
  "quality_gates": {
    "enabled": true,
    "fail_fast": false,
    "gates": [
      {"name": "format", "type": "format", "required": false, "check_only": false},
      {"name": "typecheck", "type": "typecheck", "required": true},
      {"name": "tests", "type": "test", "required": true},
      {"name": "lint", "type": "lint", "required": false},
      {"name": "tdd", "type": "tdd_compliance", "required": false},
      {"name": "code-review", "type": "code_review", "required": false, "min_score": 0.7, "block_on_critical": true},
      {"name": "implementation_verify", "type": "implementation_verify", "required": false}
    ]
  }
}

Gate Execution Order:

PRE_VALIDATION: FORMAT (auto-format code)
VALIDATION: TYPECHECK, TEST, LINT (parallel)
POST_VALIDATION: CODE_REVIEW, IMPLEMENTATION_VERIFY (parallel)

Gate Types:

Type	Description	Options
`format`	Auto-format code	`check_only`: only check, don't modify
`typecheck`	Type checking (mypy/tsc)	-
`test`	Run tests (pytest/jest)	-
`lint`	Linting (ruff/eslint)	-
`tdd_compliance`	TDD compliance check	-
`code_review`	AI code review	`min_score`, `block_on_critical`
`implementation_verify`	AI implementation verification	-
`custom`	Custom script	`command`

Monitoring

Use /plan-cascade:dashboard (aggregated), /plan-cascade:hybrid-status, /plan-cascade:mega-status, and progress.txt.

Multi-Agent Collaboration

Supported Agents

Agent	Type	Description
`claude-code`	task-tool	Claude Code Task tool (built-in, always available)
`codex`	cli	OpenAI Codex CLI
`amp-code`	cli	Amp Code CLI
`aider`	cli	Aider AI pair programming assistant
`cursor-cli`	cli	Cursor CLI

Specifying Agents

For hybrid-auto (PRD generation):

# Use default agent (claude-code)
/plan-cascade:hybrid-auto "Implement user authentication"

# Specify agent for PRD generation
/plan-cascade:hybrid-auto "Implement user authentication" --agent=codex

For approve (story execution):

# Global agent override (all stories)
/plan-cascade:approve --agent=codex

# Phase-specific agents
/plan-cascade:approve --impl-agent=claude-code --retry-agent=aider

# Disable auto-fallback
/plan-cascade:approve --agent=codex --no-fallback

# Disable AI verification gate (enabled by default)
/plan-cascade:approve --no-verify

# Disable AI code review (enabled by default)
/plan-cascade:approve --no-review

# Specify code review agent
/plan-cascade:approve --review-agent=claude-code

For mega-approve (feature execution):

# Specify agents for different phases
/plan-cascade:mega-approve --auto-prd --prd-agent=codex --impl-agent=aider

# Global override
/plan-cascade:mega-approve --auto-prd --agent=claude-code

Specifying Agent in PRD

{
  "stories": [
    {
      "id": "story-001",
      "agent": "aider",
      "title": "Refactor data layer",
      ...
    }
  ]
}

Agent Configuration File (agents.json)

{
  "default_agent": "claude-code",
  "agents": {
    "claude-code": {"type": "task-tool"},
    "codex": {"type": "cli", "command": "codex"},
    "aider": {"type": "cli", "command": "aider"}
  },
  "phase_defaults": {
    "implementation": {
      "default_agent": "claude-code",
      "fallback_chain": ["codex", "aider"],
      "story_type_overrides": {
        "refactor": "aider",
        "bugfix": "codex"
      }
    }
  }
}

Agent Priority

1. Command parameter --agent              # Highest priority
2. Phase override --impl-agent etc.
3. Story-level agent field
4. Story type override               # bugfix -> codex, refactor -> aider
5. Phase default Agent
6. Fallback chain
7. claude-code                       # Final fallback

Complete Command Reference

Setup

/plan-cascade:init                     # Environment setup (uv/Python checks)
/plan-cascade:check-gitignore           # Ensure .gitignore entries

Auto Strategy

/plan-cascade:auto <description> [options]

Options:
  --flow <quick|standard|full>    Override execution flow depth
  --tdd <off|on|auto>             Control TDD mode
  --confirm | --no-confirm        Confirmation behavior
  --spec <off|auto|on>            Planning-time spec interview
  --first-principles              Spec: ask first-principles questions
  --max-questions N               Spec: soft cap interview length
  --explain [--json]              Show analysis without executing

Spec Interview

/plan-cascade:spec-plan "<desc>" [--compile] [--output-dir <dir>] [--flow <quick|standard|full>] [--first-principles] [--max-questions N] [--feature-slug <slug>]
/plan-cascade:spec-resume [--output-dir <dir>] [--flow <quick|standard|full>]
/plan-cascade:spec-cleanup [--output-dir <dir>] [--all]

Status Monitoring

/plan-cascade:dashboard [--verbose]

Project-Level (Mega Plan)

/plan-cascade:mega-plan <description> [options]
/plan-cascade:mega-edit
/plan-cascade:mega-approve [--auto-prd] [options]
/plan-cascade:mega-resume [--auto-prd]
/plan-cascade:mega-status
/plan-cascade:mega-complete [branch]

Feature-Level (Hybrid)

/plan-cascade:hybrid-worktree <name> <branch> <desc> [options]
/plan-cascade:hybrid-auto <desc> [options]
/plan-cascade:edit
/plan-cascade:approve [options]
/plan-cascade:show-dependencies
/plan-cascade:hybrid-status
/plan-cascade:hybrid-resume [--auto]
/plan-cascade:hybrid-manual
/plan-cascade:hybrid-complete [branch] [--force]

Design Documents

/plan-cascade:design-generate
/plan-cascade:design-import <path>
/plan-cascade:design-review

Basic Planning

/plan-cascade:start
/plan-cascade:resume
/plan-cascade:worktree <name> <branch>
/plan-cascade:complete [branch] [--force]

Status File Reference

State files may be stored in the project root (legacy mode) or under <user-dir>/.state/ (new mode).

File	Type	Description
`prd.json`	Planning	PRD document
`mega-plan.json`	Planning	Project plan
`design_doc.json`	Planning	Technical design document
`spec.json`	Planning	Structured planning spec (optional)
`spec.md`	Planning	Rendered spec generated from `spec.json` (optional)
`agents.json`	Configuration	Agent configuration
`findings.md`	Shared	Findings record
`mega-findings.md`	Shared	Project-level findings (mega-plan)
`progress.txt`	Shared	Progress log
`.mega-status.json` / `.state/.mega-status.json`	Status	Mega-plan execution status
`.agent-status.json` / `.state/agent-status.json`	Status	Agent status
`.iteration-state.json` / `.state/iteration-state.json`	Status	Iteration state
`.retry-state.json` / `.state/retry-state.json`	Status	Retry record
`.state/spec-interview.json`	Status	Spec interview resume state (optional)
`.state/stage-state.json`	Status	Stage state machine state (v4.4.0+)
`.hybrid-execution-context.md`	Context	Hybrid task context for AI recovery
`.mega-execution-context.md`	Context	Mega-plan context for AI recovery
`.agent-outputs/`	Output	Agent logs

Troubleshooting

Agent Unavailable

[AgentExecutor] Agent 'codex' unavailable (CLI 'codex' not found in PATH)

Solution: Install the corresponding Agent or use --no-fallback to disable fallback.

Quality Gate Failure

[QualityGate] typecheck failed: error TS2304

Solution: Fix type errors and retry, or disable that gate in prd.json.

Worktree Conflict

fatal: 'feature-xxx' is already checked out

Solution: Use /plan-cascade:hybrid-complete to clean up existing worktree.

Interrupted Execution

If a mega-plan or hybrid task was interrupted (e.g., connection lost, Claude Code crashed):

# For mega-plan
/plan-cascade:mega-resume --auto-prd

# For hybrid task
/plan-cascade:hybrid-resume --auto

These commands will:

Auto-detect current state from existing files
Skip already-completed work
Resume from where execution stopped
Support both old and new progress marker formats

Context Recovery After Long Sessions

Plan Cascade automatically generates context files that help recover execution state after:

Context compression (AI summarizes old messages)
Context truncation (old messages deleted)
New conversation session
Claude Code restart

Context files generated:

File	Mode	Description
`.hybrid-execution-context.md`	Hybrid	Current batch, pending stories, progress summary
`.mega-execution-context.md`	Mega Plan	Active worktrees, parallel execution state

These files are automatically updated via hooks during execution. If you notice the AI has lost context:

# Universal recovery command (auto-detects mode)
/plan-cascade:resume

# Or check the context file directly
cat .hybrid-execution-context.md
cat .mega-execution-context.md