deepflow 0.1.5 → 0.1.7

package/.claude/commands/df/execute.md

@@ -17,63 +17,34 @@ Implement tasks from PLAN.md with parallel agents, atomic commits, and context-e
 - Agent: `general-purpose` (Sonnet) — Task implementation
 - Agent: `reasoner` (Opus) — Debugging failures
 
-## Context Budget
+## Context-Aware Execution
 
-| Threshold | Tokens | Action |
-|-----------|--------|--------|
-| Normal | <60k | Continue execution |
-| Warning | 60k | Display budget status |
-| Checkpoint | 80k | Save state, prompt resume |
-| Limit | 100k | Hard stop |
+Statusline writes to `.deepflow/context.json`: `{"percentage": 45}`
 
-Display after each wave: `Budget: ~45k/100k tokens`
+| Context % | Action |
+|-----------|--------|
+| < 50% | Full parallelism (up to 5 agents) |
+| ≥ 50% | Wait for running agents, checkpoint, exit |
 
-Token estimates: ~650/task, ~200/wave overhead.
-
-## Agent Output Protocol
-
-Agents MUST return exactly 5 lines:
+## Agent Protocol
 
+Agents write results to `.deepflow/results/{task_id}.yaml`:
 ```yaml
 task: T3
-status: success|failed
+status: success
 commit: abc1234
-duration: 45s
-error: "single line if failed"
-```
-
-**Agent instructions (include in spawn):**
-```
-Return ONLY 5-line YAML. No test output, git logs, or stack traces.
-Handle all verification internally. Fix issues before returning.
 ```
 
-If verbose output received: extract minimal data, discard rest.
+**Spawn with:** `run_in_background: true`
+**Poll:** `Glob(".deepflow/results/T*.yaml")`
+**NEVER use TaskOutput** — returns full trace, wastes context.
 
 ## Checkpoint & Resume
 
-**File:** `.deepflow/checkpoint.json`
-
-```json
-{
-  "session_id": "exec_abc123",
-  "completed_tasks": ["T1", "T2"],
-  "current_wave": 2,
-  "last_commit": "def5678",
-  "estimated_tokens_used": 82000,
-  "decisions_made": ["Used multer for uploads"],
-  "resume_instructions": "Continue with Wave 3"
-}
-```
-
-**Checkpoint protocol** (at 80k tokens):
-1. Complete current task
-2. Wait for parallel agents
-3. Update PLAN.md
-4. Write checkpoint atomically (.tmp → rename)
-5. Print: `Context limit reached. Run /df:execute --continue`
+**File:** `.deepflow/checkpoint.json` — stores completed tasks, current wave.
 
-**Resume** (`--continue`): Load checkpoint, skip completed tasks, reset token counter.
+**On checkpoint:** Complete wave → update PLAN.md → save → exit.
+**Resume:** `--continue` loads checkpoint, skips completed tasks.
 
 ## Behavior
 
@@ -89,44 +60,40 @@ else → Start fresh
 ### 2. LOAD PLAN
 
 ```
-Load: PLAN.md (required), specs/*.md, .deepflow/config.yaml
+Load: PLAN.md (required), specs/doing-*.md, .deepflow/config.yaml
 If missing: "No PLAN.md found. Run /df:plan first."
 ```
 
-### 3. IDENTIFY READY TASKS
+### 3. CHECK FOR UNPLANNED SPECS
+
+Warn if `specs/*.md` (excluding doing-/done-) exist. Non-blocking.
+
+### 4. IDENTIFY READY TASKS
 
-Ready = `[ ]` status + all `blocked_by` complete + not in checkpoint.
+Ready = `[ ]` + all `blocked_by` complete + not in checkpoint.
 
-### 4. EXECUTE IN PARALLEL
+### 5. CHECK CONTEXT & EXECUTE
 
-| Ready | Strategy |
-|-------|----------|
-| 1-3 | All parallel |
-| 4+ | 5 parallel, queue rest |
+If context ≥50%: wait for agents, checkpoint, exit.
 
