deepflow 0.1.49 → 0.1.51

package/README.md

@@ -27,6 +27,7 @@
 - **Spike-first planning** — Validate risky hypotheses before full implementation
 - **Worktree isolation** — Main branch stays clean during execution
 - **Parallel execution** with context-aware checkpointing
+- **Automatic decision capture** on spec completion, periodic consolidation
 - **Atomic commits** for clean rollback
 
 ## Quick Start
@@ -41,29 +42,38 @@ npx deepflow --uninstall
 # In your project
 claude
 
-# 1. Discuss what you want to build
-# 2. Generate spec when ready
+# 1. Explore the problem space
+/df:discover image-upload
+
+# 2. Debate tradeoffs (optional)
+/df:debate upload-strategy
+
+# 3. Generate spec from conversation
 /df:spec image-upload
 
-# 3. Compare specs to code, generate tasks
+# 4. Compare specs to code, generate tasks
 /df:plan
 
-# 4. Execute tasks with parallel agents
+# 5. Execute tasks with parallel agents
 /df:execute
 
-# 5. Verify specs are satisfied
+# 6. Verify specs are satisfied
 /df:verify
 ```
 
 ## The Flow
 
 ```
-CONVERSATION
-    │ Describe what you want
-    │ LLM asks gap questions
+/df:discover <name>
+    │ Socratic questioning (motivation, scope, constraints...)
+    ▼
+/df:debate <topic>          ← optional
+    │ 4 perspectives: User Advocate, Tech Skeptic,
+    │   Systems Thinker, LLM Efficiency
+    │ Creates specs/.debate-{topic}.md
     ▼
 /df:spec <name>
-    │ Creates specs/{name}.md
+    │ Creates specs/{name}.md from conversation
     ▼
 /df:plan
     │ Checks past experiments (learn from failures)
@@ -80,7 +90,8 @@ CONVERSATION
 /df:verify
     │ Checks requirements met
     │ Merges worktree to main, cleans up
-    │ Renames: doing-feature.md → done-feature.md
+    │ Extracts decisions → .deepflow/decisions.md
+    │ Deletes done-* spec after extraction
 ```
 
 ## Spec Lifecycle
@@ -89,7 +100,7 @@ CONVERSATION
 specs/
   feature.md        → new, needs /df:plan
   doing-feature.md  → in progress, has tasks in PLAN.md
-  done-feature.md   → completed, history embedded
+  done-feature.md   → transient (decisions extracted, then deleted)
 ```
 
 ## Works With Any Project
@@ -130,10 +141,15 @@ Statusline shows context usage. At ≥50%:
 
 | Command | Purpose |
 |---------|---------|
+| `/df:discover <name>` | Explore problem space with Socratic questioning |
+| `/df:debate <topic>` | Multi-perspective analysis (4 agents) |
 | `/df:spec <name>` | Generate spec from conversation |
 | `/df:plan` | Compare specs to code, create tasks |
 | `/df:execute` | Run tasks with parallel agents |
-| `/df:verify` | Check specs satisfied |
+| `/df:verify` | Check specs satisfied, merge to main |
+| `/df:note` | Capture decisions ad-hoc from conversation |
+| `/df:consolidate` | Deduplicate and clean up decisions.md |
+| `/df:resume` | Session continuity briefing |
 | `/df:update` | Update deepflow to latest |
 
 ## File Structure
@@ -142,15 +158,16 @@ Statusline shows context usage. At ≥50%:
 your-project/
 ├── specs/
 │   ├── auth.md           # new spec
-│   ├── doing-upload.md   # in progress
-│   └── done-payments.md  # completed
+│   └── doing-upload.md   # in progress
 ├── PLAN.md               # active tasks
 └── .deepflow/
