deepflow 0.1.49 → 0.1.51

package/src/commands/df/spec.md

@@ -31,28 +31,11 @@ Transform conversation context into a structured specification file.
 
 ### 1. GATHER CODEBASE CONTEXT
 
-**Check for debate file first:** If `specs/.debate-{name}.md` exists, read it using the Read tool. Pass its content (especially the Synthesis section) to the reasoner agent in step 3 as additional context. The debate file contains multi-perspective analysis that should inform requirements and constraints.
+**Check for debate file first:** If `specs/.debate-{name}.md` exists, read it using the Read tool. Pass its content (especially the Synthesis section) to the reasoner agent in step 3 as additional context.
 
-**NEVER use `run_in_background` for Explore agents** — causes late "Agent completed" notifications that pollute output after work is done.
+Follow `templates/explore-agent.md` for spawn rules, prompt structure, and scope restrictions.
 
-**NEVER use TaskOutput** — returns full agent transcripts (100KB+) that explode context.
-
-**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:
-- Related existing implementations
-- Code patterns and conventions
-- Integration points relevant to the feature
-- Existing TODOs or placeholders in related areas
+Find: related implementations, code patterns/conventions, integration points, existing TODOs.
 
 | Codebase Size | Agents |
 |---------------|--------|
@@ -60,35 +43,6 @@ Find:
 | 20-100 | 5-8 |
 | 100+ | 10-15 |
 
-**Explore Agent Prompt Structure:**
-```
-Find: [specific question]
-
-Return ONLY:
-- File paths matching criteria
-- One-line description per file
-- Integration points (if asked)
-
-DO NOT:
-- Read or summarize spec files
-- Make recommendations
-- Propose solutions
-- Generate tables or lengthy explanations
-
-Max response: 500 tokens (configurable via .deepflow/config.yaml explore.max_tokens)
-```
-
-**Explore Agent Scope Restrictions:**
-- MUST only report factual findings:
-  - Files found
-  - Patterns/conventions observed
-  - Integration points
-- MUST NOT:
-  - Make recommendations
-  - Propose architectures
-  - Read and summarize specs (that's orchestrator's job)
-  - Draw conclusions about what should be built
-
 ### 2. GAP CHECK
 Use the `gap-discovery` skill to analyze conversation + agent findings.
 
@@ -176,18 +130,6 @@ Acceptance criteria: {count}
 Next: Run /df:plan to generate tasks
 ```
 
-### 6. CAPTURE DECISIONS
-
-Extract up to 4 candidate decisions (requirements chosen, constraints accepted). Use `AskUserQuestion` with `multiSelect: true`:
-- `label`: `[APPROACH|PROVISIONAL|ASSUMPTION] <decision>`
-- `description`: rationale
-
-Append each confirmed selection to `.deepflow/decisions.md` (create if absent):
-```
-### {YYYY-MM-DD} — spec
-- [TAG] <decision> — <rationale>
-```
-
 ## Rules
 - **Orchestrator never searches** — Spawn agents for all codebase exploration
 - Do NOT generate spec if critical gaps remain

package/src/commands/df/verify.md

@@ -7,9 +7,9 @@ Check that implemented code satisfies spec requirements and acceptance criteria.
 
 ## Usage
 ```
-/df:verify                  # Verify all done-* specs
-/df:verify --doing          # Also verify in-progress specs
-/df:verify done-upload      # Verify specific spec
+/df:verify                  # Verify doing-* specs with all tasks completed
+/df:verify doing-upload     # Verify specific spec
+/df:verify --re-verify      # Re-verify done-* specs (already merged)
 ```
 
 ## Skills & Agents
@@ -20,31 +20,30 @@ Check that implemented code satisfies spec requirements and acceptance criteria.
 |-------|---------------|-------|---------|
 | Scanner | `Explore` | `haiku` | Fast codebase scanning |
 
+Follow `templates/explore-agent.md` for all Explore agent spawning. Scale: 1-2 agents per spec, cap 10.
+
 ## Spec File States
 
 ```
 specs/
   feature.md        → Unplanned (skip)
