codecruise 0.1.0

package/config/commands/architect.md

@@ -0,0 +1,118 @@
+---
+name: architect
+description: Generate comprehensive Engineering Design Documents from spec and context
+disable-model-invocation: true
+tools: Read, Write, Edit, Glob, Grep, Bash, Task
+model: opus
+---
+
+# /architect — EDD Generator
+
+Transform approved specs into architecture documents (WHAT → HOW).
+
+## When to Use
+
+| Situation | Use /architect? |
+|-----------|-----------------|
+| After spec-review, before planning | ✅ Yes |
+| New major feature needs design | ✅ Yes |
+| Database schema or API contracts needed | ✅ Yes |
+| Quick architecture question | ❌ Use architect agent |
+| Spec not complete | ❌ Finish spec workflow first |
+
+## Usage
+
+```
+/architect                        # Full EDD from spec + context
+/architect "payment integration"  # Feature-specific EDD
+/architect --section database     # Generate specific section
+/architect --dry-run              # Preview without writing
+```
+
+| Argument | Description |
+|----------|-------------|
+| `--section` | Generate: `database`, `api`, `security`, `components` |
+| `--stack` | Tech stack preferences |
+| `--scale` | Scale hints: "10k users, 100 req/s" |
+| `--compliance` | Requirements: "GDPR, PCI-DSS" |
+
+## Inputs (read-only)
+
+**Required**: `docs/canon/spec.md`, `docs/context/architecture.yaml`
+
+**Optional**: `docs/context/*.yaml`, `docs/canon/issues.md`, `docs/canon/decisions.md`
+
+**Stop conditions**:
+- No spec.md → STOP, run `/spec-forge`
+- P0 blocking issues → WARN, list them
+
+## Outputs
+
+```
+docs/architecture/
+├── overview.md      # C4 diagrams, principles, tech stack, phases
+├── database.md      # ERD, Prisma schema, SQL, indexes
+├── api.md           # tRPC/REST routing, OpenAPI, error codes
+├── components.md    # Module structure, dependencies
+├── security.md      # Auth flow, tokens, encryption, RBAC
+├── data-flow.md     # Flow diagrams per feature
+├── integrations.md  # External services, webhooks
+├── decisions.md     # ADRs with rationale
+└── extensibility.md # Where future features plug in
+```
+
+## Process
+
+1. **Load Context**: Extract FRs, NFRs, entities, decisions from spec + context files
+2. **Overview**: C4 diagrams, design principles, tech stack with rationale, phases & features
+3. **Database**: Extract entities, relationships, generate Prisma + SQL, index strategy
+4. **API**: Map use cases to endpoints, tRPC vs REST routing rules, OpenAPI for REST
+5. **Components**: Module structure, dependency rules, layered access
+6. **Security**: Auth flow (sequence diagram), token strategy, encryption, RBAC
+7. **Data Flow**: Per-feature flow diagrams
+8. **Integrations**: External services with fallbacks
+9. **ADRs**: Decision + rationale + alternatives + consequences
+10. **Extensibility**: Where v2 features plug in
+
+## Output Structures
+
+**overview.md**: C4Context + C4Container diagrams, principles list, stack table, phases table
+
+**database.md**: ERD (Mermaid), Prisma schema, SQL DDL, index strategy table
+
+**api.md**: Routing strategy table, endpoint reference tables, OpenAPI YAML, error codes table
+
+**security.md**: Auth sequence diagram, token table, encryption table, RBAC model
+
+**decisions.md**: ADR format: Status, Context, Decision, Alternatives, Consequences
+
+## Final Report
+
+```
+✓ Architecture documentation complete
+
+Spec version: {from spec.md}
+Documents created: 9
+
+Coverage:
+  - Entities: {N}
+  - API endpoints: {N}
+  - ADRs: {N}
+
+Traceability:
+  - FR covered: {N}/{total}
+  - NFR covered: {N}/{total}
+
+Next:
+  /architect-review  → Validate architecture
+  /plan              → Create roadmap
+```
+
+## Quality Bar
+
+- All spec requirements traceable to architecture
+- No orphan components
+- Diagrams render (valid Mermaid)
+- Prisma schema valid
+- OpenAPI spec valid
+- ADRs have clear rationale

