deepflow 0.1.35 → 0.1.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "description": "Stay in flow state - lightweight spec-driven task orchestration for Claude Code",
   "keywords": [
     "claude",

package/src/commands/df/plan.md

@@ -81,15 +81,19 @@ Include patterns in task descriptions for agents to follow.
 
 ### 4. ANALYZE CODEBASE
 
-**Spawn ALL Explore agents in ONE message, then wait for ALL with TaskOutput in ONE message:**
-```
-// Spawn all in single message:
-t1 = Task(subagent_type="Explore", model="haiku", run_in_background=true, prompt="...")
-t2 = Task(subagent_type="Explore", model="haiku", run_in_background=true, prompt="...")
+**NEVER use `run_in_background` for Explore agents** — causes late "Agent completed" notifications that pollute output after work is done.
+
+**NEVER use TaskOutput** — returns full agent transcripts (100KB+) that explode context.
 
-// Wait all in single message:
-TaskOutput(task_id=t1)
-TaskOutput(task_id=t2)
+**Spawn ALL Explore agents in ONE message (non-background, parallel):**
+
+```python
+# All in single message — runs in parallel, blocks until all complete:
+Task(subagent_type="Explore", model="haiku", prompt="Find: ...")
+Task(subagent_type="Explore", model="haiku", prompt="Find: ...")
+Task(subagent_type="Explore", model="haiku", prompt="Find: ...")
+# Each returns agent's final message only (not full transcript)
+# No late notifications — agents complete before orchestrator proceeds
 ```
 
 Scale agent count based on codebase size:
@@ -104,6 +108,7 @@ Scale agent count based on codebase size:
 **Explore Agent Prompt Structure:**
 ```
 Find: [specific question]
+
 Return ONLY:
 - File paths matching criteria
 - One-line description per file
@@ -216,6 +221,8 @@ Append tasks grouped by `### doing-{spec-name}`. Include spec gaps and validatio
 `✓ Plan generated — {n} specs, {n} tasks. Run /df:execute`
 
 ## Rules
+- **Never use TaskOutput** — Returns full transcripts that explode context
+- **Never use run_in_background for Explore agents** — Causes late notifications that pollute output
 - **Spike-first** — Generate spike task before full implementation if no `--passed.md` experiment exists
 - **Block on spike** — Full implementation tasks MUST be blocked by spike validation
 - **Learn from failures** — Extract "next hypothesis" from failed experiments, never repeat same approach

package/src/commands/df/spec.md

@@ -4,9 +4,9 @@
 
 You coordinate agents and ask questions. You never search code directly.
 
-**NEVER:** Read source files, use Glob/Grep directly, run git
+**NEVER:** Read source files, use Glob/Grep directly, run git, use TaskOutput
 
-**ONLY:** Spawn agents, use TaskOutput to get results, ask user questions, write spec file
+**ONLY:** Spawn agents (non-background), ask user questions, write spec file
 
 ---
 
@@ -31,15 +31,19 @@ Transform conversation context into a structured specification file.
 
 ### 1. GATHER CODEBASE CONTEXT
 
-**Spawn ALL Explore agents in ONE message, then wait for ALL with TaskOutput in ONE message:**
-```
-// Spawn all in single message:
-t1 = Task(subagent_type="Explore", model="haiku", run_in_background=true, prompt="...")
-t2 = Task(subagent_type="Explore", model="haiku", run_in_background=true, prompt="...")
+**NEVER use `run_in_background` for Explore agents** — causes late "Agent completed" notifications that pollute output after work is done.
+
+**NEVER use TaskOutput** — returns full agent transcripts (100KB+) that explode context.
 
-// Wait all in single message:
-TaskOutput(task_id=t1)
-TaskOutput(task_id=t2)
+**Spawn ALL Explore agents in ONE message (non-background, parallel):**
+
+```python
+# All in single message — runs in parallel, blocks until all complete:
+Task(subagent_type="Explore", model="haiku", prompt="Find: ...")
+Task(subagent_type="Explore", model="haiku", prompt="Find: ...")
+Task(subagent_type="Explore", model="haiku", prompt="Find: ...")
+# Each returns agent's final message only (not full transcript)
+# No late notifications — agents complete before orchestrator proceeds
 ```
 
 Find:
@@ -57,6 +61,7 @@ Find:
 **Explore Agent Prompt Structure:**
 ```
 Find: [specific question]
+
 Return ONLY:
 - File paths matching criteria
 - One-line description per file

package/src/commands/df/verify.md

@@ -83,6 +83,8 @@ Files: ...
 Default: L1-L3 (L4 optional, can be slow)
 
 ## Rules
+- **Never use TaskOutput** — Returns full transcripts that explode context
+- **Never use run_in_background for Explore agents** — Causes late notifications that pollute output
 - Verify against spec, not assumptions
 - Flag partial implementations
 - Report TODO/FIXME as quality issues
@@ -91,15 +93,18 @@ Default: L1-L3 (L4 optional, can be slow)
 
 ## Agent Usage
 
-**Spawn ALL Explore agents in ONE message, then wait for ALL with TaskOutput in ONE message:**
-```
-// Spawn all in single message:
-t1 = Task(subagent_type="Explore", model="haiku", run_in_background=true, prompt="...")
-t2 = Task(subagent_type="Explore", model="haiku", run_in_background=true, prompt="...")
+**NEVER use `run_in_background` for Explore agents** — causes late "Agent completed" notifications that pollute output after work is done.
+
+**NEVER use TaskOutput** — returns full agent transcripts (100KB+) that explode context.
+
+**Spawn ALL Explore agents in ONE message (non-background, parallel):**
 
-// Wait all in single message:
-TaskOutput(task_id=t1)
-TaskOutput(task_id=t2)
+```python
+# All in single message — runs in parallel, blocks until all complete:
+Task(subagent_type="Explore", model="haiku", prompt="Find: ...")
+Task(subagent_type="Explore", model="haiku", prompt="Find: ...")
+# Each returns agent's final message only (not full transcript)
+# No late notifications — agents complete before orchestrator proceeds
 ```
 
 Scale: 1-2 agents per spec, cap 10.