feat: integrate native task system for real-time orchestration (#186)

* feat: integrate native task system for real-time orchestration

Add guidance for using Claude Code's native task tools (TaskCreate,
TaskUpdate, TaskList) during phase execution:

- Native tasks = session coordination layer (real-time tracking)
- Markdown tasks.md = persistent record (survives compactions)

Key changes to commands/tasks.md:
- New "Real-Time Task Coordination" section explaining two-layer approach
- TaskUpdate calls in sequential phase execution flow
- TaskList usage for parallel phase dependency tracking

Key changes to templates/tasks-template.md:
- "Real-Time Coordination" section in Orchestration Model
- Setup instructions for creating tasks with blockedBy dependencies
- Updated sequential/parallel execution to use native task status
- Checkpoint sync instructions for markdown persistence

The blockedBy feature automatically enforces TDD order (can't start
Tests until Stub completes) and surfaces ready-to-dispatch work via
TaskList.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: standardize task naming and clarify sync timing

- Use consistent short format "PN: Step" (e.g., "P1: Stub") for task names
- Clarify markdown sync happens after each phase, not just at checkpoints
- Replace "..." with explicit comment "(repeat pattern for each phase)"

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Craig Haseler <cahaseler@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: cahaseler

commands/tasks.md

@@ -193,43 +193,109 @@ Phase 4 ──┘
 
 When the user approves this task breakdown and says to begin implementation:
 
