codingbuddy-rules 4.4.0 → 5.0.0

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. |

package/.ai-rules/skills/cross-repo-issues/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: cross-repo-issues
+description: Use when a bug or feature request belongs in an upstream, parent, or dependency repository rather than the current one. Guides detection, mapping, and safe cross-repo issue creation with user confirmation.
+---
+
+# Cross-Repo Issue Creation
+
+## Overview
+
+Not every issue belongs in the repository where it was discovered. Bugs in forked code belong upstream. Problems in a monorepo dependency belong in that dependency's repo. Filing issues in the wrong place wastes maintainer time and delays fixes.
+
+**Core principle:** ALWAYS confirm the target repository with the user before creating an issue elsewhere. Never auto-create issues in repositories you don't own.
+
+**Iron Law:**
+
+```
+NO CROSS-REPO ISSUE CREATION WITHOUT EXPLICIT USER CONFIRMATION
+```
+
+## When to Use
+
+- Bug discovered in forked code that should be reported upstream
+- Issue in a monorepo sub-package that belongs in the package's source repo
+- Bug in a third-party dependency that should be filed in the library's repo
+- Feature request that affects an upstream project
+- Security vulnerability that needs to be reported to the upstream maintainer
+
+**Use this ESPECIALLY when:**
+- Working in a fork and the bug exists in the original repo
+- A monorepo package wraps an external library and the bug is in the library
+- You need to coordinate fixes across multiple repositories
+
+## When NOT to Use
+
+- Issue is local to the current repository (use normal issue workflow)
+- You don't have access to the target repository
+- The upstream project is archived or unmaintained
+- Simple configuration issues that are project-specific
+
+## Configuration
+
+Add `upstreamRepos` to your `codingbuddy.config.json`:
+
+```json
+{
+  "upstreamRepos": {
+    ".": "original-owner/original-repo",
+    "packages/ui": "design-system/ui-kit",
+    "dep:react": "facebook/react"
+  }
+}
+```
+
+### Key Conventions
+
+| Key Pattern | Meaning | Example |
+|-------------|---------|---------|
+| `"."` | Current repo is a fork of this upstream | `"original-owner/repo"` |
+| `"packages/..."` | Monorepo package maps to external repo | `"org/package-repo"` |
+| `"dep:<name>"` | npm/pip dependency maps to its source repo | `"facebook/react"` |
+
+### Minimal Configuration
+
+For a simple fork, only one entry is needed:
+
+```json
+{
+  "upstreamRepos": {
+    ".": "upstream-owner/upstream-repo"
+  }
+}
+```
+
+## The Three Phases
+
+### Phase 1: Detect — Identify Where the Issue Belongs
+
+**Determine if the issue should go to another repository:**
+
+1. **Check the code origin**
+   - Is the buggy code from an upstream repo? (`git log --follow <file>`)
+   - Is it in a vendored or forked dependency?
+   - Does `git remote -v` show an upstream remote?
+
+2. **Check the config mapping**
+   - Read `upstreamRepos` from `codingbuddy.config.json`
+   - Match the affected file path or package name to a mapping key
+   - If no mapping exists, ask the user for the target repo
+
+3. **Verify the issue doesn't already exist upstream**
+   - Search upstream issues: `gh issue list -R <upstream> --search "<keywords>"`
+   - Check for duplicates before creating
+
+**Decision matrix:**
+
+| Scenario | Target Repo | Key |
+|----------|-------------|-----|
+| Bug in forked code | Upstream repo | `"."` |
+| Bug in monorepo sub-package's upstream | Package source repo | `"packages/<name>"` |
+| Bug in third-party dependency | Library repo | `"dep:<package>"` |
+| Bug in your own code | Current repo (stop here) | N/A |
+
+**Completion criteria:**
+- [ ] Target repository identified
+- [ ] Duplicate check completed
+- [ ] Issue is confirmed to belong upstream
+
+### Phase 2: Confirm — Get User Approval
+
+**MANDATORY: Never skip this phase.**
+
+Present the following to the user before proceeding:
+
+```
+Cross-Repo Issue Detected:
+  Source:  <current-repo> (<file-or-package>)
+  Target:  <upstream-repo>
+  Reason:  <why this belongs upstream>
+  Title:   <proposed issue title>
+
+Proceed with creating issue in <upstream-repo>? (y/n)
+```
+
+**Include in the confirmation:**
+- The exact target repository (`owner/repo`)
+- Why the issue belongs there (not here)
+- Proposed issue title and summary
+- Whether user has write access to the target repo
+
+**If user declines:**
+- Offer to create the issue in the current repo instead
+- Add a label like `upstream` or `external-dependency` for tracking
+
+**Completion criteria:**
+- [ ] User explicitly confirmed target repo
+- [ ] User approved issue title and content
+
+### Phase 3: Create — File the Issue
+
+**Create the issue in the confirmed target repository:**
+
+1. **Format the issue body**
+
+```markdown
+## Description
+
+<Clear description of the issue>
+
+## Reproduction
+
+- Repository: <your-repo> (discovered while working on <context>)
+- File/Package: <affected file or package>
+- Steps to reproduce: <steps>
+
+## Expected Behavior
+
+<what should happen>
+
+## Actual Behavior
+
+<what actually happens>
+
+## Environment
+
+- Version: <upstream version in use>
+- OS: <if relevant>
+
+## Additional Context
+
+Discovered in downstream repo: <your-repo-url>
+```
+
+1. **Create the issue**
+
+```bash
+gh issue create -R <owner/repo> \
+  --title "<title>" \
+  --body "<body>"
+```
+
+1. **Link back to current repo (optional)**
+   - Create a tracking issue in current repo referencing the upstream issue
+   - Add label: `blocked-upstream` or `waiting-upstream`
+
+```bash
+gh issue create \
+  --title "Tracking: <upstream-owner/repo>#<number>" \
+  --body "Upstream issue: <url>\nBlocked until upstream fix is available." \
+  --label "blocked-upstream"
+```
+
+**Completion criteria:**
+- [ ] Issue created in target repository
+- [ ] Issue URL shared with user
+- [ ] (Optional) Tracking issue created in current repo
+
+## Quick Reference
+
+| Phase | Action | Verification |
+|-------|--------|-------------|
+| **1. Detect** | Identify target repo from config or code origin | Target repo confirmed |
+| **2. Confirm** | Present plan to user, get explicit approval | User said yes |
+| **3. Create** | File issue via `gh`, link back if needed | Issue URL available |
+
+## Safety Checklist
+
+Before creating any cross-repo issue:
+
+- [ ] Target repo is correct (double-check `owner/repo`)
+- [ ] Issue doesn't already exist upstream (searched)
+- [ ] User explicitly approved the creation
+- [ ] Issue body is professional and includes reproduction steps
+- [ ] No sensitive/proprietary information in the issue body
+- [ ] You have access to create issues in the target repo
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "I'll just create it, the user won't mind" | STOP. Always confirm. Cross-repo actions are visible to external maintainers. |
+| "It's obviously an upstream bug" | Maybe. But confirm the target repo with the user first. |
+| "I'll skip the duplicate check" | Duplicate issues waste maintainer time and hurt your credibility. |
+| "The config mapping is enough confirmation" | Config maps repos, but the user must confirm each issue creation. |
+| "I'll include our internal details for context" | STOP. Review for sensitive information before posting to external repos. |
+| "No config? I'll guess the upstream repo" | Ask the user. Wrong repo = noise for unrelated maintainers. |
+
+## Examples
+
+### Fork → Upstream
+
+```
+Config: { "upstreamRepos": { ".": "expressjs/express" } }
+
+Detected: Bug in request parsing (inherited from upstream)
+Target:   expressjs/express
+Action:   Confirm with user → Create issue in expressjs/express
+```
+
+### Monorepo Package → Source Repo
+
+```
+Config: { "upstreamRepos": { "packages/icons": "design-org/icon-library" } }
+
+Detected: Missing icon in packages/icons (sourced from design-org/icon-library)
+Target:   design-org/icon-library
+Action:   Confirm with user → Create issue in design-org/icon-library
+```
+
+### Dependency → Library Repo
+
+```
+Config: { "upstreamRepos": { "dep:zod": "colinhacks/zod" } }
+
+Detected: Validation bug in zod usage
+Target:   colinhacks/zod
+Action:   Confirm with user → Search existing issues → Create if new
+```

package/.ai-rules/skills/database-migration/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: database-migration
 description: Use when performing database schema changes, data migrations, large table modifications, or when zero-downtime deployment is required - guides systematic, reversible database changes with rollback planning
+disable-model-invocation: true
 ---
 
 # Database Migration