micode 0.5.2 → 0.6.0

package/README.md

@@ -45,13 +45,14 @@ 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 |
 |----------|---------|
@@ -59,17 +60,27 @@ Refine rough ideas into fully-formed designs through collaborative questioning.
 | `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
+
+All agents use the **fire-poll-collect** pattern for parallel work:
+
+```
+# 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"
+
+# COLLECT: Get results
+background_output(task_id=task_1)
+background_output(task_id=task_2)
+```
 
 ## Hooks
 

package/dist/index.js

@@ -24,34 +24,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"
+  </poll>
+  <collect>
+    background_output(task_id=...) for each completed task
+  </collect>
   <focus>purpose, constraints, success criteria</focus>
 </phase>
 
@@ -81,16 +97,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>
@@ -351,13 +380,24 @@ Every task is bite-sized (2-5 minutes), with exact paths and complete code.
 
 <critical-rules>
   <rule>FOLLOW THE DESIGN: The brainstormer's design is the spec. Do not explore alternatives.</rule>
-  <rule>SUBAGENTS: Spawn for implementation details (paths, signatures, line numbers).</rule>
-  <rule>TOOLS (grep, read, etc.): Do NOT use directly - use subagents instead.</rule>
+  <rule>BACKGROUND TASKS: Use background_task for parallel research (fire-and-collect pattern).</rule>
+  <rule>TOOLS (grep, read, etc.): Do NOT use directly - use background subagents instead.</rule>
   <rule>Every code example MUST be complete - never write "add validation here"</rule>
   <rule>Every file path MUST be exact - never write "somewhere in src/"</rule>
   <rule>Follow TDD: failing test \u2192 verify fail \u2192 implement \u2192 verify pass \u2192 commit</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>
+
+<fallback-rule>
+If background_task fails or is unavailable, fall back to Task() for sequential execution.
+Always prefer background_task for parallel research, but Task() works as a reliable fallback.
+</fallback-rule>
+
 <research-scope>
 Brainstormer did conceptual research (architecture, patterns, approaches).
 Your research is IMPLEMENTATION-LEVEL only:
@@ -375,18 +415,19 @@ All research must serve the design - never second-guess design decisions.
 </library-research>
 
 <available-subagents>
-  <subagent name="codebase-locator" spawn="parallel">
+  <subagent name="codebase-locator" spawn="background">
     Find exact file paths needed for implementation.
     Examples: "Find exact path to UserService", "Find test directory structure"
   </subagent>
-  <subagent name="codebase-analyzer" spawn="parallel">
+  <subagent name="codebase-analyzer" spawn="background">
     Get exact signatures and types for code examples.
     Examples: "Get function signature for createUser", "Get type definition for UserConfig"
   </subagent>
-  <subagent name="pattern-finder" spawn="parallel">
+  <subagent name="pattern-finder" spawn="background">
     Find exact patterns to copy in code examples.
     Examples: "Find exact test setup pattern", "Find exact error handling in similar endpoint"
   </subagent>
+  <fallback>If background_task unavailable, use Task() with same subagent types.</fallback>
 </available-subagents>
 
 <inputs>
@@ -402,15 +443,21 @@ All research must serve the design - never second-guess design decisions.
   <action>Note any constraints or decisions made by brainstormer</action>
 </phase>
 
-<phase name="implementation-research">
-  <action>Spawn subagents in PARALLEL to gather exact details:</action>
-  <spawn-example>
-    In a SINGLE message, spawn:
-    - codebase-locator: "Find exact path to [component from design]"
-    - codebase-locator: "Find test file naming convention"
-    - codebase-analyzer: "Get exact signature for [function mentioned in design]"
-    - pattern-finder: "Find exact test setup pattern for [type of test]"
-  </spawn-example>
+<phase name="implementation-research" pattern="fire-and-collect">
+  <action>Fire background tasks AND library research in parallel:</action>
+  <fire-phase description="Launch all research simultaneously">
+    In a SINGLE message, fire:
+    - background_task(agent="codebase-locator", prompt="Find exact path to [component]")
+    - background_task(agent="codebase-analyzer", prompt="Get signature for [function]")
+    - background_task(agent="pattern-finder", prompt="Find test setup pattern")
+    - context7_resolve-library-id + context7_query-docs for API docs
+    - btca_ask for library internals when needed
+  </fire-phase>
+  <collect-phase description="Poll until all complete, then collect">
+    - Poll with background_list until all tasks show completed
+    - Call background_output(task_id=...) for each completed task
+    - Combine all results for planning phase
+  </collect-phase>
   <rule>Only research what's needed to implement the design</rule>
   <rule>Never research alternatives to design decisions</rule>
 </phase>
@@ -502,6 +549,29 @@ git commit -m "feat(scope): add specific feature"
 </template>
 </output-format>
 
+<execution-example pattern="fire-and-collect">
+<step name="fire">
+// In a SINGLE message, fire all research tasks:
+background_task(agent="codebase-locator", prompt="Find UserService path")  // returns task_id_1
+background_task(agent="codebase-analyzer", prompt="Get createUser signature")  // returns task_id_2
+background_task(agent="pattern-finder", prompt="Find test setup pattern")  // returns task_id_3
+context7_resolve-library-id(libraryName="express")  // runs in parallel
+btca_ask(tech="express", question="middleware chain order")  // runs in parallel
+</step>
+<step name="collect">
+// Poll until all background tasks complete:
+background_list()  // check status of all tasks
+// When all show "completed":
+background_output(task_id=task_id_1)  // get result
+background_output(task_id=task_id_2)  // get result
+background_output(task_id=task_id_3)  // get result
+// context7 and btca_ask results already available from fire step
+</step>
+<step name="plan">
+// Use all collected results to write the implementation plan
+</step>
+</execution-example>
+
 <principles>
   <principle name="zero-context">Engineer knows nothing about our codebase</principle>
   <principle name="complete-code">Every code block is copy-paste ready</principle>
@@ -553,6 +623,7 @@ Execute the plan. Write code. Verify.
 <step>Verify preconditions match plan</step>
 <step>Make the changes</step>
 <step>Run verification (tests, lint, build)</step>
+<step>If verification passes: commit with message from plan</step>
 <step>Report results</step>
 </process>
 
@@ -566,8 +637,17 @@ Execute the plan. Write code. Verify.
 <check>Run tests if available</check>
 <check>Check for type errors</check>
 <check>Verify no regressions</check>
+<check>If all pass: git add and commit with plan's commit message</check>
 </after-each-change>
 
+<commit-rules>
+<rule>Commit ONLY after verification passes</rule>
+<rule>Use the commit message from the plan (e.g., "feat(scope): description")</rule>
+<rule>Stage only the files mentioned in the task</rule>
+<rule>If plan doesn't specify commit message, use: "feat(task): [task description]"</rule>
+<rule>Do NOT push - just commit locally</rule>
+</commit-rules>
+
 <output-format>
 <template>
 ## Task: [Description]
@@ -580,6 +660,8 @@ Execute the plan. Write code. Verify.
 - [x] Types check
 - [ ] Manual check needed: [what]
 
+**Commit**: \`[commit hash]\` - [commit message]
+
 **Issues**: None / [description]
 </template>
 </output-format>
@@ -708,16 +790,24 @@ var executorAgent = {
   model: "anthropic/claude-opus-4-5",
   temperature: 0.2,
   prompt: `<purpose>
