codecruise 0.1.0

package/config/commands/scope.md

@@ -0,0 +1,85 @@
+---
+name: scope
+description: List available phases, features, and subfeatures for execution
+model: haiku
+tools: Read, Glob
+---
+
+# /scope — List Execution Scopes
+
+Display available phases, features, and subfeatures from roadmap.
+
+## Usage
+
+```bash
+/scope                    # All phases with features
+/scope phase-01           # Features for phase
+/scope feature-1.2        # Subfeatures for feature
+/scope --pending          # Only pending items
+/scope --tree             # Full tree view
+/scope --todos            # Include TODO details
+```
+
+## Data Sources
+
+```yaml
+roadmap/project.yaml     # Phase definitions
+roadmap/**/*.yaml        # Features/TODOs
+progress.yaml            # Current state
+```
+
+## Status Icons
+
+| Status | Icon |
+|--------|------|
+| complete | ✓ |
+| in_progress | 🔄 |
+| pending | ○ |
+| blocked | ⚠ |
+
+## Default View
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  AVAILABLE SCOPES                                              ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Current: todo-1.1b-004 (Verify directory structure)          ║
+╠═══════════════════════════════════════════════════════════════╣
+║  PHASES                                                        ║
+║  phase-01  Alpha Bootstrap       🔄  7% (12/164)              ║
+║  phase-02  Domain Modules        ○   0% (0/98)                ║
+╠═══════════════════════════════════════════════════════════════╣
+║  FEATURES (phase-01)                                           ║
+║  feature-1.1  Monorepo Foundation   🔄 50% (7/14)             ║
+║  feature-1.2  Infrastructure        ○   0% (0/34)             ║
+╠═══════════════════════════════════════════════════════════════╣
+║  COMMANDS                                                      ║
+║  /run phase-01        Run entire phase                        ║
+║  /run feature-1.1     Run specific feature                    ║
+║  /scope feature-1.1   Drill into feature                      ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+## Tree View (`--tree`)
+
+```
+Project: Figu (7% complete)
+├── phase-01: Alpha Bootstrap 🔄 7%
+│   ├── feature-1.1: Monorepo Foundation 🔄 50%
+│   │   ├── subfeature-1.1a: Root Config ✓ 100%
+│   │   └── subfeature-1.1b: TypeScript 🔄 75%
+│   └── feature-1.2: Infrastructure ○ 0%
+└── phase-02: Domain Modules ○ 0%
+```
+
+## Error Handling
+
+**No roadmap**: "Run /plan first"
+**Invalid scope**: Lists available scopes
+
+## Quality Bar
+
+- Fast execution (< 1 second)
+- Clear, scannable output
+- Accurate progress
+- Helpful next-step commands

package/config/commands/setup-permissions.md

@@ -0,0 +1,104 @@
+---
+name: setup-permissions
+description: Configure Claude Code permissions for autonomous task execution
+model: haiku
+tools: Read, Write, Bash
+---
+
+# /setup-permissions — Permission Configuration
+
+Configure `.claude/settings.json` for autonomous execution without prompts.
+
+## Usage
+
+```bash
+/setup-permissions                  # Interactive setup
+/setup-permissions --profile exec   # Apply execution profile
+/setup-permissions --profile strict # Apply strict profile
+/setup-permissions --show           # Show current permissions
+/setup-permissions --reset          # Remove custom permissions
+```
+
+## Profiles
+
+| Profile | Description | Use Case |
+|---------|-------------|----------|
+| `exec` | Full execution permissions | Autonomous /run |
+| `strict` | Minimal, ask for most | Security-conscious |
+| `readonly` | Read + search only | Code review |
+
+## Profile: exec (Default)
+
+**Allow**: Package managers, git operations, build tools, file operations
+
+```json
+"allow": [
+  "Bash(pnpm *)", "Bash(npm *)", "Bash(turbo *)",
+  "Bash(git add *)", "Bash(git commit *)", "Bash(git checkout *)",
+  "Bash(vitest *)", "Bash(eslint *)", "Bash(tsc *)",
+  "Bash(mkdir *)", "Bash(cp *)", "Bash(mv *)"
+]
+```
+
+**Ask**: Destructive operations, cloud CLIs
+
+```json
+"ask": [
+  "Bash(git push *)", "Bash(rm -rf *)",
+  "Bash(docker *)", "Bash(aws *)"
+]
+```
+
+**Deny**: Dangerous commands, secrets
+
+```json
+"deny": [
+  "Bash(rm -rf /)", "Bash(curl * | bash)",
+  "Read(./.env)", "Read(./secrets/*)"
+]
+```
+
+## Profile: strict
+
+**Allow**: Read-only git, file viewing
+**Ask**: Package managers, git writes
+**Deny**: Secrets
+
+## Profile: readonly
+
+**Allow**: git status/diff/log, cat/head/tail, find/grep
+**Deny**: All writes, git commits
+
+## Process
+
+1. **Check State**: Look for existing settings.json
+2. **Detect Stack**: Read package.json, turbo.json, CLAUDE.md
+3. **Generate Profile**: Based on detection + selection
+4. **Apply**: Merge with existing settings
+
+## Integration with /run
+
+Pre-flight checks if permissions configured. If not:
+→ "Run /setup-permissions first? [Y/n]"
+
+## Security Notes
+
+- **Never allow** `Bash(*)` (any command)
+- **Always deny** secrets files
+- **Always ask** for destructive operations
+- Review custom patterns before committing
+
+## Output
+
+```
+✓ PERMISSIONS CONFIGURED
+
+Profile: exec
+File: .claude/settings.json
+
+Allowed (45): pnpm, git, build tools
+Ask (10): git push, rm -rf, cloud CLIs
+Denied (16): dangerous commands, secrets
+
+Next: /run will execute without prompts
+```

