codebyplan 1.13.32 → 1.13.33

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.32";
+    VERSION = "1.13.33";
     PACKAGE_NAME = "codebyplan";
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.32",
+  "version": "1.13.33",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

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

@@ -1,7 +1,7 @@
 ---
 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.
+description: Audit + apply the CHK-109 model/effort convention across every authoring skill and agent under `packages/codebyplan-package/templates/`. Skills set `effort:` only and inherit the session model; agents pin `model:` + `effort:`. Bare invocation audits and reports frontmatter gaps; with a path argument, edits the target file's frontmatter to the convention-decided values.
 argument-hint: "[path-to-agent-or-skill]"
 allowed-tools: Read, Write, Edit, Glob, Grep
 effort: xhigh
@@ -9,66 +9,47 @@ 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.
+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.
+
+The convention splits by surface:
+
+- **Skills do NOT pin `model:`.** A skill's inline turn runs inside the user's active session, so it must inherit the session model. Pinning a model (a) forces a model the user did not choose and (b) can carry the session's 1M `[1m]` context tier onto the skill, producing `API Error: Usage credits required for 1M context`. Skills set `effort:` only.
+- **Agents pin `model:` explicitly.** A spawned/forked subagent should not silently inherit the parent's model or context tier — every agent states its model so each subagent's cost/quality is auditable. Agents set both `model:` and `effort:`.
 
 ## When to Use
 
-- Authoring a new agent or skill — look up the matrix below to pick the right `model` + `effort` before writing the frontmatter.
+- Authoring a new agent or skill — look up the convention below 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.
+- Onboarding a new exception — record the rationale here first, then apply.
 
 ## Decision Matrix
 
-### Default (applies to all agents and most skills)
-
-`model: sonnet` + `effort: xhigh`
-
-Fifteen of the 16 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-testing-qa-agent`, `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest`). The 16th — `cbp-mechanical-edits` — is an explicit haiku-low exception (see below). 26 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-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)
+### Skills — `effort:` only, never `model:`
 
-`model: sonnet` + `effort: high`. Opus reasoning retained; effort dropped from `xhigh` because the skill body is summary/dispatch rather than deep authoring.
+Omit `model:` entirely (inherit the session model). Set `effort:` per the skill's nature. Default `effort: xhigh`; tiers:
 
-| skill             | model  | effort | reason                                                                                                            |
-| ----------------- | ------ | ------ | ----------------------------------------------------------------------------------------------------------------- |
-| cbp-round-end         | sonnet | high   | Spawns cbp-improve-round agent; auto-applies in-scope findings + routes out-of-scope to round-update — 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                                  |
+| effort   | use for                                                | examples                                                                                                                                                              |
+| -------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `xhigh`  | deep authoring / planning / orchestration (most skills) | build-cc-*, checkpoint-check/end/plan, round-start/input/execute, task-create/start/complete/testing, standalone-task-*, frontend-*, ship, ship-configure, supabase-*, setup-e2e/eslint, session-end |
+| `high`   | summary / orchestration, lighter than xhigh            | checkpoint-create, checkpoint-start, checkpoint-update, round-end, task-check, standalone-task-check, ship-main, merge-main                                           |
+| `medium` | moderate, scoped sync work                             | refresh-infra                                                                                                                                                        |
+| `low`    | pure mechanical / dispatch / templated work            | checkpoint-complete, round-check, round-complete, round-update, todo, session-start, git-commit, git-branch-feat-create, git-worktree-create, git-worktree-remove    |
 
-### Haiku-low skills (10)
+A skill that carries a `model:` line is a **gap** — remove it unless a deliberate, documented exception is recorded here (currently none).
 
-`model: haiku` + `effort: low`. Pure mechanical / dispatch / templated work.
+### Agents — `model:` + `effort:`
 
-| skill                  | model | effort | reason                                                                                   |
-| ---------------------- | ----- | ------ | ---------------------------------------------------------------------------------------- |
-| cbp-round-update           | haiku | low    | Pure mechanical: triage round state (claude_approved/findings/hard_fail), route to round-complete or round-input |
-| cbp-round-complete         | haiku | low    | Pure mechanical: sync-approvals git-add reconcile, complete round, route per unapproved count |
-| 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 16th authoring agent — pure I/O mechanical work, never authors logic.
+Default `model: sonnet` + `effort: xhigh`. Fifteen of the 16 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-testing-qa-agent`, `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest`). The 16th is the one exception:
 
 | agent                | model | effort | reason                                                                              |
 | -------------------- | ----- | ------ | ----------------------------------------------------------------------------------- |
 | cbp-mechanical-edits | haiku | low    | Mechanical rename/substitution/frontmatter-edit subagent; no judgment, pure dispatch |
 
