deepflow 0.1.18 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "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, identify gaps, generate prioritized task list informed by historical learnings.
 
 ## Usage
 ```
@@ -42,7 +42,36 @@ 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
+
+Before proposing approaches, learn from history:
+
+```
+1. Extract domains from spec keywords (performance, auth, caching, api, etc.)
+2. Glob `.deepflow/experiments/{domain}--*`
+3. Read matching files (filenames are the index, minimal token cost)
+4. Note failed approaches to avoid
+5. Note successful patterns to reuse
+```
+
+**If experiments found:**
+- Failed: Exclude approach from plan, note why
+- Success: Reference as pattern to follow
+
+**File naming convention:**
+```
+.deepflow/experiments/
+  {domain}--{approach}--{result}.md
+
+Examples:
+  perf--redis-caching--failed.md
+  perf--connection-pooling--success.md
+  auth--jwt-refresh--success.md
+```
+
+**No experiments?** Continue normally—this is expected for new projects.
+
+### 3. DETECT PROJECT CONTEXT
 
 For existing codebases, identify:
 - Code style/conventions
@@ -51,7 +80,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 +97,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,20 +115,49 @@ Include patterns in task descriptions for agents to follow.
 2. Impact — core features before enhancements
 3. Risk — unknowns early
 
-### 5. OUTPUT PLAN.md
+### 6. VALIDATE HYPOTHESES
+
+Before finalizing the plan, identify and test risky assumptions:
+
+**When to validate:**
+- Unfamiliar APIs or libraries
+- Architectural decisions with multiple approaches
+- Integration with external systems
+- Performance-critical paths
+
+**How to validate:**
+1. Create minimal prototype (scratchpad, not committed)
+2. Test the specific assumption
+3. If fails: Write to `.deepflow/experiments/{domain}--{approach}--failed.md`
+4. Adjust approach based on findings
+5. Document learnings in task description
+
+**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
+
+**Skip validation when:**
+- Using well-known patterns
+- Simple CRUD operations
+- Clear documentation exists
+
+### 7. OUTPUT PLAN.md
 
-Append tasks grouped by `### doing-{spec-name}`. Include spec gaps if any.
+Append tasks grouped by `### doing-{spec-name}`. Include spec gaps and validation findings.
 
-### 6. RENAME SPECS
+### 8. RENAME SPECS
 
 `mv specs/feature.md specs/doing-feature.md`
 
-### 7. REPORT
+### 9. REPORT
 
 `✓ Plan generated — {n} specs, {n} tasks. Run /df:execute`
 
 ## Rules
-- **Plan only** — Do NOT implement anything
+- **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"
 - **One task = one logical unit** — Atomic, committable
 - Prefer existing utilities over new code
@@ -123,7 +181,9 @@ Append tasks grouped by `### doing-{spec-name}`. Include spec gaps if any.
   - 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,33 @@ 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
+
+After successful verification, document significant learnings:
+
+**When to write experiment:**
+- Non-trivial implementation approach was used
+- Alternative approaches were considered/rejected during planning
+- Performance optimizations were made
+- Integration patterns were discovered
+
+**Write to:** `.deepflow/experiments/{domain}--{approach}--success.md`
+
+**Format:**
+```markdown
+# {Approach} [SUCCESS]
+Objective: {What was the goal}
+Context: {Spec reference, why this was needed}
+Approach: {What was implemented}
+Why it worked: {Key insight}
+Files: {Main files involved}
+```
+
+**Skip when:**
+- Simple CRUD, no learnings
+- Standard patterns, well-documented
+- User declines ("No significant learnings")
+
 ## Verification Levels
 
 | Level | Check | Method |
@@ -62,6 +89,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 +104,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
 ```