-**Critical:** 1 writer per file. If T1 and T2 both modify `src/api.ts`, execute sequentially.
+All ready tasks run in parallel. File conflicts execute sequentially.
 
-**On failure:** Spawn `reasoner` (Opus) for debugging.
+On failure: spawn `reasoner`.
 
-### 5. PER-TASK EXECUTION
+### 6. PER-TASK (agent)
 
-Each agent internally:
-1. Read spec requirements
-2. Implement completely (no stubs/TODOs)
-3. Verify (tests, types, lint) — fix issues
-4. Commit atomically: `feat({spec}): {description}`
-5. Return 5-line YAML only
+Implement → verify → commit → write result file.
 
-### 6. UPDATE & CHECK BUDGET
+### 7. COMPLETE SPECS
 
-- Mark task complete in PLAN.md with commit hash
-- Update token estimate
-- If >80k: checkpoint and exit
-- If >60k: show warning
+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
 
-### 7. ITERATE
+### 8. ITERATE
 
-Repeat until: all done, all blocked, or budget reached.
+Repeat until: all done, all blocked, or checkpoint.
 
 ## Rules
 
@@ -141,24 +108,21 @@ Repeat until: all done, all blocked, or budget reached.
 ## Example
 
 ```
-/df:execute
+/df:execute (context: 12%)
 
-Loading PLAN.md...
-Found 5 tasks, 3 ready
+Wave 1: T1, T2 parallel (context: 25%)
+  T1: success (abc1234)
+  T2: success (def5678)
 
-Wave 1: T1, T2, T5 in parallel...
-  T1: success (abc1234) 45s
-  T2: success (def5678) 32s
-  T5: success (ghi9012) 28s
-Budget: ~32k/100k tokens
+Wave 2: T3 (context: 48%)
+  T3: success (ghi9012)
 
-Wave 2: T3, T4 unblocked
-  T3: success (jkl3456) 67s
-  T4: success (mno7890) 41s
-Budget: ~52k/100k tokens
-
-✓ Execution complete
-Tasks: 5/5 | Commits: 5
+✓ doing-upload → done-upload
+✓ Complete: 3/3 tasks
+```
 
-Run /df:verify to confirm specs satisfied.
+With checkpoint:
+```
+Wave 1 complete (context: 52%)
+Checkpoint saved. Run /df:execute --continue
 ```

package/.claude/commands/df/plan.md

@@ -5,26 +5,43 @@ Compare specs against codebase, identify gaps, generate prioritized task list.
 
 ## Usage
 ```
-/df:plan
+/df:plan                 # Plan all new specs
+/df:plan feature.md      # Plan specific spec
 ```
 
 ## Skills & Agents
 - Skill: `code-completeness` — Find TODOs, stubs, incomplete work
 - Agent: `reasoner` (Opus) — Complex analysis and prioritization
 
+## Spec File States
+
+```
+specs/
+  feature.md        → New, needs planning (this command reads these)
+  doing-auth.md     → In progress, has tasks in PLAN.md
+  done-payments.md  → Completed, history embedded
+```
+
+**Filtering:**
+- New: `specs/*.md` excluding `doing-*` and `done-*`
+- In progress: `specs/doing-*.md`
+- Completed: `specs/done-*.md`
+
 ## Behavior
 
 ### 1. LOAD CONTEXT
 
 ```
 Load:
-- specs/*.md (all spec files)
-- PLAN.md (if exists, prior state)
-- .specflow/config.yaml (if exists)
+- specs/*.md EXCLUDING doing-* and done-* (only new specs)
+- PLAN.md (if exists, for appending)
+- .deepflow/config.yaml (if exists)
 
 Determine source_dir from config or default to src/
 ```
 
+If no new specs: report counts, suggest `/df:execute`.
+
 ### 2. ANALYZE CODEBASE
 
 **Spawn Explore agents** (haiku, read-only) with dynamic count:
@@ -44,68 +61,33 @@ Determine source_dir from config or default to src/
 
 ### 3. COMPARE & PRIORITIZE
 
