codebyplan 1.13.60 → 1.13.62

package/package.json

@@ -1,18 +1,28 @@
 {
   "name": "codebyplan",
-  "version": "1.13.60",
+  "version": "1.13.62",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {
     "codebyplan": "dist/cli.js"
   },
+  "exports": {
+    ".": null,
+    "./ci": {
+      "types": "./dist/ci-public.d.ts",
+      "default": "./dist/ci.js"
+    }
+  },
   "files": [
     "dist/cli.js",
+    "dist/ci.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
     "templates/",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc --project tsconfig.build.json",
+    "build": "tsc --project tsconfig.build.json && node esbuild.npm.mjs",
     "build:npm": "node esbuild.npm.mjs",
     "prepare": "node -e \"const v=process.env.CI;process.exit(v&&v!=='false'&&v!=='0'?0:1)\" || node esbuild.npm.mjs",
     "lint": "eslint",

package/templates/agents/cbp-e2e-maestro.md

@@ -3,7 +3,7 @@ name: cbp-e2e-maestro
 description: Maestro E2E flow authoring + execution for Expo/React Native mobile apps (android + ios). Spawned by /cbp-round-build Step 5 and /cbp-checkpoint-check Step 5b when framework is 'maestro'.
 tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
 model: sonnet
-effort: xhigh
+effort: high
 ---
 
 # Maestro E2E Agent

package/templates/agents/cbp-e2e-playwright.md

@@ -3,7 +3,7 @@ name: cbp-e2e-playwright
 description: Playwright E2E test authoring + execution for web app routes. Spawned by /cbp-round-build Step 5 and /cbp-checkpoint-check Step 5b when framework is 'playwright'.
 tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
 model: sonnet
-effort: xhigh
+effort: high
 ---
 
 # Playwright E2E Agent

package/templates/agents/cbp-e2e-tauri.md

@@ -3,7 +3,7 @@ name: cbp-e2e-tauri
 description: WebDriverIO + tauri-driver E2E test authoring + execution for Tauri desktop apps. Spawned by /cbp-round-build Step 5 and /cbp-checkpoint-check Step 5b when framework is 'webdriverio'.
 tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
 model: sonnet
-effort: xhigh
+effort: high
 ---
 
 # Tauri E2E Agent

package/templates/agents/cbp-e2e-vscode.md

@@ -3,7 +3,7 @@ name: cbp-e2e-vscode
 description: VS Code extension E2E test authoring + execution using @vscode/test-cli and @vscode/test-electron. Spawned by /cbp-round-build Step 5 and /cbp-checkpoint-check Step 5b when framework is 'vscode-test'.
 tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
 model: sonnet
-effort: xhigh
+effort: high
 ---
 
 # VS Code Extension E2E Agent

package/templates/agents/cbp-e2e-xcuitest.md

@@ -3,7 +3,7 @@ name: cbp-e2e-xcuitest
 description: XCUITest native iOS E2E test authoring + execution for Expo apps targeting system dialogs, HealthKit, watchOS, or other areas Maestro cannot reach. Spawned by /cbp-round-build Step 5 and /cbp-checkpoint-check Step 5b when framework is 'xcuitest'.
 tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
 model: sonnet
-effort: xhigh
+effort: high
 ---
 
 # XCUITest E2E Agent

package/templates/rules/effort-and-ultracode.md

@@ -0,0 +1,70 @@
+---
+description: Effort ladder (low..max), per-model support, frontmatter usage, and the session-only ultracode mode.
+---
+
+# Effort and Ultracode
+
+On-demand reference for effort levels and the ultracode mode in Claude Code.
+
+## Effort Ladder
+
+| Level | Gloss |
+|-------|-------|
+| `low` | Latency-sensitive, trivial tasks — minimal reasoning |
+| `medium` | Standard tasks — moderate reasoning |
+| `high` | Default for most models — solid reasoning budget |
+| `xhigh` | Extended reasoning — slower, better for complex multi-step work |
+| `max` | Deepest reasoning available — session-only, can overthink simple tasks |
+
+## Per-Model Support
+
+| Model | Supported levels | Default effort |
+|-------|-----------------|----------------|
+| Opus 4.8, Fable 5 | `low` `medium` `high` `xhigh` `max` | `high` |
+| Opus 4.7 | `low` `medium` `high` `xhigh` `max` | `xhigh` |
+| Opus 4.6, Sonnet 4.6 | `low` `medium` `high` `max` (`xhigh` → falls back to `high`) | `high` |
+
+## Precedence (highest → lowest)
+
+1. `CLAUDE_CODE_EFFORT_LEVEL` env var
+2. Frontmatter `effort:` (while a skill/agent is active)
+3. `effortLevel` in `settings.json`
+4. Model default
+
+## Frontmatter Usage
+
+Skills set `model: inherit` + `effort: <level>`. Subagents pin `model: <id>` + `effort: <level>`.
+Both override the session level only while active.
+
+`effort: ultracode` is **invalid** in frontmatter — `validate-skill.sh` errors on it. Use
+`effort: max` for the heaviest per-skill reasoning budget; enable ultracode session-wide with
+`/effort ultracode`.
+
+## settings.json `effortLevel`
+
+Accepts `low | medium | high | xhigh` **only**. `max` and `ultracode` are session-only and
+rejected by the settings validator.
+
+This repo's default is `xhigh` (`.claude/settings.json`). You **cannot** default ultracode
+in settings.json — enable it per-session instead.
+
+## Ultracode Mode
+
+ultracode = `xhigh` reasoning + automatic Workflow orchestration for substantive tasks.
+It is a **session-only** Claude Code mode, NOT a frontmatter `effort` value, NOT `effortLevel`,
+NOT `--effort`, NOT `CLAUDE_CODE_EFFORT_LEVEL`.
+
+**Enable via:**
+- `/effort ultracode` (in-session slash command)
+- `claude --settings '{"ultracode": true}'`
+- An Agent SDK control request
+
+Applies to the current session only — resets on a new session.
+
+**When to enable:** heavy multi-step checkpoints where deterministic multi-agent fan-out
+helps. See `rules/workflow-orchestration.md` for full orchestration guidance.
+
+## Related
+
+- `rules/model-invocation-convention.md` — model pinning in skill/agent frontmatter
+- `rules/workflow-orchestration.md` — Workflow tool pattern, opt-in gate, and when to use it instead of ad-hoc Task/Agent spawns

package/templates/rules/model-invocation-convention.md

@@ -38,3 +38,4 @@ See `.claude/skills/cbp-build-cc-settings/reference/cbp-permission-policy.md` fo
 
 - `rules/scope-vocabulary.md` — scope marker conventions for managed vs user-created files
 - `cbp-build-cc-settings/reference/cbp-permission-policy.md` — allow/ask tiers
+- `rules/effort-and-ultracode.md` — effort ladder, per-model support, and the session-only ultracode mode

package/templates/rules/workflow-orchestration.md

@@ -0,0 +1,59 @@
+---
+description: Workflow tool — deterministic JS multi-agent orchestration for heavy fan-out. What it is, when to reach for it, the opt-in gate, and how it relates to ad-hoc Task/Agent spawning.
+---
+
+# Workflow Orchestration
+
+On-demand reference for the `Workflow` tool — the structured alternative to ad-hoc `Task`/`Agent`
+spawning when a step fans out across many independent units of work.
+
+## What It Is
+
+`Workflow` runs a deterministic JavaScript orchestration script that spawns and coordinates
+subagents. The control flow (loops, conditionals, fan-out) lives in the script, not in model
+judgement. Core primitives:
+
+- `agent(prompt, opts)` — spawn a subagent; with a `schema` it returns a validated structured
+  object instead of raw text.
+- `parallel(thunks)` — run tasks concurrently to a **barrier** (awaits all before returning).
+- `pipeline(items, ...stages)` — stream each item through stages with **no barrier** between them
+  (the default for multi-stage work — wall-clock is the slowest single chain, not sum-of-stages).
+- `phase(title)` / `log(message)` — progress grouping and narration.
+
+Built in: per-agent structured-output validation, a concurrency cap, a shared token budget,
+loop-until-done / loop-until-dry accumulation, and resume from a prior run.
+
+## When To Reach For It
+
+- **Many independent items** — a per-module sweep, a per-file migration, a per-surface deploy.
+- **Parallel waves with a barrier** — wave A must fully complete before wave B starts.
+- **Adversarial / multi-vote verification** — N independent reviewers vote to confirm a finding.
+- **Scale beyond one context** — coverage a single conversation cannot hold.
+
+Contrast: a single one-off subagent stays on the plain `Task`/`Agent` tool. Workflow's setup
+overhead only pays off at fan-out scale.
+
+## Opt-In Gate
+
+`Workflow` is **not** invoked by default. Reach for it only when one holds:
+
+- **ultracode** mode is active in the session (`/effort ultracode`) — under ultracode Claude
+  auto-reaches for Workflow on substantive fan-out tasks; **or**
+- the **user explicitly opts in** ("use a workflow", "fan out agents", "orchestrate this"); **or**
+- a skill or command's own instructions tell you to author one.
+
+Outside those, do NOT call `Workflow` — use the existing `Task`/`Agent` spawn, or describe what a
+workflow could do and ask first. The tool can spawn dozens of agents and is token-heavy — the scale
+must be requested, not inferred.
+
+## Relationship to Task/Agent Spawning
+
+`Task`/`Agent` spawning is the **default** for subagent work and is unchanged everywhere it is used.
+`Workflow` is the **structured alternative** for heavy fan-out — additive, not a replacement. A
+common shape is **hybrid**: scout inline first to discover the work-list, then author a `Workflow`
+that pipelines over it.
+
+## Related
+
+- `rules/effort-and-ultracode.md` — effort ladder, per-model support, and the session-only ultracode mode that auto-enables this orchestration path
+- `rules/model-invocation-convention.md` — model pinning in skill/agent frontmatter

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

@@ -3,6 +3,7 @@ name: cbp-build-cc-agent
 description: Build a Claude Code subagent at .claude/agents/{name}.md (flat form, per the official sub-agents spec) following the official sub-agents spec (frontmatter, tools, model, hooks, skills preload, permission modes, isolation).
 argument-hint: "[agent-name] [--scope=project|user] [--isolation=worktree]"
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir *), Bash(chmod *)
+model: inherit
 effort: xhigh
 ---
 

package/templates/skills/cbp-build-cc-claude-file/SKILL.md

@@ -3,6 +3,7 @@ name: cbp-build-cc-claude-file
 description: Create or update a CLAUDE.md file at any scope (managed, project, user, local) following the official memory spec — imports (@path), nested discovery, AGENTS.md bridge, comment stripping, and claudeMdExcludes.
 argument-hint: "[action] [--scope=managed|project|user|local]"
 allowed-tools: Read, Write, Edit, Glob, Grep
+model: inherit
 effort: xhigh
 ---
 

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

@@ -1,8 +1,9 @@
 ---
 name: cbp-build-cc-mode
-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.
+description: Audit + apply the CHK-229 model/effort convention across every authoring skill and agent under `packages/codebyplan-package/templates/`. Skills set `model: inherit` + `effort:`; 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
+model: inherit
 effort: xhigh
 ---
 
@@ -12,8 +13,8 @@ Audit or apply the canonical model/effort frontmatter convention across every au
 
 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:`.
+- **Skills set `model: inherit` AND `effort:`.** The `model: inherit` value signals explicitly that the skill inherits the user's active session model — it is the standard value. A non-inherit model or an absent model field is a gap. A justified explicit pin (e.g. `model: sonnet`) is permitted when documented here as an exception.
+- **Agents pin `model:` explicitly.** A spawned/forked subagent must 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:`. `model: inherit` is NOT permitted for agents.
 
 ## When to Use
 
@@ -23,33 +24,40 @@ The convention splits by surface:
 
 ## Decision Matrix
 
-### Skills — `effort:` only, never `model:`
+### Skills — `model: inherit` + `effort:`
 
-Omit `model:` entirely (inherit the session model). Set `effort:` per the skill's nature. Default `effort: xhigh`; tiers:
+Set `model: inherit` (the standard value) and `effort:` per the skill's nature. Default `effort: xhigh`; tiers:
 
-| 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    |
+| effort   | use for                                                | examples                                                                                                                                                                    |
+| -------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `xhigh`  | deep authoring / planning / orchestration (most skills) | build-cc-*, checkpoint-check/end/plan, finalize, frontend-design, map-architecture, round-build/plan, ship, standalone-task-complete, supabase-migrate, task-start, verify |
+| `high`   | lighter orchestration, review, setup, targeted flows   | checkpoint-create/start, frontend-ui/ux, merge-main, refresh-arch-map, session-end, setup-cd/ci/e2e/eslint, ship-configure/main, standalone-task-check/create/start/testing, stripe, supabase-branch-check/setup, task-create |
+| `medium` | moderate, scoped sync work                             | checkpoint-update, clear-prep, todo                                                                                                                                          |
+| `low`    | pure mechanical / dispatch / templated work            | checkpoint-complete, clear-continue, git-commit, git-branch-feat-create, round-complete, session-start                                                                      |
 
-A skill that carries a `model:` line is a **gap** — remove it unless a deliberate, documented exception is recorded here (currently none).
+A skill with an absent `model:` field or a non-`inherit` model value is a **gap** — add `model: inherit` or document the exception here before applying a different pin.
+
+> **Note on effort tiers**: `max` is the highest frontmatter effort tier. `ultracode` is a SESSION-ONLY runtime mode (`/effort ultracode`) — it is NOT a valid frontmatter value and `validate-skill.sh` rejects `effort: ultracode` with an explicit error.
 
 ### Agents — `model:` + `effort:`
 
-Default `model: sonnet` + `effort: xhigh`. Fifteen of the 17 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-research`, `cbp-round-builder`, `cbp-security-agent`, `cbp-stripe-agent`, `cbp-verify-reviewer`, `cbp-round-planner`, `cbp-testing-qa-agent`, `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest`). The other two are exceptions:
+Default `model: sonnet` + `effort: xhigh`. Ten of the 17 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-research`, `cbp-round-builder`, `cbp-round-planner`, `cbp-security-agent`, `cbp-stripe-agent`, `cbp-testing-qa-agent`, `cbp-verify-reviewer`). The other seven are exceptions:
 
 | agent                | model  | effort | reason                                                                              |
 | -------------------- | ------ | ------ | ----------------------------------------------------------------------------------- |
 | cbp-mechanical-edits | haiku  | low    | Mechanical rename/substitution/frontmatter-edit subagent; no judgment, pure dispatch |
 | cbp-map-architecture | sonnet | high   | Read-only module analyzer; bounded structured-map generation, lighter than xhigh     |