package/config/commands/compact.md

@@ -0,0 +1,118 @@
+---
+name: compact
+description: Compress context and prepare for session handoff
+disable-model-invocation: true
+tools: Bash, Read
+model: sonnet
+---
+
+# /compact Command
+
+Safely compress context while preserving state.
+
+## Read First
+
+1. `~/.claude/rules/hygiene.md`
+
+## Process
+
+### 1. Verify State Persistence
+
+Check that all work is persisted:
+
+- [ ] `progress.yaml` is up to date
+- [ ] Current TODO status reflects reality
+- [ ] All changes committed
+- [ ] No uncommitted work in progress
+
+If any check fails, complete it before compacting.
+
+### 2. Summarize Session
+
+Create session summary:
+
+```markdown
+## Session Summary
+
+### Completed
+- {todo_id}: {description}
+- {todo_id}: {description}
+
+### In Progress
+- {todo_id}: {description} - {current state}
+
+### Blocked
+- {todo_id}: {reason}
+
+### Decisions Made
+- {decision 1}
+- {decision 2}
+
+### Notes for Next Session
+- {important context}
+- {gotcha discovered}
+```
+
+### 3. Report Status
+
+```
+✓ Ready for compact
+
+State persisted:
+- progress.yaml ✓
+- Commits: 3 new ✓
+- Branch: feature/auth-login
+
+Session summary:
+- Completed: 2 TODOs
+- In progress: 1 TODO
+- Next: {todo_id} - {description}
+
+Safe to compact. Context will be cleared.
+```
+
+### 4. Handoff Notes
+
+Include in summary any context the next session needs:
+
+- Unusual patterns discovered
+- Workarounds implemented
+- Open questions
+- Suggested approach for next TODO
+
+## When to Compact
+
+Suggest compacting when:
+- TODO completed
+- 15+ exchanges in conversation
+- Switching to different feature
+- Context feels "fuzzy" or responses degrade
+- Before taking a break
+
+## Safety Checks
+
+Before allowing compact:
+
+1. **Uncommitted changes?**
+   ```
+   ⚠️ You have uncommitted changes:
+   - src/auth/login.ts
+   
+   Commit these before compacting?
+   ```
+
+2. **TODO in progress?**
+   ```
+   ⚠️ TODO-003 is in progress.
+   
+   Options:
+   1. Complete it first
+   2. Save state and continue later
+   ```
+
+3. **State not synced?**
+   ```
+   ⚠️ progress.yaml shows TODO-002 but roadmap shows TODO-003.
+   
+   Sync state before compacting.
+   ```

package/config/commands/companion.md

