deepflow 0.1.73 → 0.1.75

package/README.md

@@ -49,6 +49,8 @@ npx deepflow
 npx deepflow --uninstall
 ```
 
+The installer configures granular permissions so background agents can read, write, run git, and execute health checks (build/test/typecheck/lint) without blocking on approval prompts. All permissions are scoped and cleaned up on uninstall.
+
 ## Two Modes
 
 ### Interactive (human-in-the-loop)

package/bin/install.js

@@ -184,13 +184,14 @@ async function main() {
   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, /df:auto, /df:note, /df:resume, /df:update');
-  console.log('  skills/          — gap-discovery, atomic-commits, code-completeness');
+  console.log('  skills/          — gap-discovery, atomic-commits, code-completeness, context-hub');
   console.log('  agents/          — reasoner (/df:auto — autonomous execution via /loop)');
   if (level === 'global') {
     console.log('  hooks/           — statusline, update checker');
   }
   console.log('  hooks/df-spec-*  — spec validation (auto-enforced by /df:spec and /df:plan)');
   console.log('  env/             — ENABLE_LSP_TOOL (code navigation via goToDefinition, findReferences, workspaceSymbol)');
+  console.log('  permissions/     — granular allow-list for background agents (git, build, test, read/write)');
   console.log('');
   if (level === 'project') {
     console.log(`${c.dim}Note: Statusline is only available with global install.${c.reset}`);
@@ -252,6 +253,10 @@ async function configureHooks(claudeDir) {
   settings.env.ENABLE_LSP_TOOL = "1";
   log('LSP tool enabled');
 
+  // Configure permissions for background agents
+  configurePermissions(settings);
+  log('Agent permissions configured');
+
   // Configure statusline
   if (settings.statusLine) {
     const answer = await ask(
@@ -319,8 +324,72 @@ function configureProjectSettings(claudeDir) {
   if (!settings.env) settings.env = {};
   settings.env.ENABLE_LSP_TOOL = "1";
 
+  // Configure permissions for background agents
+  configurePermissions(settings);
+
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-  log('LSP tool enabled (project)');
+  log('LSP tool enabled + agent permissions configured (project)');
+}
+
+// Permissions required for background agents to work without blocking
+const DEEPFLOW_PERMISSIONS = [
+  // Agents need to read/write code
+  "Edit",
+  "Write",
+  "Read",
+  // Agents need to search codebase
+  "Glob",
+  "Grep",
+  // Git operations (orchestrator handles worktrees, agents read status)
+  "Bash(git status:*)",
+  "Bash(git diff:*)",
+  "Bash(git add:*)",
+  "Bash(git commit:*)",
+  "Bash(git log:*)",
+  "Bash(git stash:*)",
+  "Bash(git checkout:*)",
+  "Bash(git branch:*)",
+  "Bash(git revert:*)",
+  "Bash(git worktree:*)",
+  "Bash(git ls-files:*)",
+  "Bash(git merge:*)",
+  // Build & test (ratchet health checks)
+  "Bash(npm run build:*)",
+  "Bash(npm test:*)",
+  "Bash(npm run lint:*)",
+  "Bash(npx tsc:*)",
+  "Bash(cargo build:*)",
+  "Bash(cargo test:*)",
+  "Bash(go build:*)",
+  "Bash(go test:*)",
+  "Bash(pytest:*)",
+  "Bash(python -m pytest:*)",
+  "Bash(ruff:*)",
+  "Bash(mypy:*)",
+  // Utility
+  "Bash(node:*)",
+  "Bash(ls:*)",
+  "Bash(cat:*)",
+  "Bash(mkdir:*)",
+  "Bash(date:*)",
+  "Bash(wc:*)",
+  "Bash(head:*)",
+  "Bash(tail:*)",
+];
+
+function configurePermissions(settings) {
+  if (!settings.permissions) settings.permissions = {};
+  if (!settings.permissions.allow) settings.permissions.allow = [];
+
+  const existing = new Set(settings.permissions.allow);
+  let added = 0;
+
+  for (const perm of DEEPFLOW_PERMISSIONS) {
+    if (!existing.has(perm)) {
+      settings.permissions.allow.push(perm);
+      added++;
+    }
+  }
 }
 
 function ask(question) {
@@ -400,6 +469,7 @@ async function uninstall() {
     'skills/atomic-commits',
     'skills/code-completeness',
     'skills/gap-discovery',
+    'skills/context-hub',
     'agents/reasoner.md'
   ];
 
@@ -449,23 +519,30 @@ async function uninstall() {
       }
     }
 
-    // Remove ENABLE_LSP_TOOL from global settings
+    // Remove ENABLE_LSP_TOOL and deepflow permissions from global settings
     if (fs.existsSync(settingsPath)) {
       try {
         const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
         if (settings.env?.ENABLE_LSP_TOOL) {
           delete settings.env.ENABLE_LSP_TOOL;
           if (settings.env && Object.keys(settings.env).length === 0) delete settings.env;
-          fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
           console.log(`  ${c.green}✓${c.reset} Removed ENABLE_LSP_TOOL from settings`);
         }
+        if (settings.permissions?.allow) {
+          const dfPerms = new Set(DEEPFLOW_PERMISSIONS);
+          settings.permissions.allow = settings.permissions.allow.filter(p => !dfPerms.has(p));
+          if (settings.permissions.allow.length === 0) delete settings.permissions.allow;
+          if (settings.permissions && Object.keys(settings.permissions).length === 0) delete settings.permissions;
+          console.log(`  ${c.green}✓${c.reset} Removed deepflow permissions from settings`);
+        }
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
       } catch (e) {
         // Fail silently
       }
     }
   }
 
-  // Remove ENABLE_LSP_TOOL from project settings.local.json
+  // Remove ENABLE_LSP_TOOL and deepflow permissions from project settings.local.json
   if (level === 'project') {
     const localSettingsPath = path.join(PROJECT_DIR, 'settings.local.json');
     if (fs.existsSync(localSettingsPath)) {
@@ -474,13 +551,19 @@ async function uninstall() {
         if (localSettings.env?.ENABLE_LSP_TOOL) {
           delete localSettings.env.ENABLE_LSP_TOOL;
           if (localSettings.env && Object.keys(localSettings.env).length === 0) delete localSettings.env;
-          if (Object.keys(localSettings).length === 0) {
-            fs.unlinkSync(localSettingsPath);
-            console.log(`  ${c.green}✓${c.reset} Removed settings.local.json (empty after cleanup)`);
-          } else {
-            fs.writeFileSync(localSettingsPath, JSON.stringify(localSettings, null, 2));
-            console.log(`  ${c.green}✓${c.reset} Removed ENABLE_LSP_TOOL from settings.local.json`);
-          }
+        }
+        if (localSettings.permissions?.allow) {
+          const dfPerms = new Set(DEEPFLOW_PERMISSIONS);
+          localSettings.permissions.allow = localSettings.permissions.allow.filter(p => !dfPerms.has(p));
+          if (localSettings.permissions.allow.length === 0) delete localSettings.permissions.allow;
+          if (localSettings.permissions && Object.keys(localSettings.permissions).length === 0) delete localSettings.permissions;
+        }
+        if (Object.keys(localSettings).length === 0) {
+          fs.unlinkSync(localSettingsPath);
+          console.log(`  ${c.green}✓${c.reset} Removed settings.local.json (empty after cleanup)`);
+        } else {
+          fs.writeFileSync(localSettingsPath, JSON.stringify(localSettings, null, 2));
+          console.log(`  ${c.green}✓${c.reset} Removed deepflow settings from settings.local.json`);
         }
       } catch (e) {
         // Fail silently

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.73",
+  "version": "0.1.75",
   "description": "Doing reveals what thinking can't predict — spec-driven iterative development for Claude Code",
   "keywords": [
     "claude",

package/src/commands/df/execute.md

@@ -24,6 +24,7 @@ Implement tasks from PLAN.md with parallel agents, atomic commits, ratchet-drive
 
 ## Skills & Agents
 - Skill: `atomic-commits` — Clean commit protocol
+- Skill: `context-hub` — Fetch external API docs before coding (when task involves external libraries)
 
 **Use Task tool to spawn agents:**
 | Agent | subagent_type | Purpose |
@@ -453,8 +454,11 @@ Files: {target files}
 Spec: {spec_name}
 
 Steps:
-1. Implement the task
-2. Commit as feat({spec}): {description}
+1. If the task involves external APIs/SDKs, run: chub search "<library>" --json → chub get <id> --lang <lang>
+   Use fetched docs as ground truth for API signatures. Annotate any gaps: chub annotate <id> "note"
+   Skip this step if chub is not installed or the task only touches internal code.
+2. Implement the task
+3. Commit as feat({spec}): {description}
 
 Your ONLY job is to write code and commit. The orchestrator will run health checks after you finish.
 ```
