deepflow 0.1.4 → 0.1.6

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

@@ -1,12 +1,15 @@
 # /df:execute — Execute Tasks from Plan
 
 ## Purpose
-Implement tasks from PLAN.md with parallel agents and atomic commits.
+Implement tasks from PLAN.md with parallel agents, atomic commits, and context-efficient execution.
 
 ## Usage
 ```
-/df:execute
-/df:execute T1 T2    # Execute specific tasks only
+/df:execute              # Execute all ready tasks
+/df:execute T1 T2        # Specific tasks only
+/df:execute --continue   # Resume from checkpoint
+/df:execute --fresh      # Ignore checkpoint
+/df:execute --dry-run    # Show plan only
 ```
 
 ## Skills & Agents
@@ -14,177 +17,115 @@ Implement tasks from PLAN.md with parallel agents and atomic commits.
 - Agent: `general-purpose` (Sonnet) — Task implementation
 - Agent: `reasoner` (Opus) — Debugging failures
 
-## Behavior
-
-### 1. LOAD PLAN
-
-```
-Load:
-- PLAN.md (required)
-- specs/*.md (for context)
-- .specflow/config.yaml (if exists)
-```
+## Context-Aware Execution
 
-If PLAN.md missing:
-```
-No PLAN.md found. Run /df:plan first.
-```
+Statusline writes to `.deepflow/context.json`: `{"percentage": 45}`
 
-### 2. IDENTIFY READY TASKS
+| Context % | Action |
+|-----------|--------|
+| < 50% | Full parallelism (up to 5 agents) |
+| ≥ 50% | Wait for running agents, checkpoint, exit |
 
-Find tasks where:
-- Status is `[ ]` (not done)
-- All `blocked_by` tasks are `[x]` (complete)
+## Agent Protocol
 
-```
-Ready: [T1, T2, T5]     # No blockers
-Blocked: [T3, T4]       # Waiting on dependencies
-Done: []
+Agents write results to `.deepflow/results/{task_id}.yaml`:
+```yaml
+task: T3
+status: success
+commit: abc1234
 ```
 
-### 3. EXECUTE IN PARALLEL
+**Spawn with:** `run_in_background: true`
+**Poll:** `Glob(".deepflow/results/T*.yaml")`
+**NEVER use TaskOutput** — returns full trace, wastes context.
 
-**Spawn `general-purpose` agents** (Sonnet) for ready tasks:
+## Checkpoint & Resume
 
-| Ready Tasks | Agents |
-|-------------|--------|
-| 1-3 | All parallel |
-| 4-10 | 5 parallel, queue rest |
-| 10+ | 5 parallel, queue rest |
+**File:** `.deepflow/checkpoint.json` — stores completed tasks, current wave.
 
-Each agent uses `atomic-commits` skill for commit protocol.
+**On checkpoint:** Complete wave → update PLAN.md → save → exit.
+**Resume:** `--continue` loads checkpoint, skips completed tasks.
 
-**Critical rule: 1 writer per file**
-If T1 and T2 both modify `src/api.ts`, execute sequentially.
+## Behavior
 
-**On failure:** Spawn `reasoner` agent (Opus) for debugging.
+### 1. CHECK CHECKPOINT
 
-### 4. PER-TASK EXECUTION
+```
+--continue → Load and resume
+--fresh → Delete checkpoint, start fresh
+checkpoint exists → Prompt: "Resume? (y/n)"
+else → Start fresh
+```
 
-Each executor agent:
+### 2. LOAD PLAN
 
 ```
