deepflow 0.1.24 → 0.1.27

package/package.json

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

package/src/commands/df/execute.md

@@ -24,8 +24,12 @@ Implement tasks from PLAN.md with parallel agents, atomic commits, and context-e
 
 ## Skills & Agents
 - Skill: `atomic-commits` — Clean commit protocol
-- Agent: `general-purpose` (Sonnet) — Task implementation
-- Agent: `reasoner` (Opus) — Debugging failures
+
+**Use Task tool to spawn agents:**
+| Agent | subagent_type | model | Purpose |
+|-------|---------------|-------|---------|
+| Implementation | `general-purpose` | `sonnet` | Task implementation |
+| Debugger | `reasoner` | `opus` | Debugging failures |
 
 ## Context-Aware Execution
 
@@ -55,22 +59,66 @@ summary: "one line"
 
 ## Checkpoint & Resume
 
-**File:** `.deepflow/checkpoint.json` — stores completed tasks, current wave.
+**File:** `.deepflow/checkpoint.json` — stored in WORKTREE directory, not main.
+
+**Schema:**
+```json
+{
+  "completed_tasks": ["T1", "T2"],
+  "current_wave": 2,
+  "worktree_path": ".deepflow/worktrees/df/doing-upload/20260202-1430",
+  "worktree_branch": "df/doing-upload/20260202-1430"
+}
+```
 
-**On checkpoint:** Complete wave → update PLAN.md → save → exit.
-**Resume:** `--continue` loads checkpoint, skips completed tasks.
+**On checkpoint:** Complete wave → update PLAN.md → save to worktree → exit.
+**Resume:** `--continue` loads checkpoint, verifies worktree, skips completed tasks.
 
 ## Behavior
 
 ### 1. CHECK CHECKPOINT
 
 ```
---continue → Load and resume
+--continue → Load checkpoint
+  → If worktree_path exists:
+    → Verify worktree still exists on disk
+    → If missing: Error "Worktree deleted. Use --fresh"
+    → If exists: Use it, skip worktree creation
+  → Resume execution with completed tasks
 --fresh → Delete checkpoint, start fresh
 checkpoint exists → Prompt: "Resume? (y/n)"
 else → Start fresh
 ```
 