@@ -0,0 +1,279 @@
+---
+name: companion
+description: Pattern detection engine integrated with OODA loop and standalone advisor mode
+model: sonnet
+tools: Read, Glob, Grep
+---
+
+# /companion — OODA Pattern Engine
+
+Real-time pattern detection for ORIENT phase + standalone advisor mode.
+
+## Dual Role
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  COMPANION                                              │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  1. IN-LOOP (called by /run ORIENT phase)              │
+│     → Real-time pattern detection                       │
+│     → Confidence adjustment                             │
+│     → Routing recommendations                           │
+│                                                         │
+│  2. STANDALONE (/companion command)                     │
+│     → Session analysis                                  │
+│     → Actionable insights                               │
+│     → Skill effectiveness review                        │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+## In-Loop Mode (ORIENT Integration)
+
+Called automatically during `/run` ORIENT phase.
+
+### Input (from OBSERVE)
+
+```yaml
+observation:
+  todo_id: todo-1.2a-004
+  module: auth
+  retry_count: 2
+  last_error: "JWT validation failed"
+  last_3_todos:
+    - id: todo-1.2a-003
+      status: failed
+      retries: 3
+      error_type: auth_error
+    - id: todo-1.2a-002
+      status: done
+      retries: 1
+    - id: todo-1.2a-001
+      status: done
+      retries: 0
+  context_exchanges: 12
+  external_deps:
+    docker: up
+    redis: down
+```
+
+### Output (to ORIENT)
+
+```yaml
+orientation:
+  confidence: low  # high | medium | low
+
+  patterns:
+    - id: retry_spike
+      severity: warning
+      message: "3 retries in last 3 TODOs"
+
+    - id: module_failing
+      severity: critical
+      message: "auth module: 2/3 failed"
+      recommendation: replan
+
+    - id: external_dep_down
+      severity: blocker
+      message: "Redis unavailable"
+      affected_todos: [todo-1.2a-004, todo-1.2a-005]
+
+  confidence_factors:
+    base: 0.8
+    retry_penalty: -0.2      # high retries recently
+    module_penalty: -0.3     # module failing
+    dep_penalty: -0.2        # external dep down
+    final: 0.1               # low confidence
+
+  recommendation: escalate   # proceed | proceed_cautious | replan | escalate | skip
+```
+
+### Pattern Detection Rules
+
+| Pattern | Detection | Confidence Impact | Recommendation |
+|---------|-----------|-------------------|----------------|
+| `retry_spike` | 3+ retries in last 5 TODOs | -0.1 per retry above 2 | proceed_cautious |
+| `error_cluster` | Same error type 3+ times | -0.2 | replan |
+| `module_failing` | 3+ failures in module | -0.3 | replan |
+| `external_dep_down` | Connection/timeout errors | -0.3 | skip dependents |
+| `context_bloat` | 20+ exchanges | -0.1 | suggest /compact |
+| `skill_mismatch` | No skill for TODO type | -0.1 | proceed_cautious |
+
+### Confidence Calculation
+
+```
+confidence = base(0.8)
+           - retry_penalty
+           - module_penalty
+           - dep_penalty
+           - skill_penalty
+
+high:   confidence >= 0.7
+medium: confidence >= 0.4
+low:    confidence < 0.4
+```
+
+### Routing Logic
+
+```yaml
+routing:
+  high_confidence:
+    ship-fast: proceed
+    balanced: proceed
+    careful: proceed
+
+  medium_confidence:
+    ship-fast: proceed
+    balanced: proceed_cautious
+    careful: escalate
+
+  low_confidence:
+    ship-fast: skip
+    balanced: escalate
+    careful: replan
+
+  blocker_detected:
+    all_tempos: skip_dependents + notify
+```
+
+## Standalone Mode
+
+```bash
+/companion                    # Current insights
+/companion --detailed         # With evidence
+/companion --skills           # Skill effectiveness
+/companion --history          # Insight history
+```
+
+### Data Sources
+
+```
+.codecruise/
+├─ execution_history.yaml     # Session history
+├─ scorecards/                # TODO results
+└─ insights.yaml              # Persisted insights
+
+.codecruise/progress.yaml                 # Current OODA state
+```
+
+### Insight Categories
+
+**🔴 BLOCKER** — Fix now
+```
+🔴 BLOCKER: Redis not running
+   Last 2 TODOs failed with "connection refused"
+   → docker compose up -d redis
+```
+
+**🟡 FRICTION** — Slowing you down
+```
+🟡 FRICTION: TypeScript retries high (2.1 avg)
+   Pattern: Missing return types
+   → Add stricter eslint rules
+```
+
+**🟢 OPPORTUNITY** — Could be better
+```
+🟢 OPPORTUNITY: Context at 18 exchanges
+   → Run /compact soon
+```
+
+**✓ WIN** — What's working
+```
+✓ WIN: Frontend quality at 0.94
+   React skill highly effective
+```
+
+### Standalone Output
+
+```
+═══════════════════════════════════════════════════════════
+  COMPANION INSIGHTS
+═══════════════════════════════════════════════════════════
+
+  Session: feature-1.2 | 8 TODOs | 34 minutes
+  Avg Confidence: 0.72
+
+  🔴 BLOCKERS (1)
+  ─────────────────────────────────────────────────────────
+  Redis connection failing
+  → docker compose up -d redis
+
+  🟡 FRICTION (1)
+  ─────────────────────────────────────────────────────────
+  Auth module: 2/4 TODOs needed replan
+  → Review auth architecture
+
+  ✓ WINS (1)
+  ─────────────────────────────────────────────────────────
+  Frontend TODOs: 0.93 quality, 0.3 avg retries
+
+═══════════════════════════════════════════════════════════
+```
+
+### Skills View
+
+```
+═══════════════════════════════════════════════════════════
+  SKILL EFFECTIVENESS (OODA metrics)
+═══════════════════════════════════════════════════════════
+
+  Skill        TODOs   Avg Conf   Avg Retries   Replans
+  ───────────────────────────────────────────────────────
+  typescript   23      0.84       1.8           0        ⚠
+  react        18      0.93       0.4           0        ✓
+  auth         12      0.52       2.8           2        🔴
+  database     8       0.71       2.5           1        ⚠
+
+  Auth skill needs improvement (low confidence, high replans)
+
+═══════════════════════════════════════════════════════════
+```
+
+## Persistence
+
+```yaml
+# .codecruise/insights.yaml
+generated: 2026-02-20T14:30:00Z
+
+# Real-time pattern state (for ORIENT)
+pattern_state:
+  retry_window: [2, 3, 1, 0, 2]  # last 5 TODOs
+  error_types:
+    auth_error: 3
+    type_error: 1
+  module_failures:
+    auth: 2
+    api: 0
+
+# Standalone insights
+active_insights:
+  - id: insight-001
+    type: friction
+    pattern: module_failing
+    module: auth
+    message: "Auth module averaging 0.52 confidence"
+    first_seen: 2026-02-20
+    occurrences: 4
+    status: active
+
+dismissed_insights: []
+```
+
+## Integration
+
+| Command | Integration |
+|---------|-------------|
+| `/run` | Calls companion during ORIENT for pattern detection |
+| `/status` | Shows active blocker count from companion |
+| `/retro` | Uses companion data for retrospective |
+| `/dashboard` | Displays confidence trends |
+
+## Quality Bar
+
+- In-loop detection: < 100ms response
+- Patterns updated after every TODO
+- Confidence calculation deterministic
+- Recommendations actionable
+- No false positives on blockers

package/config/commands/dashboard.md

@@ -0,0 +1,152 @@
+---
+name: dashboard
+description: Real-time progress dashboard with OODA state, blockers, costs, and recommendations
+tools: Read, Write, Glob
+model: sonnet
+---
+
+# /dashboard — Real-Time Progress View
+
+Live project status. Shows OODA state, progress, blockers, costs, recommendations.
+
+## Usage
+
+```bash
+/dashboard              # Snapshot view
+/dashboard --live       # Real-time updates (auto-refresh every 5s)
+/dashboard --watch      # Continuous tail of activity.log + progress
+/dashboard --json       # Machine-readable
+/dashboard --html       # Generate HTML report
+```
+
+## Philosophy
+
+Answer: Where are we? What's the OODA state? What's blocking? What should change?
+
+## Live Mode
+
+`/dashboard --live` provides real-time task tracking:
+- Auto-refreshes every 5 seconds
+- Shows current TODO and OODA phase
+- Updates progress bar as TODOs complete
+- Surfaces new blockers immediately
+- Ctrl+C to exit
+
+## Terminal Output
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  {PROJECT}                                      {date} {time}│
+├─────────────────────────────────────────────────────────────┤
+│  PROGRESS ════════════════════════════════════════ 68%      │
+│  Phase 2/4 · Feature 3/8 · 12 TODOs remaining               │
+├─────────────────────────────────────────────────────────────┤
+│  CURRENT                                                     │
+│  ▶ todo-1.2b-007: Implement rate limiting                   │
+│  OODA: 🧭 ORIENT · Confidence: 0.82 · Tempo: balanced       │
+│  Patterns: none · Retries: 0/3                              │
+├─────────────────────────────────────────────────────────────┤
+│  BLOCKERS & NOTES                                            │
+│  🔴 Redis failing - blocks feature-2.3                      │
+│  📝 Rate limits hit - added retry logic                     │
+├─────────────────────────────────────────────────────────────┤
+│  SESSION                                                     │
+│  Duration: 1h 23m · TODOs: 8 · Retries: 2                   │
+│  Tokens: ~45K in · ~12K out · Est: $0.42                    │
+│  Speed: quality_command 8.2s ✅                              │
+├─────────────────────────────────────────────────────────────┤
+│  RECOMMENDATIONS                                             │
+│  → Run /compact - context large (18 exchanges)              │
+│  → Blocker aged 2 days - escalate?                          │
+│  → TypeScript retries high - review patterns                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Live Mode Output
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  {PROJECT}                            LIVE 🔴  {date} {time}│
+├─────────────────────────────────────────────────────────────┤
+│  ▶ todo-1.2b-007: Implement rate limiting                   │
+│    └─ ⚡ ACT (green) · Writing implementation...             │
+│                                                              │
+│  PROGRESS ═══════════════════════════════════════ 68%       │
+│  ✓✓✓✓✓✓✓✓✓✓✓✓○○○○○○ 12/18 TODOs                            │
+│                                                              │
+│  RECENT ACTIVITY                                             │
+│  10:33:50 ✓ todo-1.2b-006 complete (3m 30s)                 │
+│  10:33:51 → Started todo-1.2b-007                           │
+│  10:33:52 👁 OBSERVE: git clean, deps ok                    │
+│  10:33:53 🧭 ORIENT: confidence 0.82                        │
+│  10:33:54 ⚡ DECIDE: execute                                 │
+│  10:34:01 ▶ ACT: red phase (writing tests)                  │
+└─────────────────────────────────────────────────────────────┘
+                                          [Ctrl+C to exit]
+```
+
+## Sections
+
+### Progress
+- Current phase/feature/TODO
+- Percentage complete
+- Visual progress bar
+
+### Current TODO & OODA State
+From `.codecruise/progress.yaml`:
+- Current TODO ID and description
+- OODA phase: OBSERVE / ORIENT / DECIDE / ACT
+- Confidence score
+- Tempo setting
+- Patterns detected
+- Retry count
+
+### Blockers & Notes
+From `.codecruise/progress.yaml`:
+- `blockers[]` - Issues (🔴)
+- `notes[]` - Observations (📝)
+
+### Session Stats
+- Duration, TODOs completed, retries
+- Token usage, estimated cost
+- quality_command speed (✅ <10s, ⚠️ 10-30s, 🐢 >30s)
+
+### Recommendations
+Max 3, prioritized by impact:
+
+| Signal | Recommendation |
+|--------|----------------|
+| Context > 15 | "Run /compact" |
+| Blocker > 2 days | "Escalate or descope?" |
+| High retry rate | "Review patterns" |
+| Session > 2 hours | "Take a break" |
+| Feature complete | "Good PR checkpoint" |
+
+## Token Tracking
+
+```yaml
+# .codecruise/progress.yaml
+session:
+  tokens: {input: 45000, output: 12000}
+  estimated_cost: 0.42
+
+cumulative:
+  total_tokens: 1250000
+  total_cost: 12.50
+```
+
+Cost = (input × $3 + output × $15) / 1M
+
+## Data Sources
+
+```yaml
+.codecruise/progress.yaml: current, stats, blockers, notes, session
+.codecruise/: execution_history, insights
+```
+
+## Output Files
+
+| File | Purpose |
+|------|---------|
+| `dashboard/dashboard.html` | Shareable report |
+| `dashboard/dashboard.md` | Markdown version |