feat: integrate background_task system into agents

README.md

@@ -45,31 +45,42 @@ Research subagents (codebase-locator, codebase-analyzer, pattern-finder) are spa
 
 Refine rough ideas into fully-formed designs through collaborative questioning.
 
-- One question at a time
+- One question at a time (critical rule!)
 - 2-3 approaches with trade-offs
 - Section-by-section validation
-- Spawns research subagents to understand codebase
+- Fires research subagents in parallel via `background_task`
+- Auto-hands off to planner when user approves
 - Output: `thoughts/shared/designs/YYYY-MM-DD-{topic}-design.md`
 
-**Research subagents** (spawned in parallel):
+**Research subagents** (fired in parallel via background_task):
 
 | Subagent | Purpose |
 |----------|---------|
 | `codebase-locator` | Find WHERE files live (paths, no content) |
 | `codebase-analyzer` | Explain HOW code works (with file:line refs) |
 | `pattern-finder` | Find existing patterns to follow |
 
+**Auto-handoff:** When user approves the design, brainstormer automatically spawns the planner - no extra confirmation needed.
+
 ### 2. Plan
 
 Transform validated designs into comprehensive implementation plans.
 
-- Spawns research subagents for exact paths, signatures, patterns
+- Fires research subagents in parallel via `background_task`
+- Uses `context7` and `btca_ask` for external library documentation
 - Bite-sized tasks (2-5 minutes each)
 - Exact file paths, complete code examples
 - TDD workflow: failing test → verify fail → implement → verify pass → commit
 - Get human approval before implementing
 - Output: `thoughts/shared/plans/YYYY-MM-DD-{topic}.md`
 
+**Library research tools:**
+
+| Tool | Purpose |
+|------|---------|
+| `context7` | Documentation lookup for external libraries |
+| `btca_ask` | Source code search for library internals |
+
 ### 3. Implement
 
 Execute plan in git worktree for isolation:
@@ -104,34 +115,47 @@ Dependent tasks (must be sequential):
 - Task B's test relies on Task A's implementation
 ```
 
-#### Parallel Execution
+#### Parallel Execution (Fire-and-Check Pattern)
+
+The executor uses a **fire-and-check** pattern for maximum parallelism:
 
-Within a batch, all tasks run concurrently by spawning multiple subagents in a single message:
+1. **Fire** - Launch all implementers as `background_task` in ONE message
+2. **Poll** - Check `background_list` for completions
+3. **React** - Start reviewer immediately when each implementer finishes
+4. **Repeat** - Continue polling until batch complete
 
 ```
 Plan with 6 tasks:
 ├── Batch 1 (parallel): Tasks 1, 2, 3 → independent, different files
