Transform complex tasks into structured plans with interactive gates and multi-domain support.

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.

What's new in v5.1.0
What's new in v5.0.0
How it works
Install
Usage
Planning modes
Plan categories
What's in the box
Key concepts
Gate flow

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

Every finding includes concrete tradeoffs, an opinionated recommendation, and a user input gate before assuming direction.

How it works

You: "Add a notification system with email, push, and in-app"

Auto-detected: feat/notification-system

Claude asks:                          You answer:
  What kind of planning? ---------> Spec-driven
  Which priority? ----------------> Speed
  These requirements right? ------> [picks 3, adds 1]
  This spec breakdown ok? --------> Looks good

Claude creates:
  docs/plans/feat/notification-system/
    manifest.md                     <- dependency graph, phase/sprint map
    specs/email-spec.md             <- requirements, tasks, acceptance criteria
    specs/push-spec.md
    specs/inapp-spec.md
    findings.md                     <- decisions, research
    progress.md                     <- session log, reboot check
    workflow.md                     <- execution contract for /orchestrate
  .claude/
    handoff.md                      <- inter-agent communication (fixed-size)
    progress-log.md                 <- append-only session history
  + TaskCreate entries with blocking dependencies wired up

Then you build phase by phase, with checkpoints at every transition.

Install

/plugin marketplace add shihwesley/shihwesley-plugins
/plugin install interactive-planning@shihwesley-plugins

Usage

Start planning

/interactive-planning

Auto-detects category and name from your request, then walks you through interactive gates:

Mode + Priority — task-based or spec-driven? Speed or quality? (shows detected category/name)
Requirements — validates inferred requirements against your intent
Approach — presents tradeoffs, you pick (or spec decomposition in spec-driven mode)
Validation — shows the full plan with tasks, you approve or adjust
Architecture Review — 8-dimension review before any code gets written

Check status

/interactive-planning status                  # all plans
/interactive-planning status feat/auth        # specific plan

Shows current phase, completed tasks, and what's next. With multiple plans, displays a summary table.

Resume a session

/interactive-planning resume                  # single plan or pick from list
/interactive-planning resume feat/auth        # specific plan

Picks up where you left off. Reads planning files, checks git diff, finds the next unblocked task.

List all plans

/interactive-planning list

Table of all active plans with mode, category, and status.

Reset

/interactive-planning reset                   # pick which to reset
/interactive-planning reset feat/auth         # specific plan

Removes plan directory (with confirmation). Asks if you want to keep findings.md.

Auto-detection

The planning-advisor agent watches for complex tasks (3+ files, ambiguous requirements, cross-cutting concerns) and suggests planning with a likely category. It never auto-starts — just a nudge.

A SessionStart hook scans for existing plans across all categories and alerts you if sessions are in progress.

Planning modes

Task-based

Creates task_plan.md, findings.md, progress.md in the plan directory (docs/plans/{category}/{name}/). Phases are sequential with TaskCreate blocking dependencies.

Good for: single features, bug investigations, refactors with clear scope.

Spec-driven

Creates manifest.md with a dependency DAG (Mermaid) and individual spec files in specs/. Each spec has requirements, acceptance criteria, tasks, and dependency declarations.

Phases and sprints are auto-computed via topological sort. Two-level task tracking: spec-level parents with sub-tasks, intra-spec sequential blocking, and inter-spec handoff rules.

Good for: multi-domain features, large refactors, anything where separate concerns need their own requirements documents.

Plan categories

Plans are organized as docs/plans/{category}/{name}/:

docs/plans/
  feat/auth-system/         # new feature
    manifest.md
    specs/
    findings.md
    progress.md
    workflow.md               # execution contract (v5.1+)
  fix/login-crash/          # bug fix
    task_plan.md
    findings.md
    progress.md
    workflow.md
  general/app-architecture/ # whole-app planning
    manifest.md
    specs/
    findings.md
    progress.md
    workflow.md

Category is auto-detected from your request. Override anytime via "Other" at Gate 1.

Each plan is self-contained — findings.md and progress.md live inside the plan directory, not at project root. This means you can have a general architecture plan and a feature plan running side by side.

/orchestrate targets any plan directory directly: /orchestrate docs/plans/feat/auth-system.

What's in the box

Component	File	Purpose
Skill	`skills/interactive-planning/SKILL.md`	Core planning methodology
Templates	`skills/interactive-planning/templates/`	Manifest, spec, workflow, handoff, progress-log templates
Command	`commands/interactive-planning.md`	`/interactive-planning` with subcommands
Agent	`agents/planning-advisor.md`	Auto-detect complex tasks
Hook	`hooks/hooks.json`	SessionStart plan detection

Key concepts

Gates before tasks — Every decision goes through an AskUserQuestion gate. No assumptions.

Tasks before code — All phases exist as TaskCreate entries before any implementation starts.

Review before code — Gate 5 (Architecture Review) runs after plan validation. No implementation until the architecture clears review.

Auto-detect, don't ask — Category and plan name are inferred from your request. No extra gate question.

Plans are isolated — Each plan lives in its own directory. Multiple plans coexist without conflict.

2-Action Rule — After every 2 search/browse operations, write findings to findings.md immediately.

3-Strike Protocol — Three attempts at a failing approach, then escalate to the user.

Dependency DAG (spec-driven) — Specs declare what they need from upstream and what they provide downstream. Sprint grouping is computed automatically.

Gate flow

flowchart TD
    A[User request] --> A1[Phase 0.5: Auto-detect category + name]
    A1 --> B{Gate 1: Mode + Priority}
    B --> C{Gate 2: Requirements}
    C --> D{Task-based?}
    D -->|Yes| E{Gate 3: Approach}
    D -->|No| F{Gate 3: Spec Decomposition}
    E --> G["Create {PLAN_DIR}/task_plan.md + findings.md + progress.md"]
    F --> H["Create {PLAN_DIR}/manifest.md + spec files + findings.md"]
    G --> I{Gate 4: Validate plan}
    H --> I
    I -->|Adjust| B
    I -->|Approved| P{Gate 5: Architecture Review}
    P -->|Approve| J[Execute with checkpoints]
    P -->|Revise| I
    P -->|Dig deeper| P
    J --> K{Phase complete?}
    K -->|Yes| L{More phases?}
    K -->|Stuck| M[3-Strike Protocol]
    L -->|Yes| J
    L -->|No| N[Done]
    M --> J

License

MIT

interactive-planning

interactive-planning

Contents

What's new in v5.1.0

Previous: v5.0.0

What's new in v5.0.0

Previous: v4.2.0

How it works

Install

Usage

Start planning

Check status

Resume a session

List all plans

Reset

Auto-detection

Planning modes

Task-based

Spec-driven

Plan categories

What's in the box

Key concepts

Gate flow

License