codingbuddy-rules 4.5.0 → 5.1.0

package/.ai-rules/skills/build-fix/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: build-fix
+description: Use when build fails, TypeScript errors appear, or compilation breaks. Minimal diff fixes only — no refactoring, no architecture changes.
+user-invocable: true
+allowed-tools: Read, Edit, Grep, Glob, Bash
+---
+
+# Build Fix
+
+## Overview
+
+Build errors block everything. Fix them fast, fix them small, fix nothing else.
+
+**Core principle:** Fix ONLY what is broken. A build fix is not an opportunity to refactor, add features, or improve architecture. Touch the minimum lines required to restore a passing build.
+
+**Violating the letter of this process is violating the spirit of build fixing.**
+
+## The Iron Law
+
+```
+MINIMAL DIFF, NO ARCHITECTURE CHANGES — FIX WHAT'S BROKEN, NOTHING MORE
+```
+
+If your diff touches lines unrelated to the error, you are not build-fixing. You are refactoring. Stop.
+
+**No exceptions:**
+- "While I'm here, I'll clean up..." → No. Separate PR.
+- "This would be better as..." → No. Separate issue.
+- "The real problem is the architecture..." → No. File an issue, fix the build now.
+
+## When to Use
+
+Use for ANY build/compilation failure:
+- TypeScript compiler errors (`tsc --noEmit` failures)
+- Import/export resolution errors
+- Dependency version mismatches or missing packages
+- Configuration errors (tsconfig, webpack, vite, etc.)
+- CI/CD build pipeline failures
+- Module not found errors
+
+**Use this ESPECIALLY when:**
+- Build is red and blocking the team
+- CI pipeline is failing on compilation
+- Dependency update broke the build
+- Merge conflict left broken imports
+
+**Do NOT use when:**
+- Tests fail but build succeeds → use `systematic-debugging`
+- You want to improve code quality → use `refactoring`
+- You want to add features → use `brainstorming` + TDD
+- Runtime errors, not compile-time → use `error-analysis`
+
+## Error Classification
+
+First, classify the build error:
+
+| Class | Symptoms | Typical Minimal Fix |
+|-------|----------|-------------------|
+| **TypeScript Error** | `TS2345`, `TS2339`, `TS7006`, `TS2532` | Add type annotation, null check, or correct type |
+| **Import Error** | `Cannot find module`, `has no exported member` | Fix path, add missing export, correct import name |
+| **Dependency Error** | Version mismatch, missing peer dep, lockfile conflict | Align version, install missing package |
+| **Config Error** | `tsconfig.json` invalid, env var missing, wrong target | Fix config value, add missing variable |
+| **Syntax Error** | Unexpected token, missing bracket | Fix syntax at reported location |
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Read the Error
+
+**BEFORE attempting ANY fix:**
+
+1. **Read the FULL error output**
+   - Don't skim — read every line
+   - Note the error code (e.g., `TS2345`)
+   - Note the exact file and line number
+   - Note what the compiler expected vs. what it got
+
+2. **Classify the error** (see table above)
+   - What class does this error belong to?
+   - Is it a single error or a cascade?
+   - Cascading errors: fix the FIRST error only, then re-run
+
+3. **Count the errors**
+   - One error? Fix it directly.
+   - Many errors, same root cause? Fix the root, not each symptom.
+   - Many unrelated errors? Fix one at a time, verify after each.
+
+### Phase 2: Identify Root Cause
+
+**Find the MINIMUM change needed:**
+
+1. **Check recent changes**
+   ```bash
+   git diff HEAD~1        # What changed?
+   git log --oneline -5   # Recent commits
+   ```
+
+2. **Trace the error to its source**
+   - TypeScript error at line 42? Read line 42.
+   - Import error? Check if the export exists at the source.
+   - Dependency error? Check `package.json` versions.
+
+3. **Identify the scope**
+   - How many files need to change?
+   - If more than 3 files → question whether this is truly a build fix
+   - If it requires new files → this is not a build fix, it's a feature
+
+### Phase 3: Minimal Fix
+
+**Apply the SMALLEST possible change:**
+
+1. **One fix at a time**
+   - Change one thing
+   - Don't bundle fixes
+   - Don't "improve" surrounding code
+
+2. **Common minimal fixes**
+
+   ```typescript
+   // TypeScript: TS2345 - Type mismatch
+   // BAD: Rewrite the function with new types
+   // GOOD: Add the correct type annotation or assertion
+   const value = data as ExpectedType;
+
+   // TypeScript: TS2532 - Possibly undefined
+   // BAD: Refactor to eliminate the possibility
+   // GOOD: Add null check or optional chaining
+   const name = user?.name ?? 'default';
+
+   // Import: Cannot find module
+   // BAD: Restructure the module system
+   // GOOD: Fix the import path
+   import { Thing } from './correct/path';
+
+   // Dependency: Missing peer dependency
+   // BAD: Upgrade the entire dependency tree
+   // GOOD: Install the specific missing package
+   // $ yarn add missing-package@^required.version
+   ```
+
+3. **What NOT to do**
+   - Do NOT rename variables for "clarity"
+   - Do NOT extract functions for "reusability"
+   - Do NOT add error handling beyond what's needed
+   - Do NOT update unrelated dependencies
+   - Do NOT change code formatting
+
+### Phase 4: Verify
+
+**Confirm the build passes:**
+
+1. **Run the build command**
+   ```bash
+   # Run the same command that failed
+   yarn build          # or npm run build
+   tsc --noEmit        # TypeScript check
+   ```
+
+2. **Run tests to ensure no regressions**
+   ```bash
+   yarn test           # or npm test
+   ```
+
+3. **Check the diff**
+   ```bash
+   git diff
+   ```
+   - Is every changed line directly related to the error?
+   - Did you touch anything unrelated? Revert it.
+   - Is the diff as small as possible?
+
+4. **If build still fails**
+   - Read the NEW error message
+   - Is it the same error? → Your fix was wrong. Revert.
+   - Is it a different error? → Return to Phase 1 for the new error.
+   - Do NOT stack fixes without verifying between each one.
+
+## Red Flags — STOP and Return to Phase 1
+
+If you catch yourself thinking:
+
+| Thought | Reality |
+|---------|---------|
+| "While I'm fixing this, I'll also..." | Build fix. Nothing else. |
+| "This function should really be..." | File an issue. Fix the build. |
+| "The types are all wrong, let me redesign..." | Fix the ONE type error. Not all types. |
+| "I need to add a new abstraction..." | No new abstractions in a build fix. |
+| "Let me upgrade this dependency to latest..." | Only change the version if it fixes the error. |
+| "This code is messy, let me clean up..." | Messy code that compiles > clean code in a broken build. |
+| "The architecture caused this, so I should..." | Architecture changes are not build fixes. |
+
+**ALL of these mean: STOP. You are no longer build-fixing.**
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "The refactor prevents future build errors" | Future prevention is a separate task. Fix now. |
+| "It's just a small improvement" | Small improvements compound into large diffs. |
+| "The code is already open in my editor" | Being convenient doesn't make it a build fix. |
+| "No one will review a 1-line PR" | 1-line PRs are the BEST PRs. Ship it. |
+| "I need to understand the whole module" | You need to understand the error. Not the module. |
+| "The dependency is outdated anyway" | Outdated but compiling > updated and broken. |
+
+## Scope Guard
+
+Before committing, verify your changes pass the scope guard:
+
+```
+For EACH changed line, ask:
+  "Would the build fail without this specific change?"
+
+  YES → Keep it
+  NO  → Revert it
+```
+
+If any changed line fails the scope guard, you have scope creep. Remove it.
+
+## Quick Reference
+
+| Phase | Key Activity | Success Criteria |
+|-------|-------------|------------------|
+| **1. Read** | Read full error, classify, count | Know WHAT is broken |
+| **2. Identify** | Check changes, trace source | Know WHERE and WHY |
+| **3. Fix** | Smallest possible change | Minimal diff applied |
+| **4. Verify** | Build passes, tests pass, diff is clean | Build green, no extras |
+
+## Related Skills
+
+- **`error-analysis`** — For classifying and understanding error messages (Phase 1)
+- **`systematic-debugging`** — For runtime bugs, not compile-time errors
+- **`verification-before-completion`** — For confirming the fix before claiming success
+- **`refactoring`** — For when you actually WANT to improve structure (not during build fix)

