Opencode Task Planner

Task Planner - Full Orchestration Skill

Orchestrates the COMPLETE feature lifecycle: brainstorm → specify → clarify → architecture → decompose → execute.

This is the SINGLE ENTRY POINT for multi-step features. Spawns specialized agents for each phase.

Arguments

• /task-planner "description" - Start new plan (runs full flow)
• /task-planner --skip-brainstorm - Skip brainstorm phase (scope already clear)
• /task-planner --skip-clarify - Skip clarify phase (accept markers as-is)
• /task-planner --skip-specify - Skip brainstorm/specify/clarify (use existing spec)
• /task-planner --status - Show current task graph status
• /task-planner --complete - Finalize, clean up state
• /task-planner --abort - Cancel mid-execution, clean state

Note: All phases are MANDATORY by default. Skip flags allow explicit bypass with user acknowledgment.

Full Orchestration Flow

/task-planner "feature description"
        │
        ▼
┌─────────────────────────────────────────────────────────┐
│ Phase 0: BRAINSTORM [MANDATORY]                         │
│   Agent: brainstorm-agent                               │
│   Output: Refined understanding, selected approach      │
│   Skip: --skip-brainstorm                               │
└─────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────┐
│ Phase 1: SPECIFY [MANDATORY]                            │
│   Agent: specify-agent                                  │
│   Output: .opencode/specs/{slug}/spec.md                │
└─────────────────────────────────────────────────────────┘
        │
        ▼ (if >3 markers, else skip to ARCHITECTURE)
┌─────────────────────────────────────────────────────────┐
│ Phase 2: CLARIFY [MANDATORY if markers > 3]             │
│   Agent: clarify-agent                                  │
│   Output: Updated spec.md with resolved uncertainties   │
│   Skip: --skip-clarify                                  │
└─────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────┐
│ Phase 3: ARCHITECTURE                                   │
│   Agent: architecture-agent                             │
│   Output: .opencode/plans/{slug}.md                     │
└─────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────┐
│ Phase 4: DECOMPOSE                                      │
│   Extract tasks, assign agents, schedule waves          │
│   Output: Task graph + GitHub Issue                     │
└─────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────┐
│ Phase 5: EXECUTE (wave by wave)                         │
│   Spawn impl agents → wave-gate → advance               │
│   Output: Working implementation                        │
└─────────────────────────────────────────────────────────┘

Phase 0: Brainstorm (MANDATORY)

Always run unless --skip-brainstorm flag provided.

Plugin enforcement: validate-phase-order hook blocks specify-agent if brainstorm not complete (unless skipped).

Spawn brainstorm-agent with context from templates/phase-brainstorm.md.

Substitute variables:

• {feature_description} - User's original request
• {prior_context} - Any notes from prior exploration

Wait for agent completion. Extract:

• Refined feature description
• Selected approach
• Key constraints

Pass to Phase 1.

Phase 1: Specify

Always run (unless --skip-specify or spec already exists).

Spawn specify-agent with context from templates/phase-specify.md.

Substitute variables:

• {feature_description} - Refined description (from brainstorm or original)
• {brainstorm_output} - Summary from Phase 0 (or empty)
• {date_slug} - YYYY-MM-DD-feature-name format

Wait for agent completion. Extract:

• Spec file path
• Count of [NEEDS CLARIFICATION] markers

If markers > 3: Proceed to Phase 2. If markers <= 3: Skip to Phase 3.

Phase 2: Clarify (MANDATORY if markers > 3)

Run if: spec has >3 [NEEDS CLARIFICATION] markers. Skip via --skip-clarify if accepting markers as-is.

Plugin enforcement: validate-phase-order hook blocks architecture-agent if markers > 3 (unless clarify skipped).

Spawn clarify-agent with context from templates/phase-clarify.md.

Substitute variables:

• {spec_file_path} - Path to spec from Phase 1
• {marker_count} - Number of [NEEDS CLARIFICATION] markers

Wait for agent completion. Verify markers resolved.

If still >3 markers: Ask user to resolve remaining, or proceed with caveats.

Phase 3: Architecture

Always run.

Spawn architecture-agent with context from templates/phase-architecture.md.

Substitute variables:

• {feature_description} - Feature name/description
• {spec_file_path} - Path to spec from Phase 1
• {date_slug} - YYYY-MM-DD-feature-name format

Wait for agent completion. Extract:

• Plan file path
• Implementation phases

Phase 4: Decompose

Run inline (no agent spawn needed).

4a. Extract Tasks

Parse plan into tasks. Design = the plan itself, NOT a tracked task:

T1: Create User domain model (+ tests)
T2: Implement JWT service (+ tests)
T3: Add login endpoint (+ tests)

CRITICAL: Implementation tasks INCLUDE tests. Do NOT create separate test tasks for new code. The code-implementer-agent writes both implementation AND tests (per impl-agent-context.md). Separate test tasks cause circular dependencies:

• Test task depends on impl task (can't test what doesn't exist)
• Impl task already writes tests
• Test task blocked waiting for impl "completed", but wave-gate needs test task evidence → deadlock

When to use test-only agents (java-test-agent, ts-test-agent):

• Adding tests to EXISTING code that lacks coverage
• Task description: "Add missing tests for X" (not "Write tests for new X")

Sizing heuristics - decompose further if:

• Task touches >5 files
• Multiple unrelated concerns in one task
• Description needs "and" to explain

Test requirements - set new_tests_required: false for:

• migration, config, schema, rename, bump, version, refactor, cleanup, typo, docs
• Patterns: →, ->, interface update

4b. Map Spec Anchors

Link each task to spec requirements (FR-xxx, SC-xxx, US-x.acceptance[N]):

