codecruise 0.1.0

package/config/commands/spec-patch.md

@@ -0,0 +1,342 @@
+---
+name: spec-patch
+description: Patch a specific section of the canonical spec (surgical update)
+disable-model-invocation: true
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: sonnet
+---
+
+# /spec-patch <topic> — Surgical Spec Update
+
+## Goal
+
+Update ONLY the requested section of the spec, preserving everything else.
+Use inventory docs + existing canon docs as sources.
+Minimal, focused changes.
+
+## Workflow
+
+`/spec-forge` → `/spec-resolve` → `/spec-review` ⟷ **`/spec-patch`** ← YOU ARE HERE → `/plan`
+
+## When to Use
+
+| Situation | Use /spec-patch? |
+|-----------|------------------|
+| Fix specific section after audit | ✅ Yes |
+| Apply patches from spec-audit.md | ✅ Yes |
+| Resolve specific conflict | ✅ Yes |
+| Add single missing requirement | ✅ Yes |
+| Major rewrite needed | ❌ Use /spec-forge |
+| Full audit needed | ❌ Use /spec-review |
+
+## Usage
+
+```
+/spec-patch <topic>              # Patch specific section
+/spec-patch auth                 # Update authentication
+/spec-patch --dry-run <topic>    # Preview changes
+```
+
+## Cost Estimate
+
+| Patch Scope | Estimated Cost |
+|-------------|----------------|
+| Single requirement (FR-XXX) | $0.03 - $0.08 |
+| Small section (auth, pricing) | $0.08 - $0.15 |
+| Large section (data-model) | $0.15 - $0.25 |
+
+*Sonnet model used for scoped updates. Most cost-effective spec command.*
+
+## Arguments
+
+`<topic>` — The section or topic to patch
+
+**Examples:**
+
+- `/spec-patch auth` — Update authentication section
+- `/spec-patch pricing` — Update pricing/billing requirements
+- `/spec-patch edge-cases` — Update edge case handling
+- `/spec-patch data-model` — Update entities/data section
+- `/spec-patch integrations` — Update integrations section
+- `/spec-patch nfrs` — Update non-functional requirements
+- `/spec-patch FR-003` — Update specific requirement
+
+## Inputs (read-only)
+
+- `.codecruise/canon/spec.md` (required)
+- `.codecruise/canon/issues.md` (if exists)
+- `.codecruise/canon/spec-audit.md` (if exists, check for related patches)
+- `.codecruise/canon/decisions.md` (if exists)
+- `.codecruise/roadmap/future.md` (if exists)
+- `.codecruise/context/{topic}.yaml` (if exists, preferred source)
+- Relevant `.codecruise/inventory/**` files (fallback if no context)
+
+**Rule**: NEVER edit `.codecruise/inventory/**`
+
+## Outputs
+
+| File | Action |
+|------|--------|
+| `.codecruise/canon/spec.md` | Edit only `<topic>` section |
+| `.codecruise/canon/issues.md` | Update if conflicts resolved or new issues found |
+| `.codecruise/canon/decisions.md` | Append if decision made |
+| `.codecruise/canon/changelog.md` | Append patch entry |
+| `.codecruise/context/{topic}.yaml` | Update if new decisions/constraints added |
+
+## Process
+
+### 1) Locate Target Section
+
+Find the exact section(s) in spec.md for `<topic>`:
+
+```bash
+# Example for "auth"
+Grep -i "auth|authentication|login|session" .codecruise/canon/spec.md
+```
+
+**If section missing**: Create it in the appropriate location in spec.md.
+
+**Section mapping:**
+
+| Topic | Likely Sections |
+|-------|-----------------|
+| auth | 4.1 Functional (auth reqs), 6.3 Auth Model |
+| pricing | 4.1 Functional (billing reqs) |
+| data-model | 6.1 Key Entities |
+| integrations | 6.2 Integrations |
+| nfrs | 4.2 Non-Functional Requirements |
+| edge-cases | Link to appendix/edge-cases.md |
+| FR-XXX | 4.1 Functional Requirements |
+| NFR-XXX | 4.2 Non-Functional Requirements |
+
+### 2) Gather Topic-Relevant Sources
+
+**Preferred: Read context file (fast, pre-extracted)**
+
+```bash
+# Check if context file exists
+Read .codecruise/context/{topic}.yaml
+```
+
+If context file exists:
+- Use `sources` for file references
+- Use `decisions` for existing decisions
+- Use `constraints` for known limitations
+- Use `open_questions` for unresolved items
+
+**Fallback: Grep inventory (slower, more tokens)**
+
+```bash
+# Only if no context file exists
+Grep -i "<topic>" .codecruise/inventory/
+```
+
+Read relevant files. Extract:
+
+- Requirements related to `<topic>`
+- Business rules
+- Constraints
+- Edge cases
+- Decisions made
+
+### 3) Check for Existing Patches
+
+If `.codecruise/canon/spec-audit.md` exists:
+
+```bash
+Grep -i "<topic>" .codecruise/canon/spec-audit.md
+```
+
+Look for proposed patches to apply.
+
+### 4) Check for Related Issues
+
+```bash
+Grep -i "<topic>" .codecruise/canon/issues.md
+```
+
+Identify conflicts/questions to resolve.
+
+### 5) Apply Updates
+
+**For requirements:**
+
+```markdown
+#### FR-XXX: {Requirement Name}
+- **Description**: {Clear description}
+- **User Story**: As a {role}, I want {goal}, so that {benefit}
+- **Acceptance Criteria**:
+  - [ ] {Testable criterion 1}
+  - [ ] {Testable criterion 2}
+- **Source**: {inventory file(s)}
+```
+
+**Acceptance criteria rules:**
+
+- Must be testable (measurable, observable)
+- No vague words ("fast", "easy", "secure")
+- Include edge cases if known
+
+**For NFRs:**
+
+```markdown
+#### NFR-XXX: {Requirement Name}
+- **Category**: Performance | Security | Reliability | Observability
+- **Requirement**: {Specific requirement}
+- **Threshold**: {Measurable target}
+- **Source**: {inventory file(s)}
+```
+
+### 6) Handle Conflicts
+
+If patching resolves a conflict:
+
+1. Update issues.md:
+
+   ```yaml
+   - id: conflict-XXX
+     ...
+     status: resolved
+     resolution: "{How it was resolved}"
+     resolved_by: "/spec-patch <topic>"
+     resolved_date: 2024-01-24
+   ```
+
+2. Add to decisions.md:
+
+   ```markdown
+   ### D-XXX: {Decision Title}
+   - **Date**: 2024-01-24
+   - **Decision**: {What was decided}
+   - **Rationale**: {Why}
+   - **Related**: conflict-XXX
+   ```
+
+### 7) Handle New Issues
+
+If patch reveals new conflicts/questions:
+
+1. Append to issues.md with next available ID
+2. Note in output summary
+3. Do NOT silently resolve — surface explicitly
+
+### 7.5) Update Context File
+
+If `.codecruise/context/{topic}.yaml` exists, update it:
+
+```yaml
+# Add new decision
+decisions:
+  - id: D-XXX  # from decisions.md
+    summary: "{decision made during patch}"
+    source: "/spec-patch {topic}"
+
+# Add new constraint if discovered
+constraints:
+  - "{new constraint}"
+
+# Remove resolved open question
+open_questions:
+  # Remove oq-XXX if resolved by this patch
+```
+
+If context file doesn't exist but should (topic is a major feature):
+- Create `.codecruise/context/{topic}.yaml` with info gathered during patch
+- Note in output: "Created context/{topic}.yaml for future efficiency"
+
+### 8) Scope Check
+
+If content belongs in future.md instead of spec.md:
+
+1. Add to `.codecruise/roadmap/future.md`
+2. Note in output: "Moved {item} to future.md (not v1 scope)"
+
+### 9) Update Changelog
+
+Append to `.codecruise/canon/changelog.md`:
+
+```markdown
+## [0.2.2] - 2024-01-24
+### Patched: {topic}
+- Updated FR-003 acceptance criteria
+- Added FR-016: Password reset
+- Resolved conflict-004
+- Added NFR-009: Input validation
+```
+
+### 10) Update Version
+
+In spec.md frontmatter:
+
+- Increment patch version (0.2.1 → 0.2.2)
+- **Never** auto-increment major version (0→1, 1→2) without human approval
+- Update `generated_hash` with new hash
+
+## Output
+
+```
+✓ Spec patched: {topic}
+
+Version: 0.2.1 → 0.2.2
+
+Changes:
+  - Updated: FR-003 (acceptance criteria)
+  - Added: FR-016 (password reset)
+  - Added: NFR-009 (input validation)
+
+Issues resolved:
+  - conflict-004: Auth mechanism → JWT for API, sessions for web
+
+New issues found:
+  - oq-015: Password complexity requirements undefined
+
+Scope changes:
+  - Moved "SSO integration" to future.md
+
+Files modified:
+  - .codecruise/canon/spec.md (section 4.1, 4.2)
+  - .codecruise/canon/issues.md (1 resolved, 1 added)
+  - .codecruise/canon/decisions.md (1 added)
+  - .codecruise/canon/changelog.md (1.3 entry)
+
+Next: Review changes, then /spec-review for full audit
+```
+
+## Dry Run Mode
+
+When `--dry-run` flag is passed:
+
+```
+🔍 Dry Run: /spec-patch auth
+
+Topic Analysis:
+  - Sections found: 2 (4.1 Functional, 6.3 Auth Model)
+  - Related inventory files: 3
+  - Related issues: 2 (conflict-004, oq-012)
+
+Would Change:
+  - spec.md:
+    - Update: FR-003 (acceptance criteria)
+    - Add: FR-016 (password reset)
+    - Add: NFR-009 (input validation)
+  - issues.md:
+    - Resolve: conflict-004
+    - Add: oq-015 (new question found)
+  - decisions.md:
+    - Add: D-005 (auth mechanism decision)
+  - changelog.md:
+    - Add: v0.2.2 entry
+
+Estimated cost: $0.12
+
+Run without --dry-run to apply patch.
+```
+
+## Quality Bar
+
+- Only touch sections related to `<topic>`
+- Preserve all unrelated content exactly
+- All new requirements have testable criteria
+- Conflicts resolved explicitly, not silently
+- Changes are minimal and focused
+- v1 scope strictly maintained

