deepflow 0.1.22 → 0.1.24

package/package.json

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

package/src/commands/df/execute.md

@@ -1,5 +1,15 @@
 # /df:execute — Execute Tasks from Plan
 
+## Orchestrator Role
+
+You spawn agents and poll results. You never implement.
+
+**NEVER:** Read source files, edit code, run tests, run git (except status), use `TaskOutput`
+
+**ONLY:** Read `PLAN.md` + `specs/doing-*.md`, spawn background agents, poll `.deepflow/results/`, update PLAN.md
+
+---
+
 ## Purpose
 Implement tasks from PLAN.md with parallel agents, atomic commits, and context-efficient execution.
 
@@ -28,17 +38,21 @@ Statusline writes to `.deepflow/context.json`: `{"percentage": 45}`
 
 ## Agent Protocol
 
-Agents write results to `.deepflow/results/{task_id}.yaml`:
+Every task = one background agent. Poll result files, never `TaskOutput`.
+
+```python
+Task(subagent_type="general-purpose", run_in_background=True, prompt="T1: ...")
+# Poll: Glob(".deepflow/results/T*.yaml")
+```
+
+Result file `.deepflow/results/{task_id}.yaml`:
 ```yaml
 task: T3
-status: success
+status: success|failed
 commit: abc1234
+summary: "one line"
 ```
 
-**Spawn with:** `run_in_background: true`
-**Poll:** `Glob(".deepflow/results/T*.yaml")`
-**NEVER use TaskOutput** — returns full trace, wastes context.
-
 ## Checkpoint & Resume
 
 **File:** `.deepflow/checkpoint.json` — stores completed tasks, current wave.
@@ -72,19 +86,24 @@ Warn if `specs/*.md` (excluding doing-/done-) exist. Non-blocking.
 
 Ready = `[ ]` + all `blocked_by` complete + not in checkpoint.
 
-### 5. CHECK CONTEXT & EXECUTE
+### 5. SPAWN AGENTS
 
-If context ≥50%: wait for agents, checkpoint, exit.
+Context ≥50%: checkpoint and exit.
 
-All ready tasks run in parallel. File conflicts execute sequentially.
+Spawn all ready tasks in ONE message (parallel). Same-file conflicts: sequential.
 
 On failure: spawn `reasoner`.
 
-### 6. PER-TASK (agent)
+### 6. PER-TASK (agent prompt)
 
-1. Read existing code patterns (if any)
-2. Implement following existing style
-3. Verify → commit → write result file
+```
+{task_id}: {description from PLAN.md}
+Files: {target files}
+Spec: {spec_name}
+
+Implement, test, commit as feat({spec}): {description}.
+Write result to .deepflow/results/{task_id}.yaml
+```
 
 ### 7. COMPLETE SPECS
 
@@ -99,13 +118,11 @@ Repeat until: all done, all blocked, or checkpoint.
 
 ## Rules
 
-| Rule | Enforcement |
-|------|-------------|
-| 1 task = 1 commit | `atomic-commits` skill |
-| No broken commits | Verify before commit |
-| 1 writer per file | Sequential if conflict |
-| Minimal returns | 5 lines max from agents |
-| Internal verification | Agents fix issues, don't report |
+| Rule | Detail |
+|------|--------|
+| 1 task = 1 agent = 1 commit | `atomic-commits` skill |
+| 1 file = 1 writer | Sequential if conflict |
+| Agents verify internally | Fix issues, don't report |
 
 ## Example
 

package/src/commands/df/spec.md

@@ -1,5 +1,15 @@
 # /df:spec — Generate Spec from Conversation
 
+## Orchestrator Role
+
+You coordinate agents and ask questions. You never search code directly.
+
+**NEVER:** Read source files, use Glob/Grep directly, run git
+
+**ONLY:** Spawn agents, poll results, ask user questions, write spec file
+
+---
+
 ## Purpose
 Transform conversation context into a structured specification file.
 