package/config/commands/skip.md

@@ -0,0 +1,75 @@
+---
+name: skip
+description: DECIDE override - bypass TODO regardless of confidence
+model: haiku
+tools: Read, Write
+---
+
+# /skip
+
+Force DECIDE phase to route "skip" — human override of OODA routing.
+
+## Usage
+
+```bash
+/skip                              # Skip current TODO
+/skip todo-1.1b-004                # Skip specific TODO
+/skip --reason "blocked by API"    # Record reason
+/skip --force                      # Skip even with dependents
+```
+
+## Behavior
+
+| Action | Effect |
+|--------|--------|
+| Skip | DECIDE → skip, move to next TODO |
+| With dependents | Warn, offer cancel |
+| `--force` | Skip without dependent check |
+
+## With Dependents
+
+```
+⚠ todo-1.1b-004 has dependents:
+  - todo-1.1b-005
+  - todo-1.1c-001
+
+[y] Skip anyway
+[n] Cancel
+```
+
+## Output
+
+```
+⏭ SKIP: todo-1.1b-004
+
+  Reason: External API not ready
+  Source: User override
+
+  Queue: 10 done | 1 skipped | 3 remaining
+  Next: todo-1.1b-005
+
+  Undo: /retry todo-1.1b-004
+```
+
+## State Update
+
+```yaml
+queue:
+  skipped:
+    - id: todo-1.1b-004
+      reason: "External API not ready"
+      skip_source: user_override
+```
+
+## Skip vs OODA Skip
+
+| Source | Tracking |
+|--------|----------|
+| User `/skip` | Not tracked as failure |
+| OODA low-confidence | Tracked, affects confidence |
+
+User skips are **intentional** — they don't pollute OODA patterns.
+
+## OODA Integration
+
+Skip is a human override of DECIDE. See `/run` for full OODA routing logic.

package/config/commands/spec-forge.md

