deepflow 0.1.2 → 0.1.4

package/.claude/commands/df/spec.md

@@ -22,9 +22,25 @@ Before generating, use the `gap-discovery` skill to analyze conversation.
 - [ ] Key constraints identified
 - [ ] Success criteria stated
 
-**If gaps exist**, ask targeted questions (see skill for categories).
+**If gaps exist**, use the `AskUserQuestion` tool to ask structured questions:
+
+```json
+{
+  "questions": [
+    {
+      "question": "Clear, specific question ending with ?",
+      "header": "Short label",
+      "multiSelect": false,
+      "options": [
+        {"label": "Option 1", "description": "What this means"},
+        {"label": "Option 2", "description": "What this means"}
+      ]
+    }
+  ]
+}
+```
 
-Max 5 questions per round. Wait for answers before proceeding.
+Max 4 questions per tool call. Wait for answers before proceeding.
 
 ### 2. GENERATE SPEC
 
@@ -81,14 +97,53 @@ Next: Run /df:plan to generate tasks
 ```
 USER: I want to add image upload
 
-CLAUDE: A few questions before I create the spec:
-
-1. **File types**: Just images (jpg/png), or also gifs/videos?
-2. **Size limit**: Max file size?
-3. **Storage**: Local, S3, or other?
-4. **Auth**: Anyone can upload, or logged-in users only?
-
-USER: jpg/png/webp only, max 10MB, S3, logged-in only
+CLAUDE: [Uses AskUserQuestion tool]
+{
+  "questions": [
+    {
+      "question": "What file types should be supported?",
+      "header": "File types",
+      "multiSelect": true,
+      "options": [
+        {"label": "JPG/PNG only", "description": "Standard formats"},
+        {"label": "Include WebP", "description": "Modern compression"},
+        {"label": "Include GIF", "description": "Animated images"}
+      ]
+    },
+    {
+      "question": "What's the maximum upload size?",
+      "header": "Size limit",
+      "multiSelect": false,
+      "options": [
+        {"label": "5 MB", "description": "Fast uploads"},
+        {"label": "10 MB (Recommended)", "description": "Balanced"},
+        {"label": "25 MB", "description": "High-res photos"}
+      ]
+    },
+    {
+      "question": "Where should files be stored?",
+      "header": "Storage",
+      "multiSelect": false,
+      "options": [
+        {"label": "S3 (Recommended)", "description": "Scalable cloud storage"},
+        {"label": "Local filesystem", "description": "Simple, single server"},
+        {"label": "Cloudflare R2", "description": "S3-compatible, no egress fees"}
+      ]
+    },
+    {
+      "question": "Who can upload files?",
+      "header": "Auth",
+      "multiSelect": false,
+      "options": [
+        {"label": "Logged-in users", "description": "Require authentication"},
+        {"label": "Public", "description": "Anyone can upload"},
+        {"label": "Role-based", "description": "Specific roles only"}
+      ]
+    }
+  ]
+}
+
+USER: [Selects: JPG/PNG + WebP, 10MB, S3, Logged-in users]
 
 CLAUDE: ✓ Created specs/image-upload.md
 

package/.claude/commands/df/update.md

@@ -0,0 +1,33 @@
+# /df:update — Update deepflow
+
+Update deepflow to the latest version from npm.
+
+## Instructions
+
+1. Run the update command:
+```bash
+npx deepflow@latest
+```
+
+2. When prompted, choose the same installation level you used before (Global or Project).
+
+3. The installer will update all commands, skills, agents, and hooks.
+
+4. Restart Claude Code to apply changes.
+
+## What Gets Updated
+
+- Commands: `/df:spec`, `/df:plan`, `/df:execute`, `/df:verify`
+- Skills: gap-discovery, atomic-commits, code-completeness
+- Agents: reasoner
+- Hooks: statusline, update checker (global only)
+
+## Check Current Version
+
+Your installed version is stored in `~/.claude/deepflow/VERSION` (global) or `.claude/deepflow/VERSION` (project).
+
+Run this to see versions:
+```bash
+cat ~/.claude/deepflow/VERSION  # installed
+npm view deepflow version       # latest on npm
+```

package/.claude/skills/gap-discovery/SKILL.md

@@ -18,28 +18,109 @@ Proactively identify missing requirements before implementation.
 | **Success criteria** | "How will you know this works?" |
 | **Anti-goals** | "What should this explicitly NOT do?" |
 
+## Implementation
+
+**Use the `AskUserQuestion` tool** to ask structured questions with predefined options.
+
+### AskUserQuestion Format
+
+```json
+{
+  "questions": [
+    {
+      "question": "What file types should be supported?",
+      "header": "File types",
+      "multiSelect": true,
+      "options": [
+        {"label": "JPG/PNG only", "description": "Standard image formats"},
+        {"label": "Include WebP", "description": "Modern format with better compression"},
+        {"label": "Include GIF", "description": "Animated images supported"},
+        {"label": "Include video", "description": "MP4, WebM formats"}
+      ]
+    }
+  ]
+}
+```
+
+### Guidelines for AskUserQuestion
+
+- **header**: Max 12 characters (e.g., "File types", "Auth", "Storage")
+- **options**: 2-4 choices per question, each with label + description
+- **multiSelect**: Set `true` when choices aren't mutually exclusive
+- **questions**: Max 4 questions per tool call (tool limit)
+- Users can always select "Other" to provide custom input
+
+### Example Questions by Category
+
+**Scope:**
+```json
+{
+  "question": "Should this feature include admin management?",
+  "header": "Scope",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, include admin", "description": "Add admin dashboard for management"},
+    {"label": "No, user-only", "description": "Only end-user functionality"},
+    {"label": "Phase 2", "description": "Add admin features later"}
+  ]
+}
+```
+
+**Constraints:**
+```json
+{
+  "question": "What's the maximum file size for uploads?",
+  "header": "Size limit",
+  "multiSelect": false,
+  "options": [
+    {"label": "5 MB", "description": "Conservative, fast uploads"},
+    {"label": "10 MB (Recommended)", "description": "Balanced for most images"},
+    {"label": "25 MB", "description": "High-res photos supported"},
+    {"label": "50 MB", "description": "Large files, slower uploads"}
+  ]
+}
+```
+
+**Dependencies:**
+```json
+{
+  "question": "What authentication is required?",
+  "header": "Auth",
+  "multiSelect": false,
+  "options": [
+    {"label": "Public access", "description": "No login required"},
+    {"label": "Logged-in users", "description": "Require authentication"},
+    {"label": "Role-based", "description": "Different permissions per role"}
+  ]
+}
+```
+
 ## Process
 
 1. Listen to user's description
 2. Identify categories lacking clarity
-3. Ask 3-5 targeted questions (not overwhelming)
+3. Use `AskUserQuestion` with 1-4 targeted questions
 4. Wait for answers
-5. Follow up if answers reveal new gaps
+5. Follow up if answers reveal new gaps (another AskUserQuestion call)
 6. Signal when ready: "Requirements clear. Ready to proceed."
 
 ## Question Quality
 
 ```
 BAD:  "Any other requirements?"
-GOOD: "Max file size for uploads?"
+GOOD: "Max file size for uploads?" with concrete options
 
 BAD:  "What about errors?"
-GOOD: "If upload fails, retry automatically or show error to user?"
+GOOD: "If upload fails, retry automatically or show error to user?" with clear choices
 ```
 
 ## Rules
 
-- Max 5 questions per round
-- Be specific, offer choices when possible
+- Use `AskUserQuestion` tool for structured input
+- Max 4 questions per tool call (tool limitation)
+- Headers max 12 characters
+- 2-4 options per question with descriptions
+- Use multiSelect when choices can combine
+- Be specific, offer choices with trade-offs explained
 - Don't assume - ask
 - Stop when gaps are covered

package/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.4

package/package.json

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