interactive-planning

Interactive Planning (Manus + AskUserQuestion)

Combines file-based persistence (Manus-style) with interactive clarification gates.

Core Philosophy

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
Task Tools = Structured progress (visible, stateful)
AskUserQuestion = User alignment (prevents rework)

→ Tasks for actions (TaskCreate/Update)
→ Files for knowledge (findings.md)
→ Ask users before committing to approaches

---

Phase 0: Session Recovery

Before anything else, check for unsynced context:

python3 ~/.claude/skills/planning-with-files/scripts/session-catchup.py "$(pwd)"

If catchup shows unsynced context:

1. git diff --stat to see code changes
2. Read existing planning files
3. Update files based on context
4. Then proceed

---

Phase 1: Interactive Requirements Gathering

Gate 1: Planning Mode + Priority

Use AskUserQuestion BEFORE creating any files. Two questions:

Question 1: Planning Mode

AskUserQuestion(
  question="What kind of planning does this need?",
  header="Mode",
  options=[
    {"label": "Task-based (Recommended)", "description": "Single task_plan.md with phases. Best for straightforward features."},
    {"label": "Spec-driven", "description": "Multiple spec files per concern, manifest index. Best for complex multi-domain work."}
  ]
)

If "Task-based" → continue with existing flow (Gates 2-4 unchanged). If "Spec-driven" → continue with Gates 2, 3 (enhanced), 4 (enhanced) below.

Question 2: Priority (asked regardless of mode)

AskUserQuestion(
  question="Which aspect is most important?",
  header="Priority",
  options=[
    {"label": "Speed (Recommended)", "description": "MVP approach, ship fast, iterate later"},
    {"label": "Quality", "description": "Tests, docs, edge cases, production-ready"},
    {"label": "Flexibility", "description": "Extensible, configurable, multiple use cases"},
    {"label": "Simplicity", "description": "Minimal, focused, easy to understand"}
  ]
)

Gate 2: Requirements Validation

AskUserQuestion(
  question="I identified these requirements. Select all that apply:",
  header="Requirements",
  multiSelect=True,
  options=[
    {"label": "[Inferred req 1]", "description": "..."},
    {"label": "[Inferred req 2]", "description": "..."},
    {"label": "[Inferred req 3]", "description": "..."},
    {"label": "Add more", "description": "I'll provide additional requirements"}
  ]
)

Gate 3: Approach Decision (if multiple valid approaches)

AskUserQuestion(
  question="There are a few ways to approach this:",
  header="Approach",
  options=[
    {"label": "Approach A", "description": "Tradeoffs: faster but less flexible"},
    {"label": "Approach B", "description": "Tradeoffs: more setup but scalable"},
    {"label": "Approach C", "description": "Tradeoffs: full control, more work"}
  ]
)

Gate 3 (Spec-Driven): Approach + Spec Decomposition

If spec-driven mode was selected in Gate 1, replace Gate 3 above with this combined gate.

The agent:

1. Analyzes requirements from Gate 2
2. Proposes an architectural approach
3. Decomposes into spec files with dependency relationships
4. Auto-computes sprint/phase grouping via topological sort of dependency DAG
5. Presents everything together for user validation

Present to user:

Based on your requirements, here's the approach and spec breakdown:

**Approach:** {description of chosen approach with rationale}

**Spec Decomposition:**
- root-spec.md — {description} (parent of all)
  ├── {name}-spec.md — {description}
  ├── {name}-spec.md — {description} (depends on: {dep})
  └── {name}-spec.md — {description} (depends on: {dep})

**Auto-computed grouping:**
Phase 1, Sprint 1: root-spec, {independent specs}
Phase 1, Sprint 2: {specs depending on sprint 1}
Phase 2, Sprint 1: {specs depending on phase 1}

AskUserQuestion(
  question="Does this spec breakdown look right?",
  header="Specs",
  options=[
    {"label": "Looks good", "description": "Proceed with this decomposition"},
    {"label": "Adjust specs", "description": "I want to add, remove, or restructure specs"},
    {"label": "Too granular", "description": "Merge some specs together — fewer, larger specs"},
    {"label": "Not granular enough", "description": "Split some specs further"}
  ]
)

Sprint/Phase auto-assignment algorithm:

1. Topological sort of spec dependency DAG
2. Specs with no unmet dependencies → same sprint
3. Specs whose deps are all in earlier sprints → next sprint
4. Sprint groups → phases (one phase per dependency "level")
5. User can override at Gate 4

---

