cokit-cli 1.2.6 → 1.3.0

package/templates/repo/.github/skills/fix/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: fix
-description: ALWAYS activate this skill before fixing ANY bug, error, test failure, CI/CD issue, type error, lint, log error, UI issue, code problem.
+description: "ALWAYS activate this skill before fixing ANY bug, error, test failure, CI/CD issue, type error, lint, log error, UI issue, code problem."
+argument-hint: "[issue] --auto|--review|--quick|--parallel"
 ---
 
 # Fixing
@@ -12,28 +13,97 @@ Unified skill for fixing issues of any complexity with intelligent routing.
 - `--auto` - Activate autonomous mode (**default**)
 - `--review` - Activate human-in-the-loop review mode
 - `--quick` - Activate quick mode
-- `--parallel` - Fix 2+ independent issues concurrently using parallel agents
+- `--parallel` - Activate parallel mode: route to parallel `fullstack-developer` agents per issue
+
+<HARD-GATE>
+Do NOT propose or implement fixes before completing Steps 1-2 (Scout + Diagnose).
+Symptom fixes are failure. Find the cause first through structured analysis, NEVER guessing.
+If 3+ fix attempts fail, STOP and question the architecture — discuss with user before attempting more.
+User override: `--quick` mode allows fast scout→diagnose→fix cycle for trivial issues (lint, type errors).
+</HARD-GATE>
+
+## Anti-Rationalization
+
+| Thought | Reality |
+|---------|---------|
+| "I can see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. Scout first. |
+| "Quick fix for now, investigate later" | "Later" never comes. Fix properly now. |
+| "Just try changing X" | Random fixes waste time and create new bugs. Diagnose first. |
+| "It's probably X" | "Probably" = guessing. Use structured diagnosis. Verify first. |
+| "One more fix attempt" (after 2+) | 3+ failures = wrong approach. Question architecture. |
+| "Emergency, no time for process" | Systematic diagnosis is FASTER than guess-and-check. |
+| "I already know the codebase" | Knowledge decays. Scout to verify assumptions before acting. |
+| "The fix is done, tests pass" | Without prevention, same bug class will recur. Add guards. |
+
+## Process Flow (Authoritative)
+
+```mermaid
+flowchart TD
+    A[Issue Input] --> B[Step 0: Mode Selection]
+    B --> C[Step 1: Scout - Understand Context]
+    C --> D[Step 2: Diagnose - Structured Root Cause Analysis]
+    D --> E[Step 3: Complexity Assessment + Task Orchestration]
+    E -->|Simple| F[Quick Workflow]
+    E -->|Moderate| G[Standard Workflow]
+    E -->|Complex| H[Deep Workflow]
+    E -->|Parallel| I[Multi-Agent Fix]
+    F --> J[Step 4: Fix Implementation]
+    G --> J
+    H --> J
+    I --> J
+    J --> K[Step 5: Verify + Prevent]
+    K -->|Pass + Prevention in place| L[Step 6: Finalize]
+    K -->|Fail, <3 attempts| D
+    K -->|Fail, 3+ attempts| M[Question Architecture]
+    M --> N[Discuss with User]
+    L --> O[Report + Docs + Journal]
+```
+
+**This diagram is the authoritative workflow.** If prose conflicts with this flow, follow the diagram.
 
 ## Workflow
 
-### Step 1: Mode Selection
+### Step 0: Mode Selection
 
-**First action:** If there is no "auto" keyword in the request, ask the user directly to choose a workflow mode (then wait for response):
+**First action:** If there is no "auto" keyword in the request, ask the user to determine workflow mode:
 
 | Option | Recommend When | Behavior |
 |--------|----------------|----------|
 | **Autonomous** (default) | Simple/moderate issues | Auto-approve if score >= 9.5 & 0 critical |
 | **Human-in-the-loop Review** | Critical/production code | Pause for approval at each step |