-1. READ spec requirements for this task
-2. READ existing code context
-3. IMPLEMENT the task completely
-   - No stubs
-   - No placeholders
-   - No TODO comments
-4. VERIFY implementation works
-   - Run related tests if they exist
-   - Check TypeScript/lint if applicable
-5. COMMIT atomically
-   - Format: feat({spec}): {task description}
-   - One task = one commit
+Load: PLAN.md (required), specs/doing-*.md, .deepflow/config.yaml
+If missing: "No PLAN.md found. Run /df:plan first."
 ```
 
-### 5. UPDATE PLAN
+### 3. CHECK FOR UNPLANNED SPECS
 
-After each task completes:
-```markdown
-- [x] **T1**: Create upload API endpoint ✓ (abc1234)
-  - Files: src/api/upload.ts
-  - Blocked by: none
-```
+Warn if `specs/*.md` (excluding doing-/done-) exist. Non-blocking.
 
-### 6. ITERATE
+### 4. IDENTIFY READY TASKS
 
-After wave completes:
-```
-Wave 1 complete: T1 ✓, T2 ✓
+Ready = `[ ]` + all `blocked_by` complete + not in checkpoint.
 
-Unblocked: T3, T4 now ready
-Executing wave 2...
-```
+### 5. CHECK CONTEXT & EXECUTE
 
-Repeat until all tasks done or blocked.
+If context ≥50%: wait for agents, checkpoint, exit.
 
-### 7. REPORT
+| Ready | Strategy |
+|-------|----------|
+| 1-3 | All parallel |
+| 4+ | 5 parallel, queue rest |
 
-```
-✓ Execution complete
+1 writer per file. On failure: spawn `reasoner`.
 
-Tasks completed: 5/5
-Commits: 5
-Failed: 0
+### 6. PER-TASK (agent)
 
-All specs implemented. Run /df:verify to confirm.
-```
+Implement → verify → commit → write result file.
 
-Or if partial:
-```
-⚠ Execution paused
+### 7. COMPLETE SPECS
 
-Tasks completed: 3/5
-Blocked: T4 (waiting on T3)
-Failed: T3 (see error below)
+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
 
-Error in T3:
-  [error details]
+### 8. ITERATE
 
-Fix the issue and run /df:execute to continue.
-```
+Repeat until: all done, all blocked, or checkpoint.
 
 ## Rules
 
-### Parallelism
-- **Read operations**: Unlimited parallel
-- **Write operations**: Max 5 parallel, 1 per file
-- **Build/test**: Always sequential
-
-### Commits
-- One task = one commit
-- Format: `feat({spec}): {description}`
-- Include task ID in commit body
-- Never commit broken code
+| Rule | Enforcement |
+|------|-------------|
+| 1 task = 1 commit | `atomic-commits` skill |
+| No broken commits | Verify before commit |
+| 1 writer per file | Sequential if conflict |
+| Minimal returns | 5 lines max from agents |
+| Internal verification | Agents fix issues, don't report |
 
-### Completeness
-- No stubs or placeholders
-- No `// TODO` comments
-- Implement fully or don't commit
+## Example
 
-### Conflict Avoidance
-```
-If T1 writes to src/api.ts
-And T2 writes to src/api.ts
-Then execute T1, wait, then T2
 ```
+/df:execute (context: 12%)
 
-## Agent Spawning
+Wave 1: T1, T2 parallel (context: 25%)
+  T1: success (abc1234)
+  T2: success (def5678)
 
-```yaml
-executor_agents:
-  max_parallel: 5
-  per_file_limit: 1
+Wave 2: T3 (context: 48%)
+  T3: success (ghi9012)
 
-model_selection:
-  implement: sonnet
-  debug: opus
-
-commit_after: each_task
-push_after: all_complete  # Not every commit
+✓ doing-upload → done-upload
+✓ Complete: 3/3 tasks
 ```
 
-## Example Session
-
+With checkpoint:
 ```
-/df:execute
-
-Loading PLAN.md...
-Found 5 tasks, 3 ready (no blockers)
-
-Wave 1: Executing T1, T2, T5 in parallel...
-  T1: Create upload API endpoint... ✓ (abc1234)
-  T2: Add validation middleware... ✓ (def5678)
-  T5: Integrate color-thief... ✓ (ghi9012)
-
-Wave 2: T3, T4 now unblocked
-  T3: Implement S3 upload... ✓ (jkl3456)
-  T4: Complete thumbnails... ✓ (mno7890)
-
-✓ Execution complete
-Tasks: 5/5
-Commits: 5
-
-Run /df:verify to confirm specs satisfied.
+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 Limits
 
-analyze_agents:
-  base: 5
-  per_specs: 2   # 1 agent per 2 specs
-  cap: 20
-
-model_selection:
-  search: sonnet
-  analyze: opus
-```
+| Agent | Base | Scale | Cap |
+|-------|------|-------|-----|
+| Explore (search) | 10 | +1 per 20 files | 100 |
+| Reasoner (analyze) | 5 | +1 per 2 specs | 20 |
 
-## 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/.claude/skills/atomic-commits/SKILL.md

@@ -62,3 +62,17 @@ Task: T1
 - Never commit partial work
 - Never commit unrelated changes
 - One logical change per commit
+
+## Tags
+
+Format: `v{major}.{minor}.{patch}`
+
+| Trigger | Bump | Example |
+|---------|------|---------|
+| Breaking change | major | `v2.0.0` |
+| New feature | minor | `v1.1.0` |
+| Bug fix | patch | `v1.0.1` |
+
+Create: `git tag -a v1.0.0 -m "message"` → `git push origin v1.0.0`
+
+Tag after milestone complete, not every commit.

package/VERSION

@@ -1 +1 @@
-0.1.4
+0.1.5

package/bin/install.js

@@ -46,6 +46,8 @@ async function main() {
 
   if (level === 'global') {
     dirs.push('hooks', 'deepflow');
+  } else {
+    dirs.push('deepflow');
   }
 
   for (const dir of dirs) {
@@ -89,13 +91,18 @@ async function main() {
     }
   }
 
-  // Copy VERSION (global only - for update checking)
-  if (level === 'global') {
-    const versionFile = path.join(PACKAGE_DIR, 'VERSION');
-    if (fs.existsSync(versionFile)) {
-      fs.copyFileSync(versionFile, path.join(CLAUDE_DIR, 'deepflow', 'VERSION'));
-      log('Version file installed');
-    }
+  // Copy VERSION file (for update checking)
+  const versionFile = path.join(PACKAGE_DIR, 'VERSION');
+  if (fs.existsSync(versionFile)) {
+    fs.copyFileSync(versionFile, path.join(CLAUDE_DIR, 'deepflow', 'VERSION'));
+    log('Version file installed');
+  }
+
+  // Clear stale update cache to prevent false warnings
+  // Cache is always global, so clear it regardless of install level
+  const cacheFile = path.join(GLOBAL_DIR, 'cache', 'df-update-check.json');
+  if (fs.existsSync(cacheFile)) {
+    fs.unlinkSync(cacheFile);
   }
 
   // Configure statusline (global only)

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.4",
+  "version": "0.1.6",
   "description": "Stay in flow state - lightweight spec-driven task orchestration for Claude Code",
   "keywords": [
     "claude",

package/templates/state-template.md

@@ -29,6 +29,15 @@ Project context and learnings for LLM continuity.
 
 - [ ] [Blocker]: [Workaround if any]
 
+## Checkpoint
+
+[Auto-populated when /df:execute creates a checkpoint]
+
+- **Session**: [none]
+- **Progress**: [0/0 tasks]
+- **Tokens used**: [~0k/100k]
+- **Resume**: `/df:execute --continue`
+
 ## Session Log
 
 ### {Date}