Ultra Planning & Execution System — Quickstart
Quick reference for the autonomous planning and execution system.
For the full playbook, see: claude-code-slash-commands-playbook.md
3 Commands to Know
| Command | What It Does | Example |
|---|---|---|
/ultra-plan | Deep plan with multiple review cycles | /ultra-plan MAT-123 or /ultra-plan "Add user auth" |
/ultra-execute | Execute an approved plan | /ultra-execute .ultra-plans/user-auth-PLAN.md |
/ultra-auto | Full pipeline: plan + execute, walk away | /ultra-auto MAT-123 |
When to Use Ultra vs Lighter Options
| Situation | Command | Why |
|---|---|---|
| Simple task (< 15 min) | Just do it | No planning overhead |
| Medium task (15-60 min) | /deep-plan | Single review cycle, lighter weight |
| Complex task (1+ hours) | /ultra-plan | Multiple review cycles, Sonnet-executable output |
| Drop ticket and walk away | /ultra-auto | Full autonomous pipeline |
| Matchkeyz-specific work | /a-planning-start | Has Linear/test integration |
What Happens When You Run /ultra-auto
1. [INPUT] Parse your ticket/spec/description
2. [CLARIFY] Ask questions if requirements are ambiguous
3. [RESEARCH] Research codebase for existing code to reuse
4. [PLAN] Write detailed plan with XML task specs
5. [REVIEW] Adversarial review (15-point rubric)
6. [REVISE] Fix issues from review
7. [REVIEW] Second independent review
8. [VALIDATE] 5 Whys, trigger words, assumption verification
9. [BUILD] Execute plan wave-by-wave
10. [TEST] Run tests + code review IN PARALLEL
11. [GATE] Pass/fail decision matrix
12. [VERIFY] Evidence-based completion check
13. [DONE] Present results
Pauses for: Ambiguous requirements, architectural decisions, auth gates, persistent failures. Auto-handles: Bug fixes, missing features, blocking issues, review cycles.
The Agents Behind the System
Planning (Opus — makes decisions):
- ultra-planner — Writes plans with XML task specs
- ultra-plan-reviewer — 15-point adversarial review
Execution (Sonnet — follows instructions):
- ultra-executor — Implements plan tasks
- ultra-test-runner — Runs tests, detects regressions
- ultra-code-reviewer — 6-dimension code review
Verification (Opus — demands proof):
- ultra-completion-gate — Verifies every requirement with evidence
Where State Is Stored
All state lives in .ultra-plans/ in your project root:
| File | Purpose |
|---|---|
{slug}-PLAN.md | The plan document with XML tasks |
{slug}-STATE.md | Planning progress (which phase, review history) |
{slug}-RESEARCH.md | Research findings (DRY analysis, patterns) |
{slug}-EXEC-STATE.md | Execution progress (which wave, test results) |
Session interrupted? Just run the same command again — it resumes from where it left off.
Deploy
All ultra-* files live in c:/_my/claude-code-config/. Deploy to active Claude Code:
cd c:/_my/claude-code-config
python deploy.py # Deploy everything
python deploy.py --dry-run # Preview firstPro Tips
- Token-heavy by design — Ultra uses Opus for all planning/review. Budget accordingly.
- Plans are Sonnet-executable — Every task has concrete values, file paths, acceptance criteria. No interpretation needed.
- Max 3 review cycles — If plan can’t pass review in 3 tries, it escalates to you.
- Wave-based execution — Independent tasks run in parallel, dependent tasks run sequentially.
- GSD compatible — If
.planning/directory exists, Ultra syncs state to it.
Troubleshooting
| Problem | Fix |
|---|---|
/ultra-plan not found | Run python deploy.py in claude-code-config |
| Plan stuck in review loop | Check reviewer issues — may need to simplify scope |
| Executor blocked | Check deviation log — Rule 4 (architectural) needs your input |
| Tests failing after execution | Check regression list in EXEC-STATE.md |
| Session lost mid-plan | Re-run same command — auto-resumes from STATE.md |