codecruise 0.1.0

package/config/commands/doctor.md

@@ -0,0 +1,227 @@
+---
+name: doctor
+description: Validate project setup and diagnose issues with actionable fixes
+model: haiku
+tools: Read, Bash, Glob, Grep
+---
+
+# /doctor — Project Health Check
+
+Diagnose codecruise setup and provide actionable fixes.
+
+## Usage
+
+```bash
+/doctor                      # Full health check
+/doctor --fix                # Auto-fix where possible
+/doctor --validate           # Include plan consistency checks
+/doctor --validate-schema    # Schema validation only
+/doctor --validate-plan      # Plan consistency only
+/doctor --validate-steering  # Steering docs validation only
+/doctor --json               # Machine-readable output
+```
+
+## Check Categories
+
+### 1. Project Setup
+
+| Check | Pass | Fail |
+|-------|------|------|
+| CLAUDE.md exists | File in root | Missing |
+| .claude/settings.json | File present | Missing (auto-create) |
+| .codecruise/ directory | Exists | Missing (auto-create) |
+| .codecruise/progress.yaml | File present | Missing |
+| .codecruise/roadmap/ | Has .yaml files | Empty or missing |
+
+### 2. Schema Validation
+
+| Check | Pass | Fail |
+|-------|------|------|
+| .codecruise/progress.yaml schema | Valid v2 | Invalid or v1 (warn) |
+| .codecruise/roadmap/*.yaml schema | Valid | Missing required fields |
+| TODO ID pattern | `todo-N.Na-NNN` | Invalid format |
+| Feature ID pattern | `feature-N.N` | Invalid format |
+
+### 3. Hook Installation
+
+| Check | Pass | Fail |
+|-------|------|------|
+| settings.json exists | Present | Missing |
+| Referenced hooks exist | All found | Missing files |
+| Hooks executable | chmod +x | Not executable |
+| Required hooks enabled | enforce-tdd, verify-todo-completion | Disabled |
+
+### 4. Git State
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Is git repo | .git exists | — | Not a repo |
+| Uncommitted changes | Clean | Modified files | — |
+| On expected branch | Matches TODO scope | Different branch | — |
+| Remote configured | origin exists | — | No remote |
+
+### 5. Quality Command Speed
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| quality_command defined | In CLAUDE.md | — | Missing |
+| Execution time | < 10s | 10-30s | > 30s |
+| Tools installed | All pass | — | Missing deps |
+
+### 6. Steering Docs (--validate-steering)
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| CLAUDE.md exists | In root | — | Missing |
+| CLAUDE.md size | < 150 lines | 150-300 lines | > 300 lines |
+| .codecruise/steering/ | Directory exists | — | Missing |
+| product.md exists | In .codecruise/steering/ | — | Missing |
+| tech.md exists | In .codecruise/steering/ | — | Missing |
+| structure.md exists | In .codecruise/steering/ | — | Missing |
+| Docs freshness | < 30 days | 30-90 days | > 90 days |
+| Quality command works | Passes | — | Fails |
+| Required sections | All present | Some missing | Critical missing |
+
+### 7. Plan Consistency (--validate)
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Orphan TODOs | None | — | In queue, not in roadmap |
+| Missing TODOs | None | New in roadmap | — |
+| depends_on refs | All valid | — | Invalid TODO ID |
+| Circular deps | None | — | Cycle detected |
+| Stale state | Active | Paused > 24h | Paused > 7d |
+
+## Output Format
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                     DOCTOR DIAGNOSIS                           ║
+╠═══════════════════════════════════════════════════════════════╣
+║ ✓ Project Setup                                     [PASS]    ║
+║ ⚠ Schema Validation                                [WARN]    ║
+║   └─ .codecruise/progress.yaml: schema_version missing (v1 format)        ║
+║ ✓ Hook Installation                                 [PASS]    ║
+║ ✗ Git State                                         [FAIL]    ║
+║   └─ 3 uncommitted changes                                    ║
+║ ⚠ Quality Command Speed                            [WARN]    ║
+║   └─ 18s execution — consider Biome instead of ESLint         ║
+║ ✓ Plan Consistency                                  [PASS]    ║
+╠═══════════════════════════════════════════════════════════════╣
+║ Summary: 3 PASS | 2 WARN | 1 FAIL                             ║
+╚═══════════════════════════════════════════════════════════════╝
+
+Fixes:
+1. Run: git add . && git commit -m "wip"
+2. Run: /init --upgrade-schema (migrate to v2)
+3. Consider: npm install -D @biomejs/biome
+```
+
+## Auto-Fix Actions (--fix)
+
+| Issue | Auto-Fix Action |
+|-------|-----------------|
+| Missing .codecruise/ | Create directory |
+| Missing settings.json | Copy from template |
+| Non-executable hooks | `chmod +x` |
+| Orphaned queue entries | Remove from queue |
+| Unknown schema fields | Remove (with backup) |
+| Stale pause state | Clear paused_at |
+
+**Cannot auto-fix**:
+- Uncommitted git changes (user must decide)
+- Circular dependencies (requires manual refactor)
+- Missing quality_command (user must define)
+
+## Process
+
+1. **Detect**: Scan project for codecruise files
+2. **Check**: Run all applicable checks
+3. **Report**: Display results with severity
+4. **Suggest**: Provide actionable fix commands
+5. **Fix** (if --fix): Apply auto-fixes, report changes
+
+## Validation Details (--validate)
+
+### Orphan TODO Detection
+
+TODOs in `.codecruise/progress.yaml` queue but not in `.codecruise/roadmap/*.yaml`:
+
+```yaml
+# .codecruise/progress.yaml
+queue:
+  completed: [todo-1.1a-001, todo-1.1a-099]  # 099 is orphan
+
+# roadmap/phase-01.yaml
+# Only has todo-1.1a-001, todo-1.1a-002, etc.
+```
+
+**Fix**: Remove from queue or add to roadmap.
+
+### Circular Dependency Detection
+
+```yaml
+# roadmap/phase-01.yaml
+- id: todo-1.1a-001
+  depends_on: [todo-1.1a-002]  # A depends on B
+- id: todo-1.1a-002
+  depends_on: [todo-1.1a-001]  # B depends on A — CYCLE!
+```
+
+**Fix**: Manual refactor required.
+
+### Stale State Detection
+
+| Condition | Severity | Suggestion |
+|-----------|----------|------------|
+| Paused < 24h | OK | — |
+| Paused 1-7 days | Warn | "Consider resuming or resetting" |
+| Paused > 7 days | Fail | "Stale state, run /init --reset" |
+| Orphaned blockers | Warn | "Blocker resolved but still listed" |
+
+## JSON Output (--json)
+
+```json
+{
+  "timestamp": "2026-02-20T14:30:00Z",
+  "summary": {
+    "pass": 4,
+    "warn": 2,
+    "fail": 1
+  },
+  "checks": {
+    "project_setup": { "status": "pass", "details": [] },
+    "schema_validation": {
+      "status": "warn",
+      "details": [
+        { "file": ".codecruise/progress.yaml", "issue": "schema_version missing" }
+      ]
+    },
+    "git_state": {
+      "status": "fail",
+      "details": [
+        { "issue": "uncommitted_changes", "count": 3 }
+      ]
+    }
+  },
+  "fixes": [
+    { "action": "git commit", "auto": false },
+    { "action": "upgrade-schema", "auto": true }
+  ]
+}
+```
+
+## Integration
+
+| Command | Relationship |
+|---------|--------------|
+| `/init` | Use `/doctor` after init to verify setup |
+| `/run` | Run `/doctor` if experiencing failures |
+| `/status` | `/doctor` provides deeper diagnostics |
+
+## Quality Bar
+
+- All checks complete in < 5 seconds (excluding quality_command timing)
+- Clear, actionable output
+- No false positives (only report real issues)
+- Exit code: 0 (all pass), 1 (has warnings), 2 (has failures)

package/config/commands/dogfood-report.md

@@ -0,0 +1,101 @@
+---
+name: dogfood-report
+description: Generate analysis report answering Boris & Peter's questions about codecruise effectiveness
+model: sonnet
+tools: Read, Bash, Glob
+---
+
+# /dogfood-report — Analyze Codecruise Effectiveness
+
+Generate a report that answers the critical questions from the Boris/Peter analysis:
+
+1. **Agent Usage**: Which of the 12 agents actually get used? What's the 80/20?
+2. **Enforcement Effectiveness**: How many TDD violations blocked? Rationalizations caught? False dones prevented?
+3. **OODA Reality**: Is confidence calculation meaningful? Does ORIENT actually inform decisions?
+4. **Command Usage**: Which of the 34 commands are actually used?
+5. **Overall**: Is the complexity justified by the value?
+
+## Data Sources
+
+Read from `.codecruise/metrics/`:
+- `enforcement.jsonl` — Hook blocks and warnings
+- `agents.jsonl` — Agent delegations
+- `commands.jsonl` — Command invocations
+- `ooda.jsonl` — OODA phase tracking
+- `events.jsonl` — General activity (tests, commits, etc.)
+
+## Report Structure
+
+```markdown
+# Codecruise Dogfood Report
+Generated: {date}
+Projects analyzed: {list}
+Time period: {start} to {end}
+
+## Executive Summary
+{2-3 sentence verdict on whether complexity is justified}
+
+## 1. Agent Usage (Boris Q1)
+Total delegations: N
+By agent:
+  - developer: X (Y%)
+  - tester: X (Y%)
+  - ...
+80/20: {which 2-3 agents do 80% of work}
+Unused agents: {list}
+Verdict: {keep all 12 / trim to N}
+
+## 2. Enforcement Effectiveness (Peter Q1)
+TDD violations blocked: N
+  - Files that would have been written without tests
+Rationalizations caught: N
+  - Patterns: "good enough", "out of scope", etc.
+Quality gate blocks: N
+  - TODOs that tried to mark done with failing tests
+State machine blocks: N
+  - Invalid state transitions prevented
+Value: {high/medium/low} — {explanation}
+
+## 3. OODA Reality (Boris Q2, Peter Q2)
+ORIENT phases logged: N
+Confidence calculated: N times
+  - High: X, Medium: Y, Low: Z
+Decisions influenced by confidence:
+  - Executes at high confidence: X
+  - Asks at medium confidence: Y
+  - Skips/replans at low confidence: Z
+Verdict: {OODA is load-bearing / OODA is theater}
+
+## 4. Command Usage (Boris Q2)
+Total command invocations: N
+By command:
+  - /run: X
+  - /status: X
+  - ...
+80/20: {which 5 commands do 80% of work}
+Unused commands: {list}
+Verdict: {keep all 34 / trim to N}
+
+## 5. Overall Verdict
+
+Complexity justified: {yes/no/partially}
+
+Evidence:
+- {point 1}
+- {point 2}
+- {point 3}
+
+Recommendations:
+- {rec 1}
+- {rec 2}
+```
+
+## Execution
+
+1. Find all `.codecruise/metrics/` directories across projects
+2. Aggregate all JSONL files
+3. Calculate statistics
+4. Generate the report
+5. Save to `docs/DOGFOOD-REPORT.md`
+
+If no data exists yet, output instructions on what to do first.

package/config/commands/flags/run-autonomous.md

@@ -0,0 +1,110 @@
+# /run --autonomous — Autonomous Mode Details
+
+Load this content when `--autonomous` flag is detected.
+
+## Autonomous Behavior
+
+| Aspect | Interactive | Autonomous |
+|--------|-------------|------------|
+| Low confidence | Asks user | Auto-skip, log blocker |
+| Replan trigger | Asks user | Log, continue unblocked |
+| Checkpoints | Pauses | Logs only |
+| Blockers | Waits | Notifies, skips dependents |
+
+## Required Options
+
+```bash
+/run --autonomous --max-turns 100
+```
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `--max-turns` | Yes | 100 | Safety limit for API calls |
+| `--notify` | No | none | Notification channel (slack, webhook) |
+| `--on-limit` | No | pause | What happens at max-turns (pause, abort) |
+
+## OODA in Autonomous Mode
+
+### OBSERVE
+- Same environment sensing
+- Logs findings to activity.log
+
+### ORIENT
+- Same confidence calculation
+- Logs confidence and patterns
+
+### DECIDE
+- Low confidence → auto-skip (not ask)
+- Blockers → notify, skip dependents
+- Replan needed → log, skip module
+
+### ACT
+- Same TDD cycle
+- Failures → auto-retry up to limit
+- Success → commit, continue
+
+## Blocker Handling
+
+```yaml
+execution_state:
+  blockers:
+    - todo: todo-1.2a-005
+      reason: "Redis not running"
+      pattern: external_dep_down
+      notified: true
+      resolved: false
+```
+
+When blocker detected:
+1. Mark TODO as blocked
+2. Skip dependents (mark blocked_by)
+3. Send notification (if configured)
+4. Continue with unblocked TODOs
+
+## Notification Format
+
+```json
+{
+  "event": "blocker_detected",
+  "todo": "todo-1.2a-005",
+  "reason": "Redis not running",
+  "affected": ["todo-1.2a-006", "todo-1.2a-007"],
+  "action": "skipped_dependents",
+  "resume": "resolve blocker, run /retry --all-blocked"
+}
+```
+
+## Output (activity.log)
+
+```
+[2026-02-20 10:30:15] ━━━ AUTONOMOUS SESSION ━━━
+[2026-02-20 10:30:16] 👁 OBSERVE todo-1.1b-004
+[2026-02-20 10:30:18] 🧭 ORIENT confidence=0.85
+[2026-02-20 10:30:19] ⚡ DECIDE execute
+[2026-02-20 10:33:50] ✓ COMPLETE todo-1.1b-004
+[2026-02-20 10:35:20] 🔴 BLOCKER external_dep_down
+[2026-02-20 10:35:21]    └─ Redis not running, skipping 2 dependents
+[2026-02-20 10:35:22] ⏭ SKIP todo-1.1b-005 (blocked)
+[2026-02-20 11:45:00] ━━━ MAX TURNS REACHED (100) ━━━
+```
+
+## Session End Report
+
+```
+═══════════════════════════════════════════════════════════
+AUTONOMOUS SESSION COMPLETE
+
+  Duration: 1h 15m
+  Turns: 100 (limit reached)
+
+  Results:
+    ✓ Completed: 12 TODOs
+    ⏭ Skipped: 3 (blocked)
+    ✗ Failed: 1
+
+  Blockers (need attention):
+    - Redis not running (affects 2 TODOs)
+
+  Next: /retry --all-blocked after resolving blockers
+═══════════════════════════════════════════════════════════
+```

package/config/commands/flags/run-pause.md

@@ -0,0 +1,80 @@
+# /run Pause/Resume Integration
+
+Load this content when pause/resume behavior details are needed.
+
+## Pause Points in OODA
+
+```
+OBSERVE → ORIENT → DECIDE → ACT
+                              ↓
+                         checkpoint
+                              ↓
+                    ⏸ pause possible
+```
+
+Pause occurs at **checkpoints** (configurable):
+
+| Checkpoint | When | Frequency |
+|------------|------|-----------|
+| `subfeature` | After each subfeature completes | Default |
+| `feature` | After each feature completes | Less frequent |
+| `none` | Only on explicit /pause | Continuous |
+
+## State Preservation
+
+When paused, all OODA state is preserved:
+
+```yaml
+execution_state:
+  status: paused
+  paused_at: 2026-02-20T12:30:00Z
+  pause_phase: act  # Where in OODA we paused
+
+  ooda:
+    confidence: 0.75
+    last_observation: 2026-02-20T12:29:00Z
+    patterns_detected: []
+    consecutive_failures: 0
+
+  current_todo: todo-1.1b-004
+```
+
+## Resume Behavior
+
+Resume always enters at **OBSERVE**, not where we left off:
+
+```
+/resume
+    ↓
+OBSERVE (fresh sensing)
+    ↓
+ORIENT (recalculate confidence)
+    ↓
+DECIDE → ACT → loop
+```
+
+Why? Environment may have changed during pause.
+
+## Drift Detection
+
+If paused > 1 hour:
+
+1. Check git status (new commits?)
+2. Check dependencies (versions changed?)
+3. Check spec (requirements changed?)
+
+If drift detected, user chooses:
+- Continue with fresh OBSERVE
+- Re-plan affected section
+- Abort for manual review
+
+## Interrupted Sessions
+
+If session ended without clean pause (crash, ctrl-c):
+
+1. Detect `status: running` but no active session
+2. Treat as dirty pause
+3. Offer recovery options:
+   - Continue (assess partial work)
+   - Restart TODO
+   - Skip and continue

package/config/commands/ingest.md

@@ -0,0 +1,173 @@
+---
+name: ingest
+description: Process documents, free text, or mixed sources into structured summaries
+disable-model-invocation: true
+tools: Read, Write, Bash, Glob, Grep, Task
+model: sonnet
+---
+
+# /ingest — Multi-Source Document Processor
+
+Process files, free text, or mixed sources into structured summaries.
+
+## Usage
+
+```
+/ingest .codecruise/inventory                    # Files only
+/ingest "User requirements go here..."    # Free text only
+/ingest "context" .codecruise/inventory/         # Mixed: text + files
+/ingest --detail .codecruise/inventory           # Deep extraction (recommended)
+/ingest --dry-run .codecruise/inventory          # Preview
+```
+
+## Input Types
+
+| Input | Example | Stored As |
+|-------|---------|-----------|
+| **Directory** | `.codecruise/inventory/` | Process files in place |
+| **Free text** | `"Users need to reset passwords..."` | `.codecruise/inventory/user-input-{timestamp}.md` |
+| **Mixed** | `"context" .codecruise/inventory/` | Text saved, then all processed together |
+| **Stdin** | `pbpaste \| /ingest --stdin` | `.codecruise/inventory/stdin-{timestamp}.md` |
+
+## Free Text Guidelines
+
+Good free text input:
+```
+/ingest "Users should reset passwords via email. Link expires in 1 hour.
+PM said 3 attempts/day is too restrictive - make it 5.
+Mobile app is out of scope for v1.
+We discussed Redis for sessions but final decision pending."
+```
+
+The system will:
+1. Save to `.codecruise/inventory/user-input-{timestamp}.md`
+2. Extract requirements, decisions, open questions
+3. Attribute as `source: user-input-{timestamp}.md`
+4. Process alongside any file sources
+
+## Detail Levels
+
+| Mode | Extracts | Cost | Use When |
+|------|----------|------|----------|
+| Standard | Features, requirements | $0.005/file | Quick overview |
+| **Detailed** | Everything + edge cases, flows, examples | $0.008/file | **Production** |
+
+Always use `--detail` for production specs.
+
+## Outputs
+
+```
+.codecruise/inventory/
+├── user-input-{timestamp}.md    # Saved free text (if provided)
+├── stdin-{timestamp}.md         # Saved stdin (if --stdin)
+
+.codecruise/ingested/
+├── summaries/        # Individual file analyses
+├── extracted/        # Raw text from PDFs
+├── combined.md       # Final combined output
+└── source-map.yaml   # Feature-to-source index
+```
+
+## Process
+
+1. **Capture Free Text**: If text provided, save to `.codecruise/inventory/user-input-{timestamp}.md`
+2. **Discover**: Find .md, .txt, .pdf files (including newly saved text)
+3. **Extract PDFs**: pdftotext or fallbacks
+4. **Analyze Parallel**: Task agents with Haiku (batches of 5)
+5. **Combine**: Merge all summaries
+6. **Source Map**: Build feature → source index (includes user-input sources)
+
+## Stop Conditions
+
+| Condition | Action |
+|-----------|--------|
+| > 100 files | Ask confirmation |
+| > 50MB | Ask confirmation |
+| Cost > $5 | Ask confirmation |
+
+## Source Map (Detailed Mode)
+
+```yaml
+features:
+  auth:
+    sources:
+      - file: "Auth Guide.pdf"
+        pages: [2, 5-7]
+        key_points: ["Session timeout: 1hr"]
+    decisions: ["httpOnly cookies"]
+    open_questions: ["MFA for v1?"]
+
+architecture:
+  patterns:
+    - pattern: "JWT + Refresh"
+      sources: [{file, pages}]
+      rationale: "Stateless auth"
+  tech_choices:
+    - decision: "PostgreSQL"
+      rationale: "ACID compliance"
+
+discussions:
+  - file: "Discussion 2.pdf"
+    topics: [rate-limiting, budget]
+    conclusions: ["Sliding window rate limits"]
+```
+
+## Standard vs Detailed
+
+| Without --detail | With --detail |
+|------------------|---------------|
+| "Rate limiting required" | "100 req/min free, 1000 premium, sliding window" |
+| "User can create groups" | "Groups: max 200 members, 3 admin limit" |
+| "Handle errors" | "On OCR fail: retry 3x, fallback to manual" |
+
+## Output
+
+```
+✓ Ingestion Complete (DETAILED)
+
+Sources:
+  - Files: 50 (25 PDF, 15 txt, 10 md)
+  - Free text: 1 (saved as user-input-20260220-143052.md)
+  - Content: ~150,000 lines
+
+Extracted:
+  - Features: 127
+  - Thresholds: 45
+  - Edge cases: 38
+  - User flows: 22
+
+Source Map:
+  - Features: 12
+  - Decisions: 19
+  - Architecture patterns: 5
+
+Next: /spec-forge .codecruise/ingested/combined.md
+```
+
+## Free Text Examples
+
+**Quick requirements dump:**
+```
+/ingest "Login with email/password. OAuth later. Session timeout 1hr.
+Password reset via email, link expires 1hr. Max 5 reset attempts/day."
+```
+
+**Meeting notes:**
+```
+/ingest "Meeting with PM 2026-02-20:
+- Decided against SMS auth for v1 (cost)
+- Redis for sessions confirmed
+- Open question: rate limit numbers
+- Mobile app pushed to v2"
+```
+
+**Mixed sources:**
+```
+/ingest "Additional context from call: auth must support SSO for enterprise" .codecruise/inventory/
+```
+
+## Error Handling
+
+- PDF extraction fail → try alternatives, log
+- File too large → chunk processing
+- Agent timeout → retry at end