-Execute plan tasks with maximum parallelism.
+Execute plan tasks with maximum parallelism using fire-and-check pattern.
 Each task gets its own implementer \u2192 reviewer cycle.
 Detect and parallelize independent tasks.
 </purpose>
 
-<workflow>
+<background-tools>
+You have access to background task management tools:
+- background_task: Fire a subagent to run in background, returns task_id immediately
+- background_output: Check status or get results from a background task
+- background_list: List all background tasks and their status
+</background-tools>
+
+<workflow pattern="fire-and-check">
 <step>Parse plan to extract individual tasks</step>
 <step>Analyze task dependencies to build execution graph</step>
 <step>Group tasks into parallel batches (independent tasks run together)</step>
-<step>For each batch: spawn implementer \u2192 reviewer per task IN PARALLEL</step>
+<step>Fire ALL implementers in batch as background_task</step>
+<step>Poll with background_list, start reviewer immediately when each implementer finishes</step>
 <step>Wait for batch to complete before starting dependent batch</step>
 <step>Aggregate results and report</step>
 </workflow>
@@ -737,83 +827,115 @@ Tasks are DEPENDENT (must be sequential) when:
 When uncertain, assume DEPENDENT (safer).
 </dependency-analysis>
 
-<execution-pattern>
-Example: 9 tasks where tasks 1-3 are independent, 4-6 depend on 1-3, 7-9 depend on 4-6
-
-Batch 1 (parallel):
-  - Spawn implementer for task 1 \u2192 reviewer
-  - Spawn implementer for task 2 \u2192 reviewer
-  - Spawn implementer for task 3 \u2192 reviewer
-  [Wait for all to complete]
-
-Batch 2 (parallel):
-  - Spawn implementer for task 4 \u2192 reviewer
-  - Spawn implementer for task 5 \u2192 reviewer
-  - Spawn implementer for task 6 \u2192 reviewer
-  [Wait for all to complete]
-
-Batch 3 (parallel):
-  - Spawn implementer for task 7 \u2192 reviewer
-  - Spawn implementer for task 8 \u2192 reviewer
-  - Spawn implementer for task 9 \u2192 reviewer
-  [Wait for all to complete]
+<execution-pattern name="fire-and-check">
+The fire-and-check pattern maximizes parallelism by:
+1. Firing all implementers as background tasks simultaneously
+2. Polling to detect completion as early as possible
+3. Starting each reviewer immediately when its implementer finishes
+4. Not waiting for all implementers before starting any reviewers
+
+Example: 3 independent tasks
+- Fire implementer 1, 2, 3 as background_task (all start immediately)
+- Poll with background_list
+- Task 2 finishes first \u2192 immediately start reviewer 2
+- Task 1 finishes \u2192 immediately start reviewer 1
+- Task 3 finishes \u2192 immediately start reviewer 3
+- Reviewers run in parallel as they're spawned
 </execution-pattern>
 
 <available-subagents>