-  doing-auth.md     → In progress (verify with --doing)
-  done-upload.md    → Completed (default verify target)
+  doing-auth.md     → Executed, ready for verification (default target)
+  done-upload.md    → Already verified and merged (--re-verify only)
 ```
 
 ## Behavior
 
 ### 1. LOAD CONTEXT
 
-```
-Load:
-- specs/done-*.md (completed specs to verify)
-- specs/doing-*.md (if --doing flag)
-- Source code (actual implementation)
-```
+Load: `specs/doing-*.md`, `PLAN.md`, source code. Load `specs/done-*.md` only if `--re-verify`.
 
-If no done-* specs: report counts, suggest `--doing`.
+**Readiness check:** For each `doing-*` spec, check PLAN.md:
+- All tasks `[x]` → ready (proceed)
+- Some tasks `[ ]` → warn: "⚠ {spec} has {n} incomplete tasks. Run /df:execute first."
 
-### 1.5. DETECT PROJECT COMMANDS
+If no `doing-*` specs found: report counts, suggest `/df:execute`.
 
-Detect build and test commands by inspecting project files in the worktree.
+### 1.5. DETECT PROJECT COMMANDS
 
 **Config override always wins.** If `.deepflow/config.yaml` has `quality.test_command` or `quality.build_command`, use those.
 
@@ -58,7 +57,6 @@ Detect build and test commands by inspecting project files in the worktree.
 | `go.mod` | `go build ./...` | `go test ./...` |
 | `Makefile` with `test` target | `make build` (if target exists) | `make test` |
 
-**Output:**
 - Commands found: `Build: npm run build | Test: npm test`
 - Nothing found: `⚠ No build/test commands detected. L0/L4 skipped. Set quality.test_command in .deepflow/config.yaml`
 
@@ -68,10 +66,7 @@ Detect build and test commands by inspecting project files in the worktree.
 
 Run the build command in the worktree:
 - Exit code 0 → L0 pass, continue to L1-L3
-- Exit code non-zero → L0 FAIL
-  - Report: "✗ L0: Build failed" with last 30 lines of output
-  - Add fix task: "Fix build errors" to PLAN.md
-  - Do NOT proceed to L1-L4 (no point checking if code doesn't build)
+- Exit code non-zero → L0 FAIL: report "✗ L0: Build failed" with last 30 lines, add fix task to PLAN.md, stop (skip L1-L4)
 
 **L1-L3: Static analysis** (via Explore agents)
 
@@ -80,24 +75,16 @@ Mark each: ✓ satisfied | ✗ missing | ⚠ partial
 
 **L4: Test execution** (if test command detected)
 
-Run AFTER L0 passes and L1-L3 complete. Run even if L1-L3 found issues — test failures reveal additional problems.
+Run AFTER L0 passes and L1-L3 complete. Run even if L1-L3 found issues.
 
-- Run test command in the worktree (timeout from config, default 5 min)
 - Exit code 0 → L4 pass
-- Exit code non-zero → L4 FAIL
-  - Capture last 50 lines of output
-  - Report: "✗ L4: Tests failed (N of M)" with relevant output
-  - Add fix task: "Fix failing tests" with test output in description
+- Exit code non-zero → L4 FAIL: capture last 50 lines, report "✗ L4: Tests failed (N of M)", add fix task
 
 **Flaky test handling** (if `quality.test_retry_on_fail: true` in config):
-- If tests fail, re-run ONCE
-- Second run passes → L4 pass with note: "⚠ L4: Passed on retry (possible flaky test)"
-- Second run fails → genuine failure
+- Re-run ONCE on failure. Second pass → "⚠ L4: Passed on retry (possible flaky test)". Second fail → genuine failure.
 
 ### 3. GENERATE REPORT
 
-Report per spec with L0/L4 status, requirements count, acceptance count, quality issues.
-
 **Format on success:**
 ```
 done-upload.md: L0 ✓ | 4/4 reqs ✓, 5/5 acceptance ✓ | L4 ✓ (12 tests) | 0 quality issues