[{"anchor":"FR-003","score":0.85,"text":"System MUST validate email format"},...]

Review suggestions, adjust as needed, store as spec_anchors: ["FR-003", "SC-002", "US1.acceptance"]

4c. Assign Agents

Fallback: general-purpose

Note: java-test-agent and ts-test-agent are for backfilling tests on existing code, NOT for testing new implementations. New code gets tests from impl agents.

4d. Schedule Waves

Wave 1: Tasks with no dependencies (run parallel)
Wave 2: Tasks depending on Wave 1
Wave N: Tasks depending on Wave N-1

4e. User Approval

Present plan summary:

• Spec path
• Plan path
• Task breakdown with agents
• Wave schedule
• GitHub Issue will be created

Ask: "Proceed with this plan?"

4f. Create Artifacts

On approval:

A. GitHub Issue:

gh issue create --title "Plan: {title}" --body "$(cat .opencode/plans/{slug}.md)"

B. State File: .opencode/state/active_task_graph.json

• Include spec_file and plan_file paths
• Include spec_anchors per task

Phase 5: Execute

For each wave:

1. Get pending tasks in current wave
2. Spawn ALL wave tasks in parallel (single message, multiple Task calls)
3. Wait for all to reach "implemented"
4. Invoke /opencode-wave-gate (test + spec-check + review)
5. If passed: advance to next wave
6. If blocked: fix issues, re-run /opencode-wave-gate

Agent context: Use templates/impl-agent-context.md for each task.

Substitute variables:

• {task_id}, {wave}, {agent_type}, {dependencies}
• {task_description} - From task breakdown
• {spec_anchors_formatted} - Formatted anchor list with requirement text
• {plan_context} - Relevant section from plan
• {file_list} - Files to create/modify
• {plan_file_path} - Path to full plan

Quick Start Examples

Full flow (recommended):

/task-planner "Add user authentication with email/password"

Runs: brainstorm → specify → clarify → arch → decompose → execute

Skip to architecture (spec exists):

/task-planner --skip-specify "Add user authentication"

Runs: arch → decompose → execute (uses existing spec)

Simple feature (clear scope):

/task-planner "Add logout button to navbar"

Detects simple → may skip brainstorm, minimal spec

State Management

On /task-planner "description":

1. Run phases 0-4
2. Create .opencode/state/active_task_graph.json
3. Plugin hooks become active (block direct edits)

On /task-planner --status:

Plan: Issue #42 - User Authentication
Phase: Execute (Wave 2/3)
Spec: .opencode/specs/2025-01-29-user-auth/spec.md
Plan: .opencode/plans/2025-01-29-user-auth.md

[✓] T1: User model (code-implementer) — tests: PASS
[✓] T2: JWT service (code-implementer) — tests: PASS
[→] T3: Login endpoint (code-implementer) — tests: pending

On /task-planner --complete:

1. Verify all tasks completed
2. Optionally close GitHub Issue
3. Remove state file
4. Invoke /finalize for PR

On /task-planner --abort:

1. Ask: close issue or leave open?
2. Remove state file
3. Plugin hooks deactivate

Plugin Hook Integration

Hooks auto-activate when active_task_graph.json exists:

NEVER write to state file directly. All state updates happen via plugin hooks. Only exception during planning: initial state file creation.

Operations Reference

Status Transitions

pending → in_progress    (task spawned to agent)
in_progress → implemented (agent completes, hook extracts test evidence)
implemented → completed   (wave gate passed: tests + review + no critical findings)

Observability

# Current state
jq '.' .opencode/state/active_task_graph.json

# Per-task status
jq '.tasks[] | {id, status, tests_passed, review_status}' .opencode/state/active_task_graph.json

# Wave gate status
jq '.wave_gates' .opencode/state/active_task_graph.json

Common Issues

Fixing Blocked Waves

When blocked (critical findings), Edit/Write blocked too. To fix:

1. Re-spawn via Task — create fix agent with findings context (subagent CAN Edit/Write)
2. Run /opencode-wave-gate — re-reviews only blocked tasks
3. Emergency: remove state file, fix manually, rebuild from GH issue

Constraints

• ALL phases via agents - brainstorm, specify, clarify, architecture agents
• ALL implementation via Task tool - Edit/Write blocked
• ALL state writes via hooks - Bash writes blocked
• NEVER skip phases unless explicit --skip-X flag provided
• NEVER proceed with >3 unresolved markers without user acknowledgment or --skip-clarify
• Only ONE active plan at a time

Phase Enforcement (Plugin)

The task-planner plugin enforces phase ordering:

tool.execute.before: validate-phase-order

Blocks agent spawns if prerequisite phases not complete.

session.idle: advance-phase

Advances current_phase when phase agents complete.

State Tracking

{
  "current_phase": "specify",
  "phase_artifacts": {
    "brainstorm": "completed",
    "specify": null,
    "clarify": null,
    "architecture": null
  },
  "skipped_phases": ["clarify"]
}

Skip Flags

• --skip-brainstorm - Adds "brainstorm" to skipped_phases, starts at specify
• --skip-clarify - Adds "clarify" to skipped_phases, proceeds to architecture regardless of markers
• --skip-specify - Adds brainstorm, specify, clarify to skipped; requires existing spec.md

Error Recovery

Plan Limits

• Max tasks: 8-12 (split if larger)
• Max waves: 4-5
• Max parallel tasks per wave: 4-6

CRITICAL: Agent Spawning

Each phase spawns ONE agent (except Execute which spawns wave tasks in parallel).

Sequential phases: brainstorm → specify → clarify → architecture Parallel within wave: T1, T2, T3 in same message

Pass context forward between phases via agent outputs.