+| cbp-e2e-maestro      | sonnet | high   | E2E specialist: bounded test-execution scope; sonnet+high calibrated in CHK-229      |
+| cbp-e2e-playwright   | sonnet | high   | E2E specialist: bounded test-execution scope; sonnet+high calibrated in CHK-229      |
+| cbp-e2e-tauri        | sonnet | high   | E2E specialist: bounded test-execution scope; sonnet+high calibrated in CHK-229      |
+| cbp-e2e-vscode       | sonnet | high   | E2E specialist: bounded test-execution scope; sonnet+high calibrated in CHK-229      |
+| cbp-e2e-xcuitest     | sonnet | high   | E2E specialist: bounded test-execution scope; sonnet+high calibrated in CHK-229      |
 
 `model: inherit` is NOT permitted for agents — pin an explicit alias (`sonnet` / `haiku`) or a full ID.
 
 ## Precedence Rule
 
-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.
+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 (declared via `model: inherit`). 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
 
@@ -70,10 +78,10 @@ Invoked with a path argument (the target `SKILL.md` or agent `.md`). Procedure:
 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`).
+   - **Skill**: SET `model: inherit` if absent (or correct a non-inherit pin); 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.
+4. If the name is NOT covered, surface via AskUserQuestion: current state, propose the default (skill → `model: inherit` + `xhigh`; agent → `sonnet` + `xhigh`), and ask whether to (a) record an exception entry here first, or (b) apply the default.
 
 ## Self-Conformance
 
-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.
+This skill is itself a skill: its frontmatter declares `model: inherit` + `effort: xhigh`. 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-rule/SKILL.md

@@ -3,6 +3,7 @@ name: cbp-build-cc-rule
 description: Build a path-scoped rule file at .claude/rules/{name}.md following the official memory/rules spec (paths globs, always-loaded vs on-demand, symlinks) plus CBP conventions (scope field for structural classification — required only on user-created rules (validate-structure-scope.sh), narrow-paths discipline; hook warns at 100 lines, blocks at 200).
 argument-hint: '[name] [--scope=project|user] [--paths="glob,glob"]'
 allowed-tools: Read, Write, Edit, Glob, Grep
+model: inherit
 effort: xhigh
 ---
 

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

@@ -3,6 +3,7 @@ name: cbp-build-cc-settings
 description: Create or update Claude Code settings.json / settings.local.json / managed-settings.json following the official settings spec — scopes, permissions, hooks, sandbox, attribution, plugins, env vars, JSON schema validation.
 argument-hint: "[action] [--scope=user|project|local|managed]"
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash(jq *)
+model: inherit
 effort: xhigh
 ---
 

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

@@ -54,7 +54,7 @@ Source: official Claude Code settings spec. Grouped by category. All fields are
 | `model` | Override default model |
 | `modelOverrides` | Map model IDs (e.g. Bedrock profile ARNs) |
 | `availableModels` | Restrict which models `/model` exposes |
-| `effortLevel` | Persist effort across sessions |
+| `effortLevel` | Persist effort across sessions. Valid values: `low \| medium \| high \| xhigh` only — `max` and `ultracode` are session-only and rejected here. See `rules/effort-and-ultracode.md`. |
 | `alwaysThinkingEnabled` | Extended thinking on by default |
 | `showThinkingSummaries` | Show thinking summaries |
 

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

@@ -3,6 +3,7 @@ name: cbp-build-cc-skill
 description: Build a Claude Code skill at .claude/skills/{name}/SKILL.md following the official skills spec — frontmatter, supporting files (templates, examples, reference, scripts), invocation control, argument substitution, dynamic context, fork-to-subagent, allowed-tools.
 argument-hint: "[skill-name] [--scope=project|user] [--fork] [--disable-model-invocation]"
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir *), Bash(chmod *)
+model: inherit
 effort: xhigh
 ---
 
@@ -97,7 +98,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 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 |
+| Set model + effort                                   | `model: inherit` (the standard value — explicitly signals session-model inheritance) and `effort: xhigh` (default for plugin skills; lower tiers `high`/`medium`/`low` per [/cbp-build-cc-mode](../build-cc-mode/SKILL.md)). A non-`inherit` model pin 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"), so pin 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`). Upstream skills that auto-trigger this skill MUST emit a `Next: /name` directive instead — model invocation is blocked by the runtime; see SKILL.md Step 4 "Convention: User-only / permission-gated finalizer" |
 | `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. **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) |
+| `model` | Model for this skill's turn. **CBP skills set `model: inherit`** (the standard value — explicitly signals session-model inheritance). A non-`inherit` pin (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"; use 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

@@ -57,19 +57,22 @@ if grep -qE '^scope:\s*' <<< "$fm"; then
   fi
 fi
 
-# 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)"
+# Model — skills MUST declare 'model: inherit' to signal session-model inheritance
+# explicitly. Absent = warning (should be added); non-enum value = error.
+# Valid values: inherit | sonnet | opus | haiku | fable | opusplan | claude-<id> | <id>[1m]
+# Agents pin explicit model values (validate-agent.sh); skills use 'inherit'.
+model_val=$(grep -E '^model:' <<< "$fm" | head -1 | sed -E 's/^model:[[:space:]]*//; s/[[:space:]]*$//' || true)
+if [ -z "$model_val" ]; then
+  echo "  WARN: model: absent — add 'model: inherit' (skills must declare session-model inheritance)" >&2
+elif ! [[ "$model_val" =~ ^(inherit|sonnet|opus|haiku|fable|opusplan|claude-[a-z0-9][a-z0-9.-]*|.*\[1m\])$ ]]; then
+  err "model: invalid value '$model_val' (valid values: inherit | sonnet | opus | haiku | fable | opusplan | claude-<id> | <id>[1m])"
 fi
 
 # Effort (if present)
 effort=$(grep -E '^effort:' <<< "$fm" | head -1 | sed -E 's/^effort:[[:space:]]*//; s/[[:space:]]*$//; s/^"(.*)"$/\1/' || true)
-if [ -n "$effort" ] && [[ ! "$effort" =~ ^(low|medium|high|xhigh|max)$ ]]; then
+if [ "$effort" = "ultracode" ]; then
+  err "effort: ultracode is a session-only mode, not a frontmatter effort — use max + /effort ultracode"
+elif [ -n "$effort" ] && [[ ! "$effort" =~ ^(low|medium|high|xhigh|max)$ ]]; then
   err "effort invalid: '$effort'"
 fi
 

package/templates/skills/cbp-checkpoint-check/SKILL.md

@@ -3,6 +3,7 @@ scope: org-shared
 name: cbp-checkpoint-check
 description: Full re-evaluation of a checkpoint with before/after comparison
 argument-hint: [CHK-NNN]
+model: inherit
 effort: xhigh
 ---
 
@@ -133,6 +134,10 @@ Aggregate the files touched across all tasks (reusing Step 4's deduplicated tabl
 
    See `cbp-verify` reference `findings-presentation.md` "Infra Issue Absorption Contract — Infra-Class Issue Catalog" row "Checkpoint-level e2e failure" for the routing rationale.
 
+#### Orchestration (optional)
+
+Step 5b's parallel whole-checkpoint `cbp-e2e-*` specialist dispatch MAY be authored as a `Workflow(...)` script instead of ad-hoc `Task`/`Agent` spawning — for deterministic fan-out across eligible frameworks and schema-validated aggregation. This is opt-in (ultracode session or explicit user request); the dispatch flow above stays the DEFAULT and is unchanged. See `rules/workflow-orchestration.md`.
+
 ### Step 6: User Discussion
 
 Present findings and discuss with user:

package/templates/skills/cbp-checkpoint-complete/SKILL.md

@@ -2,6 +2,7 @@
 name: cbp-checkpoint-complete
 description: Complete a checkpoint after all tasks are done
 argument-hint: [checkpoint-number]
+model: inherit
 effort: low
 ---
 

package/templates/skills/cbp-checkpoint-create/SKILL.md

@@ -2,6 +2,7 @@
 name: cbp-checkpoint-create
 description: Mechanical checkpoint creation — capture the user's description, infer title + goal, dedup against existing modules, create the checkpoint row + feat branch, then hand off to /cbp-checkpoint-plan for deep planning. Creates ZERO tasks.
 argument-hint: [checkpoint description]
+model: inherit
 effort: high
 ---
 

package/templates/skills/cbp-checkpoint-end/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: cbp-checkpoint-end
 description: Single point for all shipment — branch promotion to main via /cbp-ship-main, runtime deploy via /cbp-ship, branch cleanup, summary. Standalone tasks bypass shipment entirely.
+model: inherit
 effort: xhigh
 ---
 
@@ -161,6 +162,10 @@ If `/cbp-ship` reports `aborted_at` (user aborted) or any surface failed verific
 
 If the repo has zero configured surfaces (very early-stage), `/cbp-ship` exits with `## No deployable surfaces configured` — that's a success state, continue to cleanup.
 