@@ -0,0 +1,213 @@
+---
+name: spec-forge
+description: Read inventory docs and generate canonical spec + issues + decisions
+disable-model-invocation: true
+tools: Glob, Read, Write, Edit, Grep, Bash
+model: opus
+---
+
+# /spec-forge — Canonical Spec Generator
+
+Create/refresh canonical product spec from inventory docs.
+
+## Usage
+
+```
+/spec-forge                       # Default: .codecruise/inventory/
+/spec-forge .codecruise/ingested/combined.md  # After /ingest
+/spec-forge --dry-run             # Preview without writing
+```
+
+## Size Check (Auto)
+
+| Condition | Action |
+|-----------|--------|
+| > 50 files | STOP → Suggest `/ingest` first |
+| > 2MB total | STOP → Suggest `/ingest` first |
+| Any file > 256KB | WARN → Consider `/ingest` |
+| ≤ 20 files, ≤ 2MB | Proceed |
+
+## Inputs (read-only)
+
+- `.codecruise/inventory/**` or argument path
+- `.codecruise/inventory/index.yaml` (priority/ignore rules)
+- `.codecruise/canon/**` (baseline for idempotent updates)
+- `.codecruise/ingested/source-map.yaml` (if from /ingest)
+
+## Outputs
+
+```
+.codecruise/canon/
+├── spec.md          # Canonical spec
+├── issues.md        # Conflicts + questions + assumptions
+├── decisions.md     # Resolved decisions (immutable)
+├── changelog.md     # Version history
+.codecruise/context/
+└── {feature}.yaml   # Per-feature sources, decisions, constraints
+.codecruise/roadmap/
+└── future.md        # Out-of-scope items
+```
+
+## Process
+
+1. **Discover**: Read files by priority (index.yaml) or default sort (newest first)
+2. **Extract**: Vision, requirements, entities, tech notes, future plans
+3. **Conflicts** (MUST DO): Log contradicting sources with severity
+4. **Open Questions** (MUST DO): Log ambiguous/missing requirements
+5. **Assumptions** (MUST DO): Log interpretations made
+6. **Scope Separate**: v1 → spec.md, future → future.md
+7. **Context Files**: Create `.codecruise/context/{feature}.yaml` with sources, decisions, constraints
+8. **Generate Spec**: spec.md with FR-XXX, NFR-XXX, acceptance criteria
+9. **Generate Workflows**: WF-XXX with Mermaid sequence diagrams for complex flows
+10. **Decisions Log**: Immutable D-XXX entries
+11. **Changelog**: Version history
+
+## Spec Structure
+
+```markdown
+---
+version: 0.1.0
+generated: {timestamp}
+sources_count: 12
+---
+
+# {Project} — Product Specification
+
+## 1. Overview (pitch, problem, goals, non-goals, key terms)
+## 2. Users (personas, use cases)
+## 3. Scope (v1 in/out)
+## 4. Requirements
+   - 4.1 Functional (FR-XXX with acceptance criteria)
+   - 4.2 Non-Functional (NFR-XXX with thresholds)
+## 5. Workflows (WF-XXX with Mermaid sequence diagrams)
+## 6. Data & Integrations (entities, systems, auth)
+## 7. Risks
+## 8. Links
+```
+
+## Workflow Format
+
+Generate Mermaid sequence diagrams for complex flows:
+
+```markdown
+### WF-001: Password Reset Flow
+- **Trigger**: User clicks "Forgot Password"
+- **Actors**: User, API, Database, Email Service
+- **Related**: FR-003, FR-004
+
+\`\`\`mermaid
+sequenceDiagram
+    participant U as User
+    participant A as API
+    participant D as Database
+    participant E as Email Service
+
+    U->>A: POST /reset-password {email}
+    A->>D: Find user by email
+    alt User exists
+        A->>D: Create reset token (expires 1hr)
+        A->>E: Send reset email
+        A-->>U: 200 "Check your email"
+    else User not found
+        A-->>U: 200 "Check your email" (no leak)
+    end
+    U->>A: GET /reset/{token}
+    A->>D: Validate token
+    A-->>U: Password reset form
+    U->>A: POST /reset/{token} {new_password}
+    A->>D: Update password, invalidate token
+    A-->>U: 200 "Password updated"
+\`\`\`
+
+**Error Handling:**
+- Invalid token → 400 "Invalid or expired link"
+- Rate limit exceeded → 429 with Retry-After
+
+**Edge Cases:**
+- Multiple reset requests → Only latest token valid
+```
+
+**When to generate diagrams:**
+- Multi-step user flows (auth, checkout, onboarding)
+- Async processes (webhooks, background jobs)
+- Multi-service interactions (payment, notifications)
+
+**Skip diagrams for:**
+- Simple CRUD operations
+- Single request-response flows
+
+## Issue Format
+
+```yaml
+# Conflict
+- id: conflict-001
+  description: "Auth timeout: 30min vs 1hr"
+  side_a: {position, sources}
+  side_b: {position, sources}
+  severity: P0|P1|P2
+  suggested_resolution: "..."
+
+# Open Question
+- id: oq-001
+  question: "Rate limit behavior?"
+  impact: "Cannot implement error handling"
+  owner: PM|Eng|Security
+  priority: P1
+
+# Assumption
+- id: assumption-001
+  assumption: "Free tier = no API"
+  rationale: "Inferred from pricing doc"
+  needs_validation: true
+```
+
+## Idempotency
+
+| File | On Re-run |
+|------|-----------|
+| `spec.md` | Regenerate, show diff |
+| `issues.md` | Append new, preserve existing |
+| `decisions.md` | Append only (immutable) |
+| `changelog.md` | Append version entry |
+
+**Manual Edit Detection**: If `generated_hash` mismatch, create `spec.md.new` instead.
+
+## Versioning
+
+| Version | Meaning |
+|---------|---------|
+| `0.x.y` | Draft/iterating |
+| `1.x.y` | First stable (human approved) |
+
+Never auto-increment major version without human approval.
+
+## Output
+
+```
+✓ Spec forge complete
+
+Version: 0.1.0
+Sources: 12 (10 supported, 2 skipped)
+  - Files: 11
+  - Free text: 1 (user-input-20260220-143052.md)
+
+Spec: .codecruise/canon/spec.md
+  - FR: 15, NFR: 8
+  - Workflows: 4 (with sequence diagrams)
+
+Issues:
+  - Conflicts: 3 (1 P0)
+  - Open Questions: 7
+  - Assumptions: 4
+
+Context files: 9
+
+Next: /spec-review or /plan
+```
+
+## Quality Bar
+
+- No contradictions in spec.md (conflicts → issues.md)
+- Concise spec, detail in appendices
+- All requirements have testable criteria
+- Sources attributed