@@ -546,6 +550,7 @@ After spawning wave agents, your turn ENDS. Completion notifications drive the l
 | Machine-selected winner | Fewer regressions > better coverage > fewer files changed; no LLM judge |
 | Failed probe insights logged | `.deepflow/auto-memory.yaml` in main tree; persists across cycles |
 | Winner cherry-picked to shared worktree | Downstream tasks see winning approach via shared worktree |
+| External APIs → chub first | Agents fetch curated docs before implementing external API calls; skip if chub unavailable |
 
 ## Example
 

package/src/skills/context-hub/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: context-hub
+description: Fetches curated API docs for external libraries before coding. Use when implementing code that uses external APIs/SDKs (Stripe, OpenAI, MongoDB, etc.) to avoid hallucinating APIs and reduce token usage.
+---
+
+# Context Hub
+
+Fetch curated, versioned docs for external libraries instead of guessing APIs.
+
+## When to Use
+
+Before writing code that calls an external API or SDK:
+- New library integration (e.g., Stripe payments, AWS S3)
+- Unfamiliar API version or method
+- Complex API with many options (e.g., MongoDB aggregation)
+
+**Skip when:** Working with internal code (use LSP instead) or well-known stdlib APIs.
+
+## Prerequisites
+
+Requires `chub` CLI: `npm install -g @aisuite/chub`
+
+If `chub` is not installed, tell the user and skip — don't block implementation.
+
+## Workflow
+
+### 1. Search for docs
+
+```bash
+chub search "<library or API>" --json
+```
+
+Example:
+```bash
+chub search "stripe payments" --json
+chub search "mongodb aggregation" --json
+```
+
+### 2. Fetch relevant docs
+
+```bash
+chub get <id> --lang <py|js|ts>
+```
+
+Use `--lang` matching the project language. Use `--full` only if the summary lacks what you need.
+
+### 3. Write code using fetched docs
+
+Use the retrieved documentation as ground truth for API signatures, parameter names, and patterns.
+
+### 4. Annotate discoveries
+
+When you find something the docs missed or got wrong:
+
+```bash
+chub annotate <id> "Note: method X requires param Y since v2.0"
+```
+
+This persists locally and appears on future `chub get` calls — the agent learns across sessions.
+
+### 5. Rate docs (optional)
+
+```bash
+chub feedback <id> up --label accurate
+chub feedback <id> down --label outdated
+```
+
+Labels: `accurate`, `outdated`, `incomplete`, `wrong-version`, `helpful`
+
+## Integration with LSP
+
+| Need | Tool |
+|------|------|
+| Internal code navigation | LSP (`goToDefinition`, `findReferences`) |
+| External API signatures | Context Hub (`chub get`) |
+| Symbol search in project | LSP (`workspaceSymbol`) |
+| Library usage patterns | Context Hub (`chub search`) |
+
+**Combined approach:** Use LSP to understand how the project currently uses a library, then use Context Hub to verify correct API usage and discover better patterns.
+
+## Rules
+
+- Always search before implementing external API calls
+- Trust chub docs over training data for API specifics
+- Annotate gaps so future sessions benefit
+- Don't block on chub failures — fall back to best knowledge
+- Prefer `--json` flag for programmatic parsing in automated workflows