+#### Orchestration (optional)
+
+The multi-step shipment coordinated here (Step 5 `/cbp-ship-main` → Step 7 `/cbp-ship` → screenshot upload) MAY be expressed as a `Workflow(...)` pipeline instead of ad-hoc sequential invocation. This is opt-in (ultracode session or explicit user request); the sequential flow above stays the DEFAULT and is unchanged. See `rules/workflow-orchestration.md`.
+
 ### Step 7.5: Upload E2E Screenshots to DB (best-effort)
 
 After `/cbp-ship` completes successfully, upload the checkpoint's new/changed committed E2E screenshots to the CodeByPlan DB so they can be reviewed per-checkpoint in the web UI (CHK-171). This step is **best-effort and non-blocking** — a failure here MUST NOT halt shipment or cleanup.

package/templates/skills/cbp-checkpoint-plan/SKILL.md

@@ -2,6 +2,7 @@
 name: cbp-checkpoint-plan
 description: Deep inline planning for a checkpoint — assess, gap-analyse, decide dependencies, compare alternatives, optionally e2e-probe a suspected-broken area, then create tasks as vertical slices. Runs after /cbp-checkpoint-create (mechanical) and before /cbp-checkpoint-start (activate + claim). Does NOT activate or claim.
 argument-hint: [checkpoint-number]
