codebyplan 1.5.1 → 1.8.0

package/templates/skills/cbp-build-cc-memory/SKILL.md

@@ -0,0 +1,201 @@
+---
+scope: org-shared
+name: cbp-build-cc-memory
+description: Create or update an auto-memory entry under the Claude Code auto-memory directory per the official spec. Handles path-slug encoding, per-repo redirection via autoMemoryDirectory, MEMORY.md index, and per-entry typing (user/feedback/project/reference).
+argument-hint: "[entry-name] [--type=user|feedback|project|reference] [--repo-local]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir *), Bash(cat *), Bash(ls *), Bash(jq *)
+effort: xhigh
+---
+
+# Build Claude Code Auto-Memory Entry
+
+Create or update an entry in Claude Code's auto-memory directory per the official Claude Code memory spec (section _Auto memory_).
+
+Auto memory is machine-local knowledge Claude accumulates across sessions. Only the first 200 lines or 25KB of `MEMORY.md` load at session start.
+
+## Arguments
+
+`$ARGUMENTS` — entry name (kebab-case, used as filename). Flags: `--type=user|feedback|project|reference` (see [reference/memory-types.md](reference/memory-types.md)), `--repo-local` (store at `.claude/memory/` via user-scope `autoMemoryDirectory` override; see Step 1).
+
+## When to Use
+
+| Situation                                                    | Action                                 |
+| ------------------------------------------------------------ | -------------------------------------- |
+| User tells you something about themselves                    | Save as `user` memory                  |
+| User corrects you, or confirms a non-obvious approach worked | Save as `feedback` memory              |
+| User shares project info (deadline, stakeholder, WHY)        | Save as `project` memory               |
+| User points to external system (Linear, Slack, dashboard)    | Save as `reference` memory             |
+| User says "remember this" / "save this"                      | Save immediately, pick type by content |
+| User says "forget X"                                         | Find and delete the entry              |
+
+Do **NOT** save:
+
+- Things derivable from `git log`, `git blame`, or reading the current code
+- Debugging fixes (they're already in the commit)
+- CLAUDE.md content (different mechanism)
+- Ephemeral task/conversation state
+
+## Instructions
+
+### Step 1 — Locate the memory directory
+
+**Default (global auto-memory):** `~/.claude/projects/<project-slug>/memory/`.
+
+The `<project-slug>` is the **absolute git repo path with `/` replaced by `-`**, e.g. repo at `/Users/alice/my-app` → slug `-Users-alice-my-app`. The `<project>` placeholder in the docs is not a friendly name — it's this slug.
+
+Resolve it deterministically:
+
+```bash
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+SLUG="$(echo "$REPO_ROOT" | sed 's|/|-|g')"
+DEFAULT_DIR="$HOME/.claude/projects/$SLUG/memory"
+```
+
+Worktrees get a separate slug (the spec says all worktrees share one dir, but the runtime slugs by path — verify with `ls ~/.claude/projects/ | grep "$SLUG"`).
+
+**Override (`autoMemoryDirectory`):** the runtime reads this key only from **user, local, or managed-policy** settings — never from project settings. Resolve in that priority order, then fall back to the default path.
+
+```bash
+# Check overrides in priority order
+for f in "$HOME/.claude/settings.json" ".claude/settings.local.json"; do
+  override=$(jq -r '.autoMemoryDirectory // empty' "$f" 2>/dev/null)
+  [ -n "$override" ] && MEMORY_DIR="${override/#\~/$HOME}" && break
+done
+MEMORY_DIR="${MEMORY_DIR:-$DEFAULT_DIR}"
+mkdir -p "$MEMORY_DIR"
+```
+
+### Step 2 — Pick scope: global vs repo-local vs user-global
+
+Three valid configurations (decide before writing):
+
+| Scope                        | Where it lives                      | How to enable                                                                    | When to use                                          |
+| ---------------------------- | ----------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| Global auto-memory (default) | `~/.claude/projects/<slug>/memory/` | No config — works by default                                                     | Personal learnings specific to this repo             |
+| Repo-local                   | `<repo>/.claude/memory/`            | Set `autoMemoryDirectory` in `.claude/settings.local.json` (NOT `settings.json`) | Team-shared repo memory; also gitignore if sensitive |
+| User-global                  | `~/my-notes/` or similar            | Set `autoMemoryDirectory` in `~/.claude/settings.json`                           | One memory pool across all your projects             |
+
+**CBP default: global.** Switch to repo-local only when (a) the memory would help a teammate on the same repo, (b) isn't already in CLAUDE.md, and (c) you're comfortable committing it (or gitignoring deliberately). Prefer global for automatic feedback-type memories.
+
+**Never save credentials, secrets, or PII** to any memory scope. Memory is loaded into every session.
+
+**Memory vs CLAUDE.md vs rules:**
+
+| Destination              | What belongs                                                                           |
+| ------------------------ | -------------------------------------------------------------------------------------- |
+| CLAUDE.md                | Stable, team-shared facts needed every session (tech stack, branch strategy, repo IDs) |
+| `.claude/rules/`         | Behavioural constraints enforced on specific files (paths-scoped)                      |
+| Auto-memory (global)     | Personal learnings, user's working style, past corrections                             |
+| Auto-memory (repo-local) | Team facts not yet stable enough for CLAUDE.md                                         |
+
+Don't duplicate across destinations.
+
+**Repo-local setup** (if `--repo-local` or user asks):
+
+1. Invoke `/cbp-build-cc-settings` to add `"autoMemoryDirectory": "./.claude/memory"` to `.claude/settings.local.json` (user-scope is also accepted). Project-scope `settings.json` is **rejected** by the runtime.
+2. Create the directory: `mkdir -p .claude/memory`
+3. Decide: commit to git (team-shared) or add to `.gitignore` (personal in-repo).
+
+### Step 3 — Read the existing MEMORY.md
+
+```bash
+cat "$MEMORY_DIR/MEMORY.md" 2>/dev/null || echo "(no MEMORY.md yet)"
+```
+
+MEMORY.md is the **index**, not a store. One-line pointer per entry, under ~150 chars. It's loaded every session (first 200 lines / 25KB). Keep it tight.
+
+### Step 4 — Check for an existing entry
+
+```bash
+ls "$MEMORY_DIR" | grep -i "{topic-keyword}"
+```
+
+If a related entry exists:
+
+- Updating an existing fact → edit that file
+- Same topic, different angle → edit or merge
+- New but adjacent → create new file, cross-link from MEMORY.md
+
+Never duplicate.
+
+### Step 5 — Classify the entry
+
+Pick the right type. Details: [reference/memory-types.md](reference/memory-types.md).
+
+| Type        | Saves                         | Example trigger                           |
+| ----------- | ----------------------------- | ----------------------------------------- |
+| `user`      | Who they are, how they work   | "I've been writing Go for 10 years"       |
+| `feedback`  | Corrections AND confirmations | "stop summarizing", "yeah that was right" |
+| `project`   | Work context, deadlines, WHY  | "we're freezing after Thursday"           |
+| `reference` | Pointers to external systems  | "bugs live in Linear project INGEST"      |
+
+### Step 6 — Write the entry file
+
+Read `${CLAUDE_SKILL_DIR}/templates/memory-entry.md` for the canonical format.
+
+Filename convention: `{type}_{topic}.md` (e.g. `feedback_testing.md`, `user_role.md`, `project_q1_freeze.md`).
+
+Frontmatter:
+
+```yaml
+---
+name: Human-readable entry name
+description: One-line relevance hint — used to judge if this memory matters in a new conversation
+type: user | feedback | project | reference
+---
+```
+
+For `feedback` and `project` types, structure the body as:
+
+1. Lead line — the rule or fact itself
+2. **Why:** — reason the user gave (incident, preference, deadline)
+3. **How to apply:** — when this guidance kicks in
+
+See [examples/feedback-memory.md](examples/feedback-memory.md) and [examples/project-memory.md](examples/project-memory.md).
+
+### Step 7 — Update MEMORY.md
+
+MEMORY.md is an index, not a memory. No frontmatter. One line per entry:
+
+```markdown
+# Memory
+
+- [Title](file.md) — one-line hook
+- [Another title](another.md) — one-line hook
+```
+
+Keep each line under ~150 characters. Organize by topic, not chronology.
+
+### Step 8 — Handle absolute dates
+
+Convert relative dates to absolute when saving:
+
+| User said      | Save as                     |
+| -------------- | --------------------------- |
+| "by Thursday"  | `2026-04-23` (today + days) |
+| "next week"    | `2026-04-29 to 2026-05-05`  |
+| "last quarter" | `2026-Q1`                   |
+
+Memories persist — relative dates rot.
+
+### Step 9 — Verify with `/memory`
+
+Run `/memory` in Claude Code to browse the directory. New entries appear immediately in the index load (on next session).
+
+## Integration
+
+- **Triggered by**: user asking to remember, feedback during work
+- **Reads**: `${CLAUDE_SKILL_DIR}/templates/*.md`, `${CLAUDE_SKILL_DIR}/reference/*.md`
+- **Writes**: resolved `$MEMORY_DIR` (default `~/.claude/projects/<slug>/memory/`, or `autoMemoryDirectory` override)
+- **Related skills**: `/cbp-build-cc-settings` (configure `autoMemoryDirectory`), `/cbp-build-cc-claude-file` (team-shared facts → CLAUDE.md, not memory), `/cbp-build-cc-rule` (behavioural constraints → rules)
+
+## Key Rules
+
+- `<project>` in the docs is a **slug** (`/` → `-`), not a friendly name
+- `autoMemoryDirectory` is **rejected** from project `settings.json` — only user / local / managed-policy accept it
+- MEMORY.md is an **index** — pointer lines only, no frontmatter, no long content
+- Lines after 200 (or 25KB) are not loaded at session start — keep MEMORY.md concise
+- Global auto memory is machine-local; for team-shared use repo-local and commit to git
+- Verify facts before recommending — memory can go stale; re-read the code when acting
+- When the user says "don't use memory," do not cite or act on it for this session
+- For a memory that names a file/function/flag — grep before relying on it

package/templates/skills/cbp-build-cc-memory/examples/feedback-memory.md

@@ -0,0 +1,11 @@
+---
+name: Integration tests hit a real database
+description: Never mock the DB in integration tests — prior incident taught the team this
+type: feedback
+---
+
+Integration tests must hit a real database, not mocks.
+
+**Why:** Prior incident (2025-Q4) — mocked tests passed but a prod migration failed because the mock diverged from the real schema. Team agreed to never mock the DB in integration tests afterwards.
+
+**How to apply:** Whenever writing or reviewing tests under `tests/integration/`, `apps/*/tests/integration/`, or anything tagged `@integration`. Unit tests may still mock. If you see a mock in an integration test, flag it.

package/templates/skills/cbp-build-cc-memory/examples/project-memory.md

@@ -0,0 +1,11 @@
+---
+name: Auth middleware rewrite is compliance-driven
+description: Compliance context for the auth rewrite — affects scope decisions
+type: project
+---
+
+Auth middleware rewrite is driven by legal/compliance requirements around session token storage, not tech-debt cleanup.
+
+**Why:** Legal flagged the current middleware in 2026-Q1 because session tokens are stored in a way that doesn't meet the new compliance requirements. Deadline: 2026-05-15.
+
+**How to apply:** When making scope decisions on this rewrite, favour compliance over ergonomics. Don't add unrelated refactors. Don't defer compliance work for "cleaner" architecture. If asked to trade off — compliance wins.

package/templates/skills/cbp-build-cc-memory/examples/reference-memory.md

@@ -0,0 +1,13 @@
+---
+name: Pipeline bugs tracked in Linear INGEST
+description: External system pointer for pipeline-related tickets and dashboards
+type: reference
+---
+
+Pipeline bugs are tracked in Linear project **INGEST** (https://linear.app/acme/team/INGEST).
+
+Related dashboards:
+- `grafana.internal/d/api-latency` — oncall latency dashboard; check when editing request-path code
+- `https://status.acme.com/pipeline` — customer-facing pipeline status
+
+When the user mentions a pipeline bug by ID (e.g. INGEST-4123), look there first.

package/templates/skills/cbp-build-cc-memory/examples/user-memory.md

@@ -0,0 +1,14 @@
+---
+name: User role and frontend experience
+description: User's technical background — use to calibrate explanation depth
+type: user
+---
+
+User has deep Go backend experience (10+ years) and is newly touching the React side of this repo.
+
+Frame frontend explanations in terms of backend analogues:
+- Components ≈ structs + methods
+- Hooks ≈ middleware-like composition
+- React state ≈ mutex-guarded field on a struct
+
+Skip JS fundamentals (closures, async). Go deeper on React-specific patterns (render cycles, effect semantics, ref semantics).

package/templates/skills/cbp-build-cc-memory/reference/memory-types.md

@@ -0,0 +1,59 @@
+# Memory Types Reference
+
+Four discrete types of auto-memory entries. Pick by content, not by user phrasing.
+
+## `user`
+
+**Contains:** role, goals, responsibilities, existing knowledge.
+
+**Save when:** you learn details about who the user is or how they collaborate. Tailors future behaviour.
+
+**Skip when:** the info would be a negative judgement, or it's not relevant to work.
+
+**Example trigger:** "I'm a data scientist investigating logging."
+
+## `feedback`
+
+**Contains:** guidance the user has given about how to approach work — corrections AND confirmations.
+
+**Save when:**
+- User corrects you ("no not that", "don't", "stop")
+- User confirms a non-obvious approach worked ("yes exactly", "that was the right call")
+
+**Structure:** rule → **Why:** (reason) → **How to apply:** (when).
+
+**Example trigger:** "stop summarizing at the end of every response."
+
+Record successes too — otherwise you drift toward cautious defaults and away from validated approaches.
+
+## `project`
+
+**Contains:** ongoing work context — goals, deadlines, incidents, stakeholders, WHY behind initiatives.
+
+**Save when:** you learn who is doing what, why, or by when — things not derivable from code or git history.
+
+**Convert dates to absolute** when saving (never "Thursday" — always `2026-04-23`).
+
+**Structure:** fact → **Why:** → **How to apply:**.
+
+**Example trigger:** "we're freezing after Thursday for the mobile cut."
+
+Project memories decay fast. The **Why** helps future-you judge whether the memory is still load-bearing.
+
+## `reference`
+
+**Contains:** pointers to external systems (Linear, Slack, Grafana, Notion, Confluence).
+
+**Save when:** user mentions a resource by name. Memory just says *where to look*.
+
+**Example trigger:** "the Grafana dashboard at grafana.internal/d/api-latency is what oncall watches."
+
+## What NOT to save (any type)
+
+- Code patterns, file paths, project structure (re-derivable from code)
+- Git history, who-changed-what (`git log`, `git blame` are authoritative)
+- Debugging fixes (already in the commit; PR body has the why)
+- CLAUDE.md content (that's a different mechanism)
+- Ephemeral task state (in-progress work, current conversation)
+
+Applies **even when the user asks you to save**. If they ask to save a PR list, ask what was *surprising* — that's the part worth keeping.

package/templates/skills/cbp-build-cc-memory/reference/when-to-save.md

@@ -0,0 +1,62 @@
+# When to Save vs Skip
+
+Decision tree for auto-memory entries.
+
+## Save immediately
+
+| Signal | Type |
+|--------|------|
+| User corrects you ("no", "don't", "stop") | feedback |
+| User confirms a non-obvious choice worked | feedback |
+| User shares their role, experience, preferences | user |
+| User explains **why** something is the way it is | project |
+| User names an external system (ticket tracker, dashboard, channel) | reference |
+| User says "remember this" / "save this" | pick by content |
+
+## Skip
+
+- "What's the status of X?" — derivable from code/DB, don't save
+- "Here's the PR list" — derivable from `gh pr list`, don't save unless something was surprising
+- Fix you just made — the commit has the why, don't duplicate
+- Architecture you just read — re-read when needed
+
+## Update an existing entry instead of creating
+
+Before writing a new file:
+
+```bash
+ls ~/.claude/projects/<project>/memory/ | grep -i {topic}
+```
+
+If anything matches:
+- Fact has changed → edit the existing file, update description if needed
+- New angle on same topic → merge into existing, keep one file per topic
+
+## Remove stale entries
+
+When a memory turns out wrong:
+
+1. Delete the file
+2. Remove the index line from MEMORY.md
+
+When a memory references something that no longer exists (file renamed/removed):
+
+1. Grep the codebase for the referenced symbol/path
+2. If truly gone, delete the memory
+3. If renamed, update the memory
+
+## Verify before acting
+
+A memory naming a specific function, file, or flag is a claim that it existed *when written*. Before recommending it:
+
+- Memory names a file path → check the file exists
+- Memory names a function or flag → grep for it
+- User is about to act on your recommendation → always verify first
+
+"Memory says X exists" is not the same as "X exists now."
+
+## Session gates
+
+- `/clear` wipes conversation context but NOT memory — memory reloads on next session
+- When the user says "ignore memory" or "don't use memory" — do not cite or act on memory content for this session; do not say "memory says X"
+- When memory conflicts with current code — trust the code, update or remove the stale memory

package/templates/skills/cbp-build-cc-memory/templates/MEMORY-index.md

@@ -0,0 +1,4 @@
+# Memory
+
+- [Entry title](filename.md) — one-line hook under ~150 chars
+- [Another entry](another.md) — one-line hook

package/templates/skills/cbp-build-cc-memory/templates/memory-entry.md

@@ -0,0 +1,15 @@
+---
+name: Entry title
+description: One-line relevance hint — future sessions read this to decide if the memory matters
+type: user | feedback | project | reference
+---
+
+[Memory content]
+
+# For feedback and project types, structure as:
+
+The rule or fact itself in one sentence.
+
+**Why:** The reason the user gave — often a past incident or strong preference.
+
+**How to apply:** When/where this guidance kicks in, so future-you can judge edge cases.

package/templates/skills/cbp-build-cc-mode/SKILL.md

@@ -0,0 +1,99 @@
+---
+scope: org-shared
+name: cbp-build-cc-mode
+description: Audit + apply the CHK-109 model/effort matrix across every authoring skill and agent under `packages/codebyplan-package/templates/`. Bare invocation walks all SKILL.md and AGENT.md files and reports frontmatter gaps; with a path argument, edits the target file's frontmatter to the matrix-decided values.
+argument-hint: "[path-to-agent-or-skill]"
+allowed-tools: Read, Write, Edit, Glob, Grep
+effort: xhigh
+---
+
+# Build CC Mode
+
+Audit or apply the canonical `model:` + `effort:` frontmatter convention across every authoring-source skill (`packages/codebyplan-package/templates/skills/*/SKILL.md`) and agent (`packages/codebyplan-package/templates/agents/*.md`). Bare invocation = audit; path argument = apply.
+
+## When to Use
+
+- Authoring a new agent or skill — look up the matrix below to pick the right `model` + `effort` before writing the frontmatter.
+- Sweeping `packages/codebyplan-package/templates/` for conformance after a refactor or version bump.
+- Onboarding a new exception (e.g., a fresh haiku-low skill) — record the rationale in the matrix here first, then apply.
+
+## Decision Matrix
+
+### Default (applies to all agents and most skills)
+
+`model: sonnet` + `effort: xhigh`
+
+Eleven of the 12 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-improve-round`, `cbp-research`, `cbp-round-executor`, `cbp-security-agent`, `cbp-task-check`, `cbp-task-planner`, `cbp-test-e2e-agent`, `cbp-testing-qa-agent`). The 12th — `cbp-mechanical-edits` — is an explicit haiku-low exception (see below). 27 skills take the default: cbp-round-start, cbp-round-input, cbp-round-execute, cbp-task-create, cbp-task-start, cbp-task-complete, cbp-task-testing, cbp-checkpoint-create, cbp-checkpoint-check, cbp-checkpoint-end, cbp-build-cc-mode, cbp-build-cc-agent, cbp-build-cc-skill, cbp-build-cc-rule, cbp-build-cc-claude-file, cbp-build-cc-memory, cbp-build-cc-settings, cbp-frontend-a11y, cbp-frontend-design, cbp-frontend-ui, cbp-frontend-ux, cbp-session-end, cbp-ship, cbp-ship-configure, cbp-supabase-setup, cbp-supabase-migrate, cbp-supabase-branch-check.
+
+### Effort-lowered skills (5)
+
+`model: sonnet` + `effort: high`. Opus reasoning retained; effort dropped from `xhigh` because the skill body is summary/dispatch rather than deep authoring.
+
+| skill             | model  | effort | reason                                                                                                            |
+| ----------------- | ------ | ------ | ----------------------------------------------------------------------------------------------------------------- |
+| cbp-round-end         | sonnet | high   | Spawns cbp-improve-round agent; skill body summarises + presents user findings-decision — lighter than xhigh suffices |
+| cbp-task-check        | sonnet | high   | Thin orchestrator over spawned cbp-task-check agent; inline-fallback path keeps Opus for safety                       |
+| cbp-checkpoint-update | sonnet | high   | Status updates + context patches mostly; lighter than xhigh                                                       |
+| cbp-ship-main         | sonnet | high   | Production-impacting PR creation; keep Opus reasoning but drop effort                                             |
+| cbp-merge-main        | sonnet | high   | Long-lived-branch integration merge — surgical conflict resolution, no authoring                                  |
+
+### Haiku-low skills (9)
+
+`model: haiku` + `effort: low`. Pure mechanical / dispatch / templated work.
+
+| skill                  | model | effort | reason                                                                                   |
+| ---------------------- | ----- | ------ | ---------------------------------------------------------------------------------------- |
+| cbp-round-update           | haiku | low    | Pure mechanical: read git status, check approvals, route per rules                       |
+| cbp-round-check            | haiku | low    | Run build/lint/types commands, parse output, update QA                                   |
+| cbp-todo                   | haiku | low    | Dispatch: single MCP call + route to next command                                        |
+| cbp-checkpoint-complete    | haiku | low    | Pure finalization — mark completed, write summary; judgment happened in checkpoint-check |
+| cbp-git-commit             | haiku | low    | Conventional-commit message authoring is templated; never-git-add rule codified          |
+| cbp-git-branch-feat-create | haiku | low    | Mechanical: read config, checkout production branch (main), create branch, push          |
+| cbp-git-worktree-create    | haiku | low    | Mechanical: git worktree add + .claude/ copy + MCP register                              |
+| cbp-git-worktree-remove    | haiku | low    | Mechanical: git worktree remove + cleanup + MCP deregister                               |
+| cbp-session-start          | haiku | low    | Dispatch: MCP health check, activate session, fetch logs, auto-trigger /cbp-todo             |
+
+### Haiku-low agents (1)
+
+`model: haiku` + `effort: low`. The 12th authoring agent — pure I/O mechanical work, never authors logic.
+
+| agent                | model | effort | reason                                                                              |
+| -------------------- | ----- | ------ | ----------------------------------------------------------------------------------- |
+| cbp-mechanical-edits | haiku | low    | Mechanical rename/substitution/frontmatter-edit subagent; no judgment, pure dispatch |
+
+## Precedence Rule
+
+A skill's `model:` / `effort:` apply to the inline-running turn (the orchestrator turn that invokes the skill). An agent's `model:` / `effort:` apply to the spawned/forked subagent context. For `context: fork` skills, the agent specified in `agent:` governs the forked subagent (per the official Claude Code spec). The two surfaces scope to different execution contexts and do not conflict.
+
+## Model Alias vs Pinned
+
+Pinned (`sonnet`) is the default convention for explicit version-pinning of work that depends on a specific frontier model's reasoning quality. Alias (`haiku`) is acceptable only for explicit lowering exceptions where the alias-tracked latest of that family is desired (the 10 haiku-low entries above). `model: inherit` is NOT permitted in authoring — every file under `packages/codebyplan-package/templates/` states its model explicitly so the matrix is auditable.
+
+## Audit Mode
+
+Invoked with no arguments. Procedure:
+
+1. Glob `packages/codebyplan-package/templates/agents/*.md` and `packages/codebyplan-package/templates/skills/*/SKILL.md`.
+2. For each file, read the frontmatter and parse `model:` + `effort:`.
+3. Look up the expected values from the matrix above (file basename or `name:` frontmatter field is the lookup key).
+4. Emit a pipe-delimited table line per file: `path | current_model/current_effort | expected_model/expected_effort | status`.
+5. Status values:
+   - `ok` — current matches expected
+   - `gap` — missing field, or current value differs from expected
+   - `deprecated` — uses `model: sonnet` (legacy alias; migrate to `sonnet`)
+6. Print a summary line at the end: total files audited, count `ok`, count `gap`, count `deprecated`.
+
+The audit is read-only — no edits performed.
+
+## Apply Mode
+
+Invoked with a path argument (the target `SKILL.md` or `AGENT.md`). Procedure:
+
+1. Read the file. Identify the skill or agent name from the `name:` frontmatter field (or from the path basename if `name:` is absent).
+2. Look up target `model` + `effort` from the matrix above.
+3. Use Edit to set the frontmatter `model:` and `effort:` lines to the target values. Preserve every other frontmatter field and the entire file body. Files whose current status is `deprecated` (legacy `model: sonnet`) follow the same path — the deprecated label is informational; the remediation action is identical to `gap`.
+4. If the name is NOT in the matrix, surface to the user via AskUserQuestion: current state, propose the default (`sonnet` / `xhigh`), ask whether to (a) add an exception entry to this skill's matrix first, or (b) apply the default.
+
+## Self-Conformance
+
+This skill's own frontmatter sits at the default (`sonnet` / `xhigh`). The first audit run after this skill is authored MUST emit `ok` for `packages/codebyplan-package/templates/skills/cbp-build-cc-mode/SKILL.md` — if it doesn't, the matrix is out of sync with reality and must be reconciled before any further apply.