-  <subagent name="implementer" spawn="parallel-per-task">
+  <subagent name="implementer">
     Executes ONE task from the plan.
     Input: Single task with context (which files, what to do).
     Output: Changes made and verification results for that task.
-    Invoke with: Task tool, subagent_type="implementer"
+    <invocation type="background">
+      background_task(description="Implement task 1", prompt="...", agent="implementer")
+    </invocation>
+    <invocation type="fallback">
+      Task(description="Implement task 1", prompt="...", subagent_type="implementer")
+    </invocation>
   </subagent>
-  <subagent name="reviewer" spawn="parallel-per-task">
+  <subagent name="reviewer">
     Reviews ONE task's implementation.
     Input: Single task's changes against its requirements.
     Output: APPROVED or CHANGES REQUESTED for that task.
-    Invoke with: Task tool, subagent_type="reviewer"
+    <invocation type="background">
+      background_task(description="Review task 1", prompt="...", agent="reviewer")
+    </invocation>
+    <invocation type="fallback">
+      Task(description="Review task 1", prompt="...", subagent_type="reviewer")
+    </invocation>
   </subagent>
 </available-subagents>
 
-<critical-instruction>
-You MUST use the Task tool to spawn implementer and reviewer subagents.
-Example: Task(description="Implement task 1", prompt="...", subagent_type="implementer")
-Do NOT try to implement or review yourself - delegate to subagents.
-</critical-instruction>
-
 <per-task-cycle>
 For each task:
-1. Spawn implementer with task details
-2. Wait for implementer to complete
-3. Spawn reviewer to check that task
-4. If reviewer requests changes: re-spawn implementer for fixes
+1. Fire implementer as background_task
+2. Poll until implementer completes
+3. Start reviewer immediately when implementer finishes
+4. If reviewer requests changes: fire new implementer for fixes
 5. Max 3 cycles per task before marking as blocked
 6. Report task status: DONE / BLOCKED
 </per-task-cycle>
 