+model: inherit
 effort: xhigh
 ---
 
@@ -49,6 +50,10 @@ Iterate ALL `ideas[]` (not just the first). For each:
 
 Write each idea's analysis into `ideas[N].assessment` (Claude-authored; never touch `description`, which is the user's words).
 
+#### Orchestration (optional)
+
+Step 2's `cbp-research` and any e2e-probe subagent spawns MAY be authored as a `Workflow(...)` script instead of ad-hoc `Task` spawning — useful when multiple ideas each warrant an independent research/assessment pass. This is opt-in (ultracode session or explicit user request); the single-spawn flow above stays the DEFAULT and is unchanged. See `rules/workflow-orchestration.md`.
+
 ### Step 3: Gap Analysis
 
 Find what the raw request misses — this is the core anti-"half-ass" step. Load `reference/gap-analysis-playbook.md` and run its two passes:

package/templates/skills/cbp-checkpoint-start/SKILL.md

@@ -2,6 +2,7 @@
 name: cbp-checkpoint-start
 description: Activate a planned checkpoint and claim it for the current user/worktree, then route into task work. Runs after /cbp-checkpoint-plan (which produces tasks but never activates). Refuses to start an unplanned checkpoint.
 argument-hint: [checkpoint-number]
+model: inherit
 effort: high
 ---
 

