deepflow 0.1.4 → 0.1.5

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,148 @@ Implement tasks from PLAN.md with parallel agents and atomic commits.
 - Agent: `general-purpose` (Sonnet) — Task implementation
 - Agent: `reasoner` (Opus) — Debugging failures
 
-## Behavior
+## Context Budget
 
-### 1. LOAD PLAN
+| Threshold | Tokens | Action |
+|-----------|--------|--------|
+| Normal | <60k | Continue execution |
+| Warning | 60k | Display budget status |
+| Checkpoint | 80k | Save state, prompt resume |
+| Limit | 100k | Hard stop |
 
-```
-Load:
-- PLAN.md (required)
-- specs/*.md (for context)
-- .specflow/config.yaml (if exists)
-```
+Display after each wave: `Budget: ~45k/100k tokens`
 
-If PLAN.md missing:
-```
-No PLAN.md found. Run /df:plan first.
-```
+Token estimates: ~650/task, ~200/wave overhead.
 
-### 2. IDENTIFY READY TASKS
+## Agent Output Protocol
 
-Find tasks where:
-- Status is `[ ]` (not done)
-- All `blocked_by` tasks are `[x]` (complete)
+Agents MUST return exactly 5 lines:
+
+```yaml
+task: T3
+status: success|failed
+commit: abc1234
+duration: 45s
+error: "single line if failed"
+```
 
+**Agent instructions (include in spawn):**
 ```
-Ready: [T1, T2, T5]     # No blockers
-Blocked: [T3, T4]       # Waiting on dependencies
-Done: []
+Return ONLY 5-line YAML. No test output, git logs, or stack traces.
+Handle all verification internally. Fix issues before returning.
 ```
 
-### 3. EXECUTE IN PARALLEL
+If verbose output received: extract minimal data, discard rest.
 
-**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`
 
-Each agent uses `atomic-commits` skill for commit protocol.
+```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"
+}
+```
 
-**Critical rule: 1 writer per file**
-If T1 and T2 both modify `src/api.ts`, execute sequentially.
+**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`
 
-**On failure:** Spawn `reasoner` agent (Opus) for debugging.
+**Resume** (`--continue`): Load checkpoint, skip completed tasks, reset token counter.
 
-### 4. PER-TASK EXECUTION
+## Behavior
 
-Each executor agent:
+### 1. CHECK CHECKPOINT
 
 ```
-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
+--continue → Load and resume
+--fresh → Delete checkpoint, start fresh
+checkpoint exists → Prompt: "Resume? (y/n)"
+else → Start fresh
 ```
 
-### 5. UPDATE PLAN
-
-After each task completes:
-```markdown
-- [x] **T1**: Create upload API endpoint ✓ (abc1234)
-  - Files: src/api/upload.ts
-  - Blocked by: none
-```
-
-### 6. ITERATE
-
-After wave completes:
-```
-Wave 1 complete: T1 ✓, T2 ✓
+### 2. LOAD PLAN
 
-Unblocked: T3, T4 now ready
-Executing wave 2...
 ```
-
-Repeat until all tasks done or blocked.
-
-### 7. REPORT
-
+Load: PLAN.md (required), specs/*.md, .deepflow/config.yaml
+If missing: "No PLAN.md found. Run /df:plan first."
 ```
-✓ Execution complete
-
-Tasks completed: 5/5
-Commits: 5
-Failed: 0
 
-All specs implemented. Run /df:verify to confirm.
-```
+### 3. IDENTIFY READY TASKS
 
-Or if partial:
-```
-⚠ Execution paused
+Ready = `[ ]` status + all `blocked_by` complete + not in checkpoint.
 
-Tasks completed: 3/5
-Blocked: T4 (waiting on T3)
-Failed: T3 (see error below)
+### 4. EXECUTE IN PARALLEL
 
-Error in T3:
-  [error details]
+| Ready | Strategy |
+|-------|----------|
+| 1-3 | All parallel |
+| 4+ | 5 parallel, queue rest |
 
-Fix the issue and run /df:execute to continue.
-```
+**Critical:** 1 writer per file. If T1 and T2 both modify `src/api.ts`, execute sequentially.
 
-## Rules
+**On failure:** Spawn `reasoner` (Opus) for debugging.
 
-### Parallelism
-- **Read operations**: Unlimited parallel
-- **Write operations**: Max 5 parallel, 1 per file
-- **Build/test**: Always sequential
+### 5. PER-TASK EXECUTION
 
-### Commits
-- One task = one commit
-- Format: `feat({spec}): {description}`
-- Include task ID in commit body
-- Never commit broken code
+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
 
-### Completeness
-- No stubs or placeholders
-- No `// TODO` comments
-- Implement fully or don't commit
+### 6. UPDATE & CHECK BUDGET
 
-### Conflict Avoidance
-```
-If T1 writes to src/api.ts
-And T2 writes to src/api.ts
-Then execute T1, wait, then T2
-```
+- Mark task complete in PLAN.md with commit hash
+- Update token estimate
+- If >80k: checkpoint and exit
+- If >60k: show warning
 
-## Agent Spawning
+### 7. ITERATE
 
-```yaml
-executor_agents:
-  max_parallel: 5
-  per_file_limit: 1
+Repeat until: all done, all blocked, or budget reached.
 
-model_selection:
-  implement: sonnet
-  debug: opus
+## Rules
 
-commit_after: each_task
-push_after: all_complete  # Not every commit
-```
+| 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 |
 
-## Example Session
+## Example
 
 ```
 /df:execute
 
 Loading PLAN.md...
-Found 5 tasks, 3 ready (no blockers)
+Found 5 tasks, 3 ready
 
-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 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, T4 now unblocked
-  T3: Implement S3 upload... ✓ (jkl3456)
-  T4: Complete thumbnails... ✓ (mno7890)
+Wave 2: T3, T4 unblocked
+  T3: success (jkl3456) 67s
+  T4: success (mno7890) 41s
+Budget: ~52k/100k tokens
 
 ✓ Execution complete
-Tasks: 5/5
-Commits: 5
+Tasks: 5/5 | Commits: 5
 
 Run /df:verify to confirm specs satisfied.
 ```

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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}