-| **Quick** | Type errors, lint, trivial bugs | Fast debug → fix → review cycle |
+| **Quick** | Type errors, lint, trivial bugs | Fast scout → diagnose → fix → review cycle |
+
+See `references/mode-selection.md` for asking the user format.
+
+### Step 1: Scout (MANDATORY — never skip)
+
+**Purpose:** Understand the affected codebase BEFORE forming any hypotheses.
+
+**Mandatory skill chain:**
+1. Activate `scout` skill OR launch 2-3 parallel `Explore` subagents
+2. Discover: affected files, dependencies, related tests, recent changes (`git log`)
+3. Read `./docs` for project context if unfamiliar
+
+**Quick mode:** Minimal scout — locate affected file(s) and their direct dependencies only.
+**Standard/Deep mode:** Full scout — map module boundaries, test coverage, call chains.
+
+**Output:** `✓ Step 1: Scouted - [N] files mapped, [M] dependencies, [K] tests found`
 
-See `references/mode-selection.md` for question format.
+### Step 2: Diagnose (MANDATORY — never skip)
 
-### Step 2: Debug
+**Purpose:** Structured root cause analysis. NO guessing. Evidence-based only.
 
-- Activate `debug` skill.
-- Guess all possible root causes.
-- Spawn multiple parallel search agents to verify each hypothesis.
-- Create report with all findings for the next step.
+**Mandatory skill chain:**
+1. **Capture pre-fix state:** Record exact error messages, failing test output, stack traces, log snippets. This becomes the baseline for Step 5 verification.
+2. Activate `debug` skill (systematic-debugging + root-cause-tracing techniques).
+3. Activate `sequential-thinking` skill — form hypotheses through structured reasoning, NOT guessing.
+4. Spawn parallel `Explore` subagents to test each hypothesis against codebase evidence.
+5. If 2+ hypotheses fail → auto-activate `problem-solving` skill for alternative approaches.
+6. Create diagnosis report: confirmed root cause, evidence chain, affected scope.
+
+See `references/diagnosis-protocol.md` for full methodology.
+
+**Output:** `✓ Step 2: Diagnosed - Root cause: [summary], Evidence: [brief], Scope: [N files]`
 
 ### Step 3: Complexity Assessment & Task Orchestration
 
@@ -44,65 +114,92 @@ Classify before routing. See `references/complexity-assessment.md`.
 | **Simple** | Single file, clear error, type/lint | `references/workflow-quick.md` |
 | **Moderate** | Multi-file, root cause unclear | `references/workflow-standard.md` |
 | **Complex** | System-wide, architecture impact | `references/workflow-deep.md` |
-| **Parallel** | 2+ independent issues | Parallel `fullstack-developer` agents |
+| **Parallel** | 2+ independent issues OR `--parallel` flag | Parallel `fullstack-developer` agents |
+
+**Task Orchestration (Moderate+ only):** After classifying, create native Tasks for all phases upfront with dependencies. See `references/task-orchestration.md`.
+- Skip for Quick workflow (< 3 steps, overhead exceeds benefit)
+- Use `TaskCreate` with `addBlockedBy` for dependency chains
+- Update via `TaskUpdate` as each phase completes
+- For Parallel: create separate task trees per independent issue
+- **Fallback:** Task tools (`TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList`) are CLI-only — unavailable in VSCode extension. If they error, use `TodoWrite` for progress tracking. Fix workflow remains fully functional without them.
+
+### Step 4: Fix Implementation
 
-**Task orchestration notes:**
-- **Quick workflow:** Skip task creation — proceed directly to fix.
-- **Moderate+ workflows:** After classifying, create a todo checklist for all phases upfront with dependencies before starting any implementation. Track each phase with checkboxes and note blockers inline.
+- Implement fix per selected workflow, updating Tasks as phases complete.
+- Follow diagnosis findings — fix the ROOT CAUSE, not symptoms.
+- Minimal changes only. Follow existing patterns.
 
-See `references/task-orchestration.md` for checklist structure and dependency tracking patterns.
+### Step 5: Verify + Prevent (MANDATORY — never skip)
 
