deepflow 0.1.70 → 0.1.72

package/README.md

@@ -77,10 +77,8 @@ You write the specs, then walk away. The AI runs the full pipeline — hypothesi
 ```bash
 # You define WHAT (the specs), the AI figures out HOW, overnight
 
-# Requires Agent Teams (experimental feature)
-export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
-
-deepflow auto                    # process all specs in specs/
+# Inside Claude Code (requires Agent Teams)
+/df:auto                         # process all specs in specs/
 ```
 
 **What the AI does alone:**
@@ -93,7 +91,7 @@ deepflow auto                    # process all specs in specs/
 7. If rejected: generates new hypotheses, retries (up to max-cycles)
 8. On convergence: verifies (L0-L4 gates), creates PR, merges to main
 
-**What you do:** Write specs (via interactive mode or manually) in `specs/`, run `deepflow auto`, read the morning report at `.deepflow/auto-report.md`. No need to run `/df:plan` first — auto mode promotes plain specs to `doing-*` automatically.
+**What you do:** Write specs (via interactive mode or manually) in `specs/`, run `/df:auto` inside Claude Code, read the report at `.deepflow/auto-report.md`. No need to run `/df:plan` first — auto mode promotes plain specs to `doing-*` automatically.
 
 **How to use:**
 ```bash
@@ -103,9 +101,8 @@ $ claude
 > /df:spec auth          # creates specs/auth.md
 > /exit
 
-# In your terminal — enable agent teams and run auto mode
-$ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
-$ deepflow auto
+# Inside Claude Code — run auto mode
+> /df:auto
 
 # Next morning — check what happened
 $ cat .deepflow/auto-report.md
@@ -121,9 +118,8 @@ $ git log --oneline
  ─────────────────────────────────  ──────────────────────────────────
  Define the problem                 Generate hypotheses
  Write/approve the spec             Spike, implement, compare
- Set constraints & acceptance       Self-judge via adversarial selection
- criteria                           Verify against YOUR criteria
-                                    Merge or retry
+ Set constraints & acceptance       Self-judge, verify against YOUR criteria
+ criteria                           Merge or retry
  Read morning report
  ─────────────────────────────────  ──────────────────────────────────
          specs/*.md is the handoff point
@@ -166,7 +162,7 @@ $ git log --oneline
 ## The Flow (Autonomous)
 
 ```
-deepflow auto
+/df:auto
     | Discover specs (auto-promote, topological sort by depends_on)
     | For each doing-* spec:
     |
@@ -225,7 +221,7 @@ Execution happens in an isolated git worktree:
 
 ## LSP Integration
 
-deepflow automatically enables Claude Code's LSP tools during install, giving agents access to `goToDefinition`, `findReferences`, and `workspaceSymbol` for precise code navigation instead of grep-based searching.
+/df:automatically enables Claude Code's LSP tools during install, giving agents access to `goToDefinition`, `findReferences`, and `workspaceSymbol` for precise code navigation instead of grep-based searching.
 
 - **Global install:** sets `ENABLE_LSP_TOOL=1` in `~/.claude/settings.json`
 - **Project install:** sets it in `.claude/settings.local.json`
@@ -235,7 +231,7 @@ Agents prefer LSP tools when available and fall back to Grep/Glob silently. You'
 
 ## Spec Validation
 
-Specs are validated before downstream consumption by `/df:spec`, `/df:plan`, and `deepflow auto`:
+Specs are validated before downstream consumption by `/df:spec`, `/df:plan`, and `/df:auto`:
 
 - **Hard invariants** (block on failure): required sections present, REQ-N prefixes, checkbox ACs, no duplicate IDs
 - **Advisory warnings** (warn interactively, block in auto mode): long specs, orphaned requirements, excessive technical notes
@@ -263,7 +259,7 @@ Statusline shows context usage. At >=50%:
 | `/df:consolidate` | Deduplicate and clean up decisions.md |
 | `/df:resume` | Session continuity briefing |
 | `/df:update` | Update deepflow to latest |