package/config/commands/spec-resolve.md

@@ -0,0 +1,110 @@
+---
+name: spec-resolve
+description: Apply user-provided resolutions from issues.md to spec and decisions
+disable-model-invocation: true
+tools: Read, Write, Edit, Grep, Glob
+model: sonnet
+---
+
+# /spec-resolve — Apply Issue Resolutions
+
+Apply user-provided resolutions from issues.md to spec.md and decisions.md.
+
+## Usage
+
+```
+/spec-resolve conflict-001         # Single issue
+/spec-resolve conflict-001 oq-003  # Multiple issues
+/spec-resolve --all                # All with resolution field
+/spec-resolve --dry-run <ids>      # Preview
+```
+
+## Resolution Format
+
+User adds `resolution:` field to issues.md:
+
+**Conflict**:
+```yaml
+- id: conflict-001
+  description: "Auth timeout: 30min vs 1hr"
+  status: open
+  resolution: "Use 1hr with re-auth for sensitive actions"
+  rationale: "Balances UX with security"
+  apply_to:
+    - section: "6.3 Auth Model"
+```
+
+**Open Question**:
+```yaml
+- id: oq-001
+  question: "Rate limit behavior?"
+  status: open
+  resolution: "Return 429 with Retry-After header"
+  apply_to:
+    - new_requirement: NFR-010
+```
+
+**Assumption**:
+```yaml
+- id: assumption-001
+  assumption: "Free tier = no premium API"
+  status: open
+  resolution: "confirmed"  # or "revised: <new>"
+  validated_by: "PM confirmed"
+```
+
+## Process
+
+1. **Parse IDs**: Validate format (conflict-XXX, oq-XXX, assumption-XXX)
+2. **Validate**: Check resolution exists, status is open
+3. **Determine Updates**: Use apply_to hints or infer from keywords
+4. **Update spec.md**: Modify sections, add requirements
+5. **Create Decision**: Append D-XXX to decisions.md
+6. **Update Context**: Add decision to docs/context/{feature}.yaml
+7. **Mark Resolved**: Set status = resolved in issues.md
+8. **Changelog**: Increment patch version
+
+## Outputs
+
+| File | Action |
+|------|--------|
+| `spec.md` | Update sections/requirements |
+| `decisions.md` | Append D-XXX entries |
+| `issues.md` | Mark resolved |
+| `changelog.md` | Append version entry |
+| `context/{feature}.yaml` | Update decisions |
+
+## Versioning
+
+- Increment patch (0.2.2 → 0.2.3)
+- Never auto-increment major version
+
+## Output
+
+```
+✓ Issues resolved: 3
+
+Processed:
+  ✓ conflict-001 → D-005: Auth timeout
+  ✓ oq-003 → D-006: Rate limit behavior
+  ✓ assumption-001 → Confirmed
+
+Skipped:
+  ⚠️ oq-002: No resolution provided
+
+Spec updates:
+  - Section 6.3 (updated)
+  - NFR-010 (added)
+
+Version: 0.2.2 → 0.2.3
+
+Next: /spec-review to validate
+```
+
+## Quality Bar
+
+- Only process explicit resolutions
+- Never assume or infer
+- Preserve unrelated spec content
+- Create audit trail in decisions.md
+- Idempotent: re-running = no change