-### Step 4: Fix Implementation & Verification
+**Purpose:** Prove the fix works AND prevent the same bug class from recurring.
 
-- Read and analyze all the implemented changes.
-- Spawn multiple parallel search agents to verify no regressions in related code.
-- Make sure these fixes don't break other parts of the codebase.
-- Prevent future issues by adding comprehensive validation.
+**Mandatory skill chain:**
+1. **Verify (iron-law):** Run the EXACT commands from pre-fix state capture. Compare output. NO claims without fresh evidence.
+2. **Regression test:** Add or update test(s) that specifically cover the fixed issue. The test MUST fail without the fix and pass with it.
+3. **Prevention gate:** Apply defense-in-depth validation where applicable. See `references/prevention-gate.md`.
+4. **Parallel verification:** Launch `Bash` agents for typecheck + lint + build + test.
 
-### Step 5: Finalize
+**If verification fails:** Loop back to Step 2 (re-diagnose). After 3 failures → question architecture, discuss with user.
 
-**MANDATORY — always execute all steps:**
+See `references/prevention-gate.md` for prevention requirements.
 
-1. Report summary to user with confidence score (0–10), all changes, and related files.
-2. Update `./docs` via ``docs-manager`` agent (NON-OPTIONAL — always run even for small fixes).
-3. Mark all checklist tasks complete.
-4. Ask user to commit via ``git-manager`` agent.
+**Output:** `✓ Step 5: Verified + Prevented - [before/after comparison], [N] tests added, [M] guards added`
+
+### Step 6: Finalize (MANDATORY — never skip)
+
+1. Report summary: confidence score, root cause, changes, files, prevention measures
+2. `docs-manager` subagent → update `./docs` if changes warrant (NON-OPTIONAL)
+3. `TaskUpdate` → mark ALL Tasks `completed` (skip if Task tools unavailable)
+4. Ask user if they want to commit via `git-manager` subagent
+5. Run `/ck-journal` to write a concise technical journal entry upon completion
 
 ---
 
-## IMPORTANT: Skill/Agent Activation Matrix
+## IMPORTANT: Skill/Subagent Activation Matrix
 
 See `references/skill-activation-matrix.md` for complete matrix.
 
-**Always activate:** `debug` (all workflows)
-**Conditional:** `problem-solving`, `sequential-thinking`, `brainstorming`, `context-engineering`
-**Agents:** ``debugger``, ``researcher``, ``planner``, ``code-reviewer``, ``tester``
-**Parallel patterns:** Multiple parallel search agents for scouting; parallel terminal commands for verification; parallel ``fullstack-developer`` agents for independent issues (`--parallel` flag)
+**Always activate (ALL workflows):**
+- `scout` (Step 1) — understand before diagnosing
+- `debug` (Step 2) — systematic root cause investigation
+- `sequential-thinking` (Step 2) — structured hypothesis formation
+
+**Conditional:**
+- `problem-solving` — auto-triggers when 2+ hypotheses fail in Step 2
+- `brainstorm` — multiple valid approaches, architecture decision (Deep only)
+- `context-engineering` — fixing AI/LLM/agent code
+- `project-management` — moderate+ for task hydration/sync-back
+
+**Subagents:** `debugger`, `researcher`, `planner`, `code-reviewer`, `tester`, `Bash`
+**Parallel:** Multiple `Explore` agents for scouting, `Bash` agents for verification
 
 ## Output Format
 
 Unified step markers:
 ```
-✓ Step 0: [Mode] selected - [Complexity] detected
-✓ Step 1: Root cause identified - [summary]
-✓ Step 2: Fix implemented - [N] files changed
-✓ Step 3: Tests [X/X passed]
-✓ Step 4: Review [score]/10 - [status]
-✓ Step 5: Complete - [action taken]
+✓ Step 0: [Mode] selected
+✓ Step 1: Scouted - [N] files, [M] deps
+✓ Step 2: Diagnosed - Root cause: [summary]
+✓ Step 3: [Complexity] detected - [workflow] selected
+✓ Step 4: Fixed - [N] files changed
+✓ Step 5: Verified + Prevented - [tests added], [guards added]
+✓ Step 6: Complete - [action taken]
 ```
 
 ## References
 
 Load as needed:
-- `references/mode-selection.md` - Mode selection question format
+- `references/mode-selection.md` - asking the user format for mode
+- `references/diagnosis-protocol.md` - Structured diagnosis methodology (NEW)
+- `references/prevention-gate.md` - Prevention requirements after fix (NEW)
 - `references/complexity-assessment.md` - Classification criteria
-- `references/task-orchestration.md` - Todo checklist structure and dependency tracking
-- `references/workflow-quick.md` - Quick: debug → fix → review
-- `references/workflow-standard.md` - Standard: full pipeline
-- `references/workflow-deep.md` - Deep: research + brainstorm + plan
+- `references/task-orchestration.md` - Native Task patterns for moderate+ workflows
+- `references/workflow-quick.md` - Quick: scout → diagnose → fix → verify+prevent → review
+- `references/workflow-standard.md` - Standard: full pipeline with Tasks
+- `references/workflow-deep.md` - Deep: research + brainstorm + plan with Tasks
 - `references/review-cycle.md` - Review logic (autonomous vs HITL)
 - `references/skill-activation-matrix.md` - When to activate each skill
-- `references/parallel-exploration.md` - Parallel search and execution patterns
+- `references/parallel-exploration.md` - Parallel Explore/Bash/Task coordination patterns
 
 **Specialized Workflows:**
 - `references/workflow-ci.md` - GitHub Actions/CI failures

package/templates/repo/.github/skills/fix/references/complexity-assessment.md

@@ -1,38 +1,42 @@
 # Complexity Assessment
 
-Classify issue complexity before routing to workflow.
+Classify issue complexity before routing to workflow. Assessment happens AFTER Step 1 (Scout) and Step 2 (Diagnose).
 
 ## Classification Criteria
 
-### Simple (→ workflow-quick.md)
+### Simple (→ workflow-quick.md) — No Tasks
 
 **Indicators:**
 - Single file affected
 - Clear error message (type error, syntax, lint)
 - Keywords: `type`, `typescript`, `tsc`, `lint`, `eslint`, `syntax`
 - Obvious fix location
-- No investigation needed
+- Root cause confirmed by diagnosis (not assumed)
+
+**Task usage:** Skip. < 3 steps, overhead exceeds benefit.
 
 **Examples:**
 - "Fix type error in auth.ts"
 - "ESLint errors after upgrade"
 - "Syntax error in config file"
 
-### Moderate (→ workflow-standard.md)
+### Moderate (→ workflow-standard.md) — Use Tasks (6 phases)
 
 **Indicators:**
 - 2-5 files affected
-- Root cause unclear but localized
-- Needs debugging investigation
+- Root cause identified but fix spans multiple files
+- Needs investigation to confirm diagnosis
 - Keywords: `bug`, `broken`, `not working`, `fails sometimes`
-- Test failures with unclear cause
+- Test failures with root cause traced
+
+**Task usage:** Create 6 phase tasks with dependencies. See `references/task-orchestration.md`.
 
 **Examples:**
 - "Login sometimes fails"
 - "API returns wrong data"
 - "Component not rendering correctly"
 
-### Complex (→ workflow-deep.md)
+### Complex (→ workflow-deep.md) — Use Tasks with Dependency Chains (9 phases)
 
 **Indicators:**
 - System-wide impact (5+ files)
@@ -41,13 +45,19 @@ Classify issue complexity before routing to workflow.
 - Keywords: `architecture`, `refactor`, `system-wide`, `design issue`
 - Performance/security vulnerabilities
 - Multiple interacting components
+- Root cause spans multiple layers/modules
+
+**Task usage:** Create 9 phase tasks. Steps 1+2+3 run parallel (scout+diagnose+research). Full dependency chains. See `references/task-orchestration.md`.
 
 **Examples:**
 - "Memory leak in production"
 - "Database deadlocks under load"
 - "Security vulnerability in auth flow"
 