Phase 2: Create Tasks and Files

After gates pass, create tasks for phases and files for research:

Phase 2 (Spec-Driven): Create Manifest + Spec Files

If spec-driven mode was selected in Gate 1, replace the task_plan.md creation below with this path.

Step 1: Create specs/ directory

mkdir -p docs/plans/specs

Step 2: Generate manifest.md

Use template from ~/.claude/skills/orchestrator/templates/manifest-template.md. Fill in:

• Project name, date, mode ("spec-driven"), priority from Gate 1
• Dependency graph (Mermaid) from Gate 3 decomposition
• Phase/Sprint/Spec map from auto-assignment
• Spec files table with paths and approximate line counts

Write to: docs/plans/manifest.md

Step 3: Generate individual spec files

For each spec identified in Gate 3, use template from ~/.claude/skills/orchestrator/templates/spec-template.md. Fill in:

• YAML frontmatter: name, phase, sprint, parent, depends_on, status=draft, created date
• Requirements: distribute Gate 2 requirements to relevant specs
• Acceptance criteria: derive testable criteria from requirements
• Technical approach: from Gate 3
• Files: infer from CODEBASE_MAP or project structure
• Tasks: derive 2-5 tasks per spec from requirements
• Dependencies: what it needs from upstream specs, what it provides downstream

Write each to: docs/plans/specs/{name}-spec.md

Step 4: Create findings.md (spec-driven enhanced)

Use the spec-driven findings.md template below (not the task-based version). The extra sections give /orchestrate the dependency graph and per-spec decision traceability it needs for skill-matching and agent dispatch.

Step 5: Create progress.md (spec-driven enhanced)

Use the spec-driven progress.md template below (not the task-based version). The Spec Status table is the primary resume signal for /orchestrate --resume.

Step 6: Create two-level TaskCreate entries