package/config/commands/spec-review.md

@@ -0,0 +1,153 @@
+---
+name: spec-review
+description: Audit canonical spec vs inventory; surface gaps, contradictions, and fixes
+disable-model-invocation: true
+tools: Glob, Read, Write, Edit, Grep, Bash
+model: opus
+---
+
+# /spec-review — Spec Audit
+
+Deep audit of canonical spec against inventory. Find gaps, contradictions, propose fixes.
+
+## When to Use
+
+| Situation | Use /spec-review? |
+|-----------|-------------------|
+| Before sprint planning | ✅ Yes |
+| After adding inventory docs | ✅ Yes |
+| Quick section fix | ❌ Use /spec-patch |
+| No spec exists | ❌ Use /spec-forge |
+
+## Usage
+
+```
+/spec-review                       # Review against .codecruise/inventory/
+/spec-review .codecruise/ingested/combined.md  # After /ingest
+/spec-review --dry-run             # Preview findings
+```
+
+## Size Check (Auto)
+
+| Condition | Action |
+|-----------|--------|
+| > 50 files | STOP → Suggest `/ingest` first |
+| > 2MB | STOP → Suggest `/ingest` first |
+
+## Inputs (read-only)
+
+- `.codecruise/canon/spec.md` (required)
+- `.codecruise/canon/issues.md`, `decisions.md` (existing state)
+- `.codecruise/context/*.yaml` (for efficient validation)
+- `.codecruise/inventory/**` or argument path
+
+## Outputs
+
+| File | Action |
+|------|--------|
+| `spec-audit.md` | Create/update (main report) |
+| `issues.md` | Update if new issues |
+| `spec.md` | Update ONLY for unambiguous fixes |
+
+## Process
+
+1. **Load Canonical State**: spec version, existing issues, decisions
+2. **Load Context**: .codecruise/context/*.yaml for known decisions
+3. **Deduplication**: Index existing issues (open AND resolved)
+4. **Cross-Check**: Scan inventory for issues
+5. **Classify**: Conflict, Question, Gap, Weak Criteria, Security
+6. **Grade**: A-F based on completeness, clarity, consistency
+7. **Propose Patches**: Concrete, copy-pastable fixes
+
+## Deduplication Rules
+
+| Existing Status | New Finding | Action |
+|-----------------|-------------|--------|
+| `resolved` | Same issue | **SKIP** |
+| `open` | Same issue | **SKIP** |
+| `open` | More detail | Update existing |
+| none | New | Add with next ID |
+
+## Issue Classification
+
+| Type | What to Look For |
+|------|------------------|
+| Missing requirement | Feature implied but not in spec |
+| Conflicting rule | Contradicts spec |
+| Scope confusion | v1 in future or vice versa |
+| Weak criteria | Not testable ("should be fast") |
+| Security gap | Missing validation, auth |
+
+## Audit Report Structure
+
+```markdown
+# Spec Audit Report
+
+## Executive Summary
+Grade: B
+| Category | Score | Notes |
+|----------|-------|-------|
+| Completeness | 7/10 | 3 missing reqs |
+| Consistency | 6/10 | 4 conflicts |
+
+## Top 5 Blockers
+1. conflict-004: Auth undefined (P0)
+...
+
+## Coverage Analysis
+| Source | Found | In Spec | Missing |
+...
+
+## Conflicts Found
+...
+
+## Proposed Patches
+### Patch 1: Add FR-016
+Location: Section 4.1
+```markdown
+#### FR-016: Password Reset
+- **Acceptance Criteria**:
+  - [ ] Reset link expires in 1hr
+```
+```
+
+## Grade Criteria
+
+| Grade | Meaning |
+|-------|---------|
+| A | Ship-ready |
+| B | 3-5 issues to resolve |
+| C | Significant gaps |
+| D | Major conflicts |
+| F | Contradicts itself, restart |
+
+## Output
+
+```
+✓ Spec audit complete
+
+Grade: B
+Version: 0.2.1
+
+Context validation:
+  - Decisions honored: 12/14
+  - Violations: 2
+
+Issues:
+  - New conflicts: 2 (1 blocking)
+  - New questions: 3
+  - Existing unresolved: 4
+
+Patches proposed: 5
+
+Next:
+  1. Resolve conflict-004 (BLOCKING)
+  2. /spec-patch auth
+```
+
+## Quality Bar
+
+- Every finding has actionable recommendation
+- Patches are copy-pastable
+- Blockers clearly marked
+- No duplicate issues (resolved never recreated)

package/config/commands/status.md

@@ -0,0 +1,114 @@
+---
+name: status
+description: Show current project state and progress
+disable-model-invocation: true
+model: haiku
+---
+
+# /status Command
+
+Display current project state and progress.
+
+## Read First
+
+1. `progress.yaml`
+2. `roadmap/project.yaml`
+3. Current phase file
+
+## Process
+
+### 1. Load State
+
+Read `progress.yaml` for:
+- Current phase, feature, TODO
+- Active TODOs
+- Statistics
+- Blocked items
+
+### 2. Display Status
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║                    PROJECT STATUS                             ║
+╠══════════════════════════════════════════════════════════════╣
+║ Project: {name}                                               ║
+║ Progress: [{████████░░░░░░░░░░░░}] 40%                       ║
+╠══════════════════════════════════════════════════════════════╣
+║ Current Work                                                  ║
+╠══════════════════════════════════════════════════════════════╣
+║ Phase:    {phase_name}                                        ║
+║ Feature:  {feature_name}                                      ║
+║ TODO:     {todo_id} - {description}                          ║
+║ Branch:   {branch_name}                                       ║
+╠══════════════════════════════════════════════════════════════╣
+║ Statistics                                                    ║
+╠══════════════════════════════════════════════════════════════╣
+║ Phases:   {done}/{total}                                     ║
+║ Features: {done}/{total}                                     ║
+║ TODOs:    {done}/{total}                                     ║
+╠══════════════════════════════════════════════════════════════╣
+║ Active TODOs                                                  ║
+╠══════════════════════════════════════════════════════════════╣
+║ • {todo_id}: {description} ({owner}) - {status}             ║
+╠══════════════════════════════════════════════════════════════╣
+║ Blocked                                                       ║
+╠══════════════════════════════════════════════════════════════╣
+║ • {todo_id}: {reason}                                        ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+### 3. Upcoming Work
+
+Show next 3 TODOs after current:
+
+```
+Next Up:
+1. {todo_id}: {description}
+2. {todo_id}: {description}
+3. {todo_id}: {description}
+```
+
+### 4. Token Usage
+
+Show token consumption for transparency:
+
+```
+╠══════════════════════════════════════════════════════════════╣
+║ Token Usage                                                  ║
+╠══════════════════════════════════════════════════════════════╣
+║ Session:    {input} in / {output} out = {total} tokens       ║
+║ Cumulative: {total} tokens (~${cost} USD)                    ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+### 5. Recent Activity
+
+If git available, show recent commits:
+
+```
+Recent Commits:
+• 2h ago: feat(auth): implement login validation
+• 3h ago: test(auth): add login tests
+• 5h ago: chore: setup project structure
+```
+
+## Variations
+
+### `/status --phase`
+Show detailed phase breakdown
+
+### `/status --blocked`
+Show only blocked items with context
+
+### `/status --next`
+Show just the next TODO to work on
+
+## No Project State
+
+If `progress.yaml` doesn't exist:
+
+```
+No project state found.
+
+Run /plan to create a roadmap and initialize tracking.
+```