deepflow 0.1.0

package/.claude/skills/atomic-commits/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: atomic-commits
+description: Makes atomic commits with clean messages. Use when committing code, implementing tasks, or preparing git history. Ensures one logical change per commit for easy review and rollback.
+---
+
+# Atomic Commits
+
+One task = one commit. Clean history, easy rollback.
+
+## Format
+
+```
+{type}({scope}): {description}
+
+- {detail}
+- {detail}
+
+Task: {id}
+```
+
+### Types
+
+| Type | Use |
+|------|-----|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `refactor` | Code change (no behavior change) |
+| `test` | Adding/fixing tests |
+| `docs` | Documentation |
+
+### Example
+
+```
+feat(image-upload): create upload API endpoint
+
+- Add POST /api/upload route
+- Implement multer middleware
+- Add file type validation
+
+Task: T1
+```
+
+## Process
+
+1. Implement task completely
+2. Verify it works (tests, types, lint)
+3. Stage specific files (`git add {files}`, not `-A`)
+4. Commit with proper format
+5. Return hash
+
+## Pre-Commit
+
+- [ ] Code runs without errors
+- [ ] No debug logs left
+- [ ] No commented code
+- [ ] No TODO added
+- [ ] Tests pass
+
+## Rules
+
+- Never commit broken code
+- Never commit partial work
+- Never commit unrelated changes
+- One logical change per commit