-## Precedence Rule
+`model: inherit` is NOT permitted for agents — pin an explicit alias (`sonnet` / `haiku`) or a full ID.
 
-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
+## Precedence Rule
 
-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.
+A skill's `effort:` applies to the inline-running turn (the orchestrator turn that invokes the skill); the skill runs on that turn's inherited model. An agent's `model:` / `effort:` apply to the spawned/forked subagent context. For `context: fork` skills, the agent named in `agent:` governs the forked subagent (per the official Claude Code spec) — so a forked skill's model comes from that agent, not from the skill.
 
 ## Audit Mode
 
@@ -76,25 +57,28 @@ 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`.
+3. Apply the convention by surface:
+   - **Skill**: `model:` MUST be ABSENT; `effort:` MUST be present and one of `low`/`medium`/`high`/`xhigh`/`max` (default `xhigh`).
+   - **Agent**: `model:` MUST be present (per the agent table; default `sonnet`); `effort:` present (default `xhigh`).
+4. Emit one pipe-delimited line per file: `path | current_model/current_effort | expected | 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`.
+   - `ok` — matches the convention.
+   - `gap` — a skill that carries a `model:` line, a skill missing `effort:`, an agent missing/incorrect `model:`, or any missing/invalid `effort:`.
+6. Print a summary: total audited, count `ok`, count `gap`.
 
-The audit is read-only — no edits performed.
+The audit is read-only.
 
 ## 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.
+1. Read the file. Identify the name from the `name:` frontmatter (or the path basename).
+2. Look up the target from the convention above.
+3. Use Edit to set the frontmatter to the target, preserving every other field and the entire body:
+   - **Skill**: REMOVE any `model:` line; set/keep a valid `effort:` (default `xhigh`).
+   - **Agent**: set `model:` and `effort:` to the table values.
+4. If the name is NOT covered, surface via AskUserQuestion: current state, propose the default (skill → no `model:` + `xhigh`; agent → `sonnet` + `xhigh`), and ask whether to (a) record an exception entry here 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.
+This skill is itself a skill: its frontmatter sets `effort: xhigh` and NO `model:`. The first audit run after editing this file MUST emit `ok` for `packages/codebyplan-package/templates/skills/cbp-build-cc-mode/SKILL.md` — if it doesn't, the convention is out of sync with reality and must be reconciled before any further apply.

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

@@ -90,7 +90,7 @@ Key fields by use case:
 | Hide from `/` menu                                   | `user-invocable: false`                                                                                                                                                                                                          |
 | Pre-approve tools                                    | `allowed-tools: Bash(git add *) Bash(git commit *)`                                                                                                                                                                              |
 | Accept arguments                                     | `argument-hint: [file] [mode]`, optionally `arguments: [file mode]` for named `$file`/`$mode`                                                                                                                                    |
-| Set model/effort (always required for plugin skills) | `model: sonnet`, `effort: xhigh` — defaults for plugin skills. Lower (`haiku`/`low` or Opus/`high`) only as a documented exception per [/cbp-build-cc-mode](../build-cc-mode/SKILL.md). `model: inherit` is NOT permitted |
+| Set effort (do NOT set model)                        | `effort: xhigh` — default for plugin skills; lower (`high`/`low`) per [/cbp-build-cc-mode](../build-cc-mode/SKILL.md). **Omit `model:`** so the skill inherits the active session model — pinning one forces a model the user didn't choose and can carry the session's 1M `[1m]` tier onto the skill (→ "usage credits required for 1M context"). Pin `model:` only as a deliberate, documented exception |
 | Path-scoped auto-load                                | `paths: ["src/api/**/*.ts"]`                                                                                                                                                                                                     |
 | Fork to subagent                                     | `context: fork`, `agent: Explore`                                                                                                                                                                                                |
 

package/templates/skills/cbp-build-cc-skill/reference/frontmatter-fields.md

@@ -12,7 +12,7 @@ Source: official Claude Code skills spec. All fields are optional; `description`
 | `disable-model-invocation` | `true` → only user can invoke (via `/name`) |
 | `user-invocable` | `false` → hidden from `/` menu, Claude-only |
 | `allowed-tools` | Pre-approve tools while the skill is active |
-| `model` | Override model for this skill's turn. **Plugin skills authored in CBP MUST set this explicitly** — `inherit` is not permitted; defaults to `sonnet`. See [/cbp-build-cc-mode](../../build-cc-mode/SKILL.md) for the canonical matrix |
+| `model` | Override model for this skill's turn. **CBP skills normally OMIT this** so the skill inherits the active session model. Pinning a model (e.g. `sonnet`) forces that model and can carry the session's 1M `[1m]` context tier onto the skill, triggering "usage credits required for 1M context". Set it only as a deliberate, documented exception — see [/cbp-build-cc-mode](../../build-cc-mode/SKILL.md) |
 | `effort` | Override effort level (`low`/`medium`/`high`/`xhigh`/`max`). **Plugin skills authored in CBP MUST set this explicitly** (no commented-out placeholder); defaults to `xhigh`. See [/cbp-build-cc-mode](../../build-cc-mode/SKILL.md) for the matrix |
 | `context` | `fork` → run in a subagent |
 | `agent` | Subagent type when `context: fork` — built-in or custom |

package/templates/skills/cbp-build-cc-skill/scripts/validate-skill.sh

@@ -49,10 +49,14 @@ grep -qE '^description:\s*' <<< "$fm" || echo "  WARN: no description — Claude
 # CBP scope required
 grep -qE '^scope:\s*' <<< "$fm" || err "missing CBP required field: scope (org-shared|project-shared|repo-only:<repo-name>)"
 
-# Model (if present)
-model=$(grep -E '^model:' <<< "$fm" | head -1 | sed -E 's/^model:[[:space:]]*//; s/[[:space:]]*$//; s/^"(.*)"$/\1/' || true)
-if [ -n "$model" ] && [[ ! "$model" =~ ^(sonnet|opus|haiku|inherit|claude-.+)$ ]]; then
-  err "model invalid: '$model'"
+# Model — skills MUST NOT pin a model. A skill's inline turn runs in the user's
+# active session, so it inherits the session model. Pinning one forces a model the
+# user didn't choose and can carry the session's 1M [1m] context tier onto the skill
+# ("API Error: Usage credits required for 1M context"). Agents pin model explicitly
+# (validate-agent.sh) — skills never do.
+if grep -qE '^model:' <<< "$fm"; then
+  model=$(grep -E '^model:' <<< "$fm" | head -1 | sed -E 's/^model:[[:space:]]*//; s/[[:space:]]*$//')
+  err "skills must NOT set 'model:' (found '$model') — skills inherit the session model; remove the line (see /cbp-build-cc-mode)"
 fi
 
 # Effort (if present)

package/templates/skills/cbp-build-cc-skill/templates/skill.md

@@ -8,8 +8,8 @@ description: What this skill does and when to use it. Front-load the key use cas
 # disable-model-invocation: false  # true = only user can invoke via /name
 # user-invocable: true  # false = only Claude can invoke (hidden from / menu)
 # allowed-tools: Read, Grep, Glob, Bash(git status *)
-# review with /cbp-build-cc-mode if defaults don't fit this skill's purpose
-model: sonnet
+# model:  # OMIT to inherit the session model (recommended). A pinned model can carry the session's 1M [1m] tier and require usage credits — pin only as a documented exception (see /cbp-build-cc-mode)
+# review effort with /cbp-build-cc-mode if the default doesn't fit this skill's purpose
 effort: xhigh
 # context: fork  # runs in a forked subagent
 # agent: Explore  # subagent type: Explore | Plan | general-purpose | <custom>

package/templates/skills/cbp-merge-main/SKILL.md

@@ -2,7 +2,6 @@
 scope: org-shared
 name: cbp-merge-main
 description: Merge main into the current feat branch with interactive per-conflict resolution and inline QA re-run
-model: sonnet
 effort: high
 ---
 

package/templates/skills/cbp-setup-e2e/SKILL.md

@@ -3,7 +3,6 @@ scope: org-shared
 name: cbp-setup-e2e
 description: Detect installed E2E frameworks, ask which to enable, record credentials source (gitignored env-file path + var names only, never secrets), and write/refresh .codebyplan/e2e.json. Interactive, idempotent.
 argument-hint: "[--force]"
-model: sonnet
 effort: xhigh
 allowed-tools: Read, Write, Edit, Bash(cat *), Bash(jq *), Bash(which *), Bash(test *), Bash(mkdir *), Bash(cp *), Bash(echo *), Bash(date *), Bash(mv *), Bash(git check-ignore *), AskUserQuestion, mcp__codebyplan__get_repos
 ---

package/templates/skills/cbp-setup-eslint/SKILL.md

@@ -3,7 +3,6 @@ scope: org-shared
 name: cbp-setup-eslint
 description: Detect each app's tech stack, resolve matching DB ESLint presets, confirm which to enable per app, run `codebyplan eslint init` to generate eslint.config.mjs, and write/refresh .codebyplan/eslint.json. Interactive, idempotent.
 argument-hint: "[--force]"
-model: sonnet
 effort: xhigh
 allowed-tools: Read, Write, Edit, Bash(cat *), Bash(jq *), Bash(test *), Bash(ls *), Bash(mkdir *), Bash(cp *), Bash(echo *), Bash(mv *), Bash(npx codebyplan eslint *), AskUserQuestion, mcp__codebyplan__get_repos, mcp__codebyplan__get_eslint_presets
 ---

package/templates/skills/cbp-ship-main/SKILL.md

@@ -2,7 +2,6 @@
 scope: org-shared
 name: cbp-ship-main
 description: Ship feat branch to production branch via PR — thin wrapper around `codebyplan ship`
-model: sonnet
 effort: high
 ---
 

package/templates/skills/cbp-supabase-branch-check/SKILL.md

@@ -4,7 +4,6 @@ name: cbp-supabase-branch-check
 description: Gate skill called by /cbp-ship-main (pre-merge) to verify the Supabase preview branch health check is green before allowing a PR to be merged; skips when no DB-path changes are detected.
 argument-hint: "[--mode pre_pr_create|pre_merge] [--target integration|production]"
 allowed-tools: Bash(git *), Bash(gh *), Bash(jq *), Bash(supabase *), Bash(sleep *), Bash(echo *), Read, mcp__supabase__list_branches, mcp__supabase__get_logs
-model: sonnet
 effort: xhigh
 ---
 

package/templates/skills/cbp-supabase-migrate/SKILL.md

@@ -4,7 +4,6 @@ name: cbp-supabase-migrate
 description: Scaffold or adopt a Supabase migration for the current PR branch, apply to the branch's preview DB, run advisor checks, regenerate TypeScript types. Includes a fresh-branch dry-run pre-flight that uses one persistent dry-run ephemeral branch per feature branch.
 argument-hint: "[--new <name> | <path-to-sql>]"
 allowed-tools: Read, Edit, Write, Bash(git *), Bash(supabase *), Bash(jq *), Bash(date *), Bash(which *), Bash(cp *), Bash(mv *), Bash(test *), Bash(ls *), mcp__supabase__apply_migration, mcp__supabase__list_migrations, mcp__supabase__get_advisors, mcp__supabase__generate_typescript_types, mcp__supabase__reset_branch, mcp__supabase__list_branches, mcp__supabase__create_branch, mcp__supabase__get_cost, mcp__supabase__confirm_cost, mcp__codebyplan__update_checkpoint, mcp__codebyplan__update_task
-model: sonnet
 effort: xhigh
 ---