deepflow 0.1.30 → 0.1.32

package/README.md

@@ -24,6 +24,7 @@
 - **Stay in flow** — Minimize context switches, maximize deep work
 - **Conversational ideation** with proactive gap discovery
 - **Specs define intent**, tasks close reality gaps
+- **Spike-first planning** — Validate risky hypotheses before full implementation
 - **Worktree isolation** — Main branch stays clean during execution
 - **Parallel execution** with context-aware checkpointing
 - **Atomic commits** for clean rollback
@@ -65,19 +66,20 @@ CONVERSATION
     │ Creates specs/{name}.md
     ▼
 /df:plan
-    │ Detects project context/patterns
-    │ Analyzes specs vs codebase
-    │ Creates PLAN.md with tasks
+    │ Checks past experiments (learn from failures)
+    │ Risky work? → generates spike task first
+    │ Creates PLAN.md with prioritized tasks
     │ Renames: feature.md → doing-feature.md
     ▼
 /df:execute
     │ Creates isolated worktree (main stays clean)
+    │ Spike tasks run first, verified before continuing
     │ Parallel agents, file conflicts serialize
     │ Context-aware (≥50% → checkpoint)
-    │ Atomic commit per task
     ▼
 /df:verify
     │ Checks requirements met
+    │ Merges worktree to main, cleans up
     │ Renames: doing-feature.md → done-feature.md
 ```
 
@@ -96,13 +98,26 @@ specs/
 
 **Ongoing:** Detects existing patterns, follows conventions, integrates with current code.
 
+## Spike-First Planning
+
+For risky or uncertain work, `/df:plan` generates a **spike task** first:
+
+```
+Spike: Validate streaming upload handles 10MB+ files
+  │ Run minimal experiment
+  │ Pass? → Unblock implementation tasks
+  │ Fail? → Record learning, generate new hypothesis
+```
+
+Experiments are tracked in `.deepflow/experiments/`. Failed approaches won't be repeated.
+
 ## Worktree Isolation
 
 Execution happens in an isolated git worktree:
 - Main branch stays clean during execution
 - On failure, worktree preserved for debugging
 - Resume with `/df:execute --continue`
-- On success, changes merged back to main
+- On success, `/df:verify` merges to main and cleans up
 
 ## Context-Aware Execution
 
@@ -129,12 +144,13 @@ your-project/
 │   ├── auth.md           # new spec
 │   ├── doing-upload.md   # in progress
 │   └── done-payments.md  # completed
-├── PLAN.md               # active tasks only
+├── PLAN.md               # active tasks
 └── .deepflow/
-    ├── context.json      # context % for execution
-    ├── checkpoint.json   # resume state
-    └── worktrees/        # isolated execution (main stays clean)
-        └── df/doing-upload/20260202-1430/
+    ├── config.yaml       # project settings
+    ├── context.json      # context % tracking
+    ├── experiments/      # spike results (pass/fail)
+    └── worktrees/        # isolated execution
+        └── upload/       # one worktree per spec
 ```
 
 ## Configuration
@@ -145,6 +161,14 @@ Create `.deepflow/config.yaml`:
 project:
   source_dir: src/
   specs_dir: specs/
+
+parallelism:
+  execute:
+    max: 5              # max parallel agents
+
+worktree:
+  cleanup_on_success: true
+  cleanup_on_fail: false  # preserve for debugging
 ```
 
 ## Principles

package/package.json

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

package/src/commands/df/execute.md

@@ -94,8 +94,8 @@ experiment_file: ".deepflow/experiments/upload--streaming--failed.md"
 {
   "completed_tasks": ["T1", "T2"],
   "current_wave": 2,
-  "worktree_path": ".deepflow/worktrees/df/doing-upload/20260202-1430",
-  "worktree_branch": "df/doing-upload/20260202-1430"
+  "worktree_path": ".deepflow/worktrees/upload",
+  "worktree_branch": "df/upload"
 }
 ```
 
@@ -126,26 +126,22 @@ 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
+# Generate paths
 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}"
+BRANCH_NAME="df/${SPEC_NAME}"
+WORKTREE_PATH=".deepflow/worktrees/${SPEC_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
+# Create worktree (or reuse existing)
+if [ -d "${WORKTREE_PATH}" ]; then
+  echo "Reusing existing worktree"
+else
+  git worktree add -b "${BRANCH_NAME}" "${WORKTREE_PATH}"
+fi
 ```
 
-**Resume handling:**
-- If checkpoint has worktree_path → verify it exists, use it
-- If worktree missing → Error: "Worktree deleted. Use --fresh"
+**Existing worktree:** Reuse it (same spec = same worktree).
 
-**Existing worktree handling:**
-- If worktree exists for same spec → Prompt: "Resume existing worktree? (y/n/delete)"
+**--fresh flag:** Deletes existing worktree and creates new one.
 
 ### 2. LOAD PLAN
 
@@ -357,19 +353,17 @@ When a task fails and cannot be auto-fixed:
 ✗ Task T3 failed after retry
 
 Worktree preserved for debugging:
-  Path: .deepflow/worktrees/df/doing-upload/20260202-1430
-  Branch: df/doing-upload/20260202-1430
+  Path: .deepflow/worktrees/upload
+  Branch: df/upload
 
 To investigate:
-  cd .deepflow/worktrees/df/doing-upload/20260202-1430
+  cd .deepflow/worktrees/upload
   # 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
 ```
 

package/src/commands/df/verify.md

@@ -157,7 +157,7 @@ rm .deepflow/checkpoint.json
 
 **Output on success:**
 ```
-✓ Merged df/doing-upload/20260202-1430 to main
+✓ Merged df/upload to main
 ✓ Cleaned up worktree and branch
 ✓ Spec complete: doing-upload → done-upload