-<parallel-spawning>
-Within a batch, spawn ALL implementers in a SINGLE message using the Task tool:
-
-Example for batch with tasks 1, 2, 3 - call Task tool 3 times in ONE message:
-- Task(description="Task 1", prompt="Execute task 1: [details]", subagent_type="implementer")
-- Task(description="Task 2", prompt="Execute task 2: [details]", subagent_type="implementer")
-- Task(description="Task 3", prompt="Execute task 3: [details]", subagent_type="implementer")
-
-Then after all complete, in ONE message call Task tool for reviewers:
-- Task(description="Review 1", prompt="Review task 1 implementation", subagent_type="reviewer")
-- Task(description="Review 2", prompt="Review task 2 implementation", subagent_type="reviewer")
-- Task(description="Review 3", prompt="Review task 3 implementation", subagent_type="reviewer")
-</parallel-spawning>
+<fire-and-check-loop>
+Within a batch:
+1. Fire ALL implementers as background_task in ONE message
+2. Enter polling loop:
+   a. Call background_list to check status of ALL tasks
+   b. For each newly completed task (status != "running"):
+      - Get result with background_output (task is already done)
+      - If implementer completed: start its reviewer as background_task
+      - If reviewer completed: check APPROVED or CHANGES REQUESTED
+   c. If changes needed and cycles < 3: fire new implementer
+   d. Sleep briefly, then repeat until all tasks done or blocked
+3. Move to next batch
+
+IMPORTANT: Always poll with background_list first to check status,
+then fetch results with background_output only for completed tasks.
+</fire-and-check-loop>
+
+<fallback-rule>
+If background_task fails or is unavailable, fall back to Task() tool:
+- Task(description="...", prompt="...", subagent_type="implementer")
+- Task(description="...", prompt="...", subagent_type="reviewer")
+The Task tool blocks until completion but still works correctly.
+</fallback-rule>
 
 <rules>
 <rule>Parse ALL tasks from plan before starting execution</rule>
 <rule>ALWAYS analyze dependencies before parallelizing</rule>
-<rule>Spawn parallel tasks in SINGLE message for true parallelism</rule>
+<rule>Fire parallel tasks as background_task for true parallelism</rule>
+<rule>Start reviewer immediately when its implementer finishes - don't wait for others</rule>
 <rule>Wait for entire batch before starting next batch</rule>
 <rule>Each task gets its own implement \u2192 review cycle</rule>
 <rule>Max 3 review cycles per task</rule>
 <rule>Continue with other tasks if one is blocked</rule>
 </rules>
 
+<execution-example pattern="fire-and-check">
+# Batch with tasks 1, 2, 3 (independent)
+
+## Step 1: Fire all implementers
+background_task(description="Task 1", prompt="Execute task 1: [details]", agent="implementer") \u2192 task_id_1
+background_task(description="Task 2", prompt="Execute task 2: [details]", agent="implementer") \u2192 task_id_2
+background_task(description="Task 3", prompt="Execute task 3: [details]", agent="implementer") \u2192 task_id_3
+
+## Step 2: Poll and react
+background_list() \u2192 shows task_id_2 completed
+background_output(task_id="task_id_2") \u2192 get result
+background_task(description="Review 2", prompt="Review task 2 implementation", agent="reviewer") \u2192 review_id_2
+
+background_list() \u2192 shows task_id_1, task_id_3 completed
+background_output(task_id="task_id_1") \u2192 get result
+background_output(task_id="task_id_3") \u2192 get result
+background_task(description="Review 1", prompt="Review task 1 implementation", agent="reviewer") \u2192 review_id_1
+background_task(description="Review 3", prompt="Review task 3 implementation", agent="reviewer") \u2192 review_id_3
+
+## Step 3: Continue polling until all reviews complete
+...
+</execution-example>
+
 <output-format>
 <template>
 ## Execution Complete
@@ -848,11 +970,13 @@ Then after all complete, in ONE message call Task tool for reviewers:
 </output-format>
 
 <never-do>
+<forbidden>NEVER call background_output on running tasks - always poll with background_list first</forbidden>
 <forbidden>Never skip dependency analysis</forbidden>
 <forbidden>Never spawn dependent tasks in parallel</forbidden>
 <forbidden>Never skip reviewer for any task</forbidden>
 <forbidden>Never continue past 3 cycles for a single task</forbidden>
 <forbidden>Never report success if any task is blocked</forbidden>
+<forbidden>Never wait for all implementers before starting any reviewer</forbidden>
 </never-do>`
 };
 
@@ -986,7 +1110,7 @@ var PROMPT2 = `
 
   <critical-rule>
     MAXIMIZE PARALLELISM. Speed is critical.