package/.claude/skills/code-completeness/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: code-completeness
+description: Finds incomplete code in codebase. Use when analyzing for TODOs, stubs, placeholders, skipped tests, or missing implementations. Helps compare specs against actual code state.
+---
+
+# Code Completeness
+
+Find incomplete work in codebase.
+
+## Explicit Markers
+
+| Pattern | Meaning |
+|---------|---------|
+| `TODO` | Planned, not done |
+| `FIXME` | Known broken |
+| `HACK` | Temporary workaround |
+| `XXX` | Needs attention |
+
+## Implicit Incompleteness
+
+| Pattern | Example |
+|---------|---------|
+| Stub return | `return null`, `return []` |
+| Not implemented | `throw new Error('not implemented')` |
+| Empty body | `function foo() {}` |
+| Hardcoded | `return "test"`, `return 42` |
+
+## Test Markers
+
+| Pattern | Language |
+|---------|----------|
+| `it.skip`, `test.skip` | JavaScript |
+| `describe.skip` | JavaScript |
+| `@pytest.mark.skip` | Python |
+| `t.Skip()` | Go |
+
+## Classification
+
+| Status | Criteria | Action |
+|--------|----------|--------|
+| **DONE** | Fully implemented | None |
+| **PARTIAL** | Has TODO/stub | Task to complete |
+| **MISSING** | Not in codebase | Task to create |
+| **CONFLICT** | Contradicts spec | Flag for review |
+
+## Report Format
+
+```
+REQ-1: {requirement}
+Status: PARTIAL
+Found: src/api/upload.ts:45 — `// TODO: validation`
+Action: Complete validation
+
+REQ-2: {requirement}
+Status: MISSING
+Action: Create src/services/storage.ts
+```
+
+## Rules
+
+- Search before assuming missing
+- Check test files too
+- Note file:line for findings

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

@@ -0,0 +1,45 @@
+---
+name: gap-discovery
+description: Discovers requirement gaps during ideation. Use when user describes features, planning specs, or requirements seem incomplete. Asks clarifying questions about scope, constraints, edge cases, success criteria.
+---
+
+# Gap Discovery
+
+Proactively identify missing requirements before implementation.
+
+## Gap Categories
+
+| Category | Example Question |
+|----------|------------------|
+| **Scope** | "Should this handle X, or is that separate?" |
+| **Edge cases** | "What happens if user uploads 50MB file?" |
+| **Constraints** | "Max size? Performance needs? Mobile support?" |
+| **Dependencies** | "Does this need auth? Existing API?" |
+| **Success criteria** | "How will you know this works?" |
+| **Anti-goals** | "What should this explicitly NOT do?" |
+
+## Process
+
+1. Listen to user's description
+2. Identify categories lacking clarity
+3. Ask 3-5 targeted questions (not overwhelming)
+4. Wait for answers
+5. Follow up if answers reveal new gaps
+6. Signal when ready: "Requirements clear. Ready to proceed."
+
+## Question Quality
+
+```
+BAD:  "Any other requirements?"
+GOOD: "Max file size for uploads?"
+
+BAD:  "What about errors?"
+GOOD: "If upload fails, retry automatically or show error to user?"
+```
+
+## Rules
+
+- Max 5 questions per round
+- Be specific, offer choices when possible
+- Don't assume - ask
+- Stop when gaps are covered

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+```
+     _                      __ _
+  __| | ___  ___ _ __      / _| | _____      __
+ / _` |/ _ \/ _ \ '_ \    | |_| |/ _ \ \ /\ / /
+| (_| |  __/  __/ |_) |   |  _| | (_) \ V  V /
+ \__,_|\___|\___| .__/    |_| |_|\___/ \_/\_/
+               |_|
+```
+
+<p align="center">
+  <strong>Stay in flow state — spec-driven task orchestration for Claude Code</strong>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#the-flow">The Flow</a> •
+  <a href="#commands">Commands</a> •
+  <a href="docs/getting-started.md">Docs</a>
+</p>
+
+---
+
+## Philosophy
+
+- **Stay in flow** — Minimize context switches, maximize deep work
+- **Conversational ideation** with proactive gap discovery
+- **Specs define intent**, tasks close reality gaps
+- **Parallel execution** with dependency awareness
+- **Atomic commits** for clean rollback
+- **Minimal ceremony** — 4 commands, not 27
+
+## Quick Start
+
+```bash
+# Install
+npx deepflow
+
+# In your project
+claude
+
+# 1. Discuss what you want to build (conversation)
+# 2. Generate spec when ready
+/df:spec image-upload
+
+# 3. Compare specs to code, generate tasks
+/df:plan
+
+# 4. Execute tasks with parallel agents
+/df:execute
+
+# 5. Verify specs are satisfied
+/df:verify
+```
+
+## The Flow
+
+```
+CONVERSATION
+    │ Describe what you want
+    │ LLM asks gap questions (scope, edge cases, constraints)
+    ▼
+/df:spec <name>
+    │ Generates specs/{name}.md
+    ▼
+/df:plan
+    │ Compares specs to codebase
+    │ Finds TODOs, stubs, missing implementations
+    │ Outputs PLAN.md with prioritized tasks
+    ▼
+/df:execute
+    │ Runs tasks respecting dependencies
+    │ Parallel for independent tasks
+    │ Atomic commit per task
+    ▼
+/df:verify
+    │ Checks spec requirements met
+    │ Updates PLAN.md status
+```
+
+## File Structure
+
+After running deepflow, your project will have:
+
+```
+your-project/
+├── specs/
+│   ├── feature-a.md
+│   └── feature-b.md
+├── PLAN.md          # Task checklist
+└── STATE.md         # Decisions & learnings
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/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 |
+
+## Configuration
+
+Create `.deepflow/config.yaml` in your project:
+
+```yaml
+project:
+  source_dir: src/
+  specs_dir: specs/
+
+planning:
+  search_patterns:
+    - "TODO"
+    - "FIXME"
+    - "stub"
+    - "placeholder"
+
+parallelism:
+  max_search_agents: 50
+  max_write_agents: 5
+
+models:
+  search: sonnet
+  implement: sonnet
+  reason: opus
+```
+
+## Principles
+
+1. **Stay in flow** — Uninterrupted deep work
+2. **Confirm before assume** — Search code before creating "missing" tasks
+3. **Complete implementations** — No stubs, no placeholders
+4. **Atomic commits** — One task = one commit
+5. **Single writer per file** — Avoid race conditions
+
+## License
+
+MIT

package/VERSION

@@ -0,0 +1 @@
+0.1.0

package/bin/install.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * deepflow installer
+ * Usage: npx deepflow
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+// Colors
+const c = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m'
+};
+
+// Paths
+const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+const PACKAGE_DIR = path.resolve(__dirname, '..');
+
+async function main() {
+  console.log('');
+  console.log(`${c.cyan}Installing deepflow...${c.reset}`);
+  console.log('');
+
+  // Create directories
+  const dirs = [
+    'commands/df',
+    'skills',
+    'agents',
+    'hooks',
+    'deepflow'
+  ];
+
+  for (const dir of dirs) {
+    fs.mkdirSync(path.join(CLAUDE_DIR, dir), { recursive: true });
+  }
+
+  // Copy commands
+  copyDir(
+    path.join(PACKAGE_DIR, '.claude', 'commands', 'df'),
+    path.join(CLAUDE_DIR, 'commands', 'df')
+  );
+  log('Commands installed');
+
+  // Copy skills
+  copyDir(
+    path.join(PACKAGE_DIR, '.claude', 'skills'),
+    path.join(CLAUDE_DIR, 'skills')
+  );
+  log('Skills installed');
+
+  // Copy agents
+  copyDir(
+    path.join(PACKAGE_DIR, '.claude', 'agents'),
+    path.join(CLAUDE_DIR, 'agents')
+  );
+  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)
+        );
+      }
+    }
+    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');
+  }
+
+  // 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();
+  }
+
+  console.log('');
+  console.log(`${c.green}Installation complete!${c.reset}`);
+  console.log('');
+  console.log(`Installed to ${CLAUDE_DIR}:`);
+  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');
+  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');
+  console.log('');
+}
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) return;
+
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+async function configureStatusline() {
+  const settingsPath = path.join(CLAUDE_DIR, 'settings.json');
+  const hookCmd = `node "${path.join(CLAUDE_DIR, 'hooks', 'df-statusline.js')}"`;
+
+  let settings = {};
+
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch (e) {
+      settings = {};
+    }
+
+    if (settings.statusLine) {
+      const answer = await ask(
+        `  ${c.yellow}!${c.reset} Existing statusLine found. Replace with deepflow? [y/N] `
+      );
+      if (answer.toLowerCase() !== 'y') {
+        console.log(`  ${c.yellow}!${c.reset} Skipped statusline configuration`);
+        return;
+      }
+    }
+  }
+
+  settings.statusLine = {
+    type: 'command',
+    command: hookCmd
+  };
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  log('Statusline configured');
+}
+
+function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+function log(msg) {
+  console.log(`  ${c.green}✓${c.reset} ${msg}`);
+}
+
+main().catch(err => {
+  console.error('Installation failed:', err.message);
+  process.exit(1);
+});

package/hooks/df-check-update.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * deepflow update checker
+ * Runs in background, checks npm for newer versions
+ */
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const PACKAGE_NAME = 'deepflow';
+const CACHE_DIR = path.join(os.homedir(), '.claude', 'cache');
+const CACHE_FILE = path.join(CACHE_DIR, 'df-update-check.json');
+const CHECK_INTERVAL = 24 * 60 * 60 * 1000; // 24 hours
+
+// If called directly, spawn background process and exit
+if (process.argv[2] !== '--background') {
+  const child = spawn(process.execPath, [__filename, '--background'], {
+    detached: true,
+    stdio: 'ignore'
+  });
+  child.unref();
+  process.exit(0);
+}
+
+// Background process
+async function checkForUpdate() {
+  try {
+    // Ensure cache directory exists
+    if (!fs.existsSync(CACHE_DIR)) {
+      fs.mkdirSync(CACHE_DIR, { recursive: true });
+    }
+
+    // Check if we've checked recently
+    if (fs.existsSync(CACHE_FILE)) {
+      const cache = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+      const age = Date.now() - (cache.timestamp || 0);
+      if (age < CHECK_INTERVAL) {
+        process.exit(0);
+      }
+    }
+
+    // Get current version
+    const currentVersion = getCurrentVersion();
+    if (!currentVersion) {
+      process.exit(0);
+    }
+
+    // Get latest version from npm (with timeout)
+    const latestVersion = await getLatestVersion();
+    if (!latestVersion) {
+      process.exit(0);
+    }
+
+    // Compare and cache result
+    const updateAvailable = isNewerVersion(latestVersion, currentVersion);
+
+    const result = {
+      updateAvailable,
+      currentVersion,
+      latestVersion,
+      timestamp: Date.now()
+    };
+
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(result, null, 2));
+
+  } catch (e) {
+    // Fail silently
+  }
+
+  process.exit(0);
+}
+
+function getCurrentVersion() {
+  // Check deepflow VERSION file
+  const dfLocalPath = path.join(process.cwd(), '.claude', 'deepflow', 'VERSION');
+  const dfGlobalPath = path.join(os.homedir(), '.claude', 'deepflow', 'VERSION');
+
+  for (const versionPath of [dfLocalPath, dfGlobalPath]) {
+    if (fs.existsSync(versionPath)) {
+      return fs.readFileSync(versionPath, 'utf8').trim();
+    }
+  }
+
+  return null;
+}
+
+function getLatestVersion() {
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => resolve(null), 10000);
+
+    const child = spawn('npm', ['view', PACKAGE_NAME, 'version'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      shell: true
+    });
+
+    let output = '';
+    child.stdout.on('data', data => output += data);
+
+    child.on('close', (code) => {
+      clearTimeout(timeout);
+      if (code === 0 && output.trim()) {
+        resolve(output.trim());
+      } else {
+        resolve(null);
+      }
+    });
+
+    child.on('error', () => {
+      clearTimeout(timeout);
+      resolve(null);
+    });
+  });
+}
+
+function isNewerVersion(latest, current) {
+  const latestParts = latest.split('.').map(Number);
+  const currentParts = current.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    if ((latestParts[i] || 0) > (currentParts[i] || 0)) return true;
+    if ((latestParts[i] || 0) < (currentParts[i] || 0)) return false;
+  }
+
+  return false;
+}
+
+checkForUpdate();