Create tasks at two levels: spec tasks (parents) and sub-tasks (from the spec's ## Tasks section). This gives /orchestrate granular dispatch — it can assign individual sub-tasks to agents and track completion within each spec.

Level 1 — Spec tasks (inter-spec blocking via DAG):

# Create one parent task per spec
TaskCreate(
  subject="Spec: {spec-name}",
  description="Implement docs/plans/specs/{spec-name}-spec.md\nPhase {N}, Sprint {M}\nDepends on: {deps}\n\nThis is a parent task. Sub-tasks below do the actual work.",
  activeForm="Implementing {spec-name}"
)
# Returns task ID, e.g. "1"

# Wire inter-spec dependencies from the DAG
# If api-spec depends on data-model-spec:
TaskUpdate(taskId="{api-spec-task}", addBlockedBy=["{data-model-spec-task}"])

Level 2 — Sub-tasks (intra-spec blocking, sequential within each spec):

For each task listed in the spec's ## Tasks section, create a sub-task that references its parent spec and is blocked by the previous sub-task:

# Spec: data-model has 3 tasks in its ## Tasks section:

# Sub-task 1 — blocked by the parent spec's upstream dependencies (inherits)
TaskCreate(
  subject="data-model: Create database schema",
  description="Spec: data-model (Phase 1, Sprint 1)\nParent task: #{spec_task_id}\nFile targets: {from spec ## Files table}",
  activeForm="Creating database schema"
)
# Returns e.g. "1a"
TaskUpdate(taskId="1a", addBlockedBy=["{upstream_spec_last_subtask or spec_blockers}"])

# Sub-task 2 — blocked by sub-task 1
TaskCreate(
  subject="data-model: Write migration",
  description="Spec: data-model (Phase 1, Sprint 1)\nParent task: #{spec_task_id}",
  activeForm="Writing migration"
)
# Returns e.g. "1b"
TaskUpdate(taskId="1b", addBlockedBy=["1a"])

# Sub-task 3 — blocked by sub-task 2
TaskCreate(
  subject="data-model: Add seed data",
  description="Spec: data-model (Phase 1, Sprint 1)\nParent task: #{spec_task_id}",
  activeForm="Adding seed data"
)
# Returns e.g. "1c"
TaskUpdate(taskId="1c", addBlockedBy=["1b"])

Inter-spec handoff rule: A downstream spec's first sub-task is blocked by the upstream spec's last sub-task (not the parent). This prevents the downstream spec from starting before the upstream spec's work is actually finished:

# api-spec depends on data-model. data-model's last sub-task is "1c".
# api-spec's first sub-task:
TaskCreate(subject="api-layer: Define route handlers", ...)
TaskUpdate(taskId="{api_first_subtask}", addBlockedBy=["1c"])
# NOT addBlockedBy: ["1"] — the parent task is a grouping label, not a gate.

Naming convention: Sub-task subjects are prefixed with their spec name (data-model: Create schema) so the flat task list stays readable.

Completion rule: When ALL sub-tasks for a spec are completed, mark the parent spec task as completed too:

# After all data-model sub-tasks done:
TaskUpdate(taskId="{data-model-spec-task}", status="completed")

Then continue to Gate 4 below (which validates the full structure).

Create Tasks with TaskCreate (Task-Based Mode)

For each phase identified, create a task:

# Phase 1
TaskCreate(
  subject="Phase 1: [Title]",
  description="[Details from gates]\n- Task 1\n- Task 2",
  activeForm="Working on Phase 1"
)

# Phase 2 (blocked by Phase 1)
TaskCreate(
  subject="Phase 2: [Title]",
  description="[Details]",
  activeForm="Working on Phase 2"
)
# Then: TaskUpdate(taskId="2", addBlockedBy=["1"])

Create findings.md and progress.md

Consult references/templates.md for the full findings.md and progress.md templates. Both have task-based and spec-driven variants.

Gate 4: Plan Validation

After creating tasks and files:

# First show user the task list
TaskList()

AskUserQuestion(
  question="Created X tasks (visible in UI). Ready to proceed?",
  header="Validate",
  options=[
    {"label": "Looks good, proceed", "description": "Start Phase 1"},
    {"label": "Adjust tasks", "description": "I want to modify the plan"},
    {"label": "Show more detail", "description": "Expand on the approach"}
  ]
)

---

Phase 3: Execution with Checkpoints

Task Status Updates

When starting a phase:

TaskUpdate(taskId="1", status="in_progress")

When completing a phase:

TaskUpdate(taskId="1", status="completed")
# Next task auto-unblocks if it was waiting

Automatic Behaviors (via hooks)

• PreToolUse: Auto-reads findings.md before Write/Edit/Bash
• PostToolUse: Reminds to update task status after file changes

Manual Checkpoints (use AskUserQuestion)

Trigger	Action
Phase complete	TaskUpdate(completed) + "Phase N done. Continue?"
Unexpected complexity	"More complex than expected. Simplify scope, extend timeline, or proceed?"
3-strike error	"Hit 3 failures. Try alternative, ask for help, or skip?"
Scope creep	TaskCreate for new work + "New scope detected. Add task or defer?"

The 2-Action Rule

After every 2 view/browser/search operations: → IMMEDIATELY write findings to findings.md → Multimodal content doesn't persist - capture as text NOW

The 3-Strike Protocol

ATTEMPT 1: Diagnose & fix
ATTEMPT 2: Alternative approach (NEVER repeat same action)
ATTEMPT 3: Broader rethink, search for solutions
AFTER 3: AskUserQuestion to escalate

---

Critical Rules

1. Gates before tasks - Run interactive gates before creating tasks
2. Tasks before code - TaskCreate for all phases before any implementation
3. Update task status - TaskUpdate(in_progress) when starting, (completed) when done
4. Read findings before decide - Re-read findings.md for big decisions
5. Log to files - Errors/research go in progress.md and findings.md
6. Ask when stuck - Use AskUserQuestion at checkpoints, not just initially

---

When to Use

Consult references/templates.md for full template files and detailed "when to use / skip" guidance.

---

Anti-Patterns

Don't	Do Instead
Create tasks without asking scope	Run Gate 1 first
Assume requirements	Validate with Gate 2
Pick approach silently	Use Gate 3 if multiple options
Start coding without tasks	TaskCreate for all phases FIRST
Track progress in markdown checkboxes	Use TaskUpdate for status
Store large research in task descriptions	Use findings.md
Ask too many questions	Batch related questions
Forget to update task status	TaskUpdate(completed) when done

---

Phase 4: Worktree Orchestration (Optional)

For plans with 2+ phases, offer parallel worktree execution. Full protocol in references/worktree-orchestration.md — covers Gate 5 setup decision, worktree creation, mother/worker agent spawning, and merge flow.

Handoff to /orchestrate

After Gate 4, if the user wants automated execution, hand off to the /orchestrate skill which reads findings.md and progress.md to drive the 6-stage pipeline (plan ingestion → review → skill matching → agent dispatch → testing → code review). The orchestrator consumes the same file artifacts this skill produces. | All phases done | Mother reports final summary |