-    - Spawn multiple agents simultaneously
+    - Fire ALL background tasks simultaneously
     - Run multiple tool calls in single message
     - Never wait for one thing when you can do many
   </critical-rule>
@@ -999,16 +1123,33 @@ var PROMPT2 = `
     </outputs>
   </task>
 
-  <parallel-execution-strategy>
-    <phase name="1-discovery" parallel="true">
-      <description>Spawn ALL discovery tasks simultaneously</description>
-      <spawn-agents>
+  <background-tools>
+    <tool name="background_task">
+      Fire a subagent to run in background. Returns task_id immediately.
+      Parameters: description, prompt, agent (subagent type)
+      Example: background_task(description="Find entry points", prompt="Find all entry points", agent="codebase-locator")
+    </tool>
+    <tool name="background_list">
+      List all background tasks and their status. Use to poll for completion.
+      No parameters required.
+    </tool>
+    <tool name="background_output">
+      Get results from a completed task. Only call after background_list shows task is done.
+      Parameters: task_id
+      Example: background_output(task_id="abc123")
+    </tool>
+  </background-tools>
+
+  <parallel-execution-strategy pattern="fire-and-collect">
+    <phase name="1-fire" description="Fire ALL tasks simultaneously">
+      <description>Launch ALL discovery agents + run tools in a SINGLE message</description>
+      <fire-agents>
         <agent name="codebase-locator">Find entry points, configs, main modules</agent>
         <agent name="codebase-locator">Find test files and test patterns</agent>
         <agent name="codebase-locator">Find linter, formatter, CI configs</agent>
         <agent name="codebase-analyzer">Analyze directory structure</agent>
         <agent name="pattern-finder">Find naming conventions across files</agent>
-      </spawn-agents>
+      </fire-agents>
       <parallel-tools>
         <tool>Glob for package.json, pyproject.toml, go.mod, Cargo.toml, etc.</tool>
         <tool>Glob for *.config.*, .eslintrc*, .prettierrc*, ruff.toml, etc.</tool>
@@ -1017,13 +1158,20 @@ var PROMPT2 = `
       </parallel-tools>
     </phase>
 
-    <phase name="2-deep-analysis" parallel="true">
-      <description>Analyze core modules in parallel</description>
-      <spawn-agents>
+    <phase name="2-collect" description="Poll and collect all results">
+      <description>Poll background_list until all tasks complete, then collect with background_output</description>
+      <action>Poll background_list until all tasks show "completed"</action>
+      <action>Call background_output for each completed task</action>
+      <action>Process tool results from phase 1</action>
+    </phase>
+
+    <phase name="3-deep-analysis" description="Fire deep analysis tasks">
+      <description>Based on discovery, fire more background tasks</description>
+      <fire-agents>
         <agent name="codebase-analyzer">Analyze core/domain logic</agent>
         <agent name="codebase-analyzer">Analyze API/entry points</agent>
         <agent name="codebase-analyzer">Analyze data layer</agent>
-      </spawn-agents>
+      </fire-agents>
       <parallel-tools>
         <tool>Read 5 core source files simultaneously</tool>
         <tool>Read 3 test files simultaneously</tool>
@@ -1031,8 +1179,9 @@ var PROMPT2 = `
       </parallel-tools>
     </phase>
 
-    <phase name="3-write" parallel="true">
-      <description>Write both files in parallel</description>
+    <phase name="4-collect-and-write" description="Collect and write output">
+      <description>Collect deep analysis results, then write both files</description>
+      <action>Collect all deep analysis results</action>
       <action>Write ARCHITECTURE.md</action>
       <action>Write CODE_STYLE.md</action>
     </phase>
@@ -1042,23 +1191,37 @@ var PROMPT2 = `
     <subagent name="codebase-locator" spawn="multiple">
       Fast file/pattern finder. Spawn multiple with different queries.
       Examples: "Find all entry points", "Find all config files", "Find test directories"
-      Invoke with: Task tool, subagent_type="codebase-locator"
+      
+      Background: background_task(description="Find entry points", prompt="Find all entry points and main files", agent="codebase-locator")
+      Fallback: Task(description="Find entry points", prompt="Find all entry points and main files", subagent_type="codebase-locator")
     </subagent>
     <subagent name="codebase-analyzer" spawn="multiple">
       Deep module analyzer. Spawn multiple for different areas.
       Examples: "Analyze src/core", "Analyze api layer", "Analyze database module"