@@ -105,15 +92,21 @@ done-upload.md: L0 ✓ | 4/4 reqs ✓, 5/5 acceptance ✓ | L4 ✓ (12 tests) |
 
 **Format on failure:**
 ```
-done-upload.md: L0 ✓ | 4/4 reqs ✓, 5/5 acceptance ✓ | L4 ✗ (3 failed) | 0 quality issues
+done-upload.md: L0 ✓ | 4/4 reqs ✓, 3/5 acceptance ✗ | L4 ✗ (3 failed) | 1 quality issue
 
 Issues:
+  ✗ AC-3: YAML parsing missing for consolation
   ✗ L4: 3 test failures
     FAIL src/upload.test.ts > should validate file type
     FAIL src/upload.test.ts > should reject oversized files
+  ⚠ Quality: TODO in parse_config()
 
 Fix tasks added to PLAN.md:
-  T10: Fix 3 failing tests in upload module
+  T10: Add YAML parsing for consolation section
+  T11: Fix 3 failing tests in upload module
+  T12: Remove TODO in parse_config()
+
+Run /df:execute --continue to fix in the same worktree.
 ```
 
 **Gate conditions (ALL must pass to merge):**
@@ -123,52 +116,18 @@ Fix tasks added to PLAN.md:
 
 **If all gates pass:** Proceed to Post-Verification merge.
 
-**If issues found:** Add fix tasks to PLAN.md in the worktree and register as native tasks, then loop back to execute:
-
+**If issues found:** Add fix tasks to PLAN.md in the worktree and register as native tasks:
 1. Discover worktree (same logic as Post-Verification step 1)
-2. Write new fix tasks to `{worktree_path}/PLAN.md` under the existing spec section
-   - Task IDs continue from last (e.g. if T9 was last, fixes start at T10)
-   - Format: `- [ ] **T10**: Fix {description}` with `Files:` and details
-3. Register fix tasks as native tasks for immediate tracking:
-   ```
-   For each fix task added:
-     TaskCreate(subject: "T10: Fix {description}", description: "...", activeForm: "Fixing {description}")
-     TaskUpdate(addBlockedBy: [...]) if dependencies exist
-   ```
-   This allows `/df:execute --continue` to find fix tasks via TaskList immediately.
-4. Output report + next step:
-
-```
-done-upload.md: L0 ✓ | 4/4 reqs ✓, 3/5 acceptance ✗ | L4 ✗ (2 failed) | 1 quality issue
-
-Issues:
-  ✗ AC-3: YAML parsing missing for consolation
-  ✗ L4: 2 test failures
-    FAIL src/upload.test.ts > should validate file type
-    FAIL src/upload.test.ts > should reject oversized files
-  ⚠ Quality: TODO in parse_config()
-
-Fix tasks added to PLAN.md:
-  T10: Add YAML parsing for consolation section
-  T11: Fix 2 failing tests in upload module
-  T12: Remove TODO in parse_config()
-
-Run /df:execute --continue to fix in the same worktree.
-```
+2. Write fix tasks to `{worktree_path}/PLAN.md` under existing spec section (IDs continue from last)
+3. Register each fix task: `TaskCreate(subject: "T10: Fix {description}", ...)` + `TaskUpdate(addBlockedBy: [...])` if dependencies exist
+4. Output report + "Run /df:execute --continue to fix in the same worktree."
 
 **Do NOT** create new specs, new worktrees, or merge with issues pending.
 
 ### 4. CAPTURE LEARNINGS
 
-On success, write significant learnings to `.deepflow/experiments/{domain}--{approach}--success.md`
-
-**Write when:**
-- Non-trivial approach used
-- Alternatives rejected during planning
-- Performance optimization made
-- Integration pattern discovered
+On success, write to `.deepflow/experiments/{domain}--{approach}--success.md` when: non-trivial approach used, alternatives rejected, performance optimization made, or integration pattern discovered. Skip simple CRUD/standard patterns.
 
-**Format:**
 ```markdown
 # {Approach} [SUCCESS]
 Objective: ...
@@ -177,8 +136,6 @@ Why it worked: ...
 Files: ...
 ```
 
-**Skip:** Simple CRUD, standard patterns, user declines
-
 ## Verification Levels
 
 | Level | Check | Method | Runner |