+### 1.5. CREATE WORKTREE
+
+Before spawning any agents, create an isolated worktree:
+
+```
+# Check main is clean (ignore untracked)
+git diff --quiet HEAD || Error: "Main has uncommitted changes. Commit or stash first."
+
+# Generate worktree path
+SPEC_NAME=$(basename spec/doing-*.md .md | sed 's/doing-//')
+TIMESTAMP=$(date +%Y%m%d-%H%M)
+BRANCH_NAME="df/${SPEC_NAME}/${TIMESTAMP}"
+WORKTREE_PATH=".deepflow/worktrees/${BRANCH_NAME}"
+
+# Create worktree
+git worktree add -b "${BRANCH_NAME}" "${WORKTREE_PATH}"
+
+# Store in checkpoint for resume
+checkpoint.worktree_path = WORKTREE_PATH
+checkpoint.worktree_branch = BRANCH_NAME
+```
+
+**Resume handling:**
+- If checkpoint has worktree_path → verify it exists, use it
+- If worktree missing → Error: "Worktree deleted. Use --fresh"
+
+**Existing worktree handling:**
+- If worktree exists for same spec → Prompt: "Resume existing worktree? (y/n/delete)"
+
 ### 2. LOAD PLAN
 
 ```
@@ -82,37 +130,187 @@ If missing: "No PLAN.md found. Run /df:plan first."
 
 Warn if `specs/*.md` (excluding doing-/done-) exist. Non-blocking.
 
-### 4. IDENTIFY READY TASKS
+### 4. CHECK EXPERIMENT STATUS (HYPOTHESIS VALIDATION)
+
+**Before identifying ready tasks**, check experiment validation for full implementation tasks.
+
+**Task Types:**
+- **Spike tasks**: Have `[SPIKE]` in title OR `Type: spike` in description — always executable
+- **Full implementation tasks**: Blocked by spike tasks — require validated experiment
+
+**Validation Flow:**
+
+```
+For each task in plan:
+  If task is spike task:
+    → Mark as executable (spikes are always allowed)
+  Else if task is blocked by a spike task (T{n}):
+    → Find related experiment file in .deepflow/experiments/
+    → Check experiment status:
+      - --passed.md exists → Unblock, proceed with implementation
+      - --failed.md exists → Keep blocked, warn user
+      - --active.md exists → Keep blocked, spike in progress
+      - No experiment → Keep blocked, spike not started
+```
+
+**Experiment File Discovery:**
+
+```
+Glob: .deepflow/experiments/{topic}--*--{status}.md
+
+Topic extraction:
+1. From spike task: experiment file path in task description
+2. From spec name: doing-{topic} → {topic}
+3. Fuzzy match: normalize and match
+```
 
-Ready = `[ ]` + all `blocked_by` complete + not in checkpoint.
+**Status Handling:**
 
-### 5. SPAWN AGENTS
+| Experiment Status | Task Status | Action |
+|-------------------|-------------|--------|
+| `--passed.md` | Ready | Execute full implementation |
+| `--failed.md` | Blocked | Skip, warn: "Experiment failed, re-plan needed" |
+| `--active.md` | Blocked | Skip, info: "Waiting for spike completion" |
+| Not found | Blocked | Skip, info: "Spike task not executed yet" |
+
+**Warning Output:**
+
+```
+⚠ T3 blocked: Experiment 'upload--streaming--failed.md' did not validate
+  → Run /df:plan to generate new hypothesis spike
+```
+
+### 5. IDENTIFY READY TASKS
+
+Ready = `[ ]` + all `blocked_by` complete + experiment validated (if applicable) + not in checkpoint.
+
+### 6. SPAWN AGENTS
 
 Context ≥50%: checkpoint and exit.
 
-Spawn all ready tasks in ONE message (parallel). Same-file conflicts: sequential.
+**Use Task tool to spawn all ready tasks in ONE message (parallel):**
+```
+Task tool parameters for each task:
+- subagent_type: "general-purpose"
+- model: "sonnet"
+- run_in_background: true
+- prompt: "{task details from PLAN.md}"
+```
+
+Same-file conflicts: spawn sequentially instead.
+
+**Spike Task Execution:**
+When spawning a spike task, the agent MUST:
+1. Execute the minimal validation method
+2. Record result in experiment file (update status: `--passed.md` or `--failed.md`)
+3. If passed: implementation tasks become unblocked
+4. If failed: record conclusion with "next hypothesis" for future planning
 
-On failure: spawn `reasoner`.
+**On failure, use Task tool to spawn reasoner:**
+```
+Task tool parameters:
+- subagent_type: "reasoner"
+- model: "opus"
+- prompt: "Debug failure: {error details}"
+```
 
-### 6. PER-TASK (agent prompt)
+### 7. PER-TASK (agent prompt)
 
+**Standard Task:**
 ```
 {task_id}: {description from PLAN.md}
 Files: {target files}
 Spec: {spec_name}
 
+**IMPORTANT: Working Directory**
+All file operations MUST use this absolute path as base:
+{worktree_absolute_path}
+
+Example: To edit src/foo.ts, use:
+{worktree_absolute_path}/src/foo.ts
+
+Do NOT write files to the main project directory.
+
 Implement, test, commit as feat({spec}): {description}.
-Write result to .deepflow/results/{task_id}.yaml
+Write result to {worktree_absolute_path}/.deepflow/results/{task_id}.yaml
 ```
 
-### 7. COMPLETE SPECS
+**Spike Task:**
+```
+{task_id} [SPIKE]: {hypothesis}
+Type: spike
+Method: {minimal steps to validate}
+Success criteria: {how to know it passed}
+Time-box: {duration}
+Experiment file: {worktree_absolute_path}/.deepflow/experiments/{topic}--{hypothesis}--active.md
+Spec: {spec_name}
+
+**IMPORTANT: Working Directory**
+All file operations MUST use this absolute path as base:
+{worktree_absolute_path}
+
+Example: To edit src/foo.ts, use:
+{worktree_absolute_path}/src/foo.ts
+
+Do NOT write files to the main project directory.
+
+Execute the minimal validation:
+1. Follow the method steps exactly
+2. Measure against success criteria
+3. Update experiment file with result:
+   - If passed: rename to --passed.md, record findings
+   - If failed: rename to --failed.md, record conclusion with "next hypothesis"
+4. Commit as spike({spec}): validate {hypothesis}
+5. Write result to {worktree_absolute_path}/.deepflow/results/{task_id}.yaml
+
+Result status:
+- success = hypothesis validated (passed)
+- failed = hypothesis invalidated (failed experiment, NOT agent error)
+```
+
+### 8. FAILURE HANDLING
+
+When a task fails and cannot be auto-fixed:
+
+**Behavior:**
+1. Leave worktree intact at `{worktree_path}`
+2. Keep checkpoint.json for potential resume
+3. Output debugging instructions
+
+**Output:**
+```
+✗ Task T3 failed after retry
+
+Worktree preserved for debugging:
+  Path: .deepflow/worktrees/df/doing-upload/20260202-1430
+  Branch: df/doing-upload/20260202-1430
+
+To investigate:
+  cd .deepflow/worktrees/df/doing-upload/20260202-1430
+  # examine files, run tests, etc.
+
+To resume after fixing:
+  /df:execute --continue
+
+To discard and start fresh:
+  git worktree remove --force .deepflow/worktrees/df/doing-upload/20260202-1430
+  git branch -D df/doing-upload/20260202-1430
+  /df:execute --fresh
+```
+
+**Key points:**
+- Never auto-delete worktree on failure (cleanup_on_fail: false by default)
+- Always provide the exact cleanup commands
+- Checkpoint remains so --continue can work after manual fix
+
+### 9. COMPLETE SPECS
 
 When all tasks done for a `doing-*` spec:
 1. Embed history in spec: `## Completed` section
 2. Rename: `doing-upload.md` → `done-upload.md`
 3. Remove section from PLAN.md
 
-### 8. ITERATE
+### 10. ITERATE
 
 Repeat until: all done, all blocked, or checkpoint.
 
@@ -126,6 +324,8 @@ Repeat until: all done, all blocked, or checkpoint.
 
 ## Example
 
+### Standard Execution
+
 ```
 /df:execute (context: 12%)
 
@@ -140,7 +340,52 @@ Wave 2: T3 (context: 48%)
 ✓ Complete: 3/3 tasks
 ```
 
-With checkpoint:
+### Spike-First Execution
+
+```
+/df:execute (context: 10%)
+
+Checking experiment status...
+  T1 [SPIKE]: No experiment yet, spike executable
+  T2: Blocked by T1 (spike not validated)
+  T3: Blocked by T1 (spike not validated)
+
+Wave 1: T1 [SPIKE] (context: 20%)
+  T1: success (abc1234) → upload--streaming--passed.md
+
+Checking experiment status...
+  T2: Experiment passed, unblocked
+  T3: Experiment passed, unblocked
+
+Wave 2: T2, T3 parallel (context: 45%)
+  T2: success (def5678)
+  T3: success (ghi9012)
+
+✓ doing-upload → done-upload
+✓ Complete: 3/3 tasks
+```
+
+### Spike Failed
+
+```
+/df:execute (context: 10%)
+
+Wave 1: T1 [SPIKE] (context: 20%)
+  T1: failed → upload--streaming--failed.md
+
+Checking experiment status...
+  T2: ⚠ Blocked - Experiment failed
+  T3: ⚠ Blocked - Experiment failed
+
+⚠ Spike T1 invalidated hypothesis
+  Experiment: upload--streaming--failed.md
+  → Run /df:plan to generate new hypothesis spike
+
+Complete: 1/3 tasks (2 blocked by failed experiment)
+```
+
+### With Checkpoint
+
 ```
 Wave 1 complete (context: 52%)
 Checkpoint saved. Run /df:execute --continue

package/src/commands/df/plan.md

@@ -42,21 +42,33 @@ Determine source_dir from config or default to src/
 
 If no new specs: report counts, suggest `/df:execute`.
 
-### 2. CHECK PAST EXPERIMENTS
+### 2. CHECK PAST EXPERIMENTS (SPIKE-FIRST)
 
-Extract domains from spec (perf, auth, api, etc.), then:
+**CRITICAL**: Check experiments BEFORE generating any tasks.
+
+Extract topic from spec name (fuzzy match), then:
 
 ```
-Glob .deepflow/experiments/{domain}--*
+Glob .deepflow/experiments/{topic}--*
 ```
 
+**Experiment file naming:** `{topic}--{hypothesis}--{status}.md`
+Statuses: `active`, `passed`, `failed`
+
 | Result | Action |
 |--------|--------|
-| `--failed.md` | Exclude approach, note why |
-| `--success.md` | Reference as pattern |
-| No matches | Continue (expected for new projects) |
+| `--failed.md` exists | Extract "next hypothesis" from Conclusion section |
+| `--passed.md` exists | Reference as validated pattern, can proceed to full implementation |
+| `--active.md` exists | Wait for experiment completion before planning |
+| No matches | New topic, needs initial spike |
+
+**Spike-First Rule**:
+- If `--failed.md` exists: Generate spike task to test the next hypothesis (from failed experiment's Conclusion)
+- If no experiments exist: Generate spike task for the core hypothesis
+- Full implementation tasks are BLOCKED until a spike validates the approach
+- Only proceed to full task generation after `--passed.md` exists
 
-**Naming:** `{domain}--{approach}--{result}.md`
+See: `templates/experiment-template.md` for experiment format
 
 ### 3. DETECT PROJECT CONTEXT
 
@@ -69,7 +81,15 @@ Include patterns in task descriptions for agents to follow.
 
 ### 4. ANALYZE CODEBASE
 
-**Spawn Explore agents** (haiku, read-only) with dynamic count:
+**Use Task tool to spawn Explore agents in parallel:**
+```
+Task tool parameters:
+- subagent_type: "Explore"
+- model: "haiku"
+- run_in_background: true (for parallel execution)
+```
+
+Scale agent count based on codebase size:
 
 | File Count | Agents |
 |------------|--------|
@@ -78,6 +98,34 @@ Include patterns in task descriptions for agents to follow.
 | 100-500 | 25-40 |
 | 500+ | 50-100 (cap) |
 
+**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
+
 **Use `code-completeness` skill patterns** to search for:
 - Implementations matching spec requirements
 - TODO, FIXME, HACK comments
@@ -86,7 +134,14 @@ Include patterns in task descriptions for agents to follow.
 
 ### 5. COMPARE & PRIORITIZE
 
-**Spawn `reasoner` agent** (Opus) for analysis:
+**Use Task tool to spawn reasoner agent:**
+```
+Task tool parameters:
+- subagent_type: "reasoner"
+- model: "opus"
+```
+
+Reasoner performs analysis:
 
 | Status | Action |
 |--------|--------|
@@ -102,7 +157,36 @@ Include patterns in task descriptions for agents to follow.
 2. Impact — core features before enhancements
 3. Risk — unknowns early
 
-### 6. VALIDATE HYPOTHESES
+### 6. GENERATE SPIKE TASKS (IF NEEDED)
+
+**When to generate spike tasks:**
+1. Failed experiment exists → Test the next hypothesis
+2. No experiments exist → Test the core hypothesis
+3. Passed experiment exists → Skip to full implementation
+
+**Spike Task Format:**
+```markdown
+- [ ] **T1** [SPIKE]: Validate {hypothesis}
+  - Type: spike
+  - Hypothesis: {what we're testing}
+  - Method: {minimal steps to validate}
+  - Success criteria: {how to know it passed}
+  - Time-box: 30 min
+  - Files: .deepflow/experiments/{topic}--{hypothesis}--{status}.md
+  - Blocked by: none
+```
+
+**Blocking Logic:**
+- All implementation tasks MUST have `Blocked by: T{spike}` until spike passes
+- After spike completes:
+  - If passed: Update experiment to `--passed.md`, unblock implementation tasks
+  - If failed: Update experiment to `--failed.md`, DO NOT generate implementation tasks
+
+**Full Implementation Only After Spike:**
+- Only generate full task list when spike validates the approach
+- Never generate 10-task waterfall without validated hypothesis
+
+### 7. VALIDATE HYPOTHESES
 
 Test risky assumptions before finalizing plan.
 
@@ -111,24 +195,27 @@ Test risky assumptions before finalizing plan.
 **Process:**
 1. Prototype in scratchpad (not committed)
 2. Test assumption
-3. If fails → Write `.deepflow/experiments/{domain}--{approach}--failed.md`
+3. If fails → Write `.deepflow/experiments/{topic}--{hypothesis}--failed.md`
 4. Adjust approach, document in task
 
 **Skip:** Well-known patterns, simple CRUD, clear docs exist
 
-### 7. OUTPUT PLAN.md
+### 8. OUTPUT PLAN.md
 
 Append tasks grouped by `### doing-{spec-name}`. Include spec gaps and validation findings.
 
-### 8. RENAME SPECS
+### 9. RENAME SPECS
 
 `mv specs/feature.md specs/doing-feature.md`
 
-### 9. REPORT
+### 10. REPORT
 
 `✓ Plan generated — {n} specs, {n} tasks. Run /df:execute`
 
 ## Rules
+- **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
 - **Learn from history** — Check past experiments before proposing approaches
 - **Plan only** — Do NOT implement anything (except quick validation prototypes)
 - **Validate before commit** — Test risky assumptions with minimal experiments
@@ -139,13 +226,64 @@ Append tasks grouped by `### doing-{spec-name}`. Include spec gaps and validatio
 
 ## Agent Scaling
 
-| Agent | Base | Scale |
-|-------|------|-------|
-| Explore (search) | 10 | +1 per 20 files |
-| Reasoner (analyze) | 5 | +1 per 2 specs |
+| Agent | Model | Base | Scale |
+|-------|-------|------|-------|
+| Explore (search) | haiku | 10 | +1 per 20 files |
+| Reasoner (analyze) | opus | 5 | +1 per 2 specs |
+
+**IMPORTANT**: Always use the `Task` tool with explicit `subagent_type` and `model` parameters. Do NOT use Glob/Grep/Read directly for codebase analysis - spawn agents instead.
 
 ## Example
 
+### Spike-First (No Prior Experiments)
+
+```markdown
+# Plan
+
+### doing-upload
+
+- [ ] **T1** [SPIKE]: Validate streaming upload approach
+  - Type: spike
+  - Hypothesis: Streaming uploads will handle files >1GB without memory issues
+  - Method: Create minimal endpoint, upload 2GB file, measure memory
+  - Success criteria: Memory stays under 500MB during upload
+  - Time-box: 30 min
+  - Files: .deepflow/experiments/upload--streaming--active.md
+  - Blocked by: none
+
+- [ ] **T2**: Create upload endpoint
+  - Files: src/api/upload.ts
+  - Blocked by: T1 (spike must pass)
+
+- [ ] **T3**: Add S3 service with streaming
+  - Files: src/services/storage.ts
+  - Blocked by: T1 (spike must pass), T2
+```
+
+### Spike-First (After Failed Experiment)
+
+```markdown
+# Plan
+
+### doing-upload
+
+- [ ] **T1** [SPIKE]: Validate chunked upload with backpressure
+  - Type: spike
+  - Hypothesis: Adding backpressure control will prevent buffer overflow
+  - Method: Implement pause/resume on buffer threshold, test with 2GB file
+  - Success criteria: No memory spikes above 500MB
+  - Time-box: 30 min
+  - Files: .deepflow/experiments/upload--chunked-backpressure--active.md
+  - Blocked by: none
+  - Note: Previous approach failed (see upload--buffer-upload--failed.md)
+
+- [ ] **T2**: Implement chunked upload endpoint
+  - Files: src/api/upload.ts
+  - Blocked by: T1 (spike must pass)
+```
+
+### After Spike Validates (Full Implementation)
+
 ```markdown
 # Plan
 
@@ -154,10 +292,10 @@ Append tasks grouped by `### doing-{spec-name}`. Include spec gaps and validatio
 - [ ] **T1**: Create upload endpoint
   - Files: src/api/upload.ts
   - Blocked by: none
+  - Note: Use streaming (validated in upload--streaming--passed.md)
 
 - [ ] **T2**: Add S3 service with streaming
   - Files: src/services/storage.ts
   - Blocked by: T1
-  - Note: Use streaming (see experiments/perf--chunked-upload--success.md)
-  - Avoid: Direct buffer upload failed for large files (experiments/perf--buffer-upload--failed.md)
+  - Avoid: Direct buffer upload failed (see upload--buffer-upload--failed.md)
 ```

package/src/commands/df/spec.md

@@ -20,14 +20,26 @@ Transform conversation context into a structured specification file.
 
 ## Skills & Agents
 - Skill: `gap-discovery` — Proactive requirement gap identification
-- Agent: `Explore` (haiku) — Codebase context gathering
-- Agent: `reasoner` (Opus) — Synthesize findings into requirements
+
+**Use Task tool to spawn agents:**
+| Agent | subagent_type | model | Purpose |
+|-------|---------------|-------|---------|
+| Context | `Explore` | `haiku` | Codebase context gathering |
+| Synthesizer | `reasoner` | `opus` | Synthesize findings into requirements |
 
 ## Behavior
 
 ### 1. GATHER CODEBASE CONTEXT
 
-**Spawn Explore agents** (haiku, read-only, parallel) to find:
+**Use Task tool to spawn Explore agents in parallel:**
+```
+Task tool parameters:
+- subagent_type: "Explore"
+- model: "haiku"
+- run_in_background: true
+```
+
+Find:
 - Related existing implementations
 - Code patterns and conventions
 - Integration points relevant to the feature
@@ -39,6 +51,34 @@ Transform conversation context into a structured specification file.
 | 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.
 
@@ -70,7 +110,14 @@ Max 4 questions per tool call. Wait for answers before proceeding.
 
 ### 3. SYNTHESIZE FINDINGS
 
-**Spawn `reasoner` agent** (Opus) to:
+**Use Task tool to spawn reasoner agent:**
+```
+Task tool parameters:
+- subagent_type: "reasoner"
+- model: "opus"
+```
+
+The reasoner will:
 - Analyze codebase context from Explore agents
 - Identify constraints from existing architecture
 - Suggest requirements based on patterns found
@@ -130,10 +177,12 @@ Next: Run /df:plan to generate tasks
 
 ## Agent Scaling
 
-| Agent | Base | Purpose |
-|-------|------|---------|
-| Explore (haiku) | 3-5 | Find related code, patterns |
-| Reasoner (Opus) | 1 | Synthesize into requirements |
+| Agent | subagent_type | model | Base | Purpose |
+|-------|---------------|-------|------|---------|
+| Explore | `Explore` | `haiku` | 3-5 | Find related code, patterns |
+| Reasoner | `reasoner` | `opus` | 1 | Synthesize into requirements |
+
+**IMPORTANT**: Always use the `Task` tool with explicit `subagent_type` and `model` parameters.
 
 ## Example
 

package/src/commands/df/verify.md

@@ -12,7 +12,11 @@ Check that implemented code satisfies spec requirements and acceptance criteria.
 
 ## Skills & Agents
 - Skill: `code-completeness` — Find incomplete implementations
-- Agent: `Explore` (Haiku) — Fast codebase scanning
+
+**Use Task tool to spawn agents:**
+| Agent | subagent_type | model | Purpose |
+|-------|---------------|-------|---------|
+| Scanner | `Explore` | `haiku` | Fast codebase scanning |
 
 ## Spec File States
 
@@ -87,7 +91,15 @@ Default: L1-L3 (L4 optional, can be slow)
 
 ## Agent Usage
 
-Spawn `Explore` agents (Haiku), 1-2 per spec, cap 10.
+**Use Task tool to spawn Explore agents:**
+```
+Task tool parameters:
+- subagent_type: "Explore"
+- model: "haiku"
+- run_in_background: true (for parallel)
+```
+
+Scale: 1-2 agents per spec, cap 10.
 
 ## Example
 
@@ -103,3 +115,46 @@ Learnings captured:
   → experiments/perf--streaming-upload--success.md
   → experiments/auth--jwt-refresh-rotation--success.md
 ```
+
+## Post-Verification: Worktree Merge & Cleanup
+
+After all verification passes:
+
+### 1. MERGE TO MAIN
+
+```bash
+# Get worktree info from checkpoint
+WORKTREE_BRANCH=$(cat .deepflow/checkpoint.json | jq -r '.worktree_branch')
+
+# 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
+
+### 2. CLEANUP WORKTREE
+
+After successful merge:
+
+```bash
+# Get worktree path from checkpoint
+WORKTREE_PATH=$(cat .deepflow/checkpoint.json | jq -r '.worktree_path')
+
+# Remove worktree and branch
+git worktree remove --force "${WORKTREE_PATH}"
+git branch -d "${WORKTREE_BRANCH}"
+
+# Remove checkpoint
+rm .deepflow/checkpoint.json
+```
+
+**Output on success:**
+```
+✓ Merged df/doing-upload/20260202-1430 to main
+✓ Cleaned up worktree and branch
+✓ Spec complete: doing-upload → done-upload
+```

package/templates/config-template.yaml

@@ -36,7 +36,28 @@ models:
   reason: opus         # Complex decisions
   debug: opus          # Problem solving
 
+explore:
+  max_tokens: 500      # Controls Explore agent response length
+
 commits:
   format: "feat({spec}): {description}"
   atomic: true         # One task = one commit
   push_after: complete # Or "each" for every commit
+
+# Worktree isolation for /df:execute
+# Isolates all agent work in a git worktree, keeping main clean
+worktree:
+  # Enable worktree isolation (default: true)
+  enabled: true
+
+  # Base path for worktrees relative to project root
+  base_path: .deepflow/worktrees
+
+  # Branch name prefix for worktree branches
+  branch_prefix: df/
+
+  # Automatically cleanup worktree after successful verify
+  cleanup_on_success: true
+
+  # Keep worktree after failed execution for debugging
+  cleanup_on_fail: false

package/templates/experiment-template.md

@@ -0,0 +1,74 @@
+# Experiment: {hypothesis-slug}
+
+> **Filename convention**: `{topic}--{hypothesis-slug}--{status}.md`
+> Status: `active` | `passed` | `failed`
+
+## Topic
+
+{Spec name or feature area this experiment relates to}
+
+<!--
+What problem or feature does this experiment address?
+Link to relevant spec if applicable.
+-->
+
+## Hypothesis
+
+{What we believe will work and why}
+
+<!--
+Be specific and testable:
+- "Using approach X will achieve Y because Z"
+- "The bottleneck is in component A, not B"
+- Should be falsifiable in a single experiment
+-->
+
+## Method
+
+{Minimal steps to validate the hypothesis}
+
+<!--
+Keep it minimal - fastest path to prove/disprove:
+1. Step one (e.g., "Create test file with X")
+2. Step two (e.g., "Run command Y")
+3. Step three (e.g., "Observe output Z")
+
+Time-box: ideally under 30 minutes
+-->
+
+## Result
+
+**Status**: {pass | fail}
+
+{Actual outcome with evidence}
+
+<!--
+Include concrete evidence:
+- Error messages, output logs
+- Metrics or measurements
+- Screenshots if applicable
+- What specifically happened vs. expected
+-->
+
+## Conclusion
+
+{What we learned from this experiment}
+
+<!--
+Answer these:
+- Why did it pass/fail?
+- What assumption was validated/invalidated?
+- If failed: What's the next hypothesis? (don't repeat same approach)
+- If passed: What's ready for implementation?
+-->
+
+---
+
+<!--
+Experiment Guidelines:
+- One hypothesis per experiment
+- Failed experiments are valuable - they inform the next hypothesis
+- Never repeat a failed approach without a new insight
+- Keep experiments small and fast (under 30 min)
+- Link related experiments in conclusions
+-->

package/templates/plan-template.md

@@ -29,6 +29,22 @@ Generated: {timestamp}
   - Files: {files}
   - Blocked by: T1
 
+### Spike Task Example
+
+When no experiments exist to validate an approach, start with a minimal validation spike:
+
+- [ ] **T1** (spike): Validate [hypothesis] approach
+  - Files: [minimal files needed]
+  - Blocked by: none
+  - Blocks: T2, T3, T4 (full implementation)
+  - Description: Minimal test to verify [approach] works before full implementation
+
+- [ ] **T2**: Implement [feature] based on spike results
+  - Files: [implementation files]
+  - Blocked by: T1 (spike)
+
+Spike tasks are 1-2 tasks to validate an approach before committing to full implementation.
+
 ---
 
 <!--
@@ -38,4 +54,6 @@ Plan Guidelines:
 - Blocked by references task IDs (T1, T2, etc.)
 - Mark complete with [x] and commit hash
 - Example completed: [x] **T1**: Create API ✓ (abc1234)
+- Spike tasks: If no experiments validate the approach, first task should be a minimal validation spike
+- Spike tasks block full implementation tasks until the hypothesis is validated
 -->