-      Invoke with: Task tool, subagent_type="codebase-analyzer"
+      
+      Background: background_task(description="Analyze core", prompt="Analyze the core module", agent="codebase-analyzer")
+      Fallback: Task(description="Analyze core", prompt="Analyze the core module", subagent_type="codebase-analyzer")
     </subagent>
     <subagent name="pattern-finder" spawn="multiple">
       Pattern extractor. Spawn for different pattern types.
       Examples: "Find naming patterns", "Find error handling patterns", "Find async patterns"
-      Invoke with: Task tool, subagent_type="pattern-finder"
+      
+      Background: background_task(description="Find patterns", prompt="Find naming conventions", agent="pattern-finder")
+      Fallback: Task(description="Find patterns", prompt="Find naming conventions", subagent_type="pattern-finder")
     </subagent>
   </available-subagents>
 
+  <fallback-rule>
+    If background_task fails or is unavailable, fall back to Task() tool.
+    The Task tool provides synchronous subagent execution.
+    Example fallback: Task(description="Find entry points", prompt="Find all entry points", subagent_type="codebase-locator")
+  </fallback-rule>
+
   <critical-instruction>
-  You MUST use the Task tool to spawn subagents. Call multiple Task tools in a SINGLE message for parallelism.
-  Example: Task(description="Find entry points", prompt="Find all entry points and main files", subagent_type="codebase-locator")
+    Use background_task to fire subagents for TRUE parallelism.
+    Fire ALL background_task calls in a SINGLE message.
+    Then poll with background_list until all complete, and collect with background_output.
+    This is the fire-and-collect pattern - fire everything, poll, then collect everything.
   </critical-instruction>
 
   <language-detection>
@@ -1124,10 +1287,10 @@ var PROMPT2 = `
 
   <rules>
     <category name="Speed">
-      <rule>ALWAYS spawn multiple agents in a SINGLE message</rule>
+      <rule>ALWAYS fire multiple background_task calls in a SINGLE message</rule>
       <rule>ALWAYS run multiple tool calls in a SINGLE message</rule>
       <rule>NEVER wait for one task when you can start others</rule>
-      <rule>Batch related queries into parallel agent spawns</rule>
+      <rule>Use fire-and-collect: fire all, then collect all</rule>
     </category>
 
     <category name="Analysis">
@@ -1152,27 +1315,40 @@ var PROMPT2 = `
     </category>
   </rules>
 