-**Spawn `reasoner` agent** (Opus) for complex analysis:
-
-| Status | Meaning | Action |
-|--------|---------|--------|
-| DONE | Fully implemented | Mark complete |
-| PARTIAL | Stub or incomplete | Task to complete |
-| MISSING | Not found in code | Task to implement |
-| CONFLICT | Code contradicts spec | Flag for review |
-
-Reasoner prioritizes by dependencies, impact, and risk.
-
-### 4. PRIORITIZE
+**Spawn `reasoner` agent** (Opus) for analysis:
 
-Order tasks by:
-1. **Dependencies** — Blockers first
-2. **Impact** — Core features before enhancements
-3. **Risk** — Unknowns early (reduce risk)
+| Status | Action |
+|--------|--------|
+| DONE | Skip |
+| PARTIAL | Task to complete |
+| MISSING | Task to implement |
+| CONFLICT | Flag for review |
 
-### 5. OUTPUT PLAN.md
+**Spec gaps:** If spec is ambiguous or missing details, note in output (don't silently assume).
 
-```markdown
-# Plan
-
-Generated: {timestamp}
-Specs analyzed: {count}
+**Priority order:**
+1. Dependencies — blockers first
+2. Impact — core features before enhancements
+3. Risk — unknowns early
 
-## Spec Gaps
-[If any specs need updates, list here]
-- [ ] specs/X.md: Missing error handling definition
+### 4. OUTPUT PLAN.md
 
-## Tasks
+Append tasks grouped by `### doing-{spec-name}`. Include spec gaps if any.
 
-### {spec-name}
-
-- [ ] **T1**: {task description}
-  - Files: {files to create/modify}
-  - Blocked by: none
+### 5. RENAME SPECS
 
-- [ ] **T2**: {task description}
-  - Files: {files}
-  - Blocked by: T1
-
-### {another-spec}
-
-- [ ] **T3**: {task description}
-  - Files: {files}
-  - Blocked by: none
-```
+`mv specs/feature.md specs/doing-feature.md`
 
 ### 6. REPORT
 
-```
-✓ Plan generated
-
-Specs analyzed: {n}
-Tasks created: {n}
-Spec gaps found: {n}
-
-Ready to execute: {n} tasks (no blockers)
-
-Next: Run /df:execute to start implementation
-```
+`✓ Plan generated — {n} specs, {n} tasks. Run /df:execute`
 
 ## Rules
 - **Plan only** — Do NOT implement anything
@@ -114,58 +96,25 @@ Next: Run /df:execute to start implementation
 - Prefer existing utilities over new code
 - Flag spec gaps, don't silently ignore
 
-## Agent Spawning Rules
-
-```yaml
-search_agents:
-  base: 10
-  per_files: 20  # 1 agent per 20 files
-  cap: 100
+## Agent Scaling
 
-analyze_agents:
-  base: 5
-  per_specs: 2   # 1 agent per 2 specs
-  cap: 20
-
-model_selection:
-  search: sonnet
-  analyze: opus
-```
+| Agent | Base | Scale |
+|-------|------|-------|
+| Explore (search) | 10 | +1 per 20 files |
+| Reasoner (analyze) | 5 | +1 per 2 specs |
 
-## Example Output
+## Example
 
 ```markdown
 # Plan
 
-Generated: 2025-01-28 14:30
-Specs analyzed: 2
+### doing-upload
 
-## Spec Gaps
-- [ ] specs/image-upload.md: No error handling for S3 failures defined
-
-## Tasks
-
-### image-upload
-
-- [ ] **T1**: Create upload API endpoint
-  - Files: src/api/upload.ts (create)
-  - Blocked by: none
-
-- [ ] **T2**: Add file validation middleware
-  - Files: src/middleware/validate.ts (create)
+- [ ] **T1**: Create upload endpoint
+  - Files: src/api/upload.ts
   - Blocked by: none
 
-- [ ] **T3**: Implement S3 upload service
-  - Files: src/services/storage.ts (create)
-  - Blocked by: T1
-
-- [ ] **T4**: Complete thumbnail generation
-  - Files: src/services/image.ts:45 (stub found)
-  - Blocked by: T3
-
-### color-extraction
-
-- [ ] **T5**: Integrate color-thief library
-  - Files: src/services/color.ts (create)
+- [ ] **T2**: Add S3 service
+  - Files: src/services/storage.ts
   - Blocked by: T1
 ```

package/.claude/commands/df/verify.md

@@ -5,108 +5,46 @@ Check that implemented code satisfies spec requirements and acceptance criteria.
 
 ## Usage
 ```
-/df:verify
-/df:verify image-upload    # Verify specific spec only
+/df:verify                  # Verify all done-* specs
+/df:verify --doing          # Also verify in-progress specs
+/df:verify done-upload      # Verify specific spec
 ```
 
 ## Skills & Agents
 - Skill: `code-completeness` — Find incomplete implementations
 - Agent: `Explore` (Haiku) — Fast codebase scanning
 
-## Behavior
-
-### 1. LOAD CONTEXT
+## Spec File States
 
 ```
-Load:
-- specs/*.md (requirements to verify)
-- PLAN.md (task completion status)
-- Source code (actual implementation)
+specs/
+  feature.md        → Unplanned (skip)
+  doing-auth.md     → In progress (verify with --doing)
+  done-upload.md    → Completed (default verify target)
 ```
 
-### 2. VERIFY EACH SPEC
+## Behavior
 
-For each spec file, check:
+### 1. LOAD CONTEXT
 
-#### Requirements Coverage
 ```
-For each REQ-N in spec:
-  - Find implementation in code
-  - Verify it meets the requirement
-  - Mark: ✓ satisfied | ✗ missing | ⚠ partial
+Load:
+- specs/done-*.md (completed specs to verify)
+- specs/doing-*.md (if --doing flag)
+- Source code (actual implementation)
 ```
 
-#### Acceptance Criteria
-```
-For each criterion:
-  - Can it be verified? (testable)
-  - Is there evidence it passes?
-  - Mark: ✓ | ✗ | ⚠
-```
+If no done-* specs: report counts, suggest `--doing`.
 
-#### Implementation Quality
+### 2. VERIFY EACH SPEC
 
-Use `code-completeness` skill patterns to check for:
-- Stub functions (not fully implemented)
-- TODO/FIXME comments (incomplete work)
-- Placeholder returns (fake implementations)
-- Skipped tests (untested code)
+Check requirements, acceptance criteria, and quality (stubs/TODOs).
+Mark each: ✓ satisfied | ✗ missing | ⚠ partial
 
 ### 3. GENERATE REPORT
 
-**If all pass:**
-```
-✓ Verification complete
-
-specs/image-upload.md
-  Requirements: 4/4 ✓
-  Acceptance criteria: 5/5 ✓
-  Quality: No stubs or TODOs
-
-specs/color-extraction.md
-  Requirements: 2/2 ✓
-  Acceptance criteria: 3/3 ✓
-  Quality: No stubs or TODOs
-
-All specs satisfied.
-```
-
-**If issues found:**
-```
-⚠ Verification found issues
-
-specs/image-upload.md
-  Requirements: 3/4
-    ✗ REQ-4: Error handling for S3 failures
-      Expected: Graceful error with retry option
-      Found: No error handling in src/services/storage.ts
-
-  Acceptance criteria: 4/5
-    ⚠ "Upload shows progress bar"
-      Found: Progress callback exists but UI not connected
-
-  Quality:
-    ⚠ src/services/image.ts:67 — TODO: optimize for large files
-
-Action needed:
-  1. Add S3 error handling (REQ-4)
-  2. Connect progress UI
-  3. Complete TODO in image.ts
-
-Run /df:plan to generate fix tasks, or fix manually.
-```
-
-### 4. UPDATE STATE
-
-Write findings to STATE.md:
-```markdown
-## Verification Log
-
-### 2025-01-28 15:30
-Verified: image-upload, color-extraction
-Result: 1 spec gap, 2 quality issues
-Action: Generated fix tasks
-```
+Report per spec: requirements count, acceptance count, quality issues.
+If issues: suggest creating fix spec or reopening (`mv done-* doing-*`).
 
 ## Verification Levels
 
@@ -127,43 +65,15 @@ Default: L1-L3 (L4 optional, can be slow)
 
 ## Agent Usage
 
-Spawn `Explore` agents (Haiku) for fast read-only scanning:
-- 1-2 agents per spec (based on spec size)
-- Cap: 10 parallel agents
-- Read-only: safe to parallelize heavily
+Spawn `Explore` agents (Haiku), 1-2 per spec, cap 10.
 
 ## Example
 
 ```
 /df:verify
 
-Verifying 2 specs...
-
-specs/image-upload.md
-  ├─ REQ-1: Upload endpoint ✓
-  │    src/api/upload.ts exports POST /api/upload
-  ├─ REQ-2: File validation ✓
-  │    src/middleware/validate.ts checks type, size
-  ├─ REQ-3: S3 storage ✓
-  │    src/services/storage.ts implements uploadToS3()
-  └─ REQ-4: Thumbnails ✓
-       src/services/image.ts implements generateThumbnail()
-
-  Acceptance: 5/5 ✓
-  Quality: Clean
-
-specs/color-extraction.md
-  ├─ REQ-1: Extract colors ✓
-  └─ REQ-2: Palette display ⚠
-       Found: Component exists but not exported
-
-  Acceptance: 2/3
-  Quality: 1 TODO found
-
-Summary:
-  Specs: 2
-  Passed: 1
-  Issues: 1
+done-upload.md: 4/4 reqs ✓, 5/5 acceptance ✓, clean
+done-auth.md: 2/2 reqs ✓, 3/3 acceptance ✓, clean
 
-Run /df:plan to generate fix tasks.
+✓ All specs verified
 ```

package/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nfeat: add spec lifecycle states and context-aware execution\n\nSpec file states \\(doing-/done- prefixes\\):\n- New specs: specs/*.md \\(no prefix\\)\n- In progress: specs/doing-*.md \\(has tasks in PLAN.md\\)\n- Completed: specs/done-*.md \\(history embedded\\)\n\nPlan command:\n- Only reads new specs \\(excludes doing-/done-\\)\n- Renames to doing-* after creating tasks\n- Appends to PLAN.md \\(preserves existing\\)\n\nExecute command:\n- Context-aware via .deepflow/context.json\n- At ≥50% context: stop spawning, wait, checkpoint\n- File-based agent results \\(no TaskOutput\\)\n- Completes specs: embed history, rename done-*, clean PLAN.md\n\nVerify command:\n- Verifies done-* specs by default\n- --doing flag for in-progress specs\n\nStatusline hook:\n- Writes context % to .deepflow/context.json\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git push)",
+      "Bash(npm version:*)",
+      "Bash(git commit:*)",
+      "Bash(npm publish:*)"
+    ]
+  }
+}

package/README.md

@@ -14,8 +14,7 @@
 <p align="center">
   <a href="#quick-start">Quick Start</a> •
   <a href="#the-flow">The Flow</a> •
-  <a href="#commands">Commands</a> •
-  <a href="docs/getting-started.md">Docs</a>
+  <a href="#commands">Commands</a>
 </p>
 
 ---
@@ -25,9 +24,8 @@
 - **Stay in flow** — Minimize context switches, maximize deep work
 - **Conversational ideation** with proactive gap discovery
 - **Specs define intent**, tasks close reality gaps
-- **Parallel execution** with dependency awareness
+- **Parallel execution** with context-aware checkpointing
 - **Atomic commits** for clean rollback
-- **Minimal ceremony** — 4 commands, not 27
 
 ## Quick Start
 
@@ -38,7 +36,7 @@ npx deepflow
 # In your project
 claude
 
-# 1. Discuss what you want to build (conversation)
+# 1. Discuss what you want to build
 # 2. Generate spec when ready
 /df:spec image-upload
 
@@ -57,39 +55,42 @@ claude
 ```
 CONVERSATION
     │ Describe what you want
-    │ LLM asks gap questions (scope, edge cases, constraints)
+    │ LLM asks gap questions
     ▼
 /df:spec <name>
-    │ Generates specs/{name}.md
+    │ Creates specs/{name}.md
     ▼
 /df:plan
-    │ Compares specs to codebase
-    │ Finds TODOs, stubs, missing implementations
-    │ Outputs PLAN.md with prioritized tasks
+    │ Analyzes specs vs codebase
+    │ Creates PLAN.md with tasks
+    │ Renames: feature.md → doing-feature.md
     ▼
 /df:execute
-    │ Runs tasks respecting dependencies
-    │ Parallel for independent tasks
+    │ Parallel agents per wave
+    │ Context-aware (≥50% → checkpoint)
     │ Atomic commit per task
     ▼
 /df:verify
-    │ Checks spec requirements met
-    │ Updates PLAN.md status
+    │ Checks requirements met
+    │ Renames: doing-feature.md → done-feature.md
 ```
 
-## File Structure
-
-After running deepflow, your project will have:
+## Spec Lifecycle
 
 ```
-your-project/
-├── specs/
-│   ├── feature-a.md
-│   └── feature-b.md
-├── PLAN.md          # Task checklist
-└── STATE.md         # Decisions & learnings
+specs/
+  feature.md        → new, needs /df:plan
+  doing-feature.md  → in progress, has tasks in PLAN.md
+  done-feature.md   → completed, history embedded
 ```
 
+## Context-Aware Execution
+
+Statusline shows context usage. At ≥50%:
+- Waits for running agents
+- Checkpoints state
+- Resume with `/df:execute --continue`
+
 ## Commands
 
 | Command | Purpose |
@@ -98,40 +99,40 @@ your-project/
 | `/df:plan` | Compare specs to code, create tasks |
 | `/df:execute` | Run tasks with parallel agents |
 | `/df:verify` | Check specs satisfied |
+| `/df:update` | Update deepflow to latest |
+
+## File Structure
+
+```
+your-project/
+├── specs/
+│   ├── auth.md           # new spec
+│   ├── doing-upload.md   # in progress
+│   └── done-payments.md  # completed
+├── PLAN.md               # active tasks only
+└── .deepflow/
+    ├── context.json      # context % for execution
+    ├── checkpoint.json   # resume state
+    └── results/          # agent results
+```
 
 ## Configuration
 
-Create `.deepflow/config.yaml` in your project:
+Create `.deepflow/config.yaml`:
 
 ```yaml
 project:
   source_dir: src/
   specs_dir: specs/
-
-planning:
-  search_patterns:
-    - "TODO"
-    - "FIXME"
-    - "stub"
-    - "placeholder"
-
-parallelism:
-  max_search_agents: 50
-  max_write_agents: 5
-
-models:
-  search: sonnet
-  implement: sonnet
-  reason: opus
 ```
 
 ## Principles
 
 1. **Stay in flow** — Uninterrupted deep work
-2. **Confirm before assume** — Search code before creating "missing" tasks
+2. **Confirm before assume** — Search code before marking "missing"
 3. **Complete implementations** — No stubs, no placeholders
 4. **Atomic commits** — One task = one commit
-5. **Single writer per file** — Avoid race conditions
+5. **Context-aware** — Checkpoint before limits
 
 ## License
 

package/hooks/df-statusline.js

@@ -74,6 +74,9 @@ function buildContextMeter(contextWindow) {
 
   percentage = Math.min(100, Math.round(percentage));
 
+  // Write context usage to file for deepflow commands
+  writeContextUsage(percentage);
+
   // Build 10-segment bar
   const segments = 10;
   const filled = Math.round((percentage / 100) * segments);
@@ -107,3 +110,19 @@ function checkForUpdate() {
     return null;
   }
 }
+
+function writeContextUsage(percentage) {
+  try {
+    const deepflowDir = path.join(process.cwd(), '.deepflow');
+    if (!fs.existsSync(deepflowDir)) {
+      fs.mkdirSync(deepflowDir, { recursive: true });
+    }
+    const contextPath = path.join(deepflowDir, 'context.json');
+    fs.writeFileSync(contextPath, JSON.stringify({
+      percentage,
+      timestamp: Date.now()
+    }));
+  } catch (e) {
+    // Fail silently
+  }
+}

package/package.json

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