deepflow 0.1.1 → 0.1.3

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/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.1
+0.1.3

package/bin/install.js

@@ -19,23 +19,35 @@ const c = {
 };
 
 // Paths
-const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+const GLOBAL_DIR = path.join(os.homedir(), '.claude');
+const PROJECT_DIR = path.join(process.cwd(), '.claude');
 const PACKAGE_DIR = path.resolve(__dirname, '..');
 
 async function main() {
   console.log('');
-  console.log(`${c.cyan}Installing deepflow...${c.reset}`);
+  console.log(`${c.cyan}deepflow installer${c.reset}`);
+  console.log('');
+
+  // Ask for installation level
+  const level = await askInstallLevel();
+  const CLAUDE_DIR = level === 'global' ? GLOBAL_DIR : PROJECT_DIR;
+  const levelLabel = level === 'global' ? 'globally' : 'in this project';
+
+  console.log('');
+  console.log(`Installing ${levelLabel}...`);
   console.log('');
 
   // Create directories
   const dirs = [
     'commands/df',
     'skills',
-    'agents',
-    'hooks',
-    'deepflow'
+    'agents'
   ];
 
+  if (level === 'global') {
+    dirs.push('hooks', 'deepflow');
+  }
+
   for (const dir of dirs) {
     fs.mkdirSync(path.join(CLAUDE_DIR, dir), { recursive: true });
   }
@@ -61,55 +73,71 @@ async function main() {
   );
   log('Agents installed');
 
-  // Copy hooks
-  const hooksDir = path.join(PACKAGE_DIR, 'hooks');
-  if (fs.existsSync(hooksDir)) {
-    for (const file of fs.readdirSync(hooksDir)) {
-      if (file.endsWith('.js')) {
-        fs.copyFileSync(
-          path.join(hooksDir, file),
-          path.join(CLAUDE_DIR, 'hooks', file)
-        );
+  // Copy hooks (global only - statusline requires global settings)
+  if (level === 'global') {
+    const hooksDir = path.join(PACKAGE_DIR, 'hooks');
+    if (fs.existsSync(hooksDir)) {
+      for (const file of fs.readdirSync(hooksDir)) {
+        if (file.endsWith('.js')) {
+          fs.copyFileSync(
+            path.join(hooksDir, file),
+            path.join(CLAUDE_DIR, 'hooks', file)
+          );
+        }
       }
+      log('Hooks installed');
     }
-    log('Hooks installed');
   }
 
-  // Copy VERSION
-  const versionFile = path.join(PACKAGE_DIR, 'VERSION');
-  if (fs.existsSync(versionFile)) {
-    fs.copyFileSync(versionFile, path.join(CLAUDE_DIR, 'deepflow', 'VERSION'));
-    log('Version file installed');
+  // Copy VERSION (global only - for update checking)
+  if (level === 'global') {
+    const versionFile = path.join(PACKAGE_DIR, 'VERSION');
+    if (fs.existsSync(versionFile)) {
+      fs.copyFileSync(versionFile, path.join(CLAUDE_DIR, 'deepflow', 'VERSION'));
+      log('Version file installed');
+    }
   }
 
-  // Configure statusline
-  await configureStatusline();
-
-  // Trigger background update check
-  const updateChecker = path.join(CLAUDE_DIR, 'hooks', 'df-check-update.js');
-  if (fs.existsSync(updateChecker)) {
-    const { spawn } = require('child_process');
-    const child = spawn(process.execPath, [updateChecker], {
-      detached: true,
-      stdio: 'ignore'
-    });
-    child.unref();
+  // Configure statusline (global only)
+  if (level === 'global') {
+    await configureStatusline(CLAUDE_DIR);
+
+    // Trigger background update check
+    const updateChecker = path.join(CLAUDE_DIR, 'hooks', 'df-check-update.js');
+    if (fs.existsSync(updateChecker)) {
+      const { spawn } = require('child_process');
+      const child = spawn(process.execPath, [updateChecker], {
+        detached: true,
+        stdio: 'ignore'
+      });
+      child.unref();
+    }
   }
 
   console.log('');
   console.log(`${c.green}Installation complete!${c.reset}`);
   console.log('');
-  console.log(`Installed to ${CLAUDE_DIR}:`);
+  console.log(`Installed to ${c.cyan}${CLAUDE_DIR}${c.reset}:`);
   console.log('  commands/df/     — /df:spec, /df:plan, /df:execute, /df:verify');
   console.log('  skills/          — gap-discovery, atomic-commits, code-completeness');
   console.log('  agents/          — reasoner');
-  console.log('  hooks/           — statusline, update checker');
+  if (level === 'global') {
+    console.log('  hooks/           — statusline, update checker');
+  }
   console.log('');
+  if (level === 'project') {
+    console.log(`${c.dim}Note: Statusline is only available with global install.${c.reset}`);
+    console.log('');
+  }
   console.log('Quick start:');
-  console.log('  1. cd your-project');
-  console.log('  2. claude');
-  console.log('  3. Describe what you want to build');
-  console.log('  4. /df:spec feature-name');
+  if (level === 'global') {
+    console.log('  1. cd your-project');
+    console.log('  2. claude');
+  } else {
+    console.log('  1. claude');
+  }
+  console.log('  2. Describe what you want to build');
+  console.log('  3. /df:spec feature-name');
   console.log('');
 }
 
@@ -130,9 +158,9 @@ function copyDir(src, dest) {
   }
 }
 
-async function configureStatusline() {
-  const settingsPath = path.join(CLAUDE_DIR, 'settings.json');
-  const hookCmd = `node "${path.join(CLAUDE_DIR, 'hooks', 'df-statusline.js')}"`;
+async function configureStatusline(claudeDir) {
+  const settingsPath = path.join(claudeDir, 'settings.json');
+  const hookCmd = `node "${path.join(claudeDir, 'hooks', 'df-statusline.js')}"`;
 
   let settings = {};
 
@@ -177,6 +205,21 @@ function ask(question) {
   });
 }
 
+async function askInstallLevel() {
+  console.log('Where do you want to install deepflow?');
+  console.log('');
+  console.log(`  ${c.cyan}1${c.reset}) Global  ${c.dim}(~/.claude/ - available in all projects)${c.reset}`);
+  console.log(`  ${c.cyan}2${c.reset}) Project ${c.dim}(./.claude/ - only this project)${c.reset}`);
+  console.log('');
+
+  const answer = await ask('Choose [1/2]: ');
+
+  if (answer === '2') {
+    return 'project';
+  }
+  return 'global';
+}
+
 function log(msg) {
   console.log(`  ${c.green}✓${c.reset} ${msg}`);
 }

package/package.json

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