deepflow 0.1.0

package/hooks/df-statusline.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * deepflow statusline for Claude Code
+ * Displays: model | project | context usage
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  orange: '\x1b[38;5;208m',
+  red: '\x1b[31m',
+  blink: '\x1b[5m',
+  cyan: '\x1b[36m'
+};
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    console.log(buildStatusLine(data));
+  } catch (e) {
+    // Fail silently to avoid breaking statusline
+    console.log('');
+  }
+});
+
+function buildStatusLine(data) {
+  const parts = [];
+
+  // Check for updates
+  const updateInfo = checkForUpdate();
+  if (updateInfo && updateInfo.updateAvailable) {
+    parts.push(`${colors.yellow}⬆ /df:update${colors.reset}`);
+  }
+
+  // Model name
+  const model = formatModel(data.model || 'unknown');
+  parts.push(model);
+
+  // Project name (from cwd)
+  const project = path.basename(data.cwd || process.cwd());
+  parts.push(`${colors.cyan}${project}${colors.reset}`);
+
+  // Context window meter
+  const contextMeter = buildContextMeter(data.tokenUsage || {});
+  parts.push(contextMeter);
+
+  return parts.join(` ${colors.dim}│${colors.reset} `);
+}
+
+function formatModel(model) {
+  // Shorten model names
+  const modelMap = {
+    'claude-opus-4-5-20251101': 'Opus 4.5',
+    'claude-sonnet-4-20250514': 'Sonnet 4',
+    'claude-haiku-3-5-20241022': 'Haiku 3.5'
+  };
+  return modelMap[model] || model.replace('claude-', '').replace(/-\d+$/, '');
+}
+
+function buildContextMeter(tokenUsage) {
+  const used = tokenUsage.total || 0;
+  const limit = tokenUsage.limit || 200000;
+
+  // Scale so 80% shows as 100% (enforce 80% limit visually)
+  const effectiveLimit = limit * 0.8;
+  const percentage = Math.min(100, Math.round((used / effectiveLimit) * 100));
+
+  // Build 10-segment bar
+  const segments = 10;
+  const filled = Math.round((percentage / 100) * segments);
+  const bar = '█'.repeat(filled) + '░'.repeat(segments - filled);
+
+  // Color based on usage
+  let color;
+  if (percentage < 63) {
+    color = colors.green;
+  } else if (percentage < 81) {
+    color = colors.yellow;
+  } else if (percentage < 95) {
+    color = colors.orange;
+  } else {
+    color = colors.blink + colors.red;
+  }
+
+  return `${color}${bar}${colors.reset} ${percentage}%`;
+}
+
+function checkForUpdate() {
+  try {
+    const cacheDir = path.join(os.homedir(), '.claude', 'cache');
+    const cachePath = path.join(cacheDir, 'df-update-check.json');
+
+    if (!fs.existsSync(cachePath)) return null;
+
+    const cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+    return cache;
+  } catch (e) {
+    return null;
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "deepflow",
+  "version": "0.1.0",
+  "description": "Stay in flow state - lightweight spec-driven task orchestration for Claude Code",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "flow",
+    "deep-work",
+    "orchestration",
+    "specs",
+    "tasks",
+    "automation",
+    "productivity"
+  ],
+  "author": "saidwafiq",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saidwafiq/deepflow.git"
+  },
+  "homepage": "https://github.com/saidwafiq/deepflow#readme",
+  "bugs": {
+    "url": "https://github.com/saidwafiq/deepflow/issues"
+  },
+  "bin": {
+    "deepflow": "bin/install.js"
+  },
+  "files": [
+    "bin/",
+    ".claude/",
+    "hooks/",
+    "templates/",
+    "VERSION"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/templates/config-template.yaml

@@ -0,0 +1,42 @@
+# deepflow configuration
+
+project:
+  name: my-project
+  source_dir: src/
+  specs_dir: specs/
+
+planning:
+  # Patterns to search for incomplete work
+  search_patterns:
+    - "TODO"
+    - "FIXME"
+    - "HACK"
+    - "stub"
+    - "placeholder"
+    - "it.skip"
+    - "test.skip"
+
+parallelism:
+  # Agent limits by operation type
+  search:
+    max: 100
+    per_files: 20      # 1 agent per N files
+  analyze:
+    max: 20
+    per_specs: 2       # 1 agent per N specs
+  execute:
+    max: 5
+    per_file: 1        # Never parallel on same file
+  test:
+    max: 1             # Always sequential
+
+models:
+  search: sonnet       # Fast, cheap
+  implement: sonnet    # Good balance
+  reason: opus         # Complex decisions
+  debug: opus          # Problem solving
+
+commits:
+  format: "feat({spec}): {description}"
+  atomic: true         # One task = one commit
+  push_after: complete # Or "each" for every commit

package/templates/plan-template.md

@@ -0,0 +1,41 @@
+# Plan
+
+Generated: {timestamp}
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Specs analyzed | 0 |
+| Tasks created | 0 |
+| Ready (no blockers) | 0 |
+| Blocked | 0 |
+
+## Spec Gaps
+
+[Issues found in specs that need clarification]
+
+- [ ] `specs/example.md`: [Gap description]
+
+## Tasks
+
+### {spec-name}
+
+- [ ] **T1**: {Task description}
+  - Files: {files to create or modify}
+  - Blocked by: none
+
+- [ ] **T2**: {Task description}
+  - Files: {files}
+  - Blocked by: T1
+
+---
+
+<!--
+Plan Guidelines:
+- One task = one atomic commit
+- Tasks should be 15-60 min of work
+- Blocked by references task IDs (T1, T2, etc.)
+- Mark complete with [x] and commit hash
+- Example completed: [x] **T1**: Create API ✓ (abc1234)
+-->

package/templates/spec-template.md

@@ -0,0 +1,40 @@
+# {Name}
+
+## Objective
+
+[One sentence: what this achieves for the user]
+
+## Requirements
+
+- **REQ-1**: [Requirement description]
+- **REQ-2**: [Requirement description]
+- **REQ-3**: [Requirement description]
+
+## Constraints
+
+- [Constraint 1: e.g., "Max file size 10MB"]
+- [Constraint 2: e.g., "Must work offline"]
+
+## Out of Scope
+
+- [Explicitly excluded: e.g., "Video upload is NOT included"]
+
+## Acceptance Criteria
+
+- [ ] [Testable criterion: e.g., "User can upload jpg/png/webp files"]
+- [ ] [Testable criterion: e.g., "Files over 10MB show clear error"]
+- [ ] [Testable criterion: e.g., "Upload progress is visible"]
+
+## Technical Notes
+
+[Optional: implementation hints, preferred libraries, architectural decisions]
+
+---
+
+<!--
+Spec Guidelines:
+- Keep under 100 lines
+- Requirements must be testable
+- Acceptance criteria must be verifiable
+- Be explicit about what's OUT of scope
+-->

package/templates/state-template.md

@@ -0,0 +1,47 @@
+# State
+
+Project context and learnings for LLM continuity.
+
+## Current Status
+
+- **Phase**: [ideation | planning | executing | verifying]
+- **Active spec**: [spec name or "none"]
+- **Progress**: [X/Y tasks complete]
+
+## Decisions
+
+[Key decisions made during development]
+
+| Decision | Rationale | Date |
+|----------|-----------|------|
+| [Decision] | [Why] | [Date] |
+
+## Learnings
+
+[Things discovered that future sessions should know]
+
+- [Learning 1]
+- [Learning 2]
+
+## Blockers
+
+[Current blockers and workarounds]
+
+- [ ] [Blocker]: [Workaround if any]
+
+## Session Log
+
+### {Date}
+- [What was done]
+- [What's next]
+
+---
+
+<!--
+State Guidelines:
+- Keep concise - this loads into every session
+- Focus on CONTEXT, not history
+- Decisions = things that affect future work
+- Learnings = "if I knew this earlier..."
+- Clean up resolved blockers
+-->