convez.ai
AgenteProdutividadeAvançado
shihwesley

Interactive Planning

shihwesley/interactive-planning

Planejamento estruturado com DAG de dependências e gates interativas

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent que transforma tarefas complexas em planos estruturados antes da implementação, com suporte a dois modos: task-based para features diretas e spec-driven para trabalhos multi-domínio com rastreamento de dependências. Gera artefatos de workflow (plano, handoff, log de progresso) e suporta gates interativas para controle de execução.

Instalação

$npx convez-ai shihwesley/interactive-planning

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 8 meses
Versão
v5.1.0
Issues abertas
0
Contribuidores
2

Casos de uso

  • Quebrar projetos complexos em fases executáveis com rastreamento de progresso
  • Coordenar trabalho multi-domínio com detecção automática de dependências
  • Executar planos com retry automático, gates manuais e validação de handoff entre fases

Veredito

Agent robusto para planejamento estruturado em projetos complexos, com padrão de workflow contract inspirado em sistemas enterprise (OpenAI Symphony). Excelente para coordenar múltiplas fases de execução com rastreamento e retry, mas requer disciplina na escrita de especificações.

README

A tradução para o português deste README ainda está na fila.

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:

FileLocationPurpose
workflow.mdPlan directoryDeclarative execution config: retry behavior, between-phase gates, Liquid-style prompt templates
handoff.md.claude/handoff.mdFixed-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.mdAppend-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:

CategoryTriggers on
featNew functionality (default)
fixBugs, crashes, errors
refactorRestructuring, migrations
reviewAudits, evaluations
testTest strategy, coverage
polishUI/UX, performance, accessibility
generalWhole-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:

DimensionWhat it catches
System design & boundariesResponsibility leaks, shotgun surgery
Dependency graph & couplingCascading changes, circular deps
Data flow & bottlenecksHot paths, unnecessary copies
Scaling & SPOFsWhat breaks at 10x/100x
Security architectureAuth gaps, leaky API surfaces
Error handling & failure modesRecovery vs crash, graceful degradation
TestabilityHidden runtime deps, isolation problems
Existing codebase fitPattern 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:

  1. Mode + Priority — task-based or spec-driven? Speed or quality? (shows detected category/name)
  2. Requirements — validates inferred requirements against your intent
  3. Approach — presents tradeoffs, you pick (or spec decomposition in spec-driven mode)
  4. Validation — shows the full plan with tasks, you approve or adjust
  5. 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

ComponentFilePurpose
Skillskills/interactive-planning/SKILL.mdCore planning methodology
Templatesskills/interactive-planning/templates/Manifest, spec, workflow, handoff, progress-log templates
Commandcommands/interactive-planning.md/interactive-planning with subcommands
Agentagents/planning-advisor.mdAuto-detect complex tasks
Hookhooks/hooks.jsonSessionStart 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

Ver o original no GitHub

Bom para

Relacionados