-| `deepflow auto` | Autonomous overnight execution (no human needed) |
+| `/df:auto` | Autonomous execution via /loop (no human needed) |
 
 ## File Structure
 

package/bin/install.js

@@ -10,25 +10,15 @@ const os = require('os');
 const readline = require('readline');
 const { execFileSync } = require('child_process');
 
-// Subcommand routing: `deepflow auto [...]` -> claude --agent .claude/agents/deepflow-auto.md
+// Legacy subcommand: `deepflow auto` is now `/df:auto` inside Claude Code
 if (process.argv[2] === 'auto') {
-  if (!process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) {
-    console.error('Error: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable is not set.');
-    console.error('');
-    console.error('The `deepflow auto` command now uses Claude Code Agent Teams.');
-    console.error('To enable it, set the environment variable before running:');
-    console.error('');
-    console.error('  export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1');
-    console.error('  deepflow auto');
-    console.error('');
-    process.exit(1);
-  }
-  try {
-    execFileSync('claude', ['--agent', '.claude/agents/deepflow-auto.md', '-p', 'Run the full autonomous cycle now. Auto-promote unprefixed specs to doing-*, then process all doing-* specs through every phase. Do not ask questions — act autonomously.', ...process.argv.slice(3)], { stdio: 'inherit' });
-  } catch (e) {
-    process.exit(e.status || 1);
-  }
-  process.exit(0);
+  console.error('`deepflow auto` has moved inside Claude Code for better visibility.');
+  console.error('');
+  console.error('Usage:');
+  console.error('  1. Open Claude Code: claude');
+  console.error('  2. Run: /df:auto');
+  console.error('');
+  process.exit(1);
 }
 
 // Colors
@@ -160,9 +150,6 @@ async function main() {
     }
   }
 
-  // deepflow-auto.sh has been archived; auto mode now uses Agent Teams
-  // via `claude --agent .claude/agents/deepflow-auto.md`
-
   // Get version from package.json (single source of truth)
   const packageJson = require(path.join(PACKAGE_DIR, 'package.json'));
   const installedVersion = packageJson.version;