package/.ai-rules/skills/code-explanation/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: code-explanation
 description: Use when explaining complex code to new team members, conducting code reviews, onboarding, or understanding unfamiliar codebases. Provides structured analysis from high-level overview to implementation details.
+context: fork
+agent: Explore
+allowed-tools: Read, Grep, Glob
+argument-hint: [file-or-symbol]
 ---
 
 # Code Explanation

package/.ai-rules/skills/context-management/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: context-management
 description: Use when working on long tasks that span multiple sessions, when context compaction is a concern, or when decisions from PLAN mode need to persist through ACT and EVAL modes.
+user-invocable: false
 ---
 
 # Context Management

package/.ai-rules/skills/cost-budget/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: cost-budget
+description: >-
+  Use when managing AI session costs, setting budget limits, or preventing
+  cost overruns in autonomous workflows like taskMaestro, autopilot, ralph
+  loops, and parallel agent execution. Defines cost tracking protocol,
+  threshold alerts, and auto-pause mechanism.
+---
+
+# Cost Budget Management
+
+## Overview
+
+Autonomous AI workflows can consume unbounded resources without guardrails. A single runaway loop — autopilot, ralph, or a multi-wave taskMaestro session — can burn through API credits before anyone notices.
+
+**Core principle:** Every autonomous workflow must have a cost ceiling. No budget means unlimited spend.
+
+**Iron Law:**
+```
+NO AUTONOMOUS EXECUTION WITHOUT A DECLARED BUDGET
+If no budget is set, warn before starting. If budget is exceeded, pause and require override.
+```
+
+## When to Use
+
+- Starting any autonomous workflow (autopilot, ralph, ultrawork, taskMaestro)
+- Running parallel agents across multiple panes or worktrees
+- Multi-session tasks expected to exceed a few dollars
+- Any workflow where cost visibility matters to the user
+- Setting up per-project or per-team cost guardrails
+
+## When NOT to Use
+
+- Single interactive conversations (cost is negligible)
+- Quick one-off questions or file reads
+- Workflows where the user explicitly opts out of budget tracking
+
+---
+
+## Cost Tracking Protocol
+
+### Data Collection Points
+
+Cost data is collected at three levels:
+
+| Level | Scope | Data Source | Granularity |
+|-------|-------|-------------|-------------|
+| **Session** | Single Claude Code session | Token usage from API responses | Per-request |
+| **Wave** | One taskMaestro wave (N parallel panes) | Aggregated session costs per pane | Per-wave |
+| **Project** | All sessions in a project directory | Cumulative across sessions | Running total |
+
+### Cost Estimation
+
+```
+Cost = (input_tokens × input_price) + (output_tokens × output_price)
+
+Model pricing (per 1M tokens):
+  opus:   input=$15.00  output=$75.00
+  sonnet: input=$3.00   output=$15.00
+  haiku:  input=$0.25   output=$1.25
+```
+
+**Note:** Prices are approximate and should be updated when model pricing changes. The skill defines the protocol, not hardcoded prices.
+
+### Collection Methods
+
+1. **Environment variables** (preferred):
+   ```bash
+   export COST_BUDGET_USD=10.00          # Total budget in USD
+   export COST_BUDGET_TOKENS=5000000     # Alternative: token-based budget
+   export COST_BUDGET_SCOPE=project      # session | wave | project
+   ```
+
+2. **Configuration file** (`codingbuddy.config.json`):
+   ```json
+   {
+     "costBudget": {
+       "limit": 10.00,
+       "currency": "USD",
+       "scope": "project",
+       "thresholds": {
+         "info": 0.50,
+         "warn": 0.80,
+         "critical": 1.00
+       }
+     }
+   }
+   ```
+
+3. **MCP state** (runtime tracking):
+   ```
+   state_write(mode: "cost-budget", state: {
+     "spent": "4.52",
+     "budget": "10.00",
+     "tokens_used": "2340000"
+   })
+   ```
+
+### Token Counting
+
+Track tokens per request and accumulate:
+
+```
+Per request:
+  input_tokens  → from API response headers or usage field
+  output_tokens → from API response headers or usage field
+  cost_usd      → calculated from model pricing
+
+Accumulated:
+  session_total  = sum(all request costs in session)
+  wave_total     = sum(all session costs in wave)
+  project_total  = sum(all wave/session costs in project)
+```
+
+---
+
+## Budget Configuration
+
+### Threshold Levels
+
+Three threshold levels trigger different actions:
+
+| Level | Default | Trigger | Action |
+|-------|---------|---------|--------|
+| **INFO** | 50% of budget | Informational milestone | Log to terminal, continue |
+| **WARN** | 80% of budget | Approaching limit | Terminal alert + optional webhook, continue |
+| **CRITICAL** | 100% of budget | Budget exhausted | Terminal alert + webhook + **auto-pause** |
+
+### Budget Scopes
+
+| Scope | Description | Use Case |
+|-------|-------------|----------|
+| `session` | Single CLI session | Quick tasks, one-off work |
+| `wave` | One taskMaestro wave | Per-wave cost control in parallel execution |
+| `project` | Cumulative across all sessions | Long-running projects with total budget |
+
+### Budget Override
+
+When the CRITICAL threshold is reached, the workflow pauses. To continue:
+
+```bash
+# Explicit override for current session
+export COST_BUDGET_OVERRIDE=true
+
+# Or increase the budget
+export COST_BUDGET_USD=20.00
+```
+
+**Override rules:**
+- Override must be explicit — never auto-continue past 100%
+- Override resets the threshold to the new budget
+- Log every override event for audit trail
+- Override does not disable future threshold checks
+
+---
+
+## Alert Channels
+
+### Terminal Notification (Default)
+
+Always active. Alerts appear inline in the terminal:
+
+```
+┌─────────────────────────────────────────────┐
+│ 💰 COST ALERT [INFO]                        │
+│ Budget: $5.00 / $10.00 (50%)               │
+│ Tokens: 1.2M used                           │
+│ Status: Continuing                           │
+└─────────────────────────────────────────────┘
+```
+
+```
+┌─────────────────────────────────────────────┐
+│ ⚠️  COST ALERT [WARN]                       │
+│ Budget: $8.00 / $10.00 (80%)               │
+│ Tokens: 3.8M used                           │
+│ Status: Approaching limit — review spend    │
+└─────────────────────────────────────────────┘
+```
+
+```
+┌─────────────────────────────────────────────┐
+│ 🛑 COST ALERT [CRITICAL]                    │
+│ Budget: $10.00 / $10.00 (100%)             │
+│ Tokens: 5.0M used                           │
+│ Status: PAUSED — override required          │
+│                                             │
+│ To continue:                                │
+│   export COST_BUDGET_OVERRIDE=true          │
+│   # or increase: export COST_BUDGET_USD=20  │
+└─────────────────────────────────────────────┘
+```
+
+### Webhook (Optional)
+
+For remote notifications (Slack, Discord, PagerDuty, custom endpoints):
+
+```bash
+export COST_ALERT_WEBHOOK_URL=https://hooks.slack.com/services/...
+export COST_ALERT_WEBHOOK_EVENTS=warn,critical  # which levels trigger webhook
+```
+
+**Webhook payload:**
+```json
+{
+  "event": "cost_alert",
+  "level": "warn",
+  "budget_usd": 10.00,
+  "spent_usd": 8.00,
+  "percent": 80,
+  "tokens_used": 3800000,
+  "scope": "project",
+  "project": "codingbuddy",
+  "session_id": "abc-123",
+  "timestamp": "2026-03-22T14:00:00Z"
+}
+```
+
+**Webhook rules:**
+- Webhook failures must not block the workflow
+- Retry once on failure, then log and continue
+- Include project name and session ID for traceability
+
+---
+
+## Auto-Pause Mechanism
+
+### Pause Behavior
+
+When the CRITICAL threshold (100%) is reached:
+
+1. **Stop** — Halt the current autonomous loop iteration
+2. **Alert** — Display terminal notification + fire webhook
+3. **Save state** — Persist current progress to context document
+4. **Wait** — Do not proceed until explicit override or budget increase
+5. **Log** — Record the pause event with timestamp and spend data
+
+### Pause Points by Workflow
+
+| Workflow | Pause Point | What Happens |
+|----------|-------------|--------------|
+| **autopilot** | Between iterations | Current iteration completes, next blocked |
+| **ralph** | Between architect reviews | Current cycle completes, next blocked |
+| **ultrawork** | Between task assignments | Current task completes, next blocked |
+| **taskMaestro** | Between waves | Current wave completes, next wave blocked |
+| **parallel agents** | At agent completion | Running agents finish, no new agents spawn |
+
+**Key:** Never interrupt mid-operation. Always complete the current atomic unit, then pause.
+
+### Override Protocol
+
+```
+1. User sees CRITICAL alert
+2. User reviews spend breakdown
+3. User decides:
+   a. Stop entirely → no action needed, workflow stays paused
+   b. Continue with new budget → export COST_BUDGET_USD=<new_amount>
+   c. Continue without limit → export COST_BUDGET_OVERRIDE=true
+4. Workflow resumes from saved state
+```
+
+---
+
+## TaskMaestro Integration
+
+### Per-Wave Budget Allocation
+
+When running taskMaestro with a project budget, allocate per-wave:
+
+```
+Total budget: $20.00
+Estimated waves: 4
+Per-wave allocation: $5.00 per wave
+
+Wave 1: $5.00 budget → actual: $3.20 → remaining pool: $16.80
+Wave 2: $5.60 budget (redistributed) → actual: $4.10 → remaining pool: $12.70
+Wave 3: $6.35 budget (redistributed) → ...
+```
+
+**Redistribution rule:** Unspent budget from completed waves rolls into remaining waves equally.
+
+### Cross-Pane Aggregation
+
+Each tmux pane in a taskMaestro wave runs an independent session. Aggregation:
+
+```
+Wave cost = sum(pane_1_cost + pane_2_cost + ... + pane_N_cost)
+
+Tracking via shared state:
+  state_write(mode: "cost-budget", state: {
+    "wave_id": "wave-2",
+    "pane_id": "pane-3",
+    "pane_cost": "1.25",
+    "wave_budget": "5.60"
+  })
+```
+
+### Wave-Level Threshold Checks
+
+After each pane completes, check the wave aggregate:
+
+```
+1. Pane completes → reports cost to shared state
+2. Orchestrator reads all pane costs for current wave
+3. Calculate: wave_spent = sum(all pane costs)
+4. Check: wave_spent vs wave_budget
+5. If WARN → alert, continue remaining panes
+6. If CRITICAL → let running panes finish, block next wave
+```
+
+---
+
+## Verification Checklist
+
+Before starting an autonomous workflow:
+
+- [ ] Budget is declared (`COST_BUDGET_USD` or config)
+- [ ] Scope is appropriate (`session` / `wave` / `project`)
+- [ ] Thresholds are configured (default: 50/80/100%)
+- [ ] Alert channels are set up (terminal is automatic)
+- [ ] Webhook URL is valid (if using webhook alerts)
+- [ ] Override protocol is understood by the operator
+
+During execution:
+
+- [ ] Cost is tracked per request
+- [ ] Thresholds trigger correct alert level
+- [ ] WARN alerts appear in terminal
+- [ ] CRITICAL threshold pauses the workflow
+- [ ] State is saved before pause
+- [ ] Override resumes workflow correctly
+
+After completion:
+
+- [ ] Total cost is logged
+- [ ] Cost breakdown is available (per-session, per-wave)
+- [ ] Budget vs actual comparison is recorded
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "It's just a quick autopilot run, no budget needed" | Quick runs become long runs. Set a budget. |
+| "I'll check the cost later" | Later is after the money is spent. Track now. |
+| "The budget is too small, I'll just override" | If you're always overriding, your budget is wrong. Increase it properly. |
+| "Token counting is too much overhead" | API responses include token counts. No extra cost to read them. |
+| "I'll skip the webhook, terminal alerts are enough" | You won't see terminal alerts if you walk away. Set up webhooks for unattended runs. |
+| "One pane won't affect the total budget much" | Parallel panes multiply cost linearly. 8 panes = 8x the cost rate. |