deepflow 0.1.0

package/.claude/agents/reasoner.md

@@ -0,0 +1,60 @@
+---
+name: reasoner
+description: Complex analysis and reasoning. Use for prioritization, debugging, architectural decisions, and comparing specs against code. Handles tasks requiring deep thinking.
+model: opus
+tools: Read, Grep, Glob, Edit, Bash
+skills:
+  - code-completeness
+---
+
+# Reasoner
+
+Complex reasoning tasks requiring deep analysis.
+
+## Capabilities
+
+- Prioritize tasks by dependencies and impact
+- Debug failures with systematic analysis
+- Compare specs against implementation
+- Make architectural decisions
+- Analyze trade-offs
+
+## When to Use
+
+| Task | Why Reasoner |
+|------|--------------|
+| Prioritization | Dependency graphs, impact analysis |
+| Debugging | Hypothesis testing, root cause |
+| Spec comparison | Gap analysis, conflict detection |
+| Architecture | Trade-off evaluation |
+
+## Process
+
+1. Understand the problem fully
+2. Gather relevant context
+3. Analyze systematically
+4. Present findings with rationale
+5. Recommend action
+
+## Return Format
+
+```
+## Analysis
+
+{What was analyzed}
+
+## Findings
+
+{Key discoveries with evidence}
+
+## Recommendation
+
+{Suggested action with rationale}
+```
+
+## Rules
+
+- Think before acting
+- Show reasoning, not just conclusions
+- Cite evidence (file:line)
+- Be decisive - recommend, don't waffle

package/.claude/commands/df/execute.md

@@ -0,0 +1,190 @@
+# /df:execute — Execute Tasks from Plan
+
+## Purpose
+Implement tasks from PLAN.md with parallel agents and atomic commits.
+
+## Usage
+```
+/df:execute
+/df:execute T1 T2    # Execute specific tasks only
+```
+
+## Skills & Agents
+- Skill: `atomic-commits` — Clean commit protocol
+- Agent: `general-purpose` (Sonnet) — Task implementation
+- Agent: `reasoner` (Opus) — Debugging failures
+
+## Behavior
+
+### 1. LOAD PLAN
+
+```
+Load:
+- PLAN.md (required)
+- specs/*.md (for context)
+- .specflow/config.yaml (if exists)
+```
+
+If PLAN.md missing:
+```
+No PLAN.md found. Run /df:plan first.
+```
+
+### 2. IDENTIFY READY TASKS
+
+Find tasks where:
+- Status is `[ ]` (not done)
+- All `blocked_by` tasks are `[x]` (complete)
+
+```
+Ready: [T1, T2, T5]     # No blockers
+Blocked: [T3, T4]       # Waiting on dependencies
+Done: []
+```
+
+### 3. EXECUTE IN PARALLEL
+
+**Spawn `general-purpose` agents** (Sonnet) for ready tasks:
+
+| Ready Tasks | Agents |
+|-------------|--------|
+| 1-3 | All parallel |
+| 4-10 | 5 parallel, queue rest |
+| 10+ | 5 parallel, queue rest |
+
+Each agent uses `atomic-commits` skill for commit protocol.
+
+**Critical rule: 1 writer per file**
+If T1 and T2 both modify `src/api.ts`, execute sequentially.
+
+**On failure:** Spawn `reasoner` agent (Opus) for debugging.
+
+### 4. PER-TASK EXECUTION
+
+Each executor agent:
+
+```
+1. READ spec requirements for this task
+2. READ existing code context
+3. IMPLEMENT the task completely
+   - No stubs
+   - No placeholders
+   - No TODO comments
+4. VERIFY implementation works
+   - Run related tests if they exist
+   - Check TypeScript/lint if applicable
+5. COMMIT atomically
+   - Format: feat({spec}): {task description}
+   - One task = one commit
+```
+
+### 5. UPDATE PLAN
+
+After each task completes:
+```markdown
+- [x] **T1**: Create upload API endpoint ✓ (abc1234)
+  - Files: src/api/upload.ts
+  - Blocked by: none
+```
+
+### 6. ITERATE
+
+After wave completes:
+```
+Wave 1 complete: T1 ✓, T2 ✓
+
+Unblocked: T3, T4 now ready
+Executing wave 2...
+```
+
+Repeat until all tasks done or blocked.
+
+### 7. REPORT
+
+```
+✓ Execution complete
+
+Tasks completed: 5/5
+Commits: 5
+Failed: 0
+
+All specs implemented. Run /df:verify to confirm.
+```
+
+Or if partial:
+```
+⚠ Execution paused
+
+Tasks completed: 3/5
+Blocked: T4 (waiting on T3)
+Failed: T3 (see error below)
+
+Error in T3:
+  [error details]
+
+Fix the issue and run /df:execute to continue.
+```
+
+## Rules
+
+### Parallelism
+- **Read operations**: Unlimited parallel
+- **Write operations**: Max 5 parallel, 1 per file
+- **Build/test**: Always sequential
+
+### Commits
+- One task = one commit
+- Format: `feat({spec}): {description}`
+- Include task ID in commit body
+- Never commit broken code
+
+### Completeness
+- No stubs or placeholders
+- No `// TODO` comments
+- Implement fully or don't commit
+
+### Conflict Avoidance
+```
+If T1 writes to src/api.ts
+And T2 writes to src/api.ts
+Then execute T1, wait, then T2
+```
+
+## Agent Spawning
+
+```yaml
+executor_agents:
+  max_parallel: 5
+  per_file_limit: 1
+
+model_selection:
+  implement: sonnet
+  debug: opus
+
+commit_after: each_task
+push_after: all_complete  # Not every commit
+```
+
+## Example Session
+
+```
+/df:execute
+
+Loading PLAN.md...
+Found 5 tasks, 3 ready (no blockers)
+
+Wave 1: Executing T1, T2, T5 in parallel...
+  T1: Create upload API endpoint... ✓ (abc1234)
+  T2: Add validation middleware... ✓ (def5678)
+  T5: Integrate color-thief... ✓ (ghi9012)
+
+Wave 2: T3, T4 now unblocked
+  T3: Implement S3 upload... ✓ (jkl3456)
+  T4: Complete thumbnails... ✓ (mno7890)
+
+✓ Execution complete
+Tasks: 5/5
+Commits: 5
+
+Run /df:verify to confirm specs satisfied.
+```