package/templates/skills/cbp-checkpoint-update/SKILL.md

@@ -2,7 +2,8 @@
 name: cbp-checkpoint-update
 description: Update checkpoint state (activate, update context, etc.)
 argument-hint: [checkpoint-number]
-effort: high
+model: inherit
+effort: medium
 ---
 
 # Checkpoint Update Command

package/templates/skills/cbp-clear-continue/SKILL.md

@@ -2,7 +2,8 @@
 scope: org-shared
 name: cbp-clear-continue
 description: Resume work after /clear by reading .codebyplan/clear/handoff.md and re-invoking the previously-blocked heavy skill. Reports a friendly error if no handoff file exists.
-effort: xhigh
+model: inherit
+effort: low
 ---
 
 # cbp-clear-continue

package/templates/skills/cbp-clear-prep/SKILL.md

@@ -3,7 +3,8 @@ scope: org-shared
 name: cbp-clear-prep
 description: Capture a clear-context handoff when the context window is too large to run a heavy skill. Reads active task/round state, writes .codebyplan/clear/handoff.md, then instructs the user to run /clear and /cbp-clear-continue to resume.
 argument-hint: "[blocked-skill]"
-effort: xhigh
+model: inherit
+effort: medium
 ---
 
 # cbp-clear-prep

package/templates/skills/cbp-finalize/SKILL.md