-│   ├── implementer: task 1 ─┐
-│   ├── implementer: task 2 ─┼─ spawn in ONE message
-│   └── implementer: task 3 ─┘
-│   [wait for all]
-│   ├── reviewer: task 1 ─┐
-│   ├── reviewer: task 2 ─┼─ spawn in ONE message
-│   └── reviewer: task 3 ─┘
-│   [wait for all]
+│   │
+│   │ FIRE: background_task(agent="implementer") x3
+│   │
+│   │ POLL: background_list() → task 2 completed!
+│   │ → background_output(task_2)
+│   │ → background_task(agent="reviewer", "Review task 2")
+│   │
+│   │ POLL: background_list() → tasks 1, 3 completed!
+│   │ → start reviewers for 1 and 3
+│   │
+│   │ [continue until all reviewed]
 │
 └── Batch 2 (parallel): Tasks 4, 5, 6 → depend on batch 1
     └── [same pattern]
 ```
 
+Key: Reviewers start **immediately** when their implementer finishes - no waiting for the whole batch.
+
 #### Per-Task Cycle
 
 Each task gets its own implement→review loop:
 
-1. Spawn implementer with task details
-2. Spawn reviewer to check implementation
-3. If changes requested → re-spawn implementer (max 3 cycles)
-4. Mark as DONE or BLOCKED
+1. Fire implementer via `background_task`
+2. Implementer: make changes → run tests → **commit** if passing
+3. Fire reviewer to check implementation
+4. If changes requested → fire new implementer (max 3 cycles)
+5. Mark as DONE or BLOCKED
+
+**Note:** Implementer commits after verification passes, using the commit message from the plan.
 
 ### 4. Session Continuity
 
@@ -233,10 +257,28 @@ Searches across:
 | `ast_grep_replace` | AST-aware code pattern replacement |
 | `look_at` | Extract file structure for large files |
 | `artifact_search` | Search past plans and ledgers |
-| `background_task` | Run long-running tasks in background |
-| `background_output` | Check background task status/output |
-| `background_cancel` | Cancel background tasks |
-| `background_list` | List all background tasks |
+| `btca_ask` | Query library source code (requires btca CLI) |
+| `background_task` | Fire subagent to run in background, returns task_id |
+| `background_list` | List all tasks and status (use to poll for completion) |
+| `background_output` | Get results from completed task |
+| `background_cancel` | Cancel running task(s) |
+
+### Background Task Pattern
+
+Research agents (brainstormer, planner, project-initializer) use the **fire-poll-collect** pattern. Executor uses **fire-and-check** (starts reviewers as implementers complete).
+
+```
+# FIRE: Launch all in ONE message
+task_1 = background_task(agent="locator", prompt="...")
+task_2 = background_task(agent="analyzer", prompt="...")
+
+# POLL: Check until complete
+background_list()  # repeat until all show "completed" or "error"
+
+# COLLECT: Get results (skip errored tasks)
+background_output(task_id=task_1)
+background_output(task_id=task_2)
+```
 
 ## Hooks
 

package.json

@@ -44,7 +44,7 @@
     "url": "https://github.com/vtemian/micode/issues"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.0.219"
+    "@opencode-ai/plugin": "^1.0.224"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.10",

src/agents/brainstormer.ts

@@ -13,34 +13,50 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
 <critical-rules>
   <rule priority="HIGHEST">ONE QUESTION AT A TIME: Ask exactly ONE question, then STOP and wait for the user's response. NEVER ask multiple questions in a single message. This is the most important rule.</rule>
   <rule>NO CODE: Never write code. Never provide code examples. Design only.</rule>
-  <rule>SUBAGENTS: Spawn multiple in parallel for codebase analysis.</rule>
-  <rule>TOOLS (grep, read, etc.): Do NOT use directly - use subagents instead.</rule>
+  <rule>BACKGROUND TASKS: Use background_task for parallel codebase analysis.</rule>
+  <rule>TOOLS (grep, read, etc.): Do NOT use directly - use background subagents instead.</rule>
 </critical-rules>
 
+<background-tools>
+  <tool name="background_task">Fire subagent tasks that run in parallel. Returns task_id immediately.</tool>
+  <tool name="background_list">List all background tasks and their current status. Use to poll for completion.</tool>
+  <tool name="background_output">Get results from a completed task. Only call after background_list shows task is done.</tool>
+</background-tools>
+
 <available-subagents>
-  <subagent name="codebase-locator" spawn="parallel">
-    Find files, modules, patterns. Spawn multiple with different queries.
-    Examples: "Find authentication code", "Find API routes", "Find config files"
+  <subagent name="codebase-locator" spawn="background_task">
+    Find files, modules, patterns. Fire multiple with different queries.
+    Example: background_task(agent="codebase-locator", prompt="Find authentication code", description="Find auth files")
+  </subagent>
+  <subagent name="codebase-analyzer" spawn="background_task">
+    Deep analysis of specific modules. Fire multiple for different areas.
+    Example: background_task(agent="codebase-analyzer", prompt="Analyze the auth module", description="Analyze auth")
   </subagent>
-  <subagent name="codebase-analyzer" spawn="parallel">
-    Deep analysis of specific modules. Spawn multiple for different areas.
-    Examples: "Analyze the auth module", "Explain the data layer"
+  <subagent name="pattern-finder" spawn="background_task">
+    Find existing patterns in codebase. Fire for different pattern types.
+    Example: background_task(agent="pattern-finder", prompt="Find error handling patterns", description="Find error patterns")
   </subagent>
-  <subagent name="pattern-finder" spawn="parallel">
-    Find existing patterns in codebase. Spawn for different pattern types.
-    Examples: "Find error handling patterns", "Find how similar features are implemented"
+  <subagent name="planner" spawn="Task" when="design approved">
+    Creates detailed implementation plan from validated design.
+    Example: Task(subagent_type="planner", prompt="Create implementation plan for [design path]", description="Create plan")
   </subagent>
 </available-subagents>
 
 <process>
-<phase name="understanding">
-  <action>Spawn subagents in PARALLEL to gather context:</action>
-  <spawn-example>
-    In a SINGLE message, spawn:
-    - codebase-locator: "Find files related to [topic]"
-    - codebase-analyzer: "Analyze existing [related feature]"
-    - pattern-finder: "Find patterns for [similar functionality]"
-  </spawn-example>
+<phase name="understanding" pattern="fire-poll-collect">
+  <action>Fire background tasks in PARALLEL to gather context:</action>
+  <fire-example>
+    In a SINGLE message, fire ALL background tasks:
+    background_task(agent="codebase-locator", prompt="Find files related to [topic]", description="Find [topic] files")
+    background_task(agent="codebase-analyzer", prompt="Analyze existing [related feature]", description="Analyze [feature]")
+    background_task(agent="pattern-finder", prompt="Find patterns for [similar functionality]", description="Find patterns")
+  </fire-example>
+  <poll>
+    background_list()  // repeat until all show "completed" or "error"
+  </poll>
+  <collect>
+    background_output(task_id=...) for each completed task (skip errored tasks)
+  </collect>
   <focus>purpose, constraints, success criteria</focus>
 </phase>
 
@@ -70,16 +86,29 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
   <action>Commit the design document to git</action>
   <action>Ask: "Ready for the planner to create a detailed implementation plan?"</action>
 </phase>
+
+<phase name="handoff" trigger="user approves design">
+  <action>When user says yes/approved/ready, IMMEDIATELY spawn the planner:</action>
+  <spawn>
+    Task(
+      subagent_type="planner",
+      prompt="Create a detailed implementation plan based on the design at thoughts/shared/designs/YYYY-MM-DD-{topic}-design.md",
+      description="Create implementation plan"
+    )
+  </spawn>
+  <rule>Do NOT ask again - if user approved, spawn planner immediately</rule>
+</phase>
 </process>
 
 <principles>
   <principle name="design-only">NO CODE. Describe components, not implementations. Planner writes code.</principle>
-  <principle name="subagents-first">ALWAYS use subagents for code analysis, NEVER tools directly</principle>
-  <principle name="parallel-spawn">Spawn multiple subagents in a SINGLE message</principle>
+  <principle name="background-tasks">Use background_task for parallel research, poll with background_list, collect with background_output</principle>
+  <principle name="parallel-fire">Fire ALL background tasks in a SINGLE message for true parallelism</principle>
   <principle name="one-question">Ask exactly ONE question per message. STOP after asking. Wait for user's answer before continuing. NEVER bundle multiple questions together.</principle>
   <principle name="yagni">Remove unnecessary features from ALL designs</principle>
   <principle name="explore-alternatives">ALWAYS propose 2-3 approaches before settling</principle>
   <principle name="incremental-validation">Present in sections, validate each before proceeding</principle>
+  <principle name="auto-handoff">When user approves design, IMMEDIATELY spawn planner - don't ask again</principle>
 </principles>
 
 <never-do>