@@ -189,104 +146,38 @@ Files: ...
 | L3: Wired | Integrated into system | Trace imports/calls | Explore agents |
 | L4: Tested | Tests pass | Run test command | Orchestrator (Bash) |
 
-**Default: L0 through L4.** L0 and L4 are skipped ONLY if no build/test command is detected (see step 1.5).
-L0 and L4 run directly via Bash — Explore agents cannot execute commands.
+**Default: L0 through L4.** L0 and L4 skipped ONLY if no build/test command detected (see step 1.5). L0 and L4 run via Bash — Explore agents cannot execute commands.
 
 ## 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
 - Don't auto-fix — add fix tasks to PLAN.md, then `/df:execute --continue`
 - Capture learnings — Write experiments for significant approaches
 
-## Agent Usage
-
-**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):**
-
-```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.
-
-## Examples
-
-### All pass → merge
-```
-/df:verify
-
-Build: npm run build | Test: npm test
-
-done-upload.md: L0 ✓ | 4/4 reqs ✓, 5/5 acceptance ✓ | L4 ✓ (12 tests) | 0 quality issues
-done-auth.md: L0 ✓ | 2/2 reqs ✓, 3/3 acceptance ✓ | L4 ✓ (8 tests) | 0 quality issues
-
-✓ All gates passed
-
-✓ Merged df/upload to main
-✓ Cleaned up worktree and branch
-
-Learnings captured:
-  → experiments/perf--streaming-upload--success.md
-```
-
-### Issues found → fix tasks added
-```
-/df:verify --doing
-
-Build: npm run build | Test: npm test
-
-doing-upload.md: L0 ✓ | 4/4 reqs ✓, 3/5 acceptance ✗ | L4 ✗ (3 failed) | 1 quality issue
-
-Issues:
-  ✗ AC-3: YAML parsing missing for consolation
-  ✗ L4: 3 test failures
-    FAIL src/upload.test.ts > should validate file type
-    FAIL src/upload.test.ts > should reject oversized files
-    FAIL src/upload.test.ts > should handle empty input
-  ⚠ Quality: TODO in parse_config()
-
-Fix tasks added to PLAN.md:
-  T10: Add YAML parsing for consolation section
-  T11: Fix 3 failing tests in upload module
-  T12: Remove TODO in parse_config()
-
-Run /df:execute --continue to fix in the same worktree.
-```
-
 ## Post-Verification: Worktree Merge & Cleanup
 
-**Only runs when ALL gates pass** (L0 build, L1-L3 static analysis, L4 tests). If any gate fails, fix tasks were added to PLAN.md instead (see step 3).
+**Only runs when ALL gates pass.** If any gate fails, fix tasks were added to PLAN.md instead (see step 3).
 
 ### 1. DISCOVER WORKTREE
 
-Find worktree info using two strategies (checkpoint → fallback to git):
+Find worktree info (checkpoint → fallback to git):
 
 ```bash
-# Strategy 1: checkpoint.json (from interrupted executions)
+# Strategy 1: checkpoint.json
 if [ -f .deepflow/checkpoint.json ]; then
   WORKTREE_BRANCH=$(cat .deepflow/checkpoint.json | jq -r '.worktree_branch')
   WORKTREE_PATH=$(cat .deepflow/checkpoint.json | jq -r '.worktree_path')
 fi
 
-# Strategy 2: Infer from doing-* spec + git worktree list (no checkpoint needed)
+# Strategy 2: Infer from doing-* spec + git worktree list
 if [ -z "${WORKTREE_BRANCH}" ]; then
   SPEC_NAME=$(basename specs/doing-*.md .md | sed 's/doing-//')
   WORKTREE_PATH=".deepflow/worktrees/${SPEC_NAME}"
-  # Get branch from git worktree list
   WORKTREE_BRANCH=$(git worktree list --porcelain | grep -A2 "${WORKTREE_PATH}" | grep 'branch' | sed 's|branch refs/heads/||')
 fi
 
-# No worktree found — nothing to merge
+# No worktree found
 if [ -z "${WORKTREE_BRANCH}" ]; then
   echo "No worktree found — nothing to merge. Workflow may already be on main."
   exit 0