+### Real-Time Task Coordination (Native Task System)
+
+Use Claude Code's native task system (`TaskCreate`, `TaskUpdate`, `TaskList`) for **real-time coordination** during the session. The markdown `tasks.md` file remains the **persistent record**.
+
+**Two-layer approach:**
+- **Native tasks** = Session coordination layer (tracks what's happening NOW)
+- **Markdown tasks.md** = Persistent record (survives compactions, documents history)
+
+**At the start of each phase set:**
+1. Create native tasks for each step with proper dependencies:
+   ```
+   TaskCreate: "P1: Stub" (description: files, exports needed)
+   TaskCreate: "P1: Tests" (description: test requirements)
+   TaskCreate: "P1: Implement" (description: make tests pass)
+   TaskCreate: "P1: Validate" (description: verify requirements)
+
+   TaskUpdate: "P1: Tests" addBlockedBy: ["P1: Stub"]
+   TaskUpdate: "P1: Implement" addBlockedBy: ["P1: Tests"]
+   TaskUpdate: "P1: Validate" addBlockedBy: ["P1: Implement"]
+   ```
+
+2. For parallel phases, create all tasks upfront with cross-phase dependencies:
+   ```
+   # Phase 2 and 3 can run in parallel, but each has internal TDD order
+   TaskUpdate: "P2: Tests" addBlockedBy: ["P2: Stub"]
+   TaskUpdate: "P3: Tests" addBlockedBy: ["P3: Stub"]
+   # Phase 4 depends on Phase 2 completing
+   TaskUpdate: "P4: Stub" addBlockedBy: ["P2: Validate"]
+   ```
+
+**During execution:**
+- `TaskUpdate` status to `in_progress` when dispatching a subagent
+- `TaskUpdate` status to `completed` when subagent returns successfully
+- Use `TaskList` to see what's unblocked and ready to dispatch
+
+**After each phase (and at checkpoints):**
+- Sync native task completion back to markdown checkboxes in `tasks.md`
+- This ensures the persistent record is updated for context compaction
+
+**Why this matters:**
+- Native `blockedBy` enforces TDD order automatically (can't start Tests until Stub completes)
+- `TaskList` shows exactly what's ready to dispatch vs. blocked
+- Status visible in Claude Code's UI
+- Markdown update at checkpoints preserves state across sessions
+
 ### For Sequential Phases
 
 Dispatch subagents one at a time in TDD order:
 
 1. **Stub Writer**:
    ```
+   TaskUpdate: "PN: Stub" status: in_progress
    Task tool with subagent_type: stub-writer
    Prompt: "Phase N: [Phase Name]. Create stubs for [files] with exports: [list exports needed]"
    ```
-   → On success: Check off "Stub" checkbox in tasks.md
+   → On success: `TaskUpdate: "PN: Stub" status: completed`
 
 2. **Test Writer** (after stub complete):
    ```
+   TaskUpdate: "PN: Tests" status: in_progress
    Task tool with subagent_type: test-generation
    Prompt: "Phase N: [Phase Name]. Write tests for [requirements]. Test files: [paths]. Run tests and report output."
    ```
-   → On success: Check off "Tests" checkbox in tasks.md
+   → On success: `TaskUpdate: "PN: Tests" status: completed`
 
 3. **Implementer** (after tests written and failing):
    ```
+   TaskUpdate: "PN: Implement" status: in_progress
    Task tool with subagent_type: implementer
    Prompt: "Phase N: [Phase Name]. Make tests pass. Implementation files: [paths]. Run tests and report output."
    ```
-   → On success: Check off "Implement" checkbox in tasks.md
+   → On success: `TaskUpdate: "PN: Implement" status: completed`
 
 4. **Validator** (after implementation):
    ```
+   TaskUpdate: "PN: Validate" status: in_progress
    Task tool with subagent_type: validator
    Prompt: "Phase N: [Phase Name]. Verify: [requirements from spec]. Run tests independently. Report pass/fail."
    ```
-   → On success: Check off "Validate" checkbox in tasks.md
+   → On success: `TaskUpdate: "PN: Validate" status: completed`
 
-**IMPORTANT**: Update tasks.md checkboxes immediately after each subagent returns successfully. This keeps progress visible and ensures state is preserved across context compactions.
+**After each phase completes**: Update tasks.md checkboxes to sync the persistent record. This ensures state is preserved across context compactions.
 
 ### For Parallel Phases and Dependency Enforcement
 
-See `${CLAUDE_PLUGIN_ROOT}/templates/tasks-template.md` for the orchestration patterns (pipeline flow, polling fallback, dependency rules). These are included in the generated tasks.md and followed during execution.
+**Create all native tasks upfront** with `blockedBy` relationships:
+```
+# All stubs can start immediately (no blockers)
+TaskCreate: "P2: Stub", "P3: Stub", "P4: Stub"
+
+# Tests blocked by their phase's stub
+TaskUpdate: "P2: Tests" addBlockedBy: ["P2: Stub"]
+TaskUpdate: "P3: Tests" addBlockedBy: ["P3: Stub"]
+
+# Implement blocked by tests, Validate blocked by implement
+# (repeat pattern for each phase)
+```
+
+**Use `TaskList`** to see what's unblocked and ready to dispatch. The native system enforces dependencies automatically - you can't accidentally start Tests before Stub completes.
+
+**Pipeline flow**: As each step completes, its dependents become unblocked. Dispatch newly-unblocked tasks immediately for maximum parallelism.
+
+See `${CLAUDE_PLUGIN_ROOT}/templates/tasks-template.md` for additional orchestration patterns (polling fallback, dependency diagrams). These are included in the generated tasks.md.
 
 ### For Waived Phases
 

templates/tasks-template.md

@@ -25,6 +25,19 @@ The orchestrator coordinates these agents, reviews their output, updates checkbo
 - **Checkpoints**: Pause for user approval at designated points
 - **Escalation**: Stop new work, settle in-flight agents, then raise issues
 
+### Real-Time Coordination (Native Task System)
+
+Use Claude Code's native task tools for **real-time coordination** during the session:
+
+- **Native tasks** (`TaskCreate`, `TaskUpdate`, `TaskList`) = Session coordination layer
+- **This markdown file** = Persistent record (survives compactions)
+
+**Workflow:**
+1. At phase set start: Create native tasks with `blockedBy` dependencies
+2. During execution: `TaskUpdate` status as subagents dispatch/complete
+3. Use `TaskList` to see what's unblocked and ready
+4. After each phase: Sync completed tasks back to markdown checkboxes
+
 ---
 
 ## Phase 1: [Phase Name]
@@ -111,37 +124,67 @@ Document which phases can run in parallel and which have dependencies.
 
 ## Orchestration Instructions
 
-### Sequential Phase Execution
+### Setup: Create Native Tasks
 
-For each phase, dispatch subagents in order:
+Before starting implementation, create native tasks for all steps with dependencies:
 
 ```
-1. Task tool: subagent_type=stub-writer
-   Prompt: "Phase N: [Name]. Create stubs for [files] with exports: [list]"
+# Create all tasks for Phase 1
+TaskCreate: subject="P1: Stub", description="Create exports for [files]"
+TaskCreate: subject="P1: Tests", description="Write failing tests"
+TaskCreate: subject="P1: Implement", description="Make tests pass"
+TaskCreate: subject="P1: Validate", description="Verify requirements"
+
+# Set up TDD dependency chain
+TaskUpdate: "P1: Tests" addBlockedBy: ["P1: Stub"]
+TaskUpdate: "P1: Implement" addBlockedBy: ["P1: Tests"]
+TaskUpdate: "P1: Validate" addBlockedBy: ["P1: Implement"]
+
+# For parallel phases, add cross-phase dependencies as needed
+TaskUpdate: "P4: Stub" addBlockedBy: ["P2: Validate"]  # P4 depends on P2
+```
 
-2. Task tool: subagent_type=test-generation
-   Prompt: "Phase N: [Name]. Write tests for [requirements]. Files: [paths]. Run tests, report output."
+### Sequential Phase Execution
 
-3. Task tool: subagent_type=implementer
-   Prompt: "Phase N: [Name]. Make tests pass. Files: [paths]. Run tests, report output."
+For each phase, use `TaskList` to find unblocked tasks, then dispatch:
 
-4. Task tool: subagent_type=validator
-   Prompt: "Phase N: [Name]. Verify: [requirements]. Run tests independently. Report pass/fail."
+```
+1. TaskUpdate: "P1: Stub" status: in_progress
+   Task tool: subagent_type=stub-writer
+   Prompt: "Phase 1: [Name]. Create stubs for [files] with exports: [list]"
+   → On success: TaskUpdate: "P1: Stub" status: completed
+
+2. TaskUpdate: "P1: Tests" status: in_progress
+   Task tool: subagent_type=test-generation
+   Prompt: "Phase 1: [Name]. Write tests for [requirements]. Files: [paths]. Run tests, report output."
+   → On success: TaskUpdate: "P1: Tests" status: completed
+
+3. TaskUpdate: "P1: Implement" status: in_progress
+   Task tool: subagent_type=implementer
+   Prompt: "Phase 1: [Name]. Make tests pass. Files: [paths]. Run tests, report output."
+   → On success: TaskUpdate: "P1: Implement" status: completed
+
+4. TaskUpdate: "P1: Validate" status: in_progress
+   Task tool: subagent_type=validator
+   Prompt: "Phase 1: [Name]. Verify: [requirements]. Run tests independently. Report pass/fail."
+   → On success: TaskUpdate: "P1: Validate" status: completed
 ```
 
 ### Parallel Phase Execution
 
-When multiple phases are marked [P], use **pipeline flow**:
+When multiple phases are marked [P], use **pipeline flow** with native task coordination:
 
-1. **Dispatch** ALL stub writers with `run_in_background: true` in a single message
-2. **Post status** to user: "Dispatched stub writers for Phases X, Y, Z."
-3. **Orchestration loop**:
-   - Do any pending work (check off completed steps, dispatch next agents for completed phases)
-   - Process any notifications that arrived while working
-   - If no pending work: poll all active agents with `AgentOutputTool(block: false)`
-   - If all still running: `Bash(sleep 30)` to idle efficiently, then poll again
+1. **Create all native tasks upfront** with `blockedBy` dependencies (see Setup above)
+2. **Use `TaskList`** to see all unblocked tasks ready to dispatch
+3. **Dispatch** all unblocked stub writers with `run_in_background: true` in a single message
+4. **Post status** to user: "Dispatched stub writers for Phases X, Y, Z."
+5. **Orchestration loop**:
+   - `TaskList` to find newly unblocked tasks (e.g., Tests for completed Stubs)
+   - Dispatch unblocked tasks, `TaskUpdate` status to in_progress
+   - As agents complete, `TaskUpdate` status to completed
+   - Repeat until all tasks complete
 
-This creates true pipeline parallelism - Phase 1's test writer starts as soon as Phase 1's stub finishes, even while other stubs run. Notifications usually arrive promptly, but the 30-second polling fallback catches any that don't.
+The native `blockedBy` system automatically tracks what's ready - no manual dependency checking needed. As each step completes, its dependents become unblocked and appear in `TaskList`.
 
 ### Dependency Enforcement
 
@@ -156,9 +199,12 @@ Dependencies mean the full Stub → Tests → Implement → Validate cycle, not
 
 ### At Checkpoints
 
-1. Summarize completed phases with pass/fail status
-2. List upcoming phases
-3. Wait for user approval before continuing
+1. **Sync to markdown**: Update all checkboxes in this file to match native task completion
+2. Summarize completed phases with pass/fail status
+3. List upcoming phases
+4. Wait for user approval before continuing
+
+*The markdown sync ensures progress is preserved across context compactions.*
 
 ### On Complications