deepflow 0.1.48 → 0.1.50

package/README.md

@@ -41,29 +41,39 @@ 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...)
+    │ Captures decisions to .deepflow/decisions.md
+    ▼
+/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)
@@ -130,10 +140,14 @@ 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:note` | Capture decisions from conversation |
+| `/df:resume` | Session continuity briefing |
 | `/df:update` | Update deepflow to latest |
 
 ## File Structure
@@ -147,6 +161,7 @@ your-project/
 ├── PLAN.md               # active tasks
 └── .deepflow/
     ├── config.yaml       # project settings
+    ├── decisions.md      # captured decisions (/df:note, /df:discover)
     ├── context.json      # context % tracking
     ├── experiments/      # spike results (pass/fail)
     └── worktrees/        # isolated execution

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') {

package/package.json

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

package/src/commands/df/debate.md

@@ -4,9 +4,9 @@
 
 You coordinate reasoner agents to debate a problem from multiple perspectives, then synthesize their arguments into a structured document.
 
-**NEVER:** Read source files, use Glob/Grep directly, run git, use TaskOutput, use `run_in_background`, use Explore agents, use EnterPlanMode, use ExitPlanMode
+**NEVER:** use TaskOutput, use `run_in_background`, use Explore agents, use EnterPlanMode, use ExitPlanMode
 
-**ONLY:** Spawn reasoner agents (non-background), write debate file, respond conversationally
+**ONLY:** Gather codebase context (Glob/Grep/Read), spawn reasoner agents (non-background), write debate file, respond conversationally
 
 ---
 
@@ -35,111 +35,87 @@ 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.
+Summarize conversation context in ~200 words: core problem, key requirements, constraints, user priorities. 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
+### 2. GATHER CODEBASE CONTEXT
 
-### 2. SPAWN PERSPECTIVES
+Ground the debate in what actually exists. Glob/Grep/Read relevant files (up to 5-6, focus on core logic).
 
-**Spawn ALL 4 perspective agents in ONE message (non-background, parallel):**
+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.
 
-Each agent receives the same context summary but a different role. Each must:
-- Argue from their perspective
-- Identify risks the other perspectives might miss
-- Propose concrete alternatives where they disagree with the likely approach
+### 3. SPAWN PERSPECTIVES
 
-```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.
+**Spawn ALL 4 perspective agents in ONE message (non-background, parallel):**
 
+Each agent receives the same preamble + codebase context but a different role lens.
+
+**Shared preamble for all perspectives:**
+```
 ## Context
 {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
+## Current Codebase
+{codebase_summary}
 
 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
+""")
 
-## Your Role
+Task(subagent_type="reasoner", model="opus", prompt="""
+{shared_preamble}
+
+## 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.
+{shared_preamble}
 
-## Context
-{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.
-
-## Context
-{summary}
+{shared_preamble}
 
-## 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.
 """)
 ```
 
-### 3. SYNTHESIZE
+### 4. SYNTHESIZE
 
 After all 4 perspectives return, spawn 1 additional reasoner to synthesize:
 
@@ -176,84 +152,25 @@ Keep response under 500 words.
 """)
 ```
 
-### 4. WRITE DEBATE FILE
-
-Create `specs/.debate-{name}.md`:
-
-```markdown
-# Debate: {Name}
-
-## Context
-[~200 word summary from step 1]
-
-## 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]
-```
-
-### 5. CONFIRM
+### 5. WRITE DEBATE FILE
 
-After writing the file, present a brief summary to the user:
+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).
 
-```
-✓ Created specs/.debate-{name}.md
+### 6. CONFIRM
 
-Key tensions:
-- [tension 1]
-- [tension 2]
+Present key tensions and open decisions, then: `Next: Run /df:spec {name} to formalize into a specification`
 
-Open decisions:
-- [decision 1]
-- [decision 2]
-
-Next: Run /df:spec {name} to formalize into a specification
-```
+### 7. CAPTURE DECISIONS
 
-### 6. 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.
+Follow the **default** variant from `templates/decision-capture.md`. Command name: `debate`.
 
 ---
 
 ## 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** — this command doesn't read code
-- **NEVER read source files directly** — agents receive context via prompt only
-- Reasoner agents receive context through their prompt, not by reading files
+- **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
 - File name MUST be `.debate-{name}.md` (dot prefix = auxiliary file)
 - Keep each perspective under 400 words, synthesis under 500 words
@@ -263,13 +180,16 @@ Tags: [APPROACH] directional choices · [PROVISIONAL] tentative · [ASSUMPTION]
 ```
 USER: /df:debate auth
 
-CLAUDE: Let me summarize what we've discussed and get multiple perspectives
-on the authentication design.
+CLAUDE: Let me summarize what we've discussed and understand the current
+codebase before getting multiple perspectives on the authentication design.
 
 [Summarizes: ~200 words about auth requirements from conversation]
 
-[Spawns 4 reasoner agents in parallel — User Advocate, Tech Skeptic,
-Systems Thinker, LLM Efficiency]
+[Globs/Greps/Reads relevant auth files — middleware, routes, config]
+
+[Produces ~300 word codebase summary of what exists]
+
+[Spawns 4 reasoner agents in parallel — each receives both summaries]
 
 [All 4 return their arguments]
 

package/src/commands/df/discover.md

@@ -81,31 +81,12 @@ 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.
-
+Follow the **default** variant from `templates/decision-capture.md`. Command name: `discover`.
 ### 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"):