package/.claude/commands/df/plan.md

@@ -0,0 +1,171 @@
+# /df:plan — Generate Task Plan from Specs
+
+## Purpose
+Compare specs against codebase, identify gaps, generate prioritized task list.
+
+## Usage
+```
+/df:plan
+```
+
+## Skills & Agents
+- Skill: `code-completeness` — Find TODOs, stubs, incomplete work
+- Agent: `reasoner` (Opus) — Complex analysis and prioritization
+
+## Behavior
+
+### 1. LOAD CONTEXT
+
+```
+Load:
+- specs/*.md (all spec files)
+- PLAN.md (if exists, prior state)
+- .specflow/config.yaml (if exists)
+
+Determine source_dir from config or default to src/
+```
+
+### 2. ANALYZE CODEBASE
+
+**Spawn Explore agents** (haiku, read-only) with dynamic count:
+
+| File Count | Agents |
+|------------|--------|
+| <20 | 3-5 |
+| 20-100 | 10-15 |
+| 100-500 | 25-40 |
+| 500+ | 50-100 (cap) |
+
+**Use `code-completeness` skill patterns** to search for:
+- Implementations matching spec requirements
+- TODO, FIXME, HACK comments
+- Stub functions, placeholder returns
+- Skipped tests, incomplete coverage
+
+### 3. COMPARE & PRIORITIZE
+
+**Spawn `reasoner` agent** (Opus) for complex analysis:
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| DONE | Fully implemented | Mark complete |
+| PARTIAL | Stub or incomplete | Task to complete |
+| MISSING | Not found in code | Task to implement |
+| CONFLICT | Code contradicts spec | Flag for review |
+
+Reasoner prioritizes by dependencies, impact, and risk.
+
+### 4. PRIORITIZE
+
+Order tasks by:
+1. **Dependencies** — Blockers first
+2. **Impact** — Core features before enhancements
+3. **Risk** — Unknowns early (reduce risk)
+
+### 5. OUTPUT PLAN.md
+
+```markdown
+# Plan
+
+Generated: {timestamp}
+Specs analyzed: {count}
+
+## Spec Gaps
+[If any specs need updates, list here]
+- [ ] specs/X.md: Missing error handling definition
+
+## Tasks
+
+### {spec-name}
+
+- [ ] **T1**: {task description}
+  - Files: {files to create/modify}
+  - Blocked by: none
+
+- [ ] **T2**: {task description}
+  - Files: {files}
+  - Blocked by: T1
+
+### {another-spec}
+
+- [ ] **T3**: {task description}
+  - Files: {files}
+  - Blocked by: none
+```
+
+### 6. REPORT
+
+```
+✓ Plan generated
+
+Specs analyzed: {n}
+Tasks created: {n}
+Spec gaps found: {n}
+
+Ready to execute: {n} tasks (no blockers)
+
+Next: Run /df:execute to start implementation
+```
+
+## Rules
+- **Plan only** — Do NOT implement anything
+- **Confirm before assume** — Search code before marking "missing"
+- **One task = one logical unit** — Atomic, committable
+- Prefer existing utilities over new code
+- Flag spec gaps, don't silently ignore
+
+## Agent Spawning Rules
+
+```yaml
+search_agents:
+  base: 10
+  per_files: 20  # 1 agent per 20 files
+  cap: 100
+
+analyze_agents:
+  base: 5
+  per_specs: 2   # 1 agent per 2 specs
+  cap: 20
+
+model_selection:
+  search: sonnet
+  analyze: opus
+```
+
+## Example Output
+
+```markdown
+# Plan
+
+Generated: 2025-01-28 14:30
+Specs analyzed: 2
+
+## Spec Gaps
+- [ ] specs/image-upload.md: No error handling for S3 failures defined
+
+## Tasks
+
+### image-upload
+
+- [ ] **T1**: Create upload API endpoint
+  - Files: src/api/upload.ts (create)
+  - Blocked by: none
+
+- [ ] **T2**: Add file validation middleware
+  - Files: src/middleware/validate.ts (create)
+  - Blocked by: none
+
+- [ ] **T3**: Implement S3 upload service
+  - Files: src/services/storage.ts (create)
+  - Blocked by: T1
+
+- [ ] **T4**: Complete thumbnail generation
+  - Files: src/services/image.ts:45 (stub found)
+  - Blocked by: T3
+
+### color-extraction
+
+- [ ] **T5**: Integrate color-thief library
+  - Files: src/services/color.ts (create)
+  - Blocked by: T1
+```

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