@@ -3,6 +3,7 @@ name: cbp-finalize
 description: Finalize and complete the current task — commit, merge main, push, complete
 argument-hint: [chk-task]
 triggers: [cbp-task-start, cbp-checkpoint-check]
+model: inherit
 effort: xhigh
 ---
 

package/templates/skills/cbp-frontend-design/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: cbp-frontend-design
 description: Up-front design playbook loaded BEFORE writing UI / styling code. Detects the stack, loads the matching reference file, commits to an aesthetic direction, and prevents generic AI-slop output. Modelled on Anthropic's frontend-design skill, adapted for CBP repos with existing design systems.
+model: inherit
 effort: xhigh
 ---
 

package/templates/skills/cbp-frontend-ui/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: cbp-frontend-ui
 description: Visual quality self-review pass invoked twice per round — once by round-executor Step 3.8 (phase 'style_only', no screenshots) for token/spacing/typography/color/cohesion, once by /cbp-round-build Step 5b (phase 'screenshot_review', with e2e screenshots) for rendered-output review and baseline regressions. Default phase 'full' runs everything for back-compat.
-effort: xhigh
+model: inherit
+effort: high
 ---
 
 # Frontend UI (Post-Implementation Visual Self-Review)

package/templates/skills/cbp-frontend-ux/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: cbp-frontend-ux
 description: Interaction-quality self-review pass loaded by round-executor AFTER UI code is written. Catches navigation flow issues, missing feedback states, cognitive-load problems, form usability gaps, and accessibility violations. Auto-applies in-scope mechanical UX fixes within the round's files_changed. Replaces the post-implementation ux-agent spawn with an inline skill invocation.
-effort: xhigh
+model: inherit
+effort: high
 ---
 
 # Frontend UX (Post-Implementation Interaction Self-Review)

package/templates/skills/cbp-git-branch-feat-create/SKILL.md

@@ -2,6 +2,7 @@
 name: cbp-git-branch-feat-create
 description: Create feature branch from the production branch (main, config-driven)
 argument-hint: "[name] e.g. add-user-auth"
+model: inherit
 effort: low
 ---
 

package/templates/skills/cbp-git-commit/SKILL.md

@@ -2,6 +2,7 @@
 name: cbp-git-commit
 description: Create scoped commit with conventional format
 argument-hint: "[--task|--all] [type]: [description]"
+model: inherit
 effort: low
 ---