codecruise 0.1.0

package/config/rules/pattern-detection.md

@@ -0,0 +1,372 @@
+# Pattern Detection Rules
+
+Rules for detecting patterns in execution history that warrant insights.
+
+## Data Sources
+
+```yaml
+sources:
+  execution_history:
+    path: .codecruise/execution_history.yaml
+    contains: sessions, skill_metrics
+
+  scorecards:
+    path: .codecruise/scorecards/*.json
+    contains: individual TODO results
+
+  progress:
+    path: progress.yaml
+    contains: current state, queue
+
+  verification:
+    path: .codecruise/verification/
+    contains: recent command outputs
+```
+
+## Pattern Categories
+
+### 1. Retry Patterns
+
+**High Retry Rate (Overall)**
+
+```yaml
+pattern: high_retry_rate_overall
+type: friction
+severity: medium
+
+detection:
+  metric: total_retries / total_todos
+  threshold: 1.5
+  window: current_session OR last_7_days
+
+insight:
+  message: "Overall retry rate is {rate:.1f} per TODO"
+  suggestion: "Review failing patterns in scorecards"
+```
+
+**High Retry Rate (Category)**
+
+```yaml
+pattern: high_retry_rate_category
+type: friction
+severity: high
+
+detection:
+  group_by: skill | file_extension | todo_prefix
+  metric: category_retries / category_todos
+  threshold: 2.0
+  min_sample: 3  # At least 3 TODOs in category
+
+insight:
+  message: "{category} TODOs averaging {rate:.1f} retries"
+  suggestion: "Review {category} skill or add category-specific rules"
+```
+
+### 2. Error Patterns
+
+**Repeated Error Type**
+
+```yaml
+pattern: repeated_error_type
+type: blocker | friction
+severity: high | medium
+
+detection:
+  group_by: error_type  # test_failure, lint_error, type_error, connection_error
+  threshold: 3  # Same error 3+ times
+  window: current_session
+
+severity_rules:
+  blocker: error is blocking progress (consecutive failures)
+  friction: error recurring but not blocking
+
+insight:
+  message: "{error_type} occurring repeatedly ({count} times)"
+  suggestion: based on error_type (see Error Suggestions below)
+```
+
+**Connection/Infrastructure Errors**
+
+```yaml
+pattern: infrastructure_error
+type: blocker
+severity: critical
+
+detection:
+  error_patterns:
+    - "connection refused"
+    - "ECONNREFUSED"
+    - "timeout"
+    - "service unavailable"
+    - "docker"
+  threshold: 2
+
+insight:
+  message: "Infrastructure issue detected: {pattern}"
+  suggestion: "Check if required services are running"
+  fix_command: infer from error (docker, redis, postgres, etc.)
+```
+
+### 3. Quality Patterns
+
+**Quality Decline**
+
+```yaml
+pattern: quality_decline
+type: opportunity
+severity: medium
+
+detection:
+  metric: avg_quality_score
+  compare: current_session vs previous_session
+  threshold: -0.1  # 10% decline
+
+insight:
+  message: "Quality trending down ({previous:.2f} → {current:.2f})"
+  suggestion: "Check recent changes, consider more detailed specs"
+```
+
+**Category Quality Gap**
+
+```yaml
+pattern: category_quality_gap
+type: friction
+severity: medium
+
+detection:
+  compare: category_avg vs overall_avg
+  threshold: -0.15  # 15% below average
+  min_sample: 3
+
+insight:
+  message: "{category} quality ({cat_avg:.2f}) below average ({overall:.2f})"
+  suggestion: "Review {category} skill or add patterns"
+```
+
+**Alignment Issues**
+
+```yaml
+pattern: low_alignment
+type: friction
+severity: medium
+
+detection:
+  metric: alignment_score
+  threshold: 0.75
+  frequency: 3+ TODOs with low alignment
+
+insight:
+  message: "Alignment scores low on recent TODOs"
+  suggestion: "Specs may need more detail on expected files/criteria"
+```
+
+### 4. Context Patterns
+
+**Long Session**
+
+```yaml
+pattern: long_session
+type: opportunity
+severity: low | medium
+
+detection:
+  metric: exchange_count (if available) OR todo_count
+  thresholds:
+    warning: 15 exchanges OR 10 TODOs
+    critical: 25 exchanges OR 15 TODOs
+
+insight:
+  message: "Session running long ({count} exchanges)"
+  suggestion: "Consider /compact to preserve context quality"
+```
+
+**Missing Compaction**
+
+```yaml
+pattern: missing_compaction
+type: opportunity
+severity: medium
+
+detection:
+  metric: todos_since_last_compact
+  threshold: 8
+
+insight:
+  message: "No compaction in {count} TODOs"
+  suggestion: "Run /compact to maintain context quality"
+```
+
+### 5. Positive Patterns (Wins)
+
+**High Quality Category**
+
+```yaml
+pattern: high_quality_category
+type: win
+severity: positive
+
+detection:
+  metric: category_avg_quality
+  threshold: overall_avg + 0.1
+  min_sample: 5
+
+insight:
+  message: "{category} quality excellent ({avg:.2f})"
+  suggestion: "Skill is effective - consider similar for other areas"
+```
+
+**Zero Retry Streak**
+
+```yaml
+pattern: zero_retry_streak
+type: win
+severity: positive
+
+detection:
+  metric: consecutive_todos_without_retry
+  threshold: 5
+
+insight:
+  message: "{count} TODOs completed without retries"
+  suggestion: "Great flow - patterns are working well"
+```
+
+**Improving Trend**
+
+```yaml
+pattern: improving_trend
+type: win
+severity: positive
+
+detection:
+  metric: avg_quality
+  compare: 3-session moving average
+  threshold: +0.05  # 5% improvement
+
+insight:
+  message: "Quality improving over recent sessions"
+  suggestion: "Keep up the good work!"
+```
+
+## Error Suggestions Map
+
+```yaml
+error_suggestions:
+  test_failure:
+    message: "Tests failing"
+    suggestions:
+      - "Check test expectations match implementation"
+      - "Verify test setup/teardown"
+      - "Look for async timing issues"
+
+  lint_error:
+    message: "Lint errors"
+    suggestions:
+      - "Run lint with --fix flag"
+      - "Check eslint configuration"
+      - "Review code style guidelines"
+
+  type_error:
+    message: "TypeScript errors"
+    suggestions:
+      - "Check type definitions"
+      - "Verify function signatures"
+      - "Look for implicit any usage"
+
+  connection_refused:
+    message: "Connection refused"
+    suggestions:
+      - "Check if database is running"
+      - "Verify docker containers: docker ps"
+      - "Check service ports and config"
+
+  timeout:
+    message: "Operation timeout"
+    suggestions:
+      - "Check network connectivity"
+      - "Increase timeout settings"
+      - "Look for infinite loops or blocking calls"
+
+  import_error:
+    message: "Import/module errors"
+    suggestions:
+      - "Check file paths and extensions"
+      - "Verify exports match imports"
+      - "Run npm/pnpm install"
+```
+
+## Aggregation Rules
+
+### Session-Level Aggregation
+
+```yaml
+aggregate_session:
+  from: scorecards/*.json
+
+  metrics:
+    total_todos: count(scorecards)
+    total_retries: sum(scorecard.attempt - 1)
+    avg_quality: mean(scorecard.scores.overall)
+    avg_alignment: mean(scorecard.scores.alignment)
+
+  group_by:
+    skill: extract from todo_id or files
+    file_type: extract from files touched
+    error_type: extract from verification results
+```
+
+### Cross-Session Aggregation
+
+```yaml
+aggregate_history:
+  from: execution_history.sessions
+  window: 7 days
+
+  metrics:
+    sessions_count: count(sessions)
+    total_todos: sum(session.todos.completed)
+    trend: compare(recent_3, previous_3)
+
+  skill_metrics:
+    per_skill:
+      todos: count
+      avg_quality: mean
+      avg_retries: mean
+```
+
+## Priority Rules
+
+When multiple insights detected, prioritize:
+
+```yaml
+priority_order:
+  1: blocker (critical)      # Show first, always
+  2: blocker (high)
+  3: friction (high)
+  4: friction (medium)
+  5: opportunity (medium)
+  6: opportunity (low)
+  7: win                     # Show to reinforce good patterns
+
+max_insights_shown:
+  checkpoint: 3              # At checkpoints during /run
+  companion: 10              # Full /companion output
+  status: 1                  # Just blocker count in /status
+```
+
+## Staleness Rules
+
+```yaml
+staleness:
+  # Don't repeat same insight too often
+  min_interval: 1 hour OR 5 TODOs
+
+  # Auto-resolve if condition no longer true
+  auto_resolve:
+    blocker: check every TODO
+    friction: check every 3 TODOs
+    opportunity: check every session
+
+  # Dismiss if user explicitly skips
+  user_dismiss: remember for session
+```