-### Parallel (→ multiple fullstack-developer agents)
+### Parallel (→ multiple fullstack-developer agents) — Use Task Trees
+
+**Triggers:**
+- `--parallel` flag explicitly passed (activate parallel routing regardless of auto-classification)
 
 **Indicators:**
 - 2+ independent issues mentioned
@@ -55,6 +65,8 @@ Classify issue complexity before routing to workflow.
 - No dependencies between issues
 - Keywords: list of issues, "and", "also", multiple error types
 
+**Task usage:** Create separate task trees per independent issue (each with scout+diagnose+fix+verify). Spawn `fullstack-developer` agent per tree. See `references/task-orchestration.md`.
+
 **Examples:**
 - "Fix type errors AND update UI styling"
 - "Auth bug + payment integration issue"

package/templates/repo/.github/skills/fix/references/diagnosis-protocol.md

@@ -0,0 +1,133 @@
+# Diagnosis Protocol
+
+Structured root cause analysis methodology. Replaces ad-hoc guessing with evidence-based investigation.
+
+## Core Principle
+
+**NEVER guess root causes.** Form hypotheses through structured reasoning and test them against evidence.
+
+## Pre-Diagnosis: Capture State (MANDATORY)
+
+Before any investigation, capture the current broken state as baseline:
+
+```
+1. Record exact error messages (copy-paste, not paraphrase)
+2. Record failing test output (full command + output)
+3. Record relevant stack traces
+4. Record relevant log snippets with timestamps
+5. Record git status / recent changes: git log --oneline -10
+```
+
+This baseline is required for Step 5 (Verify) — you MUST compare before/after.
+
+## Diagnosis Chain (Follow in Order)
+
+### Phase 1: Observe — What is actually happening?
+
+Read, don't assume. Use `debug` (systematic-debugging Phase 1).
+
+- What is the exact error message?
+- Where does it occur? (file, line, function)
+- When did it start? (check `git log`, `git bisect`)
+- Can it be reproduced consistently?
+- What is the expected vs actual behavior?
+
+### Phase 2: Hypothesize — Why might this happen?
+
+Activate `sequential-thinking` skill. Form hypotheses through structured reasoning.
+
+**Structured hypothesis formation:**
+```
+For each hypothesis:
+  1. State the hypothesis clearly
+  2. What evidence would CONFIRM it?
+  3. What evidence would REFUTE it?
+  4. How to test it quickly?
+```
+
+**Common hypothesis categories:**
+- Recent code change introduced regression (`git log`, `git diff`)
+- Data/state mismatch (wrong input, stale cache, race condition)
+- Environment difference (deps version, config, platform)
+- Missing validation (null check, type guard, boundary)
+- Incorrect assumption (API contract, data shape, ordering)
+
+### Phase 3: Test — Verify hypotheses against evidence
+
+Spawn parallel `Explore` subagents to test each hypothesis simultaneously:
+
+```
+// Launch in SINGLE message — max 3 parallel agents
+Task("Explore", "Test hypothesis A: [specific search/check]", "Verify H-A")
+Task("Explore", "Test hypothesis B: [specific search/check]", "Verify H-B")
+Task("Explore", "Test hypothesis C: [specific search/check]", "Verify H-C")
+```
+
+**For each hypothesis result:**
+- CONFIRMED: Evidence supports this as root cause → proceed to root cause tracing
+- REFUTED: Evidence contradicts → discard, note why
+- INCONCLUSIVE: Need more data → refine hypothesis or gather more evidence
+
+### Phase 4: Trace — Follow the root cause chain
+
+Use `debug` (root-cause-tracing technique). Trace backward:
+
+```
+Symptom (where error appears)
+  ↑ Immediate cause (what triggered the error)
+    ↑ Contributing factor (what set up the bad state)
+      ↑ ROOT CAUSE (the original trigger that must be fixed)
+```
+
+**Rule:** NEVER fix where the error appears. Trace back to the source.
+
+### Phase 5: Escalate — When hypotheses fail
+
+If 2+ hypotheses are REFUTED:
+1. Auto-activate `problem-solving` skill
+2. Apply Inversion Exercise: "What would CAUSE this bug intentionally?"
+3. Apply Scale Game: "Does this fail with 1 item? 100? 10000?"
+4. Consider environmental factors (timing, concurrency, platform)
+
+If 3+ fix attempts fail after diagnosis:
+1. STOP immediately
+2. Question the architecture — is the design fundamentally flawed?
+3. Discuss with user before attempting more
+
+## Diagnosis Report Format
+
+```markdown
+## Diagnosis Report
+
+**Issue:** [one-line description]
+**Pre-fix state captured:** Yes/No
+
+### Root Cause
+[Clear explanation of the root cause, traced back to origin]
+
+### Evidence Chain
+1. [Observation] → led to hypothesis [X]
+2. [Test result] → confirmed/refuted [X]
+3. [Trace] → root cause at [file:line]
+
+### Affected Scope
+- Files: [list]
+- Functions: [list]
+- Dependencies: [list]
+
+### Recommended Fix
+[What to change and why — addressing root cause, not symptoms]
+
+### Prevention Needed
+[What guards/tests to add to prevent recurrence]
+```
+
+## Quick Mode Diagnosis
+
+For trivial issues (type errors, lint, syntax), abbreviated diagnosis:
+
+1. Read error message
+2. Locate affected file(s) via scout results
+3. Identify root cause (usually obvious for simple issues)
+4. Skip parallel hypothesis testing
+5. Still capture pre-fix state for verification

