deepflow 0.1.34 → 0.1.36

package/package.json

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

package/src/commands/df/execute.md

@@ -4,11 +4,9 @@
 
 You are a coordinator. Spawn agents, wait for results, update PLAN.md. Never implement code yourself.
 
-**NEVER:** Read source files, edit code, run tests, run git commands (except status), process TaskOutput content
+**NEVER:** Read source files, edit code, run tests, run git commands (except status), use TaskOutput
 
-**ONLY:** Read PLAN.md, read specs/doing-*.md, spawn background agents, use TaskOutput to wait (ignore its content), read `.deepflow/results/*.yaml` for outcomes, update PLAN.md
-
-**CONTEXT CRITICAL:** TaskOutput returns FULL agent transcripts (100KB+). NEVER include this in context. Agents write results to `.deepflow/results/{task_id}.yaml`. Read those files instead.
+**ONLY:** Read PLAN.md, read specs/doing-*.md, spawn background agents, wait with Bash monitor, read `.deepflow/results/*.yaml` for outcomes, update PLAN.md
 
 ---
 
@@ -45,28 +43,53 @@ Statusline writes to `.deepflow/context.json`: `{"percentage": 45}`
 
 ## Agent Protocol
 
-Each task = one background agent. **TaskOutput blocks until agent completes.** Never poll, loop, or repeatedly check for results.
+Each task = one background agent. **NEVER use TaskOutput** — it returns full transcripts (100KB+) that explode context.
 
-**CRITICAL: Context Management**
-- TaskOutput returns the FULL agent transcript (all tool calls, messages, etc.)
-- **DO NOT** process or include TaskOutput response in context — it will explode your token usage
-- **ONLY** use TaskOutput to wait for completion (ignore its content)
-- **ALWAYS** read the result file directly to get the actual outcome
+**Wait Strategy: Bash Monitor**
+- One Bash call that monitors result files
+- Shows progress via streaming (user sees in real-time)
+- Minimal context (just the final output)
+- User can react/cancel if needed
 
 ```python
-# Spawn agents in parallel (single message, multiple Task calls)
-task_id_1 = Task(subagent_type="general-purpose", run_in_background=True, prompt="T1: ...")
-task_id_2 = Task(subagent_type="general-purpose", run_in_background=True, prompt="T2: ...")
-
-# Wait for completion (single message, multiple TaskOutput calls)
-# TaskOutput BLOCKS — no polling needed
-# IGNORE the response content — read result files instead
-TaskOutput(task_id=task_id_1)
-TaskOutput(task_id=task_id_2)
-
-# Read actual results from files (minimal context usage)
+# 1. Spawn agents in parallel (single message, multiple Task calls)
+Task(subagent_type="general-purpose", run_in_background=True, prompt="T1: ...")
+Task(subagent_type="general-purpose", run_in_background=True, prompt="T2: ...")
+Task(subagent_type="general-purpose", run_in_background=True, prompt="T3: ...")
+
+# 2. Wait with Bash monitor (ONE call, streams progress to user)
+Bash("""
+RESULTS_DIR="{worktree}/.deepflow/results"
+EXPECTED=3
+TIMEOUT=300
+
+timeout $TIMEOUT bash -c '
+  seen=""
+  while [ $(ls "$0"/*.yaml 2>/dev/null | wc -l) -lt '$EXPECTED' ]; do
+    for f in "$0"/*.yaml 2>/dev/null; do
+      if [ -f "$f" ] && [[ ! "$seen" =~ "$f" ]]; then
+        echo "✓ $(basename "$f" .yaml)"
+        seen="$seen $f"
+      fi
+    done
+    sleep 5
+  done
+  echo "ALL COMPLETE"
+' "$RESULTS_DIR" || echo "TIMEOUT: some tasks did not complete"
+""")
+
+# 3. Read actual results (minimal context)
 Read("{worktree}/.deepflow/results/T1.yaml")
 Read("{worktree}/.deepflow/results/T2.yaml")
+Read("{worktree}/.deepflow/results/T3.yaml")
+```
+
+**User sees streaming:**
+```
+✓ T1
+✓ T3
+✓ T2
+ALL COMPLETE
 ```
 
 Result file `.deepflow/results/{task_id}.yaml`:
@@ -395,17 +418,15 @@ When all tasks done for a `doing-*` spec:
 
 ### 10. ITERATE
 
-After spawning agents, call TaskOutput for ALL running agents in a SINGLE message. **TaskOutput blocks—do NOT loop, poll, or check repeatedly.** One call per agent.
-
-**CRITICAL:** TaskOutput returns FULL agent transcripts. **IGNORE the response content** — it will explode context. Read result files instead.
+After spawning agents, use Bash monitor to wait. **NEVER use TaskOutput** — it explodes context.
 
 ```python
-# After spawning T1, T2, T3 in parallel, wait for all in parallel:
-TaskOutput(task_id=t1_id)  # BLOCKS until done — IGNORE response content
-TaskOutput(task_id=t2_id)  # BLOCKS until done — IGNORE response content
-TaskOutput(task_id=t3_id)  # BLOCKS until done — IGNORE response content
+# After spawning T1, T2, T3 in parallel:
+
+# 1. Wait with Bash monitor (streams progress to user)
+Bash("timeout 300 bash -c '...' ")  # See Agent Protocol for full script
 
-# Then read actual results (minimal context):
+# 2. Read results
 Read("{worktree}/.deepflow/results/T1.yaml")
 Read("{worktree}/.deepflow/results/T2.yaml")
 Read("{worktree}/.deepflow/results/T3.yaml")

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.