@@ -8,13 +18,29 @@ Transform conversation context into a structured specification file.
 /df:spec <name>
 ```
 
-## Skills
-Uses: `gap-discovery` — Proactive requirement gap identification
+## Skills & Agents
+- Skill: `gap-discovery` — Proactive requirement gap identification
+- Agent: `Explore` (haiku) — Codebase context gathering
+- Agent: `reasoner` (Opus) — Synthesize findings into requirements
 
 ## Behavior
 
-### 1. GAP CHECK
-Before generating, use the `gap-discovery` skill to analyze conversation.
+### 1. GATHER CODEBASE CONTEXT
+
+**Spawn Explore agents** (haiku, read-only, parallel) to find:
+- Related existing implementations
+- Code patterns and conventions
+- Integration points relevant to the feature
+- Existing TODOs or placeholders in related areas
+
+| Codebase Size | Agents |
+|---------------|--------|
+| <20 files | 2-3 |
+| 20-100 | 5-8 |
+| 100+ | 10-15 |
+
+### 2. GAP CHECK
+Use the `gap-discovery` skill to analyze conversation + agent findings.
 
 **Required clarity:**
 - [ ] Core objective clear
@@ -42,9 +68,17 @@ Before generating, use the `gap-discovery` skill to analyze conversation.
 
 Max 4 questions per tool call. Wait for answers before proceeding.
 
-### 2. GENERATE SPEC
+### 3. SYNTHESIZE FINDINGS
+
+**Spawn `reasoner` agent** (Opus) to:
+- Analyze codebase context from Explore agents
+- Identify constraints from existing architecture
+- Suggest requirements based on patterns found
+- Flag potential conflicts with existing code
+
+### 4. GENERATE SPEC
 
-Once gaps covered, create `specs/{name}.md`:
+Once gaps covered and context gathered, create `specs/{name}.md`:
 
 ```markdown
 # {Name}
@@ -70,10 +104,10 @@ Once gaps covered, create `specs/{name}.md`:
 - [ ] [Testable criterion 3]
 
 ## Technical Notes
-[Any implementation hints, preferred approaches, or context]
+[Implementation hints from codebase analysis — patterns, integration points, constraints discovered by agents]
 ```
 
-### 3. CONFIRM
+### 5. CONFIRM
 
 After writing:
 ```
@@ -86,17 +120,33 @@ Next: Run /df:plan to generate tasks
 ```
 
 ## Rules
+- **Orchestrator never searches** — Spawn agents for all codebase exploration
 - Do NOT generate spec if critical gaps remain
-- Ask maximum 5 questions per round (not overwhelming)
+- Ask maximum 4 questions per tool call (not overwhelming)
 - Requirements must be testable
 - Acceptance criteria must be verifiable
+- Include agent-discovered context in Technical Notes
 - Keep specs concise (<100 lines)
 
+## Agent Scaling
+
+| Agent | Base | Purpose |
+|-------|------|---------|
+| Explore (haiku) | 3-5 | Find related code, patterns |
+| Reasoner (Opus) | 1 | Synthesize into requirements |
+
 ## Example
 
 ```
 USER: I want to add image upload
 
+CLAUDE: [Spawns 3 Explore agents in parallel]
+- "Find existing file handling patterns"
+- "Find API endpoint conventions"
+- "Find storage service implementations"
+
+[Agents return: Express multer middleware, REST conventions, no cloud storage yet]
+
 CLAUDE: [Uses AskUserQuestion tool]
 {
   "questions": [
@@ -106,18 +156,7 @@ CLAUDE: [Uses AskUserQuestion tool]
       "multiSelect": true,
       "options": [
         {"label": "JPG/PNG only", "description": "Standard formats"},
-        {"label": "Include WebP", "description": "Modern compression"},
-        {"label": "Include GIF", "description": "Animated images"}
-      ]
-    },
-    {
-      "question": "What's the maximum upload size?",
-      "header": "Size limit",
-      "multiSelect": false,
-      "options": [
-        {"label": "5 MB", "description": "Fast uploads"},
-        {"label": "10 MB (Recommended)", "description": "Balanced"},
-        {"label": "25 MB", "description": "High-res photos"}
+        {"label": "Include WebP", "description": "Modern compression"}
       ]
     },
     {
@@ -126,29 +165,22 @@ CLAUDE: [Uses AskUserQuestion tool]
       "multiSelect": false,
       "options": [
         {"label": "S3 (Recommended)", "description": "Scalable cloud storage"},
-        {"label": "Local filesystem", "description": "Simple, single server"},
-        {"label": "Cloudflare R2", "description": "S3-compatible, no egress fees"}
-      ]
-    },
-    {
-      "question": "Who can upload files?",
-      "header": "Auth",
-      "multiSelect": false,
-      "options": [
-        {"label": "Logged-in users", "description": "Require authentication"},
-        {"label": "Public", "description": "Anyone can upload"},
-        {"label": "Role-based", "description": "Specific roles only"}
+        {"label": "Local filesystem", "description": "Simple, matches current setup"}
       ]
     }
   ]
 }
 
-USER: [Selects: JPG/PNG + WebP, 10MB, S3, Logged-in users]
+USER: [Selects: JPG/PNG + WebP, S3]
+
+CLAUDE: [Spawns reasoner agent]
+- Synthesize: multer + S3 + existing API patterns
 
 CLAUDE: ✓ Created specs/image-upload.md
 
 Requirements: 4
 Acceptance criteria: 5
+Technical notes: Express/multer pattern, REST conventions from existing API
 
 Next: Run /df:plan to generate tasks
 ```