@@ -296,48 +187,48 @@ fi
 ### 2. MERGE TO MAIN
 
 ```bash
-# Switch to main and merge
 git checkout main
 git merge "${WORKTREE_BRANCH}" --no-ff -m "feat({spec}): merge verified changes"
 ```
 
-**On merge conflict:**
-- Keep worktree intact for manual resolution
-- Output: "Merge conflict detected. Resolve manually, then run /df:verify --merge-only"
-- Exit without cleanup
+**On merge conflict:** Keep worktree intact, output "Merge conflict detected. Resolve manually, then run /df:verify --merge-only", exit without cleanup.
 
 ### 3. CLEANUP WORKTREE
 
-After successful merge:
-
 ```bash
-# Remove worktree and branch
 git worktree remove --force "${WORKTREE_PATH}"
 git branch -d "${WORKTREE_BRANCH}"
-
-# Remove checkpoint if it exists
 rm -f .deepflow/checkpoint.json
 ```
 
-**Output on success:**
-```
-✓ Merged df/upload to main
-✓ Cleaned up worktree and branch
-✓ Spec complete: doing-upload → done-upload
+### 4. RENAME SPEC
 
-Workflow complete! Ready for next feature: /df:spec <name>
+```bash
+# Rename spec to done
+mv specs/doing-${SPEC_NAME}.md specs/done-${SPEC_NAME}.md
 ```
 
-### 4. CAPTURE DECISIONS (success path only)
+### 5. EXTRACT DECISIONS
 
-Extract up to 4 candidate decisions (quality findings, patterns validated, lessons learned). Present via AskUserQuestion with `multiSelect: true`; tags: `[APPROACH]`, `[PROVISIONAL]`, `[ASSUMPTION]`.
+Read the renamed `specs/done-${SPEC_NAME}.md` file. Model-extract architectural decisions:
+- Explicit choices → `[APPROACH]`
+- Unvalidated assumptions → `[ASSUMPTION]`
+- "For now" decisions → `[PROVISIONAL]`
 
+Append to `.deepflow/decisions.md`:
+```
+### {YYYY-MM-DD} — {spec-name}
+- [TAG] decision text — rationale
 ```
-AskUserQuestion(question: "Which decisions to record?", multiSelect: true,
-  options: [{ label: "[APPROACH] <decision>", description: "<rationale>" }, ...])
+
+After successful append, delete `specs/done-${SPEC_NAME}.md`. If write fails, preserve the file.
+
+Output:
 ```
+✓ Merged df/upload to main
+✓ Cleaned up worktree and branch
+✓ Spec complete: doing-upload → done-upload
 
-For each confirmed decision, append to `.deepflow/decisions.md` (create if missing):
-`### {YYYY-MM-DD} — verify` / `- [TAG] {decision text} — {rationale}`
+Workflow complete! Ready for next feature: /df:spec <name>
+```
 
-Skip if user confirms none or declines.

package/templates/explore-agent.md

@@ -0,0 +1,34 @@
+# Explore Agent Pattern
+
+## Spawn Rules
+
+**NEVER use `run_in_background`** — causes late "Agent completed" notifications.
+**NEVER use TaskOutput** — returns full transcripts (100KB+) that explode context.
+
+Spawn ALL agents in ONE message (non-background, parallel):
+```python
+Task(subagent_type="Explore", model="haiku", prompt="Find: ...")
+Task(subagent_type="Explore", model="haiku", prompt="Find: ...")
+# Returns final message only; blocks until all complete; no late notifications
+```
+
+## Prompt Structure
+
+```
+Find: [specific question]
+
+Return ONLY:
+- File paths matching criteria
+- One-line description per file
+- Integration points (if asked)
+
+DO NOT: read/summarize specs, make recommendations, propose solutions, generate tables.
+
+Max response: 500 tokens (configurable via .deepflow/config.yaml explore.max_tokens)
+```
+
+## Scope Restrictions
+
+MUST only report factual findings: files found, patterns/conventions, integration points.
+
+MUST NOT: make recommendations, propose architectures, summarize specs, draw conclusions.