-    ├── config.yaml       # project settings
-    ├── context.json      # context % tracking
-    ├── experiments/      # spike results (pass/fail)
-    └── worktrees/        # isolated execution
-        └── upload/       # one worktree per spec
+    ├── config.yaml            # project settings
+    ├── decisions.md           # auto-extracted + ad-hoc decisions
+    ├── last-consolidated.json # consolidation timestamp
+    ├── context.json           # context % tracking
+    ├── experiments/           # spike results (pass/fail)
+    └── worktrees/             # isolated execution
+        └── upload/            # one worktree per spec
 ```
 
 ## Configuration

package/bin/install.js

@@ -146,7 +146,7 @@ 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');
+  console.log('  commands/df/     — /df:discover, /df:debate, /df:spec, /df:plan, /df:execute, /df:verify, /df:note, /df:resume, /df:update');
   console.log('  skills/          — gap-discovery, atomic-commits, code-completeness');
   console.log('  agents/          — reasoner');
   if (level === 'global') {
@@ -196,6 +196,7 @@ async function configureHooks(claudeDir) {
   const settingsPath = path.join(claudeDir, 'settings.json');
   const statuslineCmd = `node "${path.join(claudeDir, 'hooks', 'df-statusline.js')}"`;
   const updateCheckCmd = `node "${path.join(claudeDir, 'hooks', 'df-check-update.js')}"`;
+  const consolidationCheckCmd = `node "${path.join(claudeDir, 'hooks', 'df-consolidation-check.js')}"`;
 
   let settings = {};
 
@@ -234,7 +235,7 @@ async function configureHooks(claudeDir) {
   // Remove any existing deepflow update check hooks
   settings.hooks.SessionStart = settings.hooks.SessionStart.filter(hook => {
     const cmd = hook.hooks?.[0]?.command || '';
-    return !cmd.includes('df-check-update');
+    return !cmd.includes('df-check-update') && !cmd.includes('df-consolidation-check');
   });
 
   // Add update check hook
@@ -244,6 +245,14 @@ async function configureHooks(claudeDir) {
       command: updateCheckCmd
     }]
   });
+
+  // Add consolidation check hook
+  settings.hooks.SessionStart.push({
+    hooks: [{
+      type: 'command',
+      command: consolidationCheckCmd
+    }]
+  });
   log('SessionStart hook configured');
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
@@ -330,7 +339,7 @@ async function uninstall() {
   ];
 
   if (level === 'global') {
-    toRemove.push('hooks/df-statusline.js', 'hooks/df-check-update.js');
+    toRemove.push('hooks/df-statusline.js', 'hooks/df-check-update.js', 'hooks/df-consolidation-check.js');
   }
 
   for (const item of toRemove) {
@@ -359,7 +368,7 @@ async function uninstall() {
         if (settings.hooks?.SessionStart) {
           settings.hooks.SessionStart = settings.hooks.SessionStart.filter(hook => {
             const cmd = hook.hooks?.[0]?.command || '';
-            return !cmd.includes('df-check-update');
+            return !cmd.includes('df-check-update') && !cmd.includes('df-consolidation-check');
           });
           if (settings.hooks.SessionStart.length === 0) {
             delete settings.hooks.SessionStart;

package/hooks/df-consolidation-check.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * deepflow consolidation checker
+ * Checks if decisions.md needs consolidation, outputs suggestion if overdue
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DAYS_THRESHOLD = 7;
+const LINES_THRESHOLD = 20;
+const DEEPFLOW_DIR = path.join(process.cwd(), '.deepflow');
+const DECISIONS_FILE = path.join(DEEPFLOW_DIR, 'decisions.md');
+const LAST_CONSOLIDATED_FILE = path.join(DEEPFLOW_DIR, 'last-consolidated.json');
+
+function checkConsolidation() {
+  try {
+    // Check if decisions.md exists
+    if (!fs.existsSync(DECISIONS_FILE)) {
+      process.exit(0);
+    }
+
+    // Check if decisions.md has more than LINES_THRESHOLD lines
+    const decisionsContent = fs.readFileSync(DECISIONS_FILE, 'utf8');
+    const lineCount = decisionsContent.split('\n').length;
+    if (lineCount <= LINES_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Get last consolidated timestamp
+    let lastConsolidated;
+    if (fs.existsSync(LAST_CONSOLIDATED_FILE)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(LAST_CONSOLIDATED_FILE, 'utf8'));
+        if (data.last_consolidated) {
+          lastConsolidated = new Date(data.last_consolidated);
+        }
+      } catch (e) {
+        // Fall through to use mtime
+      }
+    }
+
+    // Fallback: use mtime of decisions.md
+    if (!lastConsolidated || isNaN(lastConsolidated.getTime())) {
+      const stat = fs.statSync(DECISIONS_FILE);
+      lastConsolidated = stat.mtime;
+    }
+
+    // Calculate days since last consolidation
+    const now = new Date();
+    const diffMs = now - lastConsolidated;
+    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+
+    if (diffDays >= DAYS_THRESHOLD) {
+      process.stderr.write(
+        `\u{1F4A1} decisions.md hasn't been consolidated in ${diffDays} days. Run /df:consolidate to clean up.\n`
+      );
+    }
+
+  } catch (e) {
+    // Fail silently
+  }
+
+  process.exit(0);
+}
+
+checkConsolidation();

package/package.json

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

package/src/commands/df/consolidate.md

@@ -0,0 +1,58 @@
+# /df:consolidate — Consolidate Decisions
+
+## Purpose
+Remove duplicates, superseded entries, and promote stale provisionals. Keep decisions.md dense and useful.
+
+**NEVER:** use EnterPlanMode, use ExitPlanMode
+
+## Usage
+```
+/df:consolidate          # Consolidate decisions.md
+```
+
+## Behavior
+
+### 1. LOAD
+Read `.deepflow/decisions.md`. If missing or empty, report and exit.
+
+### 2. ANALYZE
+Model-driven analysis (not regex):
+- Identify duplicate decisions (same meaning, different wording)
+- Identify superseded decisions (later entry contradicts earlier)
+- Identify stale `[PROVISIONAL]` entries (>30 days old, no resolution)
+
+### 3. CONSOLIDATE
+- Remove duplicates (keep the more precise wording)
+- Silently remove superseded entries (the later decision wins)
+- Promote stale `[PROVISIONAL]` to `[DEBT]` (needs revisiting)
+- Preserve all `[APPROACH]` entries unless superseded
+- Preserve all `[ASSUMPTION]` entries unless invalidated
+- Target: 200-500 lines (if currently longer)
+- When in doubt, keep both entries (conservative)
+
+### 4. WRITE
+- Rewrite `.deepflow/decisions.md` with consolidated content
+- Write timestamp to `.deepflow/last-consolidated.json`:
+  ```json
+  { "last_consolidated": "{ISO-8601 timestamp}" }
+  ```
+
+### 5. REPORT
+```
+✓ Consolidated: {before} → {after} lines, {n} removed, {n} promoted to [DEBT]
+```
+
+## Tags
+| Tag | Meaning | Source |
+|-----|---------|--------|
+| `[APPROACH]` | Firm decision | Auto-extraction, /df:note |
+| `[PROVISIONAL]` | Revisit later | Auto-extraction, /df:note |
+| `[ASSUMPTION]` | Unverified | Auto-extraction, /df:note |
+| `[DEBT]` | Needs revisiting | Consolidation only |
+
+## Rules
+- Conservative: when in doubt, keep both entries
+- Never add new decisions — only remove, merge, or re-tag
+- [DEBT] is never manually assigned — only produced by consolidation
+- Preserve chronological ordering within sections
+- decisions.md stays a single flat file, human-readable

package/src/commands/df/debate.md

@@ -35,136 +35,83 @@ Generate a multi-perspective analysis of a problem before formalizing into a spe
 
 ### 1. SUMMARIZE
 
-Summarize the conversation context (from prior discover/conversation) in ~200 words. This summary will be passed to each perspective agent.
-
-The summary should capture:
-- The core problem being solved
-- Key requirements mentioned
-- Constraints and boundaries
-- User's stated preferences and priorities
+Summarize conversation context in ~200 words: core problem, key requirements, constraints, user priorities. Passed to each perspective agent.
 
 ### 2. GATHER CODEBASE CONTEXT
 
-Before spawning perspectives, ground the debate in what actually exists. Use Glob, Grep, and Read to understand the current implementation relevant to the debate topic.
-
-**Steps:**
-1. **Glob** for files related to the topic (e.g., `**/*{topic}*`, `src/**/*.{ts,js,py}`)
-2. **Grep** for key terms, patterns, or interfaces mentioned in the conversation
-3. **Read** the most relevant files (up to 5-6 files — focus on core logic, not boilerplate)
-
-**Produce a ~300 word codebase summary covering:**
-- What already exists (implemented features, patterns, architecture)
-- Key interfaces, types, or contracts in play
-- Current limitations or technical debt visible in the code
-- Dependencies and integration points
+Ground the debate in what actually exists. Glob/Grep/Read relevant files (up to 5-6, focus on core logic).
 
-This codebase summary is appended to the context passed to every perspective agent, so they argue from facts rather than assumptions.
+Produce a ~300 word codebase summary: what exists, key interfaces/contracts, current limitations, dependencies. Passed to every perspective agent so they argue from facts, not assumptions.
 
 ### 3. SPAWN PERSPECTIVES
 
 **Spawn ALL 4 perspective agents in ONE message (non-background, parallel):**
 
-Each agent receives the same context summary + codebase context but a different role. Each must:
-- Argue from their perspective, grounded in what the codebase actually does
-- Identify risks the other perspectives might miss
-- Propose concrete alternatives where they disagree with the likely approach
-
-```python
-# All 4 in a single message — parallel, non-background:
-Task(subagent_type="reasoner", model="opus", prompt="""
-You are the USER ADVOCATE in a design debate.
+Each agent receives the same preamble + codebase context but a different role lens.
 
+**Shared preamble for all perspectives:**
+```
 ## Context
 {summary}
 
 ## Current Codebase
 {codebase_summary}
 
-## Your Role
-Argue from the perspective of the end user. Focus on:
-- Simplicity and ease of use
-- Real user needs vs assumed needs
-- Friction points and cognitive load
-- Whether the solution matches how users actually think
-
 Provide:
 1. Your key arguments (3-5 points)
-2. Risks you see from a user perspective
+2. Risks your perspective surfaces
 3. Concrete alternatives if you disagree with the current direction
 
 Keep response under 400 words.
-""")
+```
+
+**Perspective-specific role lenses (append to preamble):**
+
+```python
+# All 4 in a single message — parallel, non-background:
 
 Task(subagent_type="reasoner", model="opus", prompt="""
-You are the TECH SKEPTIC in a design debate.
+{shared_preamble}
 
-## Context
-{summary}
+## Your Role: USER ADVOCATE
+Argue from the perspective of the end user. Focus on:
+- Simplicity and ease of use
+- Real user needs vs assumed needs
+- Friction points and cognitive load
+- Whether the solution matches how users actually think
+""")
 
-## Current Codebase
-{codebase_summary}
+Task(subagent_type="reasoner", model="opus", prompt="""
+{shared_preamble}
 
-## Your Role
+## Your Role: TECH SKEPTIC
 Challenge technical assumptions and surface hidden complexity. Focus on:
 - What could go wrong technically
 - Hidden dependencies or coupling
 - Complexity that seems simple but isn't
 - Maintenance burden over time
-
-Provide:
-1. Your key arguments (3-5 points)
-2. Technical risks others might overlook
-3. Simpler alternatives worth considering
-
-Keep response under 400 words.
 """)
 
 Task(subagent_type="reasoner", model="opus", prompt="""
-You are the SYSTEMS THINKER in a design debate.
-
-## Context
-{summary}
+{shared_preamble}
 
-## Current Codebase
-{codebase_summary}
-
-## Your Role
+## Your Role: SYSTEMS THINKER
 Analyze how this fits into the broader system. Focus on:
 - Integration with existing components
 - Scalability implications
 - Second-order effects and unintended consequences
 - Long-term evolution and extensibility
-
-Provide:
-1. Your key arguments (3-5 points)
-2. Systemic risks and ripple effects
-3. Architectural alternatives worth considering
-
-Keep response under 400 words.
 """)
 
 Task(subagent_type="reasoner", model="opus", prompt="""
-You are the LLM EFFICIENCY expert in a design debate.
+{shared_preamble}
 
-## Context
-{summary}
-
-## Current Codebase
-{codebase_summary}
-
-## Your Role
+## Your Role: LLM EFFICIENCY
 Evaluate from the perspective of LLM consumption and interaction. Focus on:
 - Token density: can the output be consumed efficiently by LLMs?
 - Minimal scaffolding: avoid ceremony that adds tokens without information
 - Navigable structure: can an LLM quickly find what it needs?
 - Attention budget: does the design respect limited context windows?
-
-Provide:
-1. Your key arguments (3-5 points)
-2. Efficiency risks others might not consider
-3. Alternatives that optimize for LLM consumption
-
-Keep response under 400 words.
 """)
 ```
 
@@ -207,83 +154,17 @@ Keep response under 500 words.
 
 ### 5. WRITE DEBATE FILE
 
-Create `specs/.debate-{name}.md`:
-
-```markdown
-# Debate: {Name}
-
-## Context
-[~200 word summary from step 1]
-
-## Codebase Context
-[~300 word summary from step 2 — what exists, key patterns, limitations]
-
-## Perspectives
-
-### User Advocate
-[arguments from agent]
-
-### Tech Skeptic
-[arguments from agent]
-
-### Systems Thinker
-[arguments from agent]
-
-### LLM Efficiency
-[arguments from agent]
-
-## Synthesis
-
-### Consensus
-[from synthesizer]
-
-### Tensions
-[from synthesizer]
-
-### Open Decisions
-[from synthesizer]
-
-### Recommendation
-[from synthesizer]
-```
+Create `specs/.debate-{name}.md` with sections: Context · Codebase Context · Perspectives (User Advocate / Tech Skeptic / Systems Thinker / LLM Efficiency) · Synthesis (Consensus / Tensions / Open Decisions / Recommendation).
 
 ### 6. CONFIRM
 
-After writing the file, present a brief summary to the user:
-
-```
-✓ Created specs/.debate-{name}.md
-
-Key tensions:
-- [tension 1]
-- [tension 2]
-
-Open decisions:
-- [decision 1]
-- [decision 2]
-
-Next: Run /df:spec {name} to formalize into a specification
-```
-
-### 7. CAPTURE DECISIONS
-
-Extract up to 4 candidates from consensus/resolved tensions. Ask user via `AskUserQuestion(multiSelect=True)` with options like `{ label: "[APPROACH] {decision}", description: "{rationale}" }`.
-
-For confirmed decisions, append to `.deepflow/decisions.md` (create if absent) using format:
-```
-### {YYYY-MM-DD} — debate
-- [{TAG}] {decision text} — {rationale}
-```
-Tags: [APPROACH] directional choices · [PROVISIONAL] tentative · [ASSUMPTION] unverified premises. If a new decision contradicts an existing one, note the conflict inline.
+Present key tensions and open decisions, then: `Next: Run /df:spec {name} to formalize into a specification`
 
 ---
 
 ## Rules
 
 - **All 4 perspective agents MUST be spawned in ONE message** (parallel, non-background)
-- **NEVER use `run_in_background`** — causes late notifications that pollute output
-- **NEVER use TaskOutput** — returns full transcripts that explode context
-- **NEVER use Explore agents** — the orchestrator gathers context directly
 - **Codebase context is gathered by the orchestrator** (step 2) and passed to agents via prompt
 - Reasoner agents receive context through their prompt, not by reading files themselves
 - The debate file goes in `specs/` so `/df:spec` can reference it

package/src/commands/df/discover.md

@@ -81,31 +81,10 @@ Example questions:
 - Mix structured questions (AskUserQuestion) with conversational follow-ups
 - Ask follow-up questions based on answers — don't just march through phases mechanically
 - Go deeper on surprising or unclear answers
-
 ### Behavioral Rules
-- **NEVER assume** — if something is ambiguous, ask
-- **NEVER suggest ending** — the user decides when they're done
-- **NEVER take action** — no code reading, no file creation, no agents
-- **NEVER skip phases** — but adapt depth based on the problem
 - Keep your responses short between questions — don't lecture
 - Acknowledge answers briefly before asking the next question
 
-### Decision Capture
-When the user signals they are ready to move on, before presenting next-step options, extract up to 4 candidate decisions from the session (meaningful choices about approach, scope, or constraints). Present via `AskUserQuestion` with `multiSelect: true`, e.g.:
-
-```json
-{"questions": [{"question": "Which decisions should be recorded?", "header": "Decisions", "multiSelect": true,
-  "options": [{"label": "[APPROACH] Use event sourcing", "description": "Matches audit requirements"}]}]}
-```
-
-For each confirmed decision, append to `.deepflow/decisions.md` (create if missing):
-```
-### {YYYY-MM-DD} — discover
-- [APPROACH] Decision text — rationale
-```
-
-Tags: `[APPROACH]` firm choice · `[PROVISIONAL]` revisit later · `[ASSUMPTION]` unverified belief.
-
 ### When the User Wants to Move On
 When the user signals they want to advance (e.g., "I think that's enough", "let's move on", "ready for next step"):