deepflow 0.1.19 → 0.1.21

package/package.json

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

package/src/commands/df/plan.md

@@ -1,7 +1,7 @@
 # /df:plan — Generate Task Plan from Specs
 
 ## Purpose
-Compare specs against codebase, identify gaps, generate prioritized task list.
+Compare specs against codebase and past experiments. Generate prioritized tasks.
 
 ## Usage
 ```
@@ -42,7 +42,23 @@ Determine source_dir from config or default to src/
 
 If no new specs: report counts, suggest `/df:execute`.
 
-### 2. DETECT PROJECT CONTEXT
+### 2. CHECK PAST EXPERIMENTS
+
+Extract domains from spec (perf, auth, api, etc.), then:
+
+```
+Glob .deepflow/experiments/{domain}--*
+```
+
+| Result | Action |
+|--------|--------|
+| `--failed.md` | Exclude approach, note why |
+| `--success.md` | Reference as pattern |
+| No matches | Continue (expected for new projects) |
+
+**Naming:** `{domain}--{approach}--{result}.md`
+
+### 3. DETECT PROJECT CONTEXT
 
 For existing codebases, identify:
 - Code style/conventions
@@ -51,7 +67,7 @@ For existing codebases, identify:
 
 Include patterns in task descriptions for agents to follow.
 
-### 3. ANALYZE CODEBASE
+### 4. ANALYZE CODEBASE
 
 **Spawn Explore agents** (haiku, read-only) with dynamic count:
 
@@ -68,7 +84,7 @@ Include patterns in task descriptions for agents to follow.
 - Stub functions, placeholder returns
 - Skipped tests, incomplete coverage
 
-### 4. COMPARE & PRIORITIZE
+### 5. COMPARE & PRIORITIZE
 
 **Spawn `reasoner` agent** (Opus) for analysis:
 
@@ -86,45 +102,34 @@ Include patterns in task descriptions for agents to follow.
 2. Impact — core features before enhancements
 3. Risk — unknowns early
 
-### 5. VALIDATE HYPOTHESES
-
-Before finalizing the plan, identify and test risky assumptions:
+### 6. VALIDATE HYPOTHESES
 
-**When to validate:**
-- Unfamiliar APIs or libraries
-- Architectural decisions with multiple approaches
-- Integration with external systems
-- Performance-critical paths
+Test risky assumptions before finalizing plan.
 
-**How to validate:**
-1. Create minimal prototype (scratchpad, not committed)
-2. Test the specific assumption
-3. Document findings in task description
-4. Adjust approach if hypothesis fails
+**Validate when:** Unfamiliar APIs, multiple approaches possible, external integrations, performance-critical
 
-**Examples:**
-- "Does SessionStart hook run once per session?" → Test with simple log
-- "Can we use streaming for large files?" → Prototype with sample data
-- "Will this regex handle edge cases?" → Test against real samples
+**Process:**
+1. Prototype in scratchpad (not committed)
+2. Test assumption
+3. If fails → Write `.deepflow/experiments/{domain}--{approach}--failed.md`
+4. Adjust approach, document in task
 
-**Skip validation when:**
-- Using well-known patterns
-- Simple CRUD operations
-- Clear documentation exists
+**Skip:** Well-known patterns, simple CRUD, clear docs exist
 
-### 6. OUTPUT PLAN.md
+### 7. OUTPUT PLAN.md
 
 Append tasks grouped by `### doing-{spec-name}`. Include spec gaps and validation findings.
 
-### 7. RENAME SPECS
+### 8. RENAME SPECS
 
 `mv specs/feature.md specs/doing-feature.md`
 
-### 8. REPORT
+### 9. REPORT
 
 `✓ Plan generated — {n} specs, {n} tasks. Run /df:execute`
 
 ## Rules
+- **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
 - **Confirm before assume** — Search code before marking "missing"
@@ -150,7 +155,9 @@ Append tasks grouped by `### doing-{spec-name}`. Include spec gaps and validatio
   - Files: src/api/upload.ts
   - Blocked by: none
 
-- [ ] **T2**: Add S3 service
+- [ ] **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)
 ```

package/src/commands/df/verify.md

@@ -46,6 +46,27 @@ Mark each: ✓ satisfied | ✗ missing | ⚠ partial
 Report per spec: requirements count, acceptance count, quality issues.
 If issues: suggest creating fix spec or reopening (`mv done-* doing-*`).
 
+### 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
+
+**Format:**
+```markdown
+# {Approach} [SUCCESS]
+Objective: ...
+Approach: ...
+Why it worked: ...
+Files: ...
+```
+
+**Skip:** Simple CRUD, standard patterns, user declines
+
 ## Verification Levels
 
 | Level | Check | Method |
@@ -62,6 +83,7 @@ Default: L1-L3 (L4 optional, can be slow)
 - Flag partial implementations
 - Report TODO/FIXME as quality issues
 - Don't auto-fix — report findings for `/df:plan`
+- Capture learnings — Write experiments for significant approaches
 
 ## Agent Usage
 
@@ -76,4 +98,8 @@ done-upload.md: 4/4 reqs ✓, 5/5 acceptance ✓, clean
 done-auth.md: 2/2 reqs ✓, 3/3 acceptance ✓, clean
 
 ✓ All specs verified
+
+Learnings captured:
+  → experiments/perf--streaming-upload--success.md
+  → experiments/auth--jwt-refresh-rotation--success.md
 ```