plan-cascade
AI-powered cascading development framework with design document system and multi-agent collaboration. Breaks down projects into Features (Mega Plan), Features into Stories (Hybrid Ralph), with auto-generated technical design docs, dependency-driven batch execution, Git Worktree isolation, and support for multiple AI agents (Codex, Amp, Aider, etc.).
pinned to #5223f82updated 2 weeks ago
Ask your AI client: “install plugins/plan-cascade”.
Requires the metahub MCP server installed in your client. Set up MCP.
mh install plugins/plan-cascademetahub onboarded this repo on the author's behalf.
If you own github.com/Taoidle/plan-cascade on GitHub, claim the listing to take over publishing. Your claim preserves the existing eval history and badges; only the curator label is replaced with verified-publisher on your next publish.
Stars
103
Last commit
2 weeks ago
Latest release
published
- #claude-code
- #claude-code-plugin
- #developer-tools
- #llm-agents
- #mcp-server
- #multi-agent
- #task-orchestration
- #workflow-automation
What's bundled
Items extracted from this plugin's manifest + directory tree.
Skills (3)
skills/hybrid-ralphHybrid architecture combining Ralph's PRD format with Planning-with-Files' structured approach. Auto-generates PRDs from task descriptions, manages parallel story execution with dependency resoluti…skills/mega-planProject-level multi-task orchestration system. Manages multiple hybrid:worktree features in parallel with dependency resolution, coordinated PRD generation, and unified merge workflow.skills/planning-with-filesImplements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requirin…
Commands (8)
/approveYou are approving the PRD and starting parallel execution of user stories./autoAI automatically analyzes the task and executes the optimal strategy without user confirmation./check-gitignoreThis command checks if your project's `.gitignore` is configured to exclude Plan Cascade temporary files, and updates it if needed./completeYou are now completing a worktree task. This will:/dashboardDisplay execution status for the current Plan Cascade task./design-generateGenerate a structured technical design document (`design_doc.json`). Auto-detects the appropriate level based on available files./design-importImport an external design document and convert it to the unified `design_doc.json` format used by Plan Cascade./design-reviewReview the current `design_doc.json` and make interactive edits to components, patterns, architectural decisions, and story mappings.
Evaluation report
WarningsAutomated checks the publisher passed at publish time — structure, docs, safety, and whether the artifact behaves as claimed.5223f82· 2 weeks ago
Maintenance
21Recent activitywarn
last push 4 months ago — looks slowing down
Consumers prefer artifacts that are actively maintained (threshold: 90 days, configurable via EVAL_RECENCY_PASS_DAYS).
Tests detected
10 test directories · 152 test files
CI configuration detected
GitHub Actions (3 workflows)
Release history
1- releasecurrent5223f82warn2 weeks ago
Contents
Why Plan Cascade?
Traditional AI coding assistants hit a wall with large, complex projects:
| Challenge | Conventional AI | Plan Cascade |
|---|---|---|
| Complexity | Gets lost in large codebases | Decomposes into manageable units |
| Parallelism | Sequential, one-at-a-time | Independent tasks run in parallel |
| Context | Lost during long sessions | Design docs + durable context survive compaction |
| Quality | Manual verification needed | Automated testing & linting at each step |
| Control | Black box execution | Transparent, inspectable workflow |
The Solution: Cascading Decomposition
┌─────────────────────────────────────────────────────────────────────┐
│ Your Project Goal │
│ "Build a REST API with authentication" │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Level 1: Mega Plan │
│ ───────────────────── │
│ Project-level orchestration → Manages multiple features in batches │
│ Output: mega-plan.json + design_doc.json │
└─────────────────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ Feature: Auth │ │ Feature: API │ │ Feature: Database │
│ ─────────────── │ │ ─────────────── │ │ ─────────────── │
│ PRD + Design Doc │ │ PRD + Design Doc │ │ PRD + Design Doc │
└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ Stories (Parallel) │ │ Stories (Parallel) │ │ Stories (Parallel) │
│ ───────────────── │ │ ───────────────── │ │ ───────────────── │
│ □ JWT Implementation│ │ □ CRUD Endpoints │ │ □ Schema Design │
│ □ Password Hashing │ │ □ Rate Limiting │ │ □ Migrations │
│ □ Session Management│ │ □ Input Validation │ │ □ Connection Pool │
└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
│
▼
┌─────────────────┐
│ Quality Gates │
│ ───────────── │
│ ✓ DoR / DoD │
│ ✓ Test Coverage │
│ ✓ Lint / Format │
└─────────────────┘
Product Editions
Plan Cascade is available in three editions to suit different workflows:
| Feature | Plugin | Desktop | CLI |
|---|---|---|---|
| Target User | Claude Code users | Multi-model teams | Automation/CI |
| LLM Backend | Claude Code only | 7+ providers (Claude, OpenAI, DeepSeek, Ollama...) | 7+ providers |
| Offline Use | ❌ | ✅ (Ollama) | ✅ (Ollama) |
| Installation | claude plugins install | Desktop app / pip install | pip install |
| UI | Slash commands | Full GUI with 4 workflow modes | Command-line |
| Quality Gates | ✅ Standard | ✅ Enterprise-grade with auto-retry | ✅ |
| Security Model | Basic | 5-layer (Guardrail → Gate → Policy → Sandbox → Audit) | Basic |
| Worktree Integration | ✅ | ✅ Visual diff viewer | ✅ |
| Visual Workflow | ❌ | ✅ Real-time timeline + checkpoints | ❌ |
| MCP Stack | Client only | Full stack (Manager + Client + Server) | Client only |
| Knowledge System | ❌ | ✅ Skills + Memory + RAG | ❌ |
| Remote Control | ❌ | ✅ A2A protocol + Telegram bot | ❌ |
| Maturity | Stable | Alpha | Development |
Which Edition Should I Choose?
- Choose Plugin if you're a Claude Code power user who wants seamless integration
- Choose Desktop if you need multi-model support, visual workflows, or offline capability
- Choose CLI if you're building automation pipelines or CI/CD integration
Core Capabilities
Unified Workflow Kernel
All modes share a common foundation:
- Unified lifecycle — Consistent state management across modes
- Event streaming — Real-time progress updates via typed events
- Mode handoff — Seamless switching between Chat → Plan → Task
- Checkpointing — Recovery from interruptions
Quality Gates Pipeline
Every Story passes through validation:
┌─────────┐ ┌─────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐
│ DoR │ → │ Code │ → │ DoD │ → │ AI Verify │ → │ Review │
│ (Ready) │ │ (Write) │ │ (Done) │ │ (No Stubs) │ │ (Score) │
└─────────┘ └─────────┘ └─────────────┘ └─────────────┘ └─────────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
Validate Implement Verify all Detect stub Code quality
requirements solution criteria code & TODOs scoring
Design Document Hierarchy
Two-level architecture ensures consistency:
- Project-level — Global patterns, shared decisions (ADR-001, ADR-002...)
- Feature-level — Component-specific decisions (ADR-F001, ADR-F002...)
External Framework Skills
Auto-injected best practices from Git submodules:
- React/Next.js — detected via
package.json - Vue/Nuxt — detected via
package.json - Rust — detected via
Cargo.toml
Architecture
┌────────────────────────────────────────────────────────────────────────────┐
│ Plan Cascade Core │
├────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Strategy │ │ PRD │ │ Parallel │ │ Quality │ │
│ │ Selector │ │ Generator │ │ Executor │ │ Gates │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
├────────────────────────────────────────────────────────────────────────────┤
│ Agent Backend Layer │
│ ┌────────────────────────────┐ ┌────────────────────────────┐ │
│ │ ClaudeCodeBackend │ │ BuiltinBackend │ │
│ │ (subprocess, no API) │ │ (direct API, ReAct loop) │ │
│ └────────────────────────────┘ └────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────────┤
│ LLM Provider Layer │
│ Anthropic │ OpenAI │ DeepSeek │ Ollama │ GLM │ Qwen │ MiniMax │
└────────────────────────────────────────────────────────────────────────────┘
Quick Start
Plugin (Stable)
# Install in Claude Code
claude plugins install plan-cascade
# Use slash commands
/plan-cascade:auto "Implement user authentication"
CLI (Development)
# Requires Python 3.10+ and uv
git clone https://github.com/Taoidle/plan-cascade.git
cd plan-cascade
uv run pytest tests/ # Run tests
# CLI entry point
uv run plan-cascade --help
Desktop (Alpha)
See desktop/README.md for the full-featured desktop application.
Documentation
| Document | Description |
|---|---|
| Plugin Guide | Claude Code plugin usage |
| CLI Guide | Command-line interface |
| Mega Plan Guide | Multi-feature orchestration |
| Desktop README | Desktop application |
| PRD Template | PRD file format |
Project Structure
plan-cascade/
├── src/plan_cascade/ # Core Python library
│ ├── core/ # Orchestration engines
│ ├── backends/ # Agent abstraction layer
│ ├── state/ # Thread-safe state management
│ ├── llm/ # LLM provider abstraction
│ └── tools/ # ReAct tool implementations
├── desktop/ # Tauri desktop application
│ ├── src/ # React frontend
│ └── src-tauri/ # Rust backend
├── skills/ # Plugin skills
│ ├── hybrid-ralph/ # PRD-driven execution
│ ├── mega-plan/ # Multi-feature orchestration
│ └── planning-with-files/ # File-based planning
├── commands/ # Slash command definitions
└── mcp_server/ # FastMCP server
Roadmap
| Component | Current | Next Milestone |
|---|---|---|
| Plugin | 4.4.0 Stable | 5.0.0 - Enhanced CLI integration |
| Desktop | 0.1.0 Alpha | 0.2.0 - Beta with full workflow |
| CLI | Development | 1.0.0 - Stable release |
| MCP Server | Stable | Enhanced tool support |
Contributing
We welcome contributions! Please see our contributing guidelines for details.
License
MIT License - see LICENSE for details.
Reviews
No reviews yet. Be the first.
Related
superloopy
Lightweight loop harness with strict evidence gates — Claude Code edition.
cc10x
The Loop Engine — harness and loop engineering plugin for Claude Code. Router-kernel orchestration, workflow artifacts, sub-agent delegation, hook enforcement, Test Honesty Gates, fresh-context verification, and memory that persists. 73% leaner than v11, zero quality regression.
espalier-engineering
Train your AI coders the way you'd train a vine — discover your codebase's actual patterns, then encode them as rules, skills, agents, hooks, and a guided pipeline so generated code lands inside your conventions on the first try, not the fifth
mh install plugins/plan-cascade