package/config/rules/profiles.md

@@ -0,0 +1,193 @@
+# Execution Profiles
+
+Profiles control the strictness/speed tradeoff during execution.
+
+## Available Profiles
+
+### ship-fast
+
+**Use for:** Client work, vibe coding, speed over polish
+
+```yaml
+profile: ship-fast
+
+guardrails:
+  no_secrets: true          # Always check for secrets
+  no_new_deps: false        # Allow new dependencies without asking
+  atomic_commit: false      # Batched commits OK
+  coverage_threshold: null  # No coverage requirement
+
+quality_threshold: 0.70     # Lower bar for "good enough"
+checkpoint_mode: feature    # Pause only at feature boundaries
+max_retries: 2              # Fail faster, move on
+on_error: skip              # Log and continue by default
+```
+
+### balanced (Default)
+
+**Use for:** Own product, good default for most work
+
+```yaml
+profile: balanced
+
+guardrails:
+  no_secrets: true          # Always check for secrets
+  no_new_deps: ask          # Ask before adding dependencies
+  atomic_commit: true       # One logical change per commit
+  coverage_threshold: null  # No strict coverage requirement
+
+quality_threshold: 0.85     # Standard quality bar
+checkpoint_mode: subfeature # Pause at subfeature boundaries
+max_retries: 3              # Standard retry limit
+on_error: ask               # Ask user on failure
+```
+
+### careful
+
+**Use for:** Existing codebases, high safety requirements
+
+```yaml
+profile: careful
+
+guardrails:
+  no_secrets: true          # Always check for secrets
+  no_new_deps: block        # Block new dependencies without explicit approval
+  atomic_commit: true       # Strict atomic commits
+  coverage_threshold: 80    # Require 80% coverage
+
+quality_threshold: 0.95     # High quality bar
+checkpoint_mode: todo       # Review after each TODO
+max_retries: 3              # Standard retry limit
+on_error: ask               # Always ask on failure
+```
+
+## Profile Selection
+
+### In CLAUDE.md (project default)
+
+```yaml
+# Project CLAUDE.md
+profile: balanced
+```
+
+### Per-command override
+
+```bash
+/run feature-1.2 --profile ship-fast
+/run "add auth" --profile careful
+```
+
+### Priority order
+
+1. Command-line flag (`--profile X`)
+2. Project CLAUDE.md (`profile: X`)
+3. Default (`balanced`)
+
+## Guardrail Definitions
+
+### no_secrets
+
+Scan for potential secrets in staged changes:
+- API keys, tokens
+- Passwords, credentials
+- Private keys
+- .env file contents
+
+**Actions:**
+- `true`: Block commit if secrets detected
+- `false`: No check (not recommended)
+
+### no_new_deps
+
+Control dependency additions:
+- `false`: Allow without asking
+- `ask`: Prompt user before adding
+- `block`: Fail if new dependency detected
+
+**Detection:** Compare package.json before/after TODO execution
+
+### atomic_commit
+
+Ensure commits are logically atomic:
+- `true`: One TODO = one commit (or related changes only)
+- `false`: Batch multiple TODOs into single commit
+
+### coverage_threshold
+
+Minimum test coverage requirement:
+- `null`: No requirement
+- `80`: Require 80% coverage
+- Fail if coverage drops below threshold
+
+## Quality Threshold
+
+The `quality_threshold` determines the minimum overall score for a TODO to pass:
+
+```
+Score calculation:
+  overall = (quality * 0.4) + (alignment * 0.4) + (guardrails * 0.2)
+
+Decision:
+  overall >= threshold        → proceed
+  overall >= threshold - 0.1  → proceed with comment
+  overall < threshold - 0.1   → retry
+```
+
+## Checkpoint Modes
+
+### todo
+
+Pause and show summary after every TODO. Maximum visibility.
+
+```
+✓ todo-1.1a-001 complete
+  Continue? [y/n]
+```
+
+### subfeature (Default)
+
+Pause at subfeature boundaries. Balanced approach.
+
+```
+✓ CHECKPOINT: subfeature-1.1a complete (7 TODOs)
+  Continue to subfeature-1.1b? [y/n]
+```
+
+### feature
+
+Pause only at feature boundaries. Minimal interruption.
+
+```
+✓ CHECKPOINT: feature-1.1 complete (14 TODOs)
+  Continue to feature-1.2? [y/n]
+```
+
+### none
+
+No pauses. Run until scope completes or error occurs.
+
+## Error Handling Modes
+
+### ask (Default)
+
+Pause execution and present options:
+```
+✗ todo-1.2a-005 failed (3/3)
+  [r]etry [s]kip [f]ix [a]bort: _
+```
+
+### skip
+
+Log error and continue to next TODO:
+```
+⚠ todo-1.2a-005 failed - skipping
+  Dependent TODOs may also fail
+```
+
+### abort
+
+Stop execution immediately:
+```
+✗ todo-1.2a-005 failed - aborting
+  State saved. Run /retry to try again.
+```