@@ -196,9 +183,9 @@ async function main() {
   console.log(`${c.green}Installation complete!${c.reset}`);
   console.log('');
   console.log(`Installed to ${c.cyan}${CLAUDE_DIR}${c.reset}:`);
-  console.log('  commands/df/     — /df:discover, /df:debate, /df:spec, /df:plan, /df:execute, /df:verify, /df:note, /df:resume, /df:update');
+  console.log('  commands/df/     — /df:discover, /df:debate, /df:spec, /df:plan, /df:execute, /df:verify, /df:auto, /df:note, /df:resume, /df:update');
   console.log('  skills/          — gap-discovery, atomic-commits, code-completeness');
-  console.log('  agents/          — reasoner, deepflow-auto (autonomous overnight execution)');
+  console.log('  agents/          — reasoner (/df:auto — autonomous execution via /loop)');
   if (level === 'global') {
     console.log('  hooks/           — statusline, update checker');
   }
@@ -413,8 +400,7 @@ async function uninstall() {
     'skills/atomic-commits',
     'skills/code-completeness',
     'skills/gap-discovery',
-    'agents/reasoner.md',
-    'agents/deepflow-auto.md'
+    'agents/reasoner.md'
   ];
 
   if (level === 'global') {

package/package.json

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

package/src/commands/df/auto-cycle.md

@@ -0,0 +1,384 @@
+# /df:auto-cycle — Single Cycle of Auto Mode
+
+## Purpose
+Execute one task from PLAN.md. Designed to be called by `/loop 1m /df:auto-cycle` — each invocation gets fresh context.
+
+**NEVER:** use EnterPlanMode, use ExitPlanMode
+
+---
+
+## Usage
+```
+/df:auto-cycle    # Pick next undone task and execute it (or verify if all done)
+```
+
+## Behavior
+
+### 1. LOAD STATE
+
+```
+Load: PLAN.md (required)
+  → If missing: Error "No PLAN.md. Run /df:plan first."
+Load: .deepflow/auto-memory.yaml (optional — cross-cycle state, ignore if missing)
+```
+
+**auto-memory.yaml full schema:**
+
+```yaml
+task_results:
+  T1: { status: success, commit: abc1234, cycle: 3 }
+  T2: { status: reverted, reason: "tests failed: 2 of 24", cycle: 4 }
+revert_history:
+  - { task: T2, cycle: 4, reason: "tests failed" }
+  - { task: T2, cycle: 5, reason: "build error" }
+consecutive_reverts:   # written by circuit breaker (step 3.5)
+  T1: 0
+  T2: 2
+probe_learnings:
+  - { spike: T1, probe: "streaming", insight: "discovered hidden dependency on fs.watch" }
+```
+
+Each section is optional. Missing keys are treated as empty. The file is created on first write if absent.
+
+### 2. PICK NEXT TASK
+
+Scan PLAN.md for the first `[ ]` task where all "Blocked by:" dependencies are `[x]`:
+
+```
+For each [ ] task in PLAN.md (top to bottom):
+  → Parse "Blocked by:" line (if present)
+  → Check each listed dependency in PLAN.md
+  → If ALL listed blockers are [x] (or no blockers) → this task is READY
+  → Select first READY task
+```
+
+**No tasks remaining (`[ ]` not found):** → skip to step 5 (completion check).
+
+**All remaining tasks blocked:** → Error with blocker info:
+```
+Error: All remaining tasks are blocked.
+  [ ] T3 — blocked by: T2 (incomplete)
+  [ ] T4 — blocked by: T2 (incomplete)
+
+Run /df:execute to investigate or resolve blockers manually.
+```
+
+### 3. EXECUTE
+
+Run the selected task using the Skill tool:
+
+```
+Skill: "df:execute"
+Args: "{task_id}"   (e.g., "T3")
+```
+
+This handles worktree creation, agent spawning, ratchet health checks, and commit.
+
+**Bootstrap handling:** `/df:execute` may report `"bootstrap: completed"` instead of a regular task result. This means the ratchet snapshot was empty (zero test files) and the cycle was used to write baseline tests. When this happens:
+
+- Do NOT treat it as a task failure or skip
+- Record the bootstrap in the report (step 4) using task ID `BOOTSTRAP` and status `passed`
+- Exit normally — the NEXT cycle will pick up the first regular task (now protected by the bootstrapped tests)
+- Do NOT attempt to execute a regular task in the same cycle as a bootstrap
+
+### 3.5. WRITE STATE
+
+After `/df:execute` returns, record the task result in `.deepflow/auto-memory.yaml`:
+
+**On success (ratchet passed):**
+
+```yaml
+# Set task_results[task_id] = success entry
+task_results:
+  {task_id}: { status: success, commit: {short_hash}, cycle: {cycle_number} }
+```
+
+**On revert (ratchet failed):**
+
+```yaml
+# Set task_results[task_id] = reverted entry
+task_results:
+  {task_id}: { status: reverted, reason: "{ratchet failure summary}", cycle: {cycle_number} }
+
+# Append to revert_history
+revert_history:
+  - { task: {task_id}, cycle: {cycle_number}, reason: "{ratchet failure summary}" }
+```
+
+Read the current file first (create if missing), merge the new values, and write back. Preserve all existing keys.
+
+### 3.6. CIRCUIT BREAKER
+
+After `/df:execute` returns, check whether the task was reverted (ratchet failed):
+
+**On revert (ratchet failed):**
+
+```
+1. Read .deepflow/auto-memory.yaml (create if missing)
+2. Increment consecutive_reverts[task_id] by 1
+3. Write updated value back to .deepflow/auto-memory.yaml
+4. Read circuit_breaker_threshold from .deepflow/config.yaml (default: 3 if key absent)
+5. If consecutive_reverts[task_id] >= threshold:
+     → Do NOT start /loop again
+     → Report: "Circuit breaker tripped: T{n} failed {N} consecutive times. Reason: {last ratchet failure}"
+     → Halt (exit without scheduling next cycle)
+   Else:
+     → Continue to step 4 (UPDATE REPORT) as normal
+```
+
+**On success (ratchet passed):**
+
+```
+1. Reset consecutive_reverts[task_id] to 0 in .deepflow/auto-memory.yaml
+```
+
+**auto-memory.yaml schema for the circuit breaker:**
+
+```yaml
+consecutive_reverts:
+  T1: 0
+  T3: 2
+```
+
+**config.yaml key:**
+
+```yaml
+circuit_breaker_threshold: 3   # halt after this many consecutive reverts on the same task
+```
+
+### 4. UPDATE REPORT
+
+Write a comprehensive report to `.deepflow/auto-report.md` after every cycle. The file is appended each cycle — never overwritten. Each cycle adds its row to the per-cycle log table and updates the running summary counts.
+
+#### 4.1 File structure
+
+The report uses four sections. On the **first cycle** (file does not exist), create the full skeleton. On **subsequent cycles**, update the existing file in-place:
+
+```markdown
+# Auto Mode Report — {spec_name}
+
+_Last updated: {YYYY-MM-DDTHH:MM:SSZ}_
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total cycles run | {N} |
+| Tasks committed | {N} |
+| Tasks reverted | {N} |
+
+## Cycle Log
+
+| Cycle | Task | Status | Commit / Revert | Reason | Timestamp |
+|-------|------|--------|-----------------|--------|-----------|
+| 1 | T1 | passed | abc1234 | — | 2025-01-15T10:00:00Z |
+| 2 | T2 | failed | reverted | tests failed: 2 of 24 | 2025-01-15T10:05:00Z |
+
+## Probe Results
+
+_(empty until a probe/spike task runs)_
+
+| Probe | Metric | Winner | Loser | Notes |
+|-------|--------|--------|-------|-------|
+
+## Health Score
+
+| Check | Status |
+|-------|--------|
+| Tests passed | {N} / {total} |
+| Build status | passing / failing |
+| Ratchet | green / red |
+
+## Reverted Tasks
+
+_(tasks that were reverted with their failure reasons)_
+
+| Task | Cycle | Reason |
+|------|-------|--------|
+```
+
+#### 4.2 Per-cycle update rules
+
+**Cycle Log — append one row:**
+
+```
+| {cycle_number} | {task_id} | {status} | {commit_hash or "reverted"} | {reason or "—"} | {YYYY-MM-DDTHH:MM:SSZ} |
+```
+
+- `cycle_number`: total number of cycles executed so far (count existing data rows in the Cycle Log + 1)
+- `task_id`: task ID from PLAN.md, or `BOOTSTRAP` for bootstrap cycles
+- `status`: `passed` (ratchet passed), `failed` (ratchet failed, reverted), or `skipped` (task was already done)
+- `commit_hash`: short hash from the commit, or `reverted` if ratchet failed
+- `reason`: failure reason from ratchet output (e.g., `"tests failed: 2 of 24"`), or `—` if passed
+
+**Summary table — recalculate from Cycle Log rows:**
+
+- `Total cycles run`: count of all data rows in the Cycle Log
+- `Tasks committed`: count of rows where Status = `passed`
+- `Tasks reverted`: count of rows where Status = `failed`
+
+**Last updated timestamp:** always overwrite the `_Last updated:` line with the current timestamp.
+
+#### 4.3 Probe results (when applicable)
+
+If the executed task was a probe/spike (task description contains "probe" or "spike"), append a row to the Probe Results table:
+
+```
+| {probe_name} | {metric description} | {winner approach} | {loser approach} | {key insight from probe_learnings in auto-memory.yaml} |
+```
+
+Read `probe_learnings` from `.deepflow/auto-memory.yaml` for the insight text.
+
+If no probe has run yet, leave the `_(empty until a probe/spike task runs)_` placeholder in place.
+
+#### 4.4 Health score (after every cycle)
+
+Read the ratchet output from the last `/df:execute` result and populate:
+
+- `Tests passed`: e.g., `22 / 24` (from ratchet summary line)
+- `Build status`: `passing` if exit code 0, `failing` if build error
+- `Ratchet`: `green` if ratchet passed, `red` if ratchet failed
+
+Replace the entire Health Score section content with the latest values each cycle.
+
+#### 4.5 Reverted tasks section
+
+After every revert, append a row to the Reverted Tasks table:
+
+```
+| {task_id} | {cycle_number} | {failure reason} |
+```
+
+Read from `revert_history` in `.deepflow/auto-memory.yaml` to ensure no entry is missed. If no tasks have been reverted, leave the `_(tasks that were reverted...)_` placeholder in place.
+
+### 5. CHECK COMPLETION
+
+**Count tasks in PLAN.md:**
+```
+done_count   = number of [x] tasks
+pending_count = number of [ ] tasks
+```
+
+**If ALL tasks are `[x]` (pending_count == 0):**
+```
+→ Run /df:verify via Skill tool (skill: "df:verify", no args)
+→ Report: "All tasks complete. Verification triggered."
+```
+
+**If tasks remain (pending_count > 0):**
+```
+→ Report: "Cycle complete. {pending_count} tasks remaining."
+→ Exit — next /loop invocation will pick up
+```
+
+## Rules
+
+| Rule | Detail |
+|------|--------|
+| One task per cycle | Fresh context each invocation — no multi-task batching |
+| Bootstrap counts as the cycle's sole task | When `/df:execute` returns `bootstrap: completed`, no regular task runs that cycle |
+| Idempotent | Safe to call with no work remaining — just reports "0 tasks remaining" |
+| Never modifies PLAN.md directly | `/df:execute` handles PLAN.md updates and commits |
+| Zero coordination overhead | Read plan → pick task → execute → update report → exit |
+| Auto-memory updated after every cycle | `task_results`, `revert_history`, and `consecutive_reverts` in `.deepflow/auto-memory.yaml` are written after each EXECUTE result |
+| Cross-cycle state read at cycle start | LOAD STATE reads the full `auto-memory.yaml` schema; prior task outcomes and probe learnings are available to the cycle |
+| Circuit breaker halts the loop | After N consecutive reverts on the same task (default 3, configurable via `circuit_breaker_threshold` in `.deepflow/config.yaml`), the loop is stopped and the reason is reported |
+
+## Example
+
+### Bootstrap Cycle (no pre-existing tests)
+
+```
+/df:auto-cycle
+
+Loading PLAN.md... 3 tasks total, 0 done, 3 pending
+Next ready task: T1 (no blockers)
+
+Running: /df:execute T1
+  Ratchet snapshot: 0 pre-existing test files
+  Bootstrap needed — writing tests for edit_scope first
+  ✓ Bootstrap: ratchet passed (boo1234)
+  bootstrap: completed
+
+Updated .deepflow/auto-report.md:
+  Summary: cycles=1, committed=1, reverted=0
+  Cycle Log row: | 1 | BOOTSTRAP | passed | boo1234 | — | 2025-01-15T10:00:00Z |
+  Health: tests 10/10, build passing, ratchet green
+
+Cycle complete. 3 tasks remaining.
+```
+
+### Normal Cycle (task executed)
+
+```
+/df:auto-cycle
+
+Loading PLAN.md... 3 tasks total, 1 done, 2 pending
+Next ready task: T2 (T1 dependency satisfied)
+
+Running: /df:execute T2
+  ✓ T2: ratchet passed (abc1234)
+
+Updated .deepflow/auto-report.md:
+  Summary: cycles=2, committed=2, reverted=0
+  Cycle Log row: | 2 | T2 | passed | abc1234 | — | 2025-01-15T10:05:00Z |
+  Health: tests 22/22, build passing, ratchet green
+
+Cycle complete. 1 tasks remaining.
+```
+
+### All Tasks Done (verify triggered)
+
+```
+/df:auto-cycle
+
+Loading PLAN.md... 3 tasks total, 3 done, 0 pending
+
+All tasks complete. Verification triggered.
+Running: /df:verify
+  ✓ L0 | ✓ L1 | ⚠ L2 (no coverage tool) | ✓ L4
+  ✓ Merged df/upload to main
+```
+
+### No Work Remaining (idempotent)
+
+```
+/df:auto-cycle
+
+Loading PLAN.md... 3 tasks total, 3 done, 0 pending
+Verification already complete (no doing-* specs found).
+
+Nothing to do. Cycle complete. 0 tasks remaining.
+```
+
+### Circuit Breaker Tripped
+
+```
+/df:auto-cycle
+
+Loading PLAN.md... 3 tasks total, 1 done, 2 pending
+Next ready task: T3 (no blockers)
+
+Running: /df:execute T3
+  ✗ T3: ratchet failed — "2 tests regressed"
+  Reverted changes.
+
+Circuit breaker: consecutive_reverts[T3] = 3 (threshold: 3)
+Circuit breaker tripped: T3 failed 3 consecutive times. Reason: 2 tests regressed
+
+Loop halted. Resolve T3 manually, then run /df:auto-cycle to resume.
+```
+
+### All Tasks Blocked
+
+```
+/df:auto-cycle
+
+Loading PLAN.md... 3 tasks total, 1 done, 2 pending
+
+Error: All remaining tasks are blocked.
+  [ ] T3 — blocked by: T2 (incomplete)
+  [ ] T4 — blocked by: T2 (incomplete)
+
+Run /df:execute to investigate or resolve blockers manually.
+```

package/src/commands/df/auto.md

@@ -0,0 +1,79 @@
+# /df:auto — Autonomous Mode Setup
+
+Set up and launch fully autonomous execution. Runs `/df:plan` if no PLAN.md exists, takes a ratchet snapshot, then starts `/loop 1m /df:auto-cycle`.
+
+**NEVER:** use EnterPlanMode, use ExitPlanMode
+
+## Usage
+```
+/df:auto    # Set up and start autonomous loop
+```
+
+## Behavior
+
+### 1. RUN PLAN IF NEEDED
+
+```
+If PLAN.md does not exist:
+  → Run /df:plan via Skill tool (skill: "df:plan", no args)
+  → Wait for plan to complete before continuing
+If PLAN.md exists:
+  → Skip planning, proceed to step 2
+```
+
+### 2. RATCHET SNAPSHOT
+
+Before starting the loop, snapshot pre-existing test files so the ratchet has a stable baseline:
+
+```bash
+# Snapshot pre-existing test files (only these count for ratchet)
+git ls-files | grep -E '\.(test|spec)\.[^/]+$|^test_|_test\.[^/]+$|^tests/|__tests__/' \
+  > .deepflow/auto-snapshot.txt
+
+echo "Ratchet snapshot: $(wc -l < .deepflow/auto-snapshot.txt) pre-existing test files"
+```
+
+**Only pre-existing test files are used for ratchet evaluation.** New test files created by agents during implementation do not influence pass/fail decisions. This prevents agents from gaming the ratchet by writing tests that pass trivially.
+
+### 3. START LOOP
+
+Launch the autonomous cycle loop:
+
+```
+/loop 1m /df:auto-cycle
+```
+
+This starts `/df:auto-cycle` on a 1-minute recurring interval. Each invocation runs with fresh context — no coordination overhead, zero LLM tokens on loop management.
+
+## Rules
+
+| Rule | Detail |
+|------|--------|
+| Plan once | Only runs `/df:plan` if PLAN.md is absent |
+| Snapshot before loop | Ratchet baseline is set before any agents run |
+| No lead agent | No custom orchestrator — `/loop` is a native Claude Code feature |
+| Zero loop overhead | Loop coordination uses zero LLM tokens |
+| Cycle logic lives in `/df:auto-cycle` | This command is setup only |
+
+## Example
+
+```
+/df:auto
+
+No PLAN.md found — running /df:plan...
+  ✓ Plan generated — 1 spec, 5 tasks.
+
+Ratchet snapshot: 12 pre-existing test files
+
+Starting loop: /loop 1m /df:auto-cycle
+```
+
+```
+/df:auto
+
+PLAN.md exists — skipping plan.
+
+Ratchet snapshot: 12 pre-existing test files
+
+Starting loop: /loop 1m /df:auto-cycle
+```