package/config/commands/spec-help.md

@@ -0,0 +1,194 @@
+---
+name: spec-help
+description: Quick reference for spec commands and workflow
+disable-model-invocation: true
+tools: Read
+model: haiku
+---
+
+# /spec-help — Spec Commands Reference
+
+Print the spec workflow and command reference.
+
+## Output
+
+```
+╔═══════════════════════════════════════════════════════════╗
+║                    SPEC COMMAND SUITE                     ║
+╠═══════════════════════════════════════════════════════════╣
+║                                                           ║
+║  /ingest            Pre-process large inventories (50+)   ║
+║  /spec-forge        Generate canonical spec from inventory║
+║  /spec-resolve      Apply issue resolutions to spec       ║
+║  /spec-review       Deep audit of spec vs inventory       ║
+║  /spec-patch <t>    Surgical update to specific section   ║
+║  /architect         Generate architecture/EDD from spec   ║
+║  /architect-review  Audit architecture against spec       ║
+║  /spec-help         This reference                        ║
+║                                                           ║
+╠═══════════════════════════════════════════════════════════╣
+║                       WORKFLOW                            ║
+╠═══════════════════════════════════════════════════════════╣
+║                                                           ║
+║  1. Gather docs ──→ docs/inventory/                       ║
+║                          │                                ║
+║            ┌─────────────┴─────────────┐                  ║
+║            │                           │                  ║
+║      (< 20 files)              (50+ files or > 256KB)     ║
+║            │                           │                  ║
+║            ▼                           ▼                  ║
+║  2. /spec-forge           2a. /ingest ──→ combined.md     ║
+║            │                           │                  ║
+║            │               2b. /spec-forge combined.md    ║
+║            │                           │                  ║
+║            └─────────────┬─────────────┘                  ║
+║                          │                                ║
+║                          ▼                                ║
+║  3. Answer issues.md (add resolution: field)              ║
+║                          │                                ║
+║                          ▼                                ║
+║  4. /spec-resolve ──→ Applies resolutions to spec         ║
+║                          │                                ║
+║                          ▼                                ║
+║  5. /spec-review ──→ docs/canon/spec-audit.md             ║
+║                          │                                ║
+║                          ▼                                ║
+║  6. /spec-patch  ──→ Fix specific sections                ║
+║         │                │                                ║
+║         └────────────────┘ (iterate)                      ║
+║                          │                                ║
+║                          ▼                                ║
+║  7. /architect   ──→ Generate architecture/EDD            ║
+║                          │                                ║
+║                          ▼                                ║
+║  8. /architect-review ─→ Validate against spec            ║
+║                          │                                ║
+║                          ▼                                ║
+║  9. /plan        ──→ Create actionable roadmap            ║
+║                                                           ║
+╠═══════════════════════════════════════════════════════════╣
+║                    WHEN TO USE                            ║
+╠═══════════════════════════════════════════════════════════╣
+║                                                           ║
+║  50+ files or files > 256KB        → /ingest first        ║
+║  First time, no spec exists        → /spec-forge          ║
+║  Added new inventory docs          → /spec-forge          ║
+║  Answered issues in issues.md      → /spec-resolve        ║
+║  Batch resolve multiple issues     → /spec-resolve --all  ║
+║  Before sprint planning            → /spec-review         ║
+║  Stakeholder review prep           → /spec-review         ║
+║  Fix specific section              → /spec-patch <topic>  ║
+║  Need to research for answer       → /spec-patch <topic>  ║
+║  Apply audit patches               → /spec-patch <topic>  ║
+║  Major rewrite needed              → /spec-forge (fresh)  ║
+║  Spec ready, need architecture     → /architect           ║
+║  Validate architecture vs spec     → /architect-review    ║
+║                                                           ║
+╠═══════════════════════════════════════════════════════════╣
+║                   FILE STRUCTURE                          ║
+╠═══════════════════════════════════════════════════════════╣
+║                                                           ║
+║  docs/                                                    ║
+║  ├── inventory/          # Source docs (read-only)        ║
+║  │   ├── index.yaml      # Optional: priority/ignore      ║
+║  │   └── *.md|pdf|txt                                     ║
+║  ├── ingested/           # From /ingest                   ║
+║  │   ├── combined.md     # Merged analyses                ║
+║  │   └── source-map.yaml # Feature→file index             ║
+║  ├── canon/              # Generated canonical docs       ║
+║  │   ├── spec.md         # THE spec                       ║
+║  │   ├── issues.md       # Conflicts + questions          ║
+║  │   ├── decisions.md    # Decision log                   ║
+║  │   ├── changelog.md    # Version history                ║
+║  │   └── spec-audit.md   # Audit report                   ║
+║  ├── context/            # Feature-scoped reference       ║
+║  │   ├── auth.yaml       # Sources, decisions, constraints║
+║  │   ├── architecture.yaml # Patterns, tech choices       ║
+║  │   └── {feature}.yaml  # One per major feature          ║
+║  ├── roadmap/                                             ║
+║  │   └── future.md       # Out-of-scope items             ║
+║  └── appendix/           # Supporting detail              ║
+║      ├── edge-cases.md                                    ║
+║      ├── examples.md                                      ║
+║      └── research.md                                      ║
+║                                                           ║
+╠═══════════════════════════════════════════════════════════╣
+║                  RESOLVE USAGE                            ║
+╠═══════════════════════════════════════════════════════════╣
+║                                                           ║
+║  /spec-resolve conflict-001        Single issue           ║
+║  /spec-resolve conflict-001 oq-003 Multiple issues        ║
+║  /spec-resolve --all               All answered issues    ║
+║                                                           ║
+║  Required format in issues.md:                            ║
+║    - id: conflict-001                                     ║
+║      status: open                                         ║
+║      resolution: "Your answer here"   # ← add this        ║
+║      rationale: "Why this decision"   # ← optional        ║
+║                                                           ║
+╠═══════════════════════════════════════════════════════════╣
+║                   PATCH TOPICS                            ║
+╠═══════════════════════════════════════════════════════════╣
+║                                                           ║
+║  /spec-patch auth          Authentication section         ║
+║  /spec-patch pricing       Pricing/billing requirements   ║
+║  /spec-patch data-model    Entities and relationships     ║
+║  /spec-patch integrations  External systems               ║
+║  /spec-patch nfrs          Non-functional requirements    ║
+║  /spec-patch edge-cases    Error/edge handling            ║
+║  /spec-patch FR-003        Specific requirement           ║
+║                                                           ║
+╚═══════════════════════════════════════════════════════════╝
+```
+
+## Model & Cost Reference
+
+| Command | Model | Est. Cost | Supports --dry-run |
+|---------|-------|-----------|-------------------|
+| /ingest | Sonnet+Haiku | $0.005/file | ✅ Yes |
+| /spec-forge | Opus | $0.30-2.00 | ✅ Yes |
+| /spec-resolve | Sonnet | $0.03-0.25 | ✅ Yes |
+| /spec-review | Opus | $0.15-1.20 | ✅ Yes |
+| /spec-patch | Sonnet | $0.03-0.25 | ✅ Yes |
+| /architect | Opus | $1.00-3.00 | ✅ Yes |
+| /architect-review | Opus | $0.30-1.50 | ✅ Yes |
+| /spec-help | Haiku | ~$0.001 | N/A |
+
+*All commands (except /spec-help) support `--dry-run` to preview output without writing files.*
+
+## Quick Decision Tree
+
+```
+Do you have a spec?
+  │
+  ├── NO  → /spec-forge
+  │
+  └── YES → Are there answered issues in issues.md?
+              │
+              ├── YES → /spec-resolve
+              │
+              └── NO  → Do you have architecture docs?
+                          │
+                          ├── NO  → /architect
+                          │
+                          └── YES → Need audit or fix?
+                                      │
+                                      ├── Audit arch → /architect-review
+                                      ├── Audit spec → /spec-review
+                                      │
+                                      └── Fix section → /spec-patch <topic>
+```
+
+## Context System (Cost Optimization)
+
+Commands use `docs/context/*.yaml` to avoid re-reading inventory:
+
+| Command | Reads context/ | Writes context/ |
+|---------|----------------|-----------------|
+| /ingest | - | source-map.yaml |
+| /spec-forge | source-map | ✅ Creates |
+| /spec-resolve | ✅ | ✅ Updates |
+| /spec-review | ✅ | - |
+| /spec-patch | ✅ | ✅ Updates |
+
+**Tip:** Use `/ingest --detail` for rich context (page numbers, decisions).