package/templates/repo/.github/skills/fix/references/mode-selection.md

@@ -1,16 +1,32 @@
 # Mode Selection
 
-Ask the user at start of fixing workflow to choose a mode. Present the question directly in your response, then stop and wait for their answer.
-
-## Question Format
-
-Ask the user:
-
-> **Fix Mode:** How should I handle the fix workflow?
->
-> 1. **Autonomous (Recommended)** — Auto-approve if quality high, only ask when stuck
-> 2. **Human-in-the-loop** — Pause for approval at each major step
-> 3. **Quick fix** — Fast debug-fix-review cycle for simple issues
+Use asking the user at start of fixing workflow.
+
+## asking the user Format
+
+```json
+{
+  "questions": [{
+    "question": "How should I handle the fix workflow?",
+    "header": "Fix Mode",
+    "options": [
+      {
+        "label": "Autonomous (Recommended)",
+        "description": "Auto-approve if quality high, only ask when stuck"
+      },
+      {
+        "label": "Human-in-the-loop",
+        "description": "Pause for approval at each major step"
+      },
+      {
+        "label": "Quick fix",
+        "description": "Fast debug-fix-review cycle for simple issues"
+      }
+    ],
+    "multiSelect": false
+  }]
+}
+```
 
 ## Mode Recommendations
 

package/templates/repo/.github/skills/fix/references/parallel-exploration.md

@@ -1,19 +1,19 @@
 # Parallel Exploration
 
-Patterns for launching multiple agents in parallel to scout codebase and verify implementation.
+Patterns for launching multiple subagents in parallel to scout codebase, verify implementation, and coordinate via native Tasks.
 
 ## Parallel Exploration (Scouting)
 
-Launch multiple `Explore` agents simultaneously when needing to find:
+Launch multiple `Explore` subagents simultaneously when needing to find:
 - Related files across different areas
 - Similar implementations/patterns
 - Dependencies and usage
 
 **Pattern:**
 ```
-Task(agent_type="Explore", prompt="Find [X] in [area1]", description="Scout area1")
-Task(agent_type="Explore", prompt="Find [Y] in [area2]", description="Scout area2")
-Task(agent_type="Explore", prompt="Find [Z] in [area3]", description="Scout area3")
+Task(subagent_type="Explore", prompt="Find [X] in [area1]", description="Scout area1")
+Task(subagent_type="Explore", prompt="Find [Y] in [area2]", description="Scout area2")
+Task(subagent_type="Explore", prompt="Find [Z] in [area3]", description="Scout area3")
 ```
 
 **Example - Multi-area scouting:**