package/config/rules/recovery.md

@@ -0,0 +1,83 @@
+# Recovery & Troubleshooting
+
+Quick fixes for common problems.
+
+## Undo Claude's Changes (Checkpointing)
+
+Claude automatically creates checkpoints before every edit.
+
+### Rewind Options
+
+1. Press `Esc + Esc` (double-tap Escape)
+2. Or run `/rewind`
+3. Choose what to restore:
+   - **Conversation only**: Keep code changes, rewind chat
+   - **Code only**: Keep conversation, restore files
+   - **Both**: Full restore to previous state
+
+### When to Use
+
+- Claude made unwanted changes
+- Want to try a different approach
+- Need to compare before/after
+
+### Limitations
+
+- Only tracks changes made BY Claude (not external edits)
+- Bash command side effects (npm install, etc.) not reversible
+- Not a replacement for git - use for quick undo, git for history
+
+## progress.yaml Corrupted
+
+1. Check git history: `git log --oneline -- progress.yaml`
+2. Restore: `git checkout HEAD~1 -- progress.yaml`
+3. Or rebuild from roadmap/ files (source of truth for TODOs)
+
+## Branch in Bad State
+
+1. Stash work: `git stash`
+2. Return to main: `git checkout main && git pull`
+3. Create fresh branch: `git checkout -b feature/{name}`
+4. Apply stash if needed: `git stash pop`
+
+## Quality Check Keeps Failing
+
+1. Read the error carefully
+2. Fix one issue at a time
+3. After 3 failed attempts → STOP
+4. Ask: Is this a test issue or implementation issue?
+5. If stuck: `git stash` and ask for help
+
+## Context Feels Lost
+
+1. Run `/status` to see current state
+2. Read `progress.yaml` for context
+3. If still unclear: `/compact` and restart
+
+## Merge Conflicts
+
+1. Never force push to main
+2. Rebase feature branch: `git rebase main`
+3. Resolve conflicts file by file
+4. Run quality check after resolution
+
+## MCP Server Not Working
+
+1. Check if configured: look in `~/.claude.json` or `.mcp.json`
+2. Check if disabled: look in `settings.json` → `disabledMcpjsonServers`
+3. Restart Claude Code after config changes
+4. Run `/mcp` to see server status
+5. Test manually: e.g., `gh mcp` for github
+
+## Dashboard Not Generating
+
+1. Ensure `roadmap/` and `progress.yaml` exist
+2. Run `/init` if project not bootstrapped
+3. Check for YAML syntax errors in progress.yaml
+
+## Tests Pass Locally but Fail in CI
+
+1. Check for environment differences
+2. Look for hardcoded paths or timestamps
+3. Ensure all dependencies installed
+4. Check for race conditions in async tests