-  <execution-example>
-    <step description="Start with maximum parallelism">
-      In a SINGLE message, call Task tool multiple times AND run other tools:
-      - Task(description="Find entry points", prompt="Find all entry points and main files", subagent_type="codebase-locator")
-      - Task(description="Find configs", prompt="Find all config files (linters, formatters, build)", subagent_type="codebase-locator")
-      - Task(description="Find tests", prompt="Find test directories and test files", subagent_type="codebase-locator")
-      - Task(description="Analyze structure", prompt="Analyze the directory structure and organization", subagent_type="codebase-analyzer")
-      - Task(description="Find patterns", prompt="Find naming conventions used across the codebase", subagent_type="pattern-finder")
+  <execution-example pattern="fire-and-collect">
+    <step description="FIRE: Launch all discovery tasks simultaneously">
+      In a SINGLE message, fire ALL background_task calls AND run other tools:
+      - background_task(description="Find entry points", prompt="Find all entry points and main files", agent="codebase-locator") -> task_id_1
+      - background_task(description="Find configs", prompt="Find all config files (linters, formatters, build)", agent="codebase-locator") -> task_id_2
+      - background_task(description="Find tests", prompt="Find test directories and test files", agent="codebase-locator") -> task_id_3
+      - background_task(description="Analyze structure", prompt="Analyze the directory structure and organization", agent="codebase-analyzer") -> task_id_4
+      - background_task(description="Find patterns", prompt="Find naming conventions used across the codebase", agent="pattern-finder") -> task_id_5
       - Glob: package.json, pyproject.toml, go.mod, Cargo.toml, etc.
       - Glob: README*, ARCHITECTURE*, docs/*
     </step>
 
-    <step description="Parallel deep analysis">
-      Based on discovery, in a SINGLE message:
-      - Task for each major module: subagent_type="codebase-analyzer"
+    <step description="COLLECT: Poll and gather all results">
+      First poll until all tasks complete:
+      - background_list()  // repeat until all show "completed"
+      Then collect ALL results:
+      - background_output(task_id=task_id_1)
+      - background_output(task_id=task_id_2)
+      - background_output(task_id=task_id_3)
+      - background_output(task_id=task_id_4)
+      - background_output(task_id=task_id_5)
+    </step>
+
+    <step description="FIRE: Deep analysis based on discovery">
+      Based on discovery, in a SINGLE message fire more tasks:
+      - background_task for each major module: agent="codebase-analyzer"
       - Read multiple source files simultaneously
       - Read multiple test files simultaneously
     </step>
 
-    <step description="Parallel write">
-      Write ARCHITECTURE.md and CODE_STYLE.md
+    <step description="COLLECT and WRITE">
+      Collect deep analysis results, then write:
+      - Write ARCHITECTURE.md
+      - Write CODE_STYLE.md
     </step>
   </execution-example>
 </agent>
@@ -15495,6 +15671,7 @@ function createArtifactAutoIndexHook(_ctx) {
 
 // src/tools/background-task/manager.ts
 var POLL_INTERVAL_MS = 2000;
+var TASK_TTL_MS = 60 * 60 * 1000;
 function generateTaskId() {
   const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
   let result = "bg_";
@@ -15556,6 +15733,7 @@ class BackgroundTaskManager {
       },
       query: { directory: this.ctx.directory }
     }).catch((error45) => {
+      console.error(`[background-task] Failed to prompt session ${sessionID}:`, error45);
       task.status = "error";
       task.error = error45 instanceof Error ? error45.message : String(error45);
       task.completedAt = new Date;
@@ -15573,7 +15751,9 @@ class BackgroundTaskManager {
       this.ctx.client.session.abort({
         path: { id: task.sessionID },
         query: { directory: this.ctx.directory }
-      }).catch(() => {});
+      }).catch((error45) => {
+        console.error(`[background-task] Failed to abort session ${task.sessionID}:`, error45);
+      });
       task.status = "cancelled";
       task.completedAt = new Date;
       this.markForNotification(task);
@@ -15615,20 +15795,18 @@ class BackgroundTaskManager {
         path: { id: task.sessionID },
         query: { directory: this.ctx.directory }
       });
-      const messages = resp.data || [];
-      const lastAssistant = [...messages].reverse().find((m) => {
-        const msg = m;
-        const info = msg.info;
-        return info?.role === "assistant";
-      });
+      const messagesResp = resp;
+      const messages = messagesResp.data || [];
+      const lastAssistant = [...messages].reverse().find((m) => m.info?.role === "assistant");
       if (lastAssistant) {
-        const parts = lastAssistant.parts;
-        const textParts = parts?.filter((p) => p.type === "text") || [];
+        const textParts = lastAssistant.parts?.filter((p) => p.type === "text") || [];
         task.result = textParts.map((p) => p.text || "").join(`
 `);
         return task.result;
       }
-    } catch {}
+    } catch (error45) {
+      console.error(`[background-task] Failed to fetch result for task ${taskId}:`, error45);
+    }
     return;
   }
   formatTaskStatus(task) {
@@ -15660,13 +15838,6 @@ class BackgroundTaskManager {
       output += `
 ### Error
 ${task.error}
-`;
-    }
-    if (task.progress?.lastMessage) {
-      const preview = task.progress.lastMessage.length > 200 ? `${task.progress.lastMessage.slice(0, 200)}...` : task.progress.lastMessage;
-      output += `
-### Last Message Preview
-${preview}
 `;
     }
     return output;
@@ -15684,7 +15855,19 @@ ${preview}
       this.pollingInterval = undefined;
     }
   }
+  cleanupOldTasks() {
+    const now = Date.now();
+    for (const [taskId, task] of this.tasks) {
+      if (task.status === "running")
+        continue;
+      const completedAt = task.completedAt?.getTime() || 0;
+      if (now - completedAt > TASK_TTL_MS) {
+        this.tasks.delete(taskId);
+      }
+    }
+  }
   async pollRunningTasks() {
+    this.cleanupOldTasks();
     const runningTasks = this.getRunningTasks();
     if (runningTasks.length === 0) {
       this.stopPolling();
@@ -15710,9 +15893,12 @@ ${preview}
               variant: "success",
               duration: 5000
             }
-          }).catch(() => {});
+          }).catch((error45) => {
+            console.error(`[background-task] Failed to show toast for task ${task.id}:`, error45);
+          });
         }
-      } catch {
+      } catch (error45) {
+        console.error(`[background-task] Failed to poll task ${task.id}:`, error45);
         if (task.status === "running") {
           task.status = "error";
           task.error = "Session lost";
@@ -15801,27 +15987,17 @@ Use \`background_output\` with task_id="${task.id}" to check progress or get res
     }
   });
   const background_output = tool({
-    description: `Check status or get results from a background task.
-By default returns immediately with current status.
-Set block=true to wait for completion (with timeout).`,
+    description: `Get status or results from a background task.
+Returns immediately with current status. Use background_list to poll for completion.`,
     args: {
-      task_id: tool.schema.string().describe("ID of the task to check (e.g., 'bg_abc12345')"),
-      block: tool.schema.boolean().optional().describe("Wait for task completion (default: false)"),
-      timeout: tool.schema.number().optional().describe("Max seconds to wait if blocking (default: 60, max: 600)")
+      task_id: tool.schema.string().describe("ID of the task to check (e.g., 'bg_abc12345')")
     },
     execute: async (args) => {
-      const { task_id, block = false, timeout = 60 } = args;
+      const { task_id } = args;
       const task = manager.getTask(task_id);
       if (!task) {
         return `Task not found: ${task_id}`;
       }
-      if (block && task.status === "running") {
-        const maxWait = Math.min(timeout || 60, 600) * 1000;
-        const startTime = Date.now();
-        while (task.status === "running" && Date.now() - startTime < maxWait) {
-          await new Promise((resolve2) => setTimeout(resolve2, 1000));
-        }
-      }
       let output = manager.formatTaskStatus(task);
       if (task.status === "completed") {
         const result = await manager.getTaskResult(task_id);

package/dist/tools/background-task/manager.d.ts

@@ -16,6 +16,7 @@ export declare class BackgroundTaskManager {
     formatTaskStatus(task: BackgroundTask): string;
     private startPolling;
     private stopPolling;
+    private cleanupOldTasks;
     private pollRunningTasks;
     private markForNotification;
     getPendingNotifications(parentSessionID: string): BackgroundTask[];

package/dist/tools/background-task/tools.d.ts

@@ -17,13 +17,9 @@ export declare function createBackgroundTaskTools(manager: BackgroundTaskManager
         description: string;
         args: {
             task_id: import("zod").ZodString;
-            block: import("zod").ZodOptional<import("zod").ZodBoolean>;
-            timeout: import("zod").ZodOptional<import("zod").ZodNumber>;
         };
         execute(args: {
             task_id: string;
-            block?: boolean | undefined;
-            timeout?: number | undefined;
         }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
     };
     background_cancel: {

package/dist/tools/background-task/types.d.ts

@@ -15,7 +15,6 @@ export interface BackgroundTask {
         toolCalls: number;
         lastTool?: string;
         lastUpdate: Date;
-        lastMessage?: string;
     };
 }
 export interface BackgroundTaskInput {
@@ -25,3 +24,30 @@ export interface BackgroundTaskInput {
     parentSessionID: string;
     parentMessageID: string;
 }
+export interface SessionCreateResponse {
+    data?: {
+        id?: string;
+    };
+}
+export interface SessionGetResponse {
+    data?: {
+        status?: "idle" | "running" | "error";
+    };
+}
+export interface MessagePart {
+    type: string;
+    text?: string;
+}
+export interface MessageInfo {
+    role?: "user" | "assistant";
+    sessionID?: string;
+    type?: string;
+    name?: string;
+}
+export interface SessionMessage {
+    info?: MessageInfo;
+    parts?: MessagePart[];
+}
+export interface SessionMessagesResponse {
+    data?: SessionMessage[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "micode",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "OpenCode plugin with Brainstorm-Research-Plan-Implement workflow",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -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",