codecruise 0.1.0

package/config/commands/role.md

@@ -0,0 +1,310 @@
+---
+name: role
+description: Analyze codebase and generate structured role for CLAUDE.md
+model: sonnet
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# /role Command
+
+Analyze the codebase, ask clarifying questions, and generate a structured role section for CLAUDE.md.
+
+## Philosophy
+
+**Don't make users write roles manually.** Scan the code, infer the domain, ask smart questions, generate the role.
+
+## Usage
+
+```bash
+/role                    # Analyze project, update root CLAUDE.md
+/role apps/web           # Analyze specific directory, create/update nested CLAUDE.md
+/role --dry-run          # Show what would be generated without writing
+/role --update           # Re-analyze and refresh existing role
+```
+
+## Process
+
+### 1. Scan Codebase
+
+Gather signals from:
+
+```bash
+# Package info
+package.json              # name, description, dependencies
+pnpm-workspace.yaml       # monorepo structure
+turbo.json / nx.json      # monorepo tooling
+
+# Folder structure
+apps/                     # Application types
+packages/                 # Shared packages
+src/                      # Source organization
+
+# Key files
+*.config.ts               # Framework configs
+schema.prisma / drizzle   # Database
+Dockerfile                # Deployment
+```
+
+### 2. Analyze Signals
+
+#### Tech Stack Detection
+
+| Signal | Detection |
+|--------|-----------|
+| Frontend | react, next, vue, angular, svelte in deps |
+| Backend | express, fastify, hono, nest in deps |
+| Mobile | expo, react-native in deps |
+| Database | prisma, drizzle, typeorm, postgres, mongodb |
+| Auth | next-auth, lucia, passport, jwt |
+| API Style | trpc, graphql, rest patterns |
+
+#### Domain Detection
+
+Scan for domain-specific keywords in:
+- File names and folder names
+- Package names
+- README content
+- Type/interface names
+
+| Keywords | Likely Domain |
+|----------|---------------|
+| wallet, transaction, currency, payment, invoice | Fintech |
+| cart, product, checkout, inventory, order | E-commerce |
+| patient, appointment, prescription, health | Healthcare |
+| course, lesson, student, enrollment | EdTech |
+| post, comment, feed, follower, like | Social |
+| cli, sdk, api, plugin, extension | DevTools |
+| dashboard, analytics, metrics, report | Analytics |
+| booking, reservation, availability | Booking/Travel |
+
+#### Pattern Detection
+
+| Pattern | Signal |
+|---------|--------|
+| Monorepo | pnpm-workspace.yaml, turbo.json, apps/, packages/ |
+| TDD | vitest, jest, *.test.ts files |
+| Type-safe | typescript, zod, strict mode |
+| API-first | openapi, swagger, trpc |
+
+### 3. Ask Clarifying Questions
+
+Based on analysis, ask 2-4 targeted questions:
+
+```
+Analyzing codebase...
+
+Detected:
+├── Stack: Next.js 15, Fastify, PostgreSQL, Expo
+├── Structure: Monorepo (apps: web, api, mobile, worker)
+├── Patterns: TDD, TypeScript strict, tRPC
+└── Domain signals: "wallet", "transaction", "budget" → Fintech?
+
+Questions:
+
+1. Domain: Is this a personal finance / fintech app?
+   [Y] Yes  [n] No, it's: ___
+
+2. Key expertise needed beyond standard engineering?
+   Examples: "multi-currency handling", "PCI compliance", "decimal precision"
+   > ___
+
+3. Target users?
+   [c] Consumers  [b] Businesses  [d] Developers  [o] Other: ___
+
+4. Any domain-specific rules I should always follow?
+   Example: "Never use floats for money, always decimal/string"
+   > ___
+```
+
+### 4. Generate Role Section
+
+#### For Root CLAUDE.md (Project-wide)
+
+```markdown
+## Role
+
+You are a senior fintech engineer building a personal finance app.
+
+**Domain expertise:**
+- Personal finance and expense tracking
+- Multi-currency transaction handling
+- Budget management and financial planning
+
+**Technical focus:**
+- Full-stack TypeScript (Next.js + Fastify + Expo)
+- PostgreSQL with Drizzle ORM
+- tRPC for type-safe APIs
+
+**Critical rules:**
+- Never use floats for money — use decimal strings
+- All financial calculations must handle currency precision
+- User financial data requires audit logging
+```
+
+#### For Nested CLAUDE.md (Directory-specific)
+
+```markdown
+# Web App
+
+Frontend for the personal finance app.
+
+## Role
+
+You are a senior frontend engineer specializing in:
+- React 19 with Next.js 15 App Router
+- Accessible, mobile-first UI with Tailwind
+- Complex form handling for financial data
+- Real-time updates with tRPC subscriptions
+
+**Key patterns:**
+- Use `@figu/design-tokens` for all styling
+- Forms use react-hook-form + zod validation
+- All money inputs use decimal string format
+```
+
+### 5. Update CLAUDE.md
+
+#### If CLAUDE.md exists with Role section:
+- Ask: "Update existing role? [Y/n]"
+- Replace the `## Role` section only
+
+#### If CLAUDE.md exists without Role section:
+- Insert `## Role` section after project description
+
+#### If no CLAUDE.md:
+- Create from template with role filled in
+
+### 6. Output
+
+```
+✓ Role generated for: figu
+
+Domain: Fintech / Personal Finance
+Stack: Next.js, Fastify, PostgreSQL, Expo
+Expertise: Multi-currency, budget tracking, financial precision
+
+Updated: CLAUDE.md
+
+Role section:
+─────────────────────────────────────────────
+## Role
+
+You are a senior fintech engineer building a personal finance app.
+...
+─────────────────────────────────────────────
+
+Run /role apps/web to generate frontend-specific role.
+Run /role apps/api to generate backend-specific role.
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Show generated role without writing |
+| `--update` | Re-analyze and refresh existing role |
+| `--force` | Overwrite without confirmation |
+| `--minimal` | Generate shorter role (3-4 lines) |
+
+## Directory-Specific Roles
+
+When targeting a specific directory:
+
+```bash
+/role apps/web
+```
+
+**Process:**
+1. Analyze that directory specifically
+2. Infer specialization (frontend/backend/mobile/etc.)
+3. Generate role tailored to that area
+4. Create/update `apps/web/CLAUDE.md`
+
+**Example outputs:**
+
+```bash
+/role apps/api
+# → "You are a senior backend engineer specializing in..."
+
+/role apps/mobile
+# → "You are a senior mobile engineer specializing in..."
+
+/role packages/db
+# → "You are a senior database engineer specializing in..."
+
+/role infra
+# → "You are a senior devops engineer specializing in..."
+```
+
+## Role Templates by Specialization
+
+### Frontend Engineer
+```markdown
+You are a senior frontend engineer specializing in:
+- {framework} with {meta-framework}
+- Accessible, responsive UI design
+- State management and data fetching
+- Performance optimization (Core Web Vitals)
+```
+
+### Backend Engineer
+```markdown
+You are a senior backend engineer specializing in:
+- {framework} with TypeScript
+- RESTful/{tRPC/GraphQL} API design
+- Database optimization and query performance
+- Authentication and authorization flows
+```
+
+### Mobile Engineer
+```markdown
+You are a senior mobile engineer specializing in:
+- {React Native/Expo/Flutter}
+- Cross-platform development
+- Offline-first architecture
+- Native module integration when needed
+```
+
+### Database Engineer
+```markdown
+You are a senior database engineer specializing in:
+- {PostgreSQL/MySQL/MongoDB} optimization
+- Schema design and migrations
+- Query performance and indexing
+- Data integrity and transactions
+```
+
+### DevOps Engineer
+```markdown
+You are a senior devops engineer specializing in:
+- {Docker/Kubernetes} containerization
+- CI/CD pipeline design
+- Infrastructure as code
+- Monitoring and observability
+```
+
+## Integration
+
+After `/role`:
+- `/init` will skip role questions (already defined)
+- `/run` uses the role context for better implementation
+- Nested CLAUDE.md roles activate when working in those directories
+
+## Examples
+
+```bash
+# New project - generate root role
+/role
+
+# Preview without writing
+/role --dry-run
+
+# Generate role for frontend app
+/role apps/web
+
+# Generate role for all major directories
+/role apps/web && /role apps/api && /role apps/mobile
+
+# Update after major changes
+/role --update
+```

package/config/commands/run.md

@@ -0,0 +1,417 @@
+---
+name: run
+description: Execute TODOs using adaptive OODA loop with continuous sensing and intelligent routing
+model: sonnet
+tools: Read, Write, Edit, Bash, Glob, Grep, Task
+---
+
+# /run — OODA Execution Loop
+
+Adaptive execution using Boyd's OODA loop: **Observe → Orient → Decide → Act**.
+
+## Mode Detection
+
+| Input | Mode | Action |
+|-------|------|--------|
+| `/run "intent"` | NEW | Detect scope, clarify, plan, execute |
+| `/run phase-01` | RESUME | Load roadmap, execute TODOs |
+| `/run` | RESUME | Continue from progress.yaml |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--tempo` | `balanced` | `ship-fast`, `balanced`, `careful` |
+| `--checkpoint` | `subfeature` | `subfeature`, `feature`, `none` |
+| `--on-error` | `ask` | `ask`, `skip`, `abort`, `replan` |
+| `--autonomous` | `false` | Run without human intervention |
+| `--promise` | none | Verify condition before complete |
+| `--max-turns` | `100` | Safety limit for autonomous |
+
+## Tempo Profiles
+
+| Tempo | OBSERVE | ORIENT | TDD | Use When |
+|-------|---------|--------|-----|----------|
+| `ship-fast` | Minimal | Skip if confident | Quick verify | Prototyping, low-risk |
+| `balanced` | Standard | Pattern check | Full cycle | Normal work |
+| `careful` | Full sensing | Deep analysis | Full + review | Critical, unfamiliar |
+
+## OODA Execution Loop
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    OODA LOOP                            │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│   ┌──────────┐                                         │
+│   │ OBSERVE  │ ← Sense environment before each TODO    │
+│   └────┬─────┘                                         │
+│        ↓                                               │
+│   ┌──────────┐                                         │
+│   │  ORIENT  │ ← Pattern analysis, confidence calc     │
+│   └────┬─────┘                                         │
+│        ↓                                               │
+│   ┌──────────┐                                         │
+│   │  DECIDE  │ ← Route: execute / skip / replan / ask  │
+│   └────┬─────┘                                         │
+│        ↓                                               │
+│   ┌──────────┐                                         │
+│   │   ACT    │ ← TDD cycle, commit, update state       │
+│   └────┬─────┘                                         │
+│        │                                               │
+│        └──────────→ Back to OBSERVE                    │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 1. OBSERVE (Before Each TODO)
+
+Sense the environment. Don't execute blind.
+
+```yaml
+observe:
+  todo_state:
+    - Read TODO from queue
+    - Check depends_on satisfied
+
+  environment:
+    - git status (uncommitted changes?)
+    - External deps (docker, API health)
+    - Branch correct?
+
+  patterns:
+    - Retry rate last 3 TODOs
+    - Error type clustering
+    - Time since last success
+
+  context:
+    - Exchange count
+    - Token usage trend
+```
+
+**Output**: `observation` object with signals.
+
+### 2. ORIENT (Analyze & Assess)
+
+Update mental model. This is the schwerpunkt.
+
+```yaml
+orient:
+  confidence: high | medium | low
+
+  factors:
+    - TODO complexity (files, dependencies)
+    - Related TODO success rate
+    - Pattern match to previous failures
+    - Skill availability
+
+  warnings:
+    - "3 consecutive retries in this module"
+    - "Similar TODO failed: todo-1.1a-003"
+    - "External dep flaky (2 timeouts)"
+
+  recommendations:
+    - proceed | proceed_cautious | replan | escalate
+```
+
+**Confidence Calculation**:
+```
+high:   No warnings, related TODOs succeeded, skill available
+medium: Minor warnings, some retries in module
+low:    Pattern match to failures, external dep issues, 3+ retries
+```
+
+### 3. DECIDE (Intelligent Routing)
+
+Choose action based on orientation, not just queue position.
+
+| Confidence | Tempo: ship-fast | Tempo: balanced | Tempo: careful |
+|------------|------------------|-----------------|----------------|
+| High | Execute | Execute | Execute |
+| Medium | Execute | Execute + monitor | Ask user |
+| Low | Skip, log | Ask: execute/skip/replan | Pause, replan |
+
+**Decision Options**:
+
+```yaml
+decisions:
+  execute:
+    action: Run TDD cycle
+    when: confidence >= threshold
+
+  execute_cautious:
+    action: Run TDD with extra verification
+    when: medium confidence, balanced tempo
+
+  skip_and_continue:
+    action: Mark skipped, proceed to next
+    when: low confidence, ship-fast tempo
+
+  replan:
+    action: Trigger section re-planning
+    when: 3+ failures in module, pattern detected
+    output: "Auth module failing consistently. Re-plan? [y/n]"
+
+  escalate:
+    action: Pause, surface to human
+    when: blocker detected, autonomous mode
+```
+
+### 4. ACT (TDD Cycle)
+
+Execute the decided action.
+
+```yaml
+act:
+  tdd_cycle:
+    RED:    Write failing tests
+    GREEN:  Implement until tests pass
+    REFACTOR: Clean up
+    VERIFY: lint ✓ | tsc ✓ | test ✓
+
+  on_pass:
+    - Mark TODO done
+    - Commit with conventional message
+    - Update progress.yaml
+    - → OBSERVE next TODO
+
+  on_fail:
+    - Increment retry counter
+    - Log error pattern
+    - → OBSERVE (not retry immediately)
+```
+
+**Key**: After ACT, return to OBSERVE, not "next TODO". This enables re-orientation.
+
+## Pattern Detection (In-Loop)
+
+Patterns detected during ORIENT phase:
+
+| Pattern | Detection | Response |
+|---------|-----------|----------|
+| Retry spike | 3+ retries in last 5 TODOs | Lower confidence |
+| Error clustering | Same error type 3+ times | Flag blocker |
+| Module failing | 3+ failures in same module | Suggest replan |
+| External dep down | Connection errors | Skip dependents |
+| Context bloat | 20+ exchanges | Suggest /compact |
+
+## Adaptive Re-planning
+
+When DECIDE routes to `replan`:
+
+```
+═══════════════════════════════════════════════════════════
+⚠ PATTERN DETECTED: Auth module failing (replan 1/2)
+
+  Last 3 TODOs in auth/ failed:
+    todo-1.2a-003: "JWT validation error" (3 retries)
+    todo-1.2a-004: "Token refresh failed" (2 retries)
+    todo-1.2a-005: "Session storage error" (3 retries)
+
+  Analysis: Possible architecture issue in auth design.
+
+  Options:
+    [c] Continue anyway (force execute)
+    [r] Re-plan auth section (generate new approach)
+    [s] Skip auth, continue other work
+    [p] Pause for investigation
+
+  Choice: _
+═══════════════════════════════════════════════════════════
+```
+
+## Guardrails (Prevent Infinite Loops)
+
+Replan is **not** "retry forever." Hard limits prevent runaway costs.
+
+### Limits
+
+| Guardrail | Default | Purpose |
+|-----------|---------|---------|
+| `max_replans_per_module` | 2 | Same module can't replan endlessly |
+| `max_replans_per_feature` | 3 | Feature-level cap |
+| `max_retries_per_todo` | 3 | Individual TODO retry cap |
+| `on_limit_hit` | `escalate` | What happens at limit |
+
+### Behavior When Limit Hit
+
+```
+⛔ GUARDRAIL: auth module replanned 2x, still failing
+
+  Replan history:
+    1. Changed JWT → session tokens (failed)
+    2. Changed to OAuth flow (failed)
+
+  This section needs human intervention.
+
+  Options:
+    [1] Skip auth module, continue other work
+    [2] Pause for manual investigation
+    [3] Abort run
+
+  ❌ Cannot replan again (limit: 2/module)
+```
+
+### Cost Protection
+
+```yaml
+guardrails:
+  max_replans_per_module: 2
+  max_replans_per_feature: 3
+  max_retries_per_todo: 3
+  on_limit_hit: escalate|abort|skip_module
+
+  # Optional cost tracking
+  cost_limit: 5.00  # USD, stop if exceeded
+  cost_current: 1.23
+```
+
+### ORIENT Checks Guardrails
+
+Before suggesting replan, ORIENT verifies:
+
+```yaml
+orient:
+  can_replan: true|false
+  replan_count_module: 1
+  replan_limit_module: 2
+
+  # If can_replan: false
+  recommendation: escalate  # Not replan
+  reason: "Module replan limit (2) reached"
+```
+
+### The Rule
+
+```
+Retry: Try same approach again (max 3x per TODO)
+Replan: Try different approach (max 2x per module)
+Escalate: Human decides (when limits hit)
+```
+
+**No infinite loops. No runaway costs.**
+
+## State: execution_state in progress.yaml
+
+```yaml
+execution_state:
+  status: running|paused|stopped|completed|error
+  scope: feature-1.1
+  tempo: balanced
+
+  current_todo: todo-1.1b-004
+
+  # OODA state
+  ooda:
+    last_observation: 2026-02-20T10:30:00Z
+    confidence: medium
+    consecutive_failures: 2
+    patterns_detected: ["retry_spike"]
+
+  # Guardrails (prevent infinite loops)
+  guardrails:
+    max_retries_per_todo: 3
+    max_replans_per_module: 2
+    max_replans_per_feature: 3
+    on_limit_hit: escalate
+
+  # Per-module replan tracking
+  module_replans:
+    auth: 1  # 1 replan used, 1 remaining
+    api: 0
+
+  queue:
+    total: 14
+    completed: [todo-1.1a-001, ...]
+    pending: [todo-1.1b-004, ...]
+    failed: []
+    skipped: []
+    replanned: []
+
+  stats:
+    todos_completed: 10
+    todos_remaining: 4
+    total_retries: 2
+    replan_count: 1
+    avg_confidence: 0.85
+```
+
+## Output Format
+
+**OBSERVE**:
+```
+👁 OBSERVE: todo-1.1b-004
+  Environment: ✓ git clean | ✓ deps up | ✓ branch correct
+  Patterns: ⚠ 2 retries last 3 TODOs
+```
+
+**ORIENT**:
+```
+🧭 ORIENT: confidence=medium
+  Module success rate: 70%
+  Similar TODO (todo-1.1a-003): passed after 2 retries
+  → Proceed with caution
+```
+
+**DECIDE**:
+```
+⚡ DECIDE: execute_cautious
+  Extra verification enabled
+```
+
+**ACT**:
+```
+▶ ACT: todo-1.1b-004 | Verify directory structure
+
+RED    3 tests written → ✗ 3 failing
+GREEN  implemented → ✓ 3 passing
+VERIFY lint ✓ | tsc ✓ | test ✓
+
+✓ COMPLETE | 2m 15s | commit: abc123
+```
+
+**Checkpoint** (includes pattern summary):
+```
+═══════════════════════════════════════════════════════════
+✓ CHECKPOINT: subfeature-1.1a
+
+  Progress: 7/7 TODOs | 45m | 3 commits
+
+  OODA Summary:
+    Avg confidence: 0.87
+    Patterns: none detected
+    Replans: 0
+
+  Next: subfeature-1.1b (4 TODOs)
+
+  [c]ontinue [p]ause [a]bort
+═══════════════════════════════════════════════════════════
+```
+
+## Autonomous Mode
+
+| 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 |
+
+## Integration
+
+| Command | Integration |
+|---------|-------------|
+| `/pause` | Sets status = paused |
+| `/resume` | Continues from current OBSERVE |
+| `/skip` | DECIDE override: skip current |
+| `/retry` | Reset TODO, back to OBSERVE |
+| `/companion` | Pattern data shared with ORIENT |
+| `/retro` | Triggered by replan decisions |
+
+## Quality Bar
+
+- OODA loop cycles continuously (not linear)
+- Pattern detection in-loop, not post-hoc
+- Confidence-based routing, not blind execution
+- Re-orientation when patterns emerge
+- Tempo adapts to situation