interactive-planning
A Claude Code plugin that turns complex tasks into structured plans before you write a line of code.
Two modes: task-based for straightforward features, spec-driven for multi-domain work with dependency tracking. Plans are categorized by type and stored in separate directories so multiple plans can coexist.
Contents
What's new in v5.1.0
Workflow contract — planning now generates three additional files that bridge /interactive-planning and /orchestrate:
| File | Location | Purpose |
|---|
workflow.md | Plan directory | Declarative execution config: retry behavior, between-phase gates, Liquid-style prompt templates |
handoff.md | .claude/handoff.md | Fixed-size file (~100-150 lines) that each phase agent reads on start and overwrites on finish. The only communication channel between sequential phase runners. |
progress-log.md | .claude/progress-log.md | Append-only session history. Newest-first entries for human review. Phase agents never read this. |
Inspired by OpenAI's Symphony workflow contract pattern. The key idea: separate what the agent does (plan phases) from how phases get executed (retry, gates, prompts).
Gate 1 now asks project type (greenfield / brownfield / prototype). This feeds into workflow.md so phase agents know the development context.
Prompt templates — workflow.md includes a ## Phase Prompt and ## Continuation Prompt section with {{ variable }} placeholders. The orchestrator renders these per-phase, so each agent gets a tailored prompt with prior phase summaries, acceptance criteria, and workspace paths.
Continuation retries — when a phase fails, the orchestrator auto-retries with a continuation prompt that tells the agent "this is attempt #N, don't restart from scratch." Configurable via execution.max_phase_retries in workflow.md.
Between-phase gates — choose auto (proceed without asking), manual (confirm before each phase), or review (show diff summary then confirm). Set via execution.gates.between_phases in workflow.md.
Progress enforcement — strict mode validates that handoff.md was actually updated before a phase reports completion. Catches the stale-progress-file problem where code changes land but the tracking file doesn't get updated.
All changes are backward compatible. Existing plans without workflow.md work exactly as before.
Previous: v5.0.0
What's new in v5.0.0
Categorized plan directories — plans now live in docs/plans/{category}/{name}/ instead of a flat docs/plans/. Multiple planning sessions coexist without overwriting each other.
7 categories, auto-detected from your request:
| Category | Triggers on |
|---|
feat | New functionality (default) |
fix | Bugs, crashes, errors |
refactor | Restructuring, migrations |
review | Audits, evaluations |
test | Test strategy, coverage |
polish | UI/UX, performance, accessibility |
general | Whole-app architecture |
No extra gate question — the category is inferred from what you ask for. You can override via "Other" at Gate 1.
You: "Plan the authentication system"
→ Auto-detected: feat/auth-system
→ Directory: docs/plans/feat/auth-system/
You: "Fix the login crash on iOS 18"
→ Auto-detected: fix/login-crash-ios18
→ Directory: docs/plans/fix/login-crash-ios18/
Commands now target specific plans:
/interactive-planning resume feat/auth-system
/interactive-planning status fix/login-crash
/interactive-planning list
/orchestrate docs/plans/feat/auth-system works with zero config — the plan ingester finds manifest.md or task_plan.md in whatever directory you point it at.
Legacy plans (flat docs/plans/ or root-level files) are still detected and resumable.
Previous: v4.2.0
Gate 5: Architecture Review — a mandatory review step between plan validation and execution. Before any code gets written, the plan is evaluated across 8 dimensions:
| Dimension | What it catches |
|---|
| System design & boundaries | Responsibility leaks, shotgun surgery |
| Dependency graph & coupling | Cascading changes, circular deps |
| Data flow & bottlenecks | Hot paths, unnecessary copies |
| Scaling & SPOFs | What breaks at 10x/100x |
| Security architecture | Auth gaps, leaky API surfaces |
| Error handling & failure modes | Recovery vs crash, graceful degradation |
| Testability | Hidden runtime deps, isolation problems |
| Existing codebase fit | Pattern conflicts, maintenance tax |
shihwesley