@@ -26,12 +26,12 @@ Task("Explore", "Find test files for auth module", "Scout tests")
 
 ## Parallel Verification (Bash)
 
-Launch multiple `Bash` agents to verify implementation from different angles.
+Launch multiple `Bash` subagents to verify implementation from different angles.
 
 **Pattern:**
 ```
-Task(agent_type="Bash", prompt="Run [command1]", description="Verify X")
-Task(agent_type="Bash", prompt="Run [command2]", description="Verify Y")
+Task(subagent_type="Bash", prompt="Run [command1]", description="Verify X")
+Task(subagent_type="Bash", prompt="Run [command2]", description="Verify Y")
 ```
 
 **Example - Multi-verification:**
@@ -42,6 +42,27 @@ Task("Bash", "Run lint: bun run lint", "Verify lint")
 Task("Bash", "Run build: bun run build", "Verify build")
 ```
 
+## Task-Coordinated Parallel (Moderate+)
+
+For multi-phase fixes, use native Tasks to coordinate parallel agents.
+See `references/task-orchestration.md` for full patterns.
+
+**Pattern - Parallel issue trees:**
+```
+// Create separate task trees per independent issue
+T_A1 = TaskCreate(subject="[Issue A] Debug", activeForm="Debugging A")
+T_A2 = TaskCreate(subject="[Issue A] Fix",   activeForm="Fixing A",   addBlockedBy=[T_A1])
+T_B1 = TaskCreate(subject="[Issue B] Debug", activeForm="Debugging B")
+T_B2 = TaskCreate(subject="[Issue B] Fix",   activeForm="Fixing B",   addBlockedBy=[T_B1])
+T_final = TaskCreate(subject="Integration verify", addBlockedBy=[T_A2, T_B2])
+
+// Spawn agents per issue tree
+Task("fullstack-developer", "Fix Issue A. Claim tasks via TaskUpdate.", "Fix A")
+Task("fullstack-developer", "Fix Issue B. Claim tasks via TaskUpdate.", "Fix B")
+```
+
+Agents claim work via `TaskUpdate(status="in_progress")` and complete via `TaskUpdate(status="completed")`. Blocked tasks auto-unblock when dependencies resolve.
+
 ## When to Use Parallel
 
 | Scenario | Parallel Strategy |
@@ -50,11 +71,12 @@ Task("Bash", "Run build: bun run build", "Verify build")
 | Multi-module fix | Explore each module in parallel |
 | After implementation | Bash agents for typecheck + lint + build |
 | Before commit | Bash agents for test + build + lint |
+| 2+ independent issues | Task trees per issue + fullstack-developer agents |
 
-## Combining Explore + Bash
+## Combining Explore + Tasks + Bash
 
 **Step 1:** Parallel Explore to scout
-**Step 2:** Sequential implementation
+**Step 2:** Sequential implementation (update Tasks as phases complete)
 **Step 3:** Parallel Bash to verify
 
 ```
@@ -62,7 +84,7 @@ Task("Bash", "Run build: bun run build", "Verify build")
 Task("Explore", "Find payment handlers", "Scout payments")
 Task("Explore", "Find order processors", "Scout orders")
 
-// Wait for results, implement fix
+// Wait for results, implement fix, TaskUpdate each phase
 
 // Verify phase - parallel
 Task("Bash", "Run tests: bun test", "Run tests")
@@ -73,5 +95,6 @@ Task("Bash", "Run build", "Verify build")
 ## Resource Limits
 
 - Max 3 parallel agents recommended (system resources)
-- Each agent has 200K token context limit
+- Each subagent has 200K token context limit
 - Keep prompts concise to avoid context bloat
+- Use `TaskList()` to check for available unblocked work