@@ -0,0 +1,99 @@
+# /df:spec — Generate Spec from Conversation
+
+## Purpose
+Transform conversation context into a structured specification file.
+
+## Usage
+```
+/df:spec <name>
+```
+
+## Skills
+Uses: `gap-discovery` — Proactive requirement gap identification
+
+## Behavior
+
+### 1. GAP CHECK
+Before generating, use the `gap-discovery` skill to analyze conversation.
+
+**Required clarity:**
+- [ ] Core objective clear
+- [ ] Scope boundaries defined (what's in/out)
+- [ ] Key constraints identified
+- [ ] Success criteria stated
+
+**If gaps exist**, ask targeted questions (see skill for categories).
+
+Max 5 questions per round. Wait for answers before proceeding.
+
+### 2. GENERATE SPEC
+
+Once gaps covered, create `specs/{name}.md`:
+
+```markdown
+# {Name}
+
+## Objective
+[One sentence: what this achieves for the user]
+
+## Requirements
+- REQ-1: [Requirement]
+- REQ-2: [Requirement]
+- REQ-3: [Requirement]
+
+## Constraints
+- [Constraint 1]
+- [Constraint 2]
+
+## Out of Scope
+- [Explicitly excluded item]
+
+## Acceptance Criteria
+- [ ] [Testable criterion 1]
+- [ ] [Testable criterion 2]
+- [ ] [Testable criterion 3]
+
+## Technical Notes
+[Any implementation hints, preferred approaches, or context]
+```
+
+### 3. CONFIRM
+
+After writing:
+```
+✓ Created specs/{name}.md
+
+Requirements: {count}
+Acceptance criteria: {count}
+
+Next: Run /df:plan to generate tasks
+```
+
+## Rules
+- Do NOT generate spec if critical gaps remain
+- Ask maximum 5 questions per round (not overwhelming)
+- Requirements must be testable
+- Acceptance criteria must be verifiable
+- Keep specs concise (<100 lines)
+
+## Example
+
+```
+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: ✓ Created specs/image-upload.md
+
+Requirements: 4
+Acceptance criteria: 5
+
+Next: Run /df:plan to generate tasks
+```

package/.claude/commands/df/verify.md

@@ -0,0 +1,169 @@
+# /df:verify — Verify Specs Satisfied
+
+## Purpose
+Check that implemented code satisfies spec requirements and acceptance criteria.
+
+## Usage
+```
+/df:verify
+/df:verify image-upload    # Verify specific spec only
+```
+
+## Skills & Agents
+- Skill: `code-completeness` — Find incomplete implementations
+- Agent: `Explore` (Haiku) — Fast codebase scanning
+
+## Behavior
+
+### 1. LOAD CONTEXT
+
+```
+Load:
+- specs/*.md (requirements to verify)
+- PLAN.md (task completion status)
+- Source code (actual implementation)
+```
+
+### 2. VERIFY EACH SPEC
+
+For each spec file, check:
+
+#### Requirements Coverage
+```
+For each REQ-N in spec:
+  - Find implementation in code
+  - Verify it meets the requirement
+  - Mark: ✓ satisfied | ✗ missing | ⚠ partial
+```
+
+#### Acceptance Criteria
+```
+For each criterion:
+  - Can it be verified? (testable)
+  - Is there evidence it passes?
+  - Mark: ✓ | ✗ | ⚠
+```
+
+#### Implementation Quality
+
+Use `code-completeness` skill patterns to check for:
+- Stub functions (not fully implemented)
+- TODO/FIXME comments (incomplete work)
+- Placeholder returns (fake implementations)
+- Skipped tests (untested code)
+
+### 3. GENERATE REPORT
+
+**If all pass:**
+```
+✓ Verification complete
+
+specs/image-upload.md
+  Requirements: 4/4 ✓
+  Acceptance criteria: 5/5 ✓
+  Quality: No stubs or TODOs
+
+specs/color-extraction.md
+  Requirements: 2/2 ✓
+  Acceptance criteria: 3/3 ✓
+  Quality: No stubs or TODOs
+
+All specs satisfied.
+```
+
+**If issues found:**
+```
+⚠ Verification found issues
+
+specs/image-upload.md
+  Requirements: 3/4
+    ✗ REQ-4: Error handling for S3 failures
+      Expected: Graceful error with retry option
+      Found: No error handling in src/services/storage.ts
+
+  Acceptance criteria: 4/5
+    ⚠ "Upload shows progress bar"
+      Found: Progress callback exists but UI not connected
+
+  Quality:
+    ⚠ src/services/image.ts:67 — TODO: optimize for large files
+
+Action needed:
+  1. Add S3 error handling (REQ-4)
+  2. Connect progress UI
+  3. Complete TODO in image.ts
+
+Run /df:plan to generate fix tasks, or fix manually.
+```
+
+### 4. UPDATE STATE
+
+Write findings to STATE.md:
+```markdown
+## Verification Log
+
+### 2025-01-28 15:30
+Verified: image-upload, color-extraction
+Result: 1 spec gap, 2 quality issues
+Action: Generated fix tasks
+```
+
+## Verification Levels
+
+| Level | Check | Method |
+|-------|-------|--------|
+| L1: Exists | File/function exists | Glob/Grep |
+| L2: Substantive | Real code, not stub | Read + analyze |
+| L3: Wired | Integrated into system | Trace imports/calls |
+| L4: Tested | Has passing tests | Run tests |
+
+Default: L1-L3 (L4 optional, can be slow)
+
+## Rules
+- Verify against spec, not assumptions
+- Flag partial implementations
+- Report TODO/FIXME as quality issues
+- Don't auto-fix — report findings for `/df:plan`
+
+## Agent Usage
+
+Spawn `Explore` agents (Haiku) for fast read-only scanning:
+- 1-2 agents per spec (based on spec size)
+- Cap: 10 parallel agents
+- Read-only: safe to parallelize heavily
+
+## Example
+
+```
+/df:verify
+
+Verifying 2 specs...
+
+specs/image-upload.md
+  ├─ REQ-1: Upload endpoint ✓
+  │    src/api/upload.ts exports POST /api/upload
+  ├─ REQ-2: File validation ✓
+  │    src/middleware/validate.ts checks type, size
+  ├─ REQ-3: S3 storage ✓
+  │    src/services/storage.ts implements uploadToS3()
+  └─ REQ-4: Thumbnails ✓
+       src/services/image.ts implements generateThumbnail()
+
+  Acceptance: 5/5 ✓
+  Quality: Clean
+
+specs/color-extraction.md
+  ├─ REQ-1: Extract colors ✓
+  └─ REQ-2: Palette display ⚠
+       Found: Component exists but not exported
+
+  Acceptance: 2/3
+  Quality: 1 TODO found
+
+Summary:
+  Specs: 2
+  Passed: 1
+  Issues: 1
+
+Run /df:plan to generate fix tasks.
+```