deepflow 0.1.44 → 0.1.45

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:spec, /df:plan, /df:execute, /df:verify');
+  console.log('  commands/df/     — /df:discover, /df:debate, /df:spec, /df:plan, /df:execute, /df:verify');
   console.log('  skills/          — gap-discovery, atomic-commits, code-completeness');
   console.log('  agents/          — reasoner');
   if (level === 'global') {
@@ -165,7 +165,7 @@ async function main() {
     console.log('  1. claude');
   }
   console.log('  2. Describe what you want to build');
-  console.log('  3. /df:spec feature-name');
+  console.log('  3. /df:discover feature-name');
   console.log('');
 }
 

package/package.json

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

package/src/commands/df/debate.md

@@ -0,0 +1,283 @@
+# /df:debate — Multi-Perspective Analysis
+
+## Orchestrator Role
+
+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
+
+**ONLY:** Spawn reasoner agents (non-background), write debate file, respond conversationally
+
+---
+
+## Purpose
+Generate a multi-perspective analysis of a problem before formalizing into a spec. Surfaces tensions, trade-offs, and blind spots that a single perspective would miss.
+
+## Usage
+```
+/df:debate <name>
+```
+
+## Skills & Agents
+
+**Use Task tool to spawn agents:**
+| Agent | subagent_type | model | Purpose |
+|-------|---------------|-------|---------|
+| User Advocate | `reasoner` | `opus` | UX, simplicity, real user needs |
+| Tech Skeptic | `reasoner` | `opus` | Technical risks, hidden complexity, feasibility |
+| Systems Thinker | `reasoner` | `opus` | Integration, scalability, long-term effects |
+| LLM Efficiency | `reasoner` | `opus` | Token density, minimal scaffolding, navigable structure |
+| Synthesizer | `reasoner` | `opus` | Merge perspectives into consensus + tensions |
+
+---
+
+## Behavior
+
+### 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
+
+### 2. SPAWN PERSPECTIVES
+
+**Spawn ALL 4 perspective agents in ONE message (non-background, parallel):**
+
+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
+
+```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.
+
+## 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
+
+Provide:
+1. Your key arguments (3-5 points)
+2. Risks you see from a user perspective
+3. Concrete alternatives if you disagree with the current direction
+
+Keep response under 400 words.
+""")
+
+Task(subagent_type="reasoner", model="opus", prompt="""
+You are the TECH SKEPTIC in a design debate.
+
+## Context
+{summary}
+
+## Your Role
+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}
+
+## Your Role
+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}
+
+## Your Role
+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
+
+After all 4 perspectives return, spawn 1 additional reasoner to synthesize:
+
+```python
+Task(subagent_type="reasoner", model="opus", prompt="""
+You are the SYNTHESIZER. Four perspectives have debated a design problem.
+
+## Context
+{summary}
+
+## User Advocate's Arguments
+{user_advocate_response}
+
+## Tech Skeptic's Arguments
+{tech_skeptic_response}
+
+## Systems Thinker's Arguments
+{systems_thinker_response}
+
+## LLM Efficiency's Arguments
+{llm_efficiency_response}
+
+## Your Task
+Synthesize these perspectives into:
+
+1. **Consensus** — Points where all or most perspectives agree
+2. **Tensions** — Unresolved disagreements and genuine trade-offs
+3. **Open Decisions** — Questions that need human judgment to resolve
+4. **Recommendation** — Your balanced recommendation considering all perspectives
+
+Be specific. Name the tensions, don't smooth them over.
+
+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
+
+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
+```
+
+---
+
+## 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
+- 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
+
+## Example
+
+```
+USER: /df:debate auth
+
+CLAUDE: Let me summarize what we've discussed and get 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]
+
+[All 4 return their arguments]
+
+[Spawns synthesizer agent with all 4 perspectives]
+
+[Synthesizer returns consensus, tensions, open decisions, recommendation]
+
+[Writes specs/.debate-auth.md]
+
+✓ Created specs/.debate-auth.md
+
+Key tensions:
+- OAuth complexity vs simpler API key approach
+- User convenience (social login) vs privacy concerns
+- Centralized auth service vs per-route middleware
+
+Open decisions:
+- Session storage strategy (JWT vs server-side)
+- Token expiration policy
+
+Next: Run /df:spec auth to formalize into a specification
+```

package/src/commands/df/discover.md

@@ -0,0 +1,182 @@
+# /df:discover — Deep Problem Exploration
+
+## Orchestrator Role
+
+You are a Socratic questioner. Your ONLY job is to ask questions that surface hidden requirements, assumptions, and constraints.
+
+**NEVER:** Read source files, use Glob/Grep, spawn agents, create files, run git, use TaskOutput, use Task tool
+
+**ONLY:** Ask questions using `AskUserQuestion` tool, respond conversationally
+
+---
+
+## Purpose
+Explore a problem space deeply before formalizing into specs. Surface motivations, constraints, scope boundaries, success criteria, and anti-goals through structured questioning.
+
+## Usage
+```
+/df:discover <name>
+```
+
+## Behavior
+
+Work through these phases organically. You don't need to announce phases — let the conversation flow naturally. Move to the next phase when the current one feels sufficiently explored.
+
+### Phase 1: MOTIVATION
+Why does this need to exist? What problem does it solve? Who suffers without it?
+
+Example questions:
+- What triggered the need for this?
+- Who will use this and what's their current workaround?
+- What happens if we don't build this?
+
+### Phase 2: CONTEXT
+What already exists? What has been tried? What's the current state?
+
+Example questions:
+- Is there existing code or infrastructure that relates to this?
+- Have you tried solving this before? What worked/didn't?
+- Are there external systems or APIs involved?
+
+### Phase 3: SCOPE
+What's in? What's out? What's the minimum viable version?
+
+Example questions:
+- What's the smallest version that would be useful?
+- What features feel essential vs nice-to-have?
+- Are there parts you explicitly want to exclude?
+
+### Phase 4: CONSTRAINTS
+Technical limits, time pressure, resource boundaries?
+
+Example questions:
+- Are there performance requirements or SLAs?
+- What technologies are non-negotiable?
+- Is there a deadline or timeline pressure?
+
+### Phase 5: SUCCESS
+How do we know it worked? What does "done" look like?
+
+Example questions:
+- How will you verify this works correctly?
+- What metrics would indicate success?
+- What would make you confident enough to ship?
+
+### Phase 6: ANTI-GOALS
+What should we explicitly NOT do? What traps to avoid?
+
+Example questions:
+- What's the most common way this kind of feature gets over-engineered?
+- Are there approaches you've seen fail elsewhere?
+- What should we explicitly avoid building?
+
+---
+
+## Rules
+
+### Questioning Rules
+- Use `AskUserQuestion` tool for structured questions with options
+- Maximum **4 questions per `AskUserQuestion` call** (tool limit)
+- Headers must be **≤12 characters**
+- 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
+
+### 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"):
+
+```
+Great, we've covered a lot of ground. To analyze this from multiple perspectives, run:
+
+/df:debate {name}
+
+Or if you want to go straight to a spec:
+
+/df:spec {name}
+```
+
+## Example
+
+```
+USER: /df:discover auth
+
+CLAUDE: Let's explore the authentication problem space.
+
+[Uses AskUserQuestion]
+{
+  "questions": [
+    {
+      "question": "What's driving the need for auth right now?",
+      "header": "Motivation",
+      "multiSelect": false,
+      "options": [
+        {"label": "Security gap", "description": "Current system has no auth or weak auth"},
+        {"label": "New users", "description": "Opening up to users who need access control"},
+        {"label": "Compliance", "description": "Regulatory or policy requirement"}
+      ]
+    },
+    {
+      "question": "Who are the primary users that will authenticate?",
+      "header": "Users",
+      "multiSelect": true,
+      "options": [
+        {"label": "End users", "description": "Public-facing users of the product"},
+        {"label": "Internal team", "description": "Your team or organization members"},
+        {"label": "API clients", "description": "Other services or integrations"}
+      ]
+    }
+  ]
+}
+
+USER: [Selects: Security gap, End users + API clients]
+
+CLAUDE: So there's a real security gap and you need to cover both human users
+and machine clients. That's two different auth flows to think about.
+
+[Uses AskUserQuestion]
+{
+  "questions": [
+    {
+      "question": "Do end users currently have any way to identify themselves?",
+      "header": "Current state",
+      "multiSelect": false,
+      "options": [
+        {"label": "Nothing", "description": "Completely open, no identification"},
+        {"label": "Basic auth", "description": "Simple username/password exists"},
+        {"label": "Third-party", "description": "Using external auth provider already"}
+      ]
+    },
+    {
+      "question": "For API clients, what authentication exists today?",
+      "header": "API auth",
+      "multiSelect": false,
+      "options": [
+        {"label": "None", "description": "APIs are open"},
+        {"label": "API keys", "description": "Static keys in headers"},
+        {"label": "OAuth/JWT", "description": "Token-based auth already in place"}
+      ]
+    }
+  ]
+}
+
+[... continues through phases based on answers ...]
+
+USER: I think we've covered everything, let's move on.
+
+CLAUDE: Great, we've covered a lot of ground. To analyze this from multiple
+perspectives, run:
+
+/df:debate auth
+
+Or if you want to go straight to a spec:
+
+/df:spec auth
+```

package/src/commands/df/spec.md

@@ -31,6 +31,8 @@ Transform conversation context into a structured specification file.
 
 ### 1. GATHER CODEBASE CONTEXT
 
+**Check for debate file first:** If `specs/.debate-{name}.md` exists, read it using the Read tool. Pass its content (especially the Synthesis section) to the reasoner agent in step 3 as additional context. The debate file contains multi-perspective analysis that should inform requirements and constraints.
+
 **NEVER use `run_in_background` for Explore agents** — causes late "Agent completed" notifications that pollute output after work is done.
 
 **NEVER use TaskOutput** — returns full agent transcripts (100KB+) that explode context.