codebyplan 1.12.0 → 1.13.3

package/templates/skills/cbp-setup-eslint/reference/react-native.md

@@ -0,0 +1,60 @@
+# react-native — React Native / Expo flat config
+
+For Expo / React Native apps (the CBP `livebyplan` mobile app). **Gap stack — no CBP DB
+preset.** Use Expo's official lint config.
+
+> **Verified 2026-05-31.** `eslint-config-expo` is the official config and ships **flat config
+> by default from Expo SDK 53** onward (SDK 52 and earlier use legacy `.eslintrc`).
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint-config-expo` | `56.0.4` | Expo's flat config (`/flat` subpath) |
+
+```bash
+npx expo lint   # installs eslint + eslint-config-expo and scaffolds eslint.config.js
+```
+
+`eslint-config-expo` bundles `eslint-plugin-expo`, `eslint-plugin-react`,
+`eslint-plugin-react-hooks`, `eslint-plugin-import`, and `@typescript-eslint/*`. It does **not**
+bundle `eslint-plugin-react-native` (that's a separate optional add-on, `@5.0.0`).
+
+## Flat config
+
+Expo's template is **CommonJS `eslint.config.js`** (not `.mjs`):
+
+```js
+// eslint.config.js
+const { defineConfig } = require("eslint/config");
+const expoConfig = require("eslint-config-expo/flat");
+const eslintPluginPrettierRecommended = require("eslint-plugin-prettier/recommended");
+
+module.exports = defineConfig([
+  expoConfig,
+  eslintPluginPrettierRecommended,
+  { ignores: ["dist/*"] },
+]);
+```
+
+Minimal form (no Prettier): just `expoConfig` in the array.
+
+## Gotchas
+
+- RN platform support comes from RN global variables + platform file extensions
+  (`.android.ts`, `.ios.ts`, `.web.ts`) and `eslint-plugin-expo` — **not** from
+  `eslint-plugin-react-native`. Add `eslint-plugin-react-native@5.0.0` manually only if you
+  want RN-specific rules (`no-inline-styles`, `no-unused-styles`).
+- Run linting with `npx expo lint` (it wires the config the first time).
+- Expo apps test with **Jest** — add the [jest.md](jest.md) override.
+
+## CBP preset divergence
+
+There is **no** CBP `react-native`/`expo` DB preset, and the `react` preset `excludes`
+nothing for RN but is browser-globals oriented. Use `eslint-config-expo/flat` directly; the
+skill does not add a preset for this stack.
+
+## Official docs
+
+- Using ESLint in Expo: https://docs.expo.dev/guides/using-eslint/
+- eslint-config-expo: https://github.com/expo/expo/tree/main/packages/eslint-config-expo

package/templates/skills/cbp-setup-eslint/reference/react.md

@@ -0,0 +1,82 @@
+# react — standalone React (Vite, Tauri) flat config
+
+For React apps that are **not** Next.js (Vite SPA, Tauri desktop webview). Layers on
+[base](base.md). Maps to the CBP **`react`** DB preset
+(`tech_match.requires: ["React"]`, `excludes: ["Next.js"]`, `requires_capabilities: ["jsx"]`).
+
+> **Verified 2026-05-31.** **Do NOT install `eslint-plugin-react-compiler`** — it is
+> superseded. React Compiler v1.0 (Oct 2025) merged the compiler lint rules into
+> **`eslint-plugin-react-hooks@7`** under `configs.flat["recommended-latest"]`.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint-plugin-react` | `7.37.5` | React rules + JSX parsing (`configs.flat.*`) |
+| `eslint-plugin-react-hooks` | `7.1.1` | hooks rules **+ bundled React Compiler rules** |
+| `eslint-plugin-jsx-a11y` | `6.10.2` | accessibility (`flatConfigs.*` — note plural) |
+
+```bash
+pnpm add -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y globals
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import { defineConfig } from "eslint/config";
+import react from "eslint-plugin-react";
+import reactHooks from "eslint-plugin-react-hooks";
+import jsxA11y from "eslint-plugin-jsx-a11y";
+import globals from "globals";
+
+export default defineConfig([
+  react.configs.flat.recommended,                 // namespaced react/, enables JSX parsing
+  react.configs.flat["jsx-runtime"],              // React 17+ automatic JSX transform
+  reactHooks.configs.flat["recommended-latest"],  // hooks + React Compiler rules
+  jsxA11y.flatConfigs.strict,                      // or flatConfigs.recommended
+  {
+    files: ["**/*.{js,jsx,ts,tsx}"],
+    languageOptions: { globals: globals.browser },
+    settings: { react: { version: "detect" } },
+  },
+]);
+```
+
+## Gotchas
+
+- **`eslint-plugin-react` flat configs do not set `files` or globals** — add your own
+  `files`/`globals.browser`/`settings.react.version` object (shown above) or you'll get the
+  "React version not specified" warning and no JSX globals.
+- **`eslint-plugin-react-hooks` v7 keys** live under `configs.flat.*`:
+  `recommended` (standard hooks) vs `recommended-latest` (hooks **+ compiler** rules — use
+  this for React 19 + the compiler).
+- **`jsx-a11y` uses `flatConfigs` (plural)** — `jsxA11y.flatConfigs.strict`, a different
+  namespace from react's `configs.flat`.
+
+## Storybook (bonus)
+
+If the app uses Storybook, add `eslint-plugin-storybook@10.4.1`:
+
+```js
+import storybook from "eslint-plugin-storybook";
+// ...spread into the array:
+...storybook.configs["flat/recommended"],
+```
+
+The standalone plugin repo was archived (2025-11); it now lives in the Storybook monorepo but
+the npm name `eslint-plugin-storybook` is unchanged.
+
+## CBP preset divergence
+
+CBP's `react` preset still depends on `eslint-plugin-react-compiler: ^19.0.0` and registers
+`react-compiler/react-compiler`. The latest guidance removes that plugin and relies on
+`eslint-plugin-react-hooks@7`'s `recommended-latest`. Adopt that when regenerating; the skill
+does not modify the preset.
+
+## Official docs
+
+- eslint-plugin-react: https://github.com/jsx-eslint/eslint-plugin-react
+- react-hooks: https://react.dev/reference/eslint-plugin-react-hooks
+- React Compiler v1.0: https://react.dev/blog/2025/10/07/react-compiler-1
+- jsx-a11y: https://github.com/jsx-eslint/eslint-plugin-jsx-a11y

package/templates/skills/cbp-setup-eslint/reference/tailwind.md

@@ -0,0 +1,64 @@
+# tailwind — Tailwind CSS class linting
+
+For apps using Tailwind CSS (the CBP `tarkur` repo uses Tailwind + shadcn/ui). **Gap stack —
+no CBP DB preset.** Adds class-sorting / validation rules on top of the app's base config.
+
+> **Verified 2026-05-31.** Use **`eslint-plugin-better-tailwindcss`** — it is the only plugin
+> with first-class **Tailwind v4** + ESLint 9/10 flat-config support. The original
+> `eslint-plugin-tailwindcss` only handles v4 on an unstable alpha — **avoid it for v4.**
+
+## Packages
+
+| Package | Latest | Tailwind v4? | Verdict |
+| ------- | ------ | ------------ | ------- |
+| `eslint-plugin-better-tailwindcss` | `4.5.0` | **yes (stable)** | **use this** |
+| `eslint-plugin-tailwindcss` | `3.18.3` (v4 only on `4.0.0-alpha`) | beta/as-is | avoid for v4 |
+
+```bash
+pnpm add -D eslint-plugin-better-tailwindcss
+```
+
+Peer deps: `eslint ^7 || ^8 || ^9 || ^10`, `tailwindcss ^3.3.0 || ^4.1.17`. Node ≥ 20.19.
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import { defineConfig } from "eslint/config";
+import betterTailwind from "eslint-plugin-better-tailwindcss";
+
+export default defineConfig([
+  {
+    extends: [betterTailwind.configs["recommended"]],
+    settings: {
+      "better-tailwindcss": {
+        // Tailwind v4: path to the CSS file with `@import "tailwindcss"`
+        entryPoint: "src/app/globals.css",
+        // Tailwind v3 ONLY (omit for v4):
+        // tailwindConfig: "tailwind.config.js",
+      },
+    },
+  },
+]);
+```
+
+## Gotchas
+
+- **`settings.entryPoint` is REQUIRED for Tailwind v4** — it points at the global CSS file
+  containing `@import "tailwindcss"` (v4 has no JS config file). For v3, use `tailwindConfig`
+  instead.
+- **Monorepo**: set `settings["better-tailwindcss"].cwd` per file-group so the plugin resolves
+  `tailwindcss` + the config from the correct project dir when ESLint runs from the repo root.
+- Config presets: `recommended`, `correctness` (errors), `stylistic` (warnings); severity
+  suffixes `-error` / `-warn`.
+- Non-JSX file types (Svelte/Vue/Astro/HTML) need the matching `languageOptions.parser`.
+
+## CBP preset divergence
+
+There is **no** CBP `tailwind` DB preset — Tailwind linting is entirely manual. `tarkur`
+currently has no Tailwind ESLint rules; add the block above to lint class order/validity.
+
+## Official docs
+
+- eslint-plugin-better-tailwindcss: https://github.com/schoero/eslint-plugin-better-tailwindcss
+- Settings: https://github.com/schoero/eslint-plugin-better-tailwindcss/blob/main/docs/settings/settings.md

package/templates/skills/cbp-setup-eslint/reference/testing-react.md

@@ -0,0 +1,57 @@
+# testing-react — Testing Library + jest-dom rules
+
+For React component tests (Testing Library assertions). Layers a **test-scoped** override on
+top of [base](base.md) + the test-runner doc ([vitest](vitest.md) or [jest](jest.md)). Maps to
+the CBP **`testing-react`** DB preset
+(`tech_match.requires: ["React", "Vitest"]`, `requires_capabilities: ["jsx"]`).
+
+> **Verified 2026-05-31.** Both plugins use bracketed `configs['flat/...']` keys and each
+> spreads its own plugin registration — keep them as **separate array entries**.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `eslint-plugin-testing-library` | `7.16.2` | Testing Library best-practices |
+| `eslint-plugin-jest-dom` | `5.5.0` | `@testing-library/jest-dom` matchers |
+
+```bash
+pnpm add -D eslint-plugin-testing-library eslint-plugin-jest-dom
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import testingLibrary from "eslint-plugin-testing-library";
+import jestDom from "eslint-plugin-jest-dom";
+
+const TEST_GLOBS = ["**/*.{test,spec}.{ts,tsx,js,jsx}", "**/__tests__/**/*.{ts,tsx,js,jsx}"];
+
+export default [
+  { files: TEST_GLOBS, ...testingLibrary.configs["flat/react"] }, // 'flat/dom' for non-React
+  { files: TEST_GLOBS, ...jestDom.configs["flat/recommended"] },
+];
+```
+
+## Gotchas
+
+- Keep the two as **separate array entries** — each `...config` spread re-declares its own
+  `plugins`. Merging them into one object means you must hand-combine `plugins` + `rules`.
+- `eslint-plugin-testing-library` framework presets: `flat/react`, `flat/dom` (agnostic),
+  `flat/vue`, `flat/angular`, `flat/svelte`, `flat/marko` — pick **one**.
+- Scope to the **same test globs** as your runner override so the rules don't bleed onto
+  production code.
+- Don't let Playwright e2e specs hit `testing-library/*` rules (e.g.
+  `prefer-screen-queries` mis-fires on Playwright's `page.getByRole`) — scope to `src/**`
+  unit tests, not the e2e dir (see [e2e.md](e2e.md)).
+
+## CBP preset divergence
+
+The CBP `testing-react` preset matches this (`eslint-plugin-testing-library: ^7.0.0`,
+`eslint-plugin-jest-dom: ^5.0.0`, `flat/react` + `flat/recommended`). No divergence.
+
+## Official docs
+
+- testing-library: https://github.com/testing-library/eslint-plugin-testing-library
+- jest-dom: https://github.com/testing-library/eslint-plugin-jest-dom

package/templates/skills/cbp-setup-eslint/reference/vitest.md

@@ -0,0 +1,62 @@
+# vitest — Vitest test-file rules
+
+For apps that test with Vitest (CBP web + CLI + most repos). Layers a **test-scoped** override
+on top of [base](base.md). Maps to the CBP **`testing`** DB preset
+(`tech_match.requires: ["Vitest"]`).
+
+> **Verified 2026-05-31.** The package was **renamed** to the scoped
+> **`@vitest/eslint-plugin`** (the old `eslint-plugin-vitest` is the deprecated name). Its
+> flat-config key is plain **`configs.recommended`** — there is **no `flat/` prefix**.
+
+## Packages
+
+| Package | Latest | Purpose |
+| ------- | ------ | ------- |
+| `@vitest/eslint-plugin` | `1.6.18` | Vitest rules (scoped pkg) |
+
+```bash
+pnpm add -D @vitest/eslint-plugin
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import vitest from "@vitest/eslint-plugin";
+
+export default [
+  {
+    files: ["**/*.{test,spec}.{ts,tsx,js,jsx}"],
+    plugins: { vitest },
+    rules: {
+      ...vitest.configs.recommended.rules,
+      // tests are I/O-heavy + mock-heavy — relax type-safety on test files:
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/no-unsafe-call": "off",
+      "@typescript-eslint/no-unsafe-argument": "off",
+      "@typescript-eslint/no-unsafe-return": "off",
+    },
+    settings: { vitest: { typecheck: true } }, // only if using Vitest type-testing
+  },
+];
+```
+
+## Gotchas
+
+- The key is **`vitest.configs.recommended`** (plain) — NOT `configs['flat/recommended']`.
+  Other plugins use the bracketed `flat/` form; Vitest does not.
+- When you spread only `.rules`, register `plugins: { vitest }` yourself. Alternatively spread
+  the whole `...vitest.configs.recommended` (carries the plugin registration).
+- The `no-unsafe-*` / `no-explicit-any` opt-outs are CBP convention — production code keeps
+  them at `error`; test surfaces relax them because mocks produce `any`-typed values.
+
+## CBP preset divergence
+
+The CBP `testing` preset matches this (the six `no-unsafe-*`/`no-explicit-any` opt-outs,
+`@vitest/eslint-plugin: ^1.0.0`). No divergence.
+
+## Official docs
+
+- @vitest/eslint-plugin: https://github.com/vitest-dev/eslint-plugin-vitest

package/templates/skills/cbp-ship/reference/versioning.md

@@ -2,11 +2,12 @@
 
 How `/cbp-ship` decides which version a surface ships at.
 
-## Three modes (per surface, configured per-package)
+## Four modes (per surface, configured per-package)
 
 | Mode | Trigger | Best for |
 |---|---|---|
 | `manual` | User bumps `package.json` / `tauri.conf.json` / `app.json` version themselves before checkpoint shipment | Apps with infrequent releases; small teams |
+| `in-branch-bump` | `codebyplan ship` detects changed workspace packages via `git diff <base>...HEAD`, patch-bumps each one, and commits a `chore(release): bump versions` commit on the feat branch BEFORE push + PR creation — so the bump rides the same feat→main PR | npm/CLI packages in a pnpm monorepo using the codebyplan CLI; never-missed patch bumps |
 | `release-please` | GH Actions opens version-bump PRs based on conventional commit messages on the watched branch; merge the PR before shipment | npm packages with frequent releases; multi-contributor repos |
 | `changesets` | Devs add `.changeset/*.md` entries in feature branches; an aggregator PR collects them | Monorepos with many independent packages |
 
@@ -16,7 +17,7 @@ Mode is set per-surface in `.codebyplan/shipment.json`:
 {
   "surfaces": {
     "npm-package": {
-      "packages/codebyplan-package": { "versioning": "release-please" }
+      "packages/codebyplan-package": { "versioning": "in-branch-bump" }
     },
     "tauri-desktop": { "versioning": "manual" },
     "expo-mobile": { "versioning": "auto-build-number" }
@@ -59,6 +60,32 @@ Conventional Commits are the trigger:
 
 The release-please workflow lives at `.github/workflows/release-please.yml` (scaffolded by `/cbp-ship-configure`).
 
+> **Retired in this repo.** CodeByPlan itself no longer uses release-please — its `release-please.yml`, `release-please-config.json`, and `.release-please-manifest.json` were removed in favour of the **publish-on-main model** (see in-branch-bump conventions below). `package.json` `version` is the sole version-of-record. The release-please workflow + config templates remain available under `templates/skills/cbp-ship/templates/` for consuming repos that prefer the conventional-commit Release-PR flow.
+
+## in-branch-bump conventions
+
+`codebyplan ship` (the CLI behind `/cbp-ship-main` and `/cbp-checkpoint-end`) runs the bump engine as part of shipping — no separate release PR, no conventional-commit parsing:
+
+1. **When** — after the main-sync merge (`/cbp-merge-main`) and the clean-tree check, BEFORE `git push` + PR creation. The bump therefore rides the same feat→main PR.
+2. **What changed** — `git diff <base>...HEAD` (base from `.codebyplan/git.json`, preferring `origin/<base>`) maps changed files to their owning workspace packages via the `pnpm-workspace.yaml` globs.
+3. **Bump** — every changed package/app is patch-bumped (`x.y.z → x.y.(z+1)`) in its version file (`package.json`, `src-tauri/tauri.conf.json`, Expo `app.json`), and a CHANGELOG entry is prepended where a `CHANGELOG.md` already exists.
+4. **Commit** — the bumped files are committed as `chore(release): bump versions` on the feat branch.
+5. **Idempotent** — a package whose working-tree version already exceeds its base version is skipped, so re-running ship never double-bumps.
+
+`codebyplan ship` is a non-interactive pipeline (bump → push → PR → checks → merge), so there is no confirm-before-merge prompt. To preview the planned bumps WITHOUT committing, run `codebyplan ship --dry-run` (or `codebyplan bump --dry-run`); opt a single real ship out of bumping with `codebyplan ship --no-bump`. The bumps committed on the feat branch are reported in the ship summary (and in `--json` as `bumps[]`). On merge to the production branch, version-change detection publishes each surface whose committed version now exceeds its published version (retiring the release-please Release-PR trigger).
+
+### publish-on-main model
+
+The bump is only half the loop — publishing is the other half. On every push to the production branch, `.github/workflows/publish.yml` closes it:
+
+1. **check-version** — reads the committed `package.json` `version` and compares it to the live `npm view <pkg> version`. Publish proceeds only when the committed version is strictly greater (semver-aware, via `sort -V`); an unchanged or lower version is a no-op. A never-published package is treated as publishable (first release).
+2. **publish** — builds and runs `npm publish --access public` via OIDC Trusted Publishing (no `NPM_TOKEN`; requires npm ≥ 11.5.1). `workflow_dispatch` keeps a manual recovery path (always publishes the current version) plus a `dry_run` input that prints the decision without publishing.
+3. **tag + release** — only after a successful publish, creates the `v{version}` git tag + a GitHub release (idempotent — skipped if the tag already exists, so no orphan tags on a failed publish).
+
+There is **no separate Release PR** — the version committed in the feat branch is the version that ships, so `package.json` is the sole version-of-record. The desktop surface keeps its own `release-desktop.yml` (tauri version vs `desktop-v{version}` tag), which the in-branch `tauri.conf.json` bump feeds automatically.
+
+Other repos inherit this workflow via `codebyplan scaffold-publish-workflow`, which writes `templates/github-workflows/publish.yml` into their `.github/workflows/`. (`.github/` is outside the `codebyplan claude install` target — which only writes under `.claude/` — so the publish workflow has its own scaffold command.)
+
 ## changesets conventions
 
 A changeset is a markdown file describing the change:
@@ -98,7 +125,7 @@ When multiple surfaces ship together, bumps may need to coordinate:
 
 ## What NOT to do
 
-- Don't manually edit `package.json` version inside `/cbp-ship` — versioning happens before shipment, not during
+- Don't hand-edit `package.json` version mid-shipment in `manual` / `release-please` / `changesets` modes — versioning happens before shipment, not during. (`in-branch-bump` inverts this: `codebyplan ship` bumps + commits automatically, after the main-sync merge and before PR creation, so the bump rides the single feat→main PR.)
 - Don't auto-bump in `manual` mode without confirmation — the user owns the bump
 - Don't squash changeset commits — release-please / changesets need each conventional commit visible
 - Don't tag a Tauri release before the version commit is on PRODUCTION branch — the tag locks the shipped version
@@ -107,6 +134,7 @@ When multiple surfaces ship together, bumps may need to coordinate:
 
 | Question | If yes |
 |---|---|
+| Is this an npm/CLI package in a pnpm monorepo shipped via the codebyplan CLI? | in-branch-bump |
 | Is this an npm package with multiple authors? | release-please |
 | Is this a monorepo with 3+ published packages? | changesets |
 | Is this a single app with infrequent releases? | manual |

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

@@ -1,7 +1,7 @@
 ---
 scope: org-shared
 name: cbp-ship-configure
-description: Configure shipment for one or more surfaces in the current repo — Vercel link, EAS project + eas.json scaffold, Apple credentials probe, npm publish auth check (including `codebyplan` asset-publish automation via release-please), Railway project link, Supabase access token verify; Supabase GitHub branching integration via /cbp-supabase-setup. Interactive step-by-step; never stores credentials in the repo.
+description: Configure shipment for one or more surfaces in the current repo — Vercel link, EAS project + eas.json scaffold, Apple credentials probe, npm publish auth check (including `codebyplan` asset-publish automation via the publish-on-main workflow), Railway project link, Supabase access token verify; Supabase GitHub branching integration via /cbp-supabase-setup. Interactive step-by-step; never stores credentials in the repo.
 argument-hint: [--surface=<id>]
 allowed-tools: Read, Write, Edit, Bash(which *), Bash(vercel *), Bash(eas *), Bash(npm *), Bash(railway *), Bash(jq *), Bash(mkdir *), Bash(cp *), Bash(echo *), Skill(cbp-supabase-setup)
 effort: xhigh
@@ -152,22 +152,23 @@ If multiple surfaces were configured, list each one's status. If any failed, lis
 
 Re-running on an already-configured surface re-runs the probe (CLI installed? logged in? token still valid?) and refreshes the `.codebyplan/shipment.json` block. It does NOT replace credentials — those stay where the CLI keeps them. This is the primary path for "I rotated my npm token, does shipment still work?" — re-run, the probe catches the bad token immediately.
 
-## Special case: opt-in to release-please
+## Special case: versioning mode (npm-package)
 
-`release-please` is one of three versioning modes (manual, release-please, changesets). Opt-in is part of npm-package configure:
+Picking a versioning mode is part of npm-package configure:
 
 ```
 Step N/M: Versioning mode
 A) Manual — bump package.json version yourself before /cbp-ship
-B) release-please — GH Action opens version-bump PRs based on conventional commits (recommended for npm packages)
-C) changesets — manual changeset entries; tooling aggregates into version PRs (recommended for monorepos with many published packages)
+B) in-branch-bump — `codebyplan ship` patch-bumps changed packages in the feat branch; merge to main auto-publishes via the publish-on-main workflow (recommended for codebyplan-CLI repos)
+C) release-please — GH Action opens version-bump PRs based on conventional commits
+D) changesets — manual changeset entries; tooling aggregates into version PRs (recommended for monorepos with many published packages)
 ```
 
-If B or C, the skill scaffolds the GitHub Actions workflow + config file (`templates/workflows/release-please.yml` or `.changeset/config.json`).
+If B, the skill scaffolds the publish-on-main workflow via `codebyplan scaffold-publish-workflow` (see the `codebyplan` asset-publish automation section below). If C or D, the skill scaffolds the GitHub Actions workflow + config file (`templates/workflows/release-please.yml` or `.changeset/config.json`). See [../ship/reference/versioning.md](../ship/reference/versioning.md) for the full mode comparison.
 
 ## Special case: `codebyplan` asset-publish automation
 
-The canonical-owner repo publishes the `codebyplan` npm package — the distribution mechanism for `scope: org-shared` skills/agents/hooks (via its `claude install|update|uninstall` subcommand group). Sibling repos consume it via `npx codebyplan claude update` (the merged CLI; package path `packages/codebyplan-package/`). This branch handles the once-per-repo setup so release-please can autopublish on merge to main. (CHK-132 consolidated the prior standalone `@codebyplan/claude` package into `codebyplan`; the legacy `@codebyplan/claude` package on npm stays un-deprecated at its last published version for backward-compat, but receives no further updates.)
+The canonical-owner repo publishes the `codebyplan` npm package — the distribution mechanism for `scope: org-shared` skills/agents/hooks (via its `claude install|update|uninstall` subcommand group). Sibling repos consume it via `npx codebyplan claude update` (the merged CLI; package path `packages/codebyplan-package/`). This branch handles the once-per-repo setup so the package autopublishes on merge to main via the publish-on-main workflow. (CHK-132 consolidated the prior standalone `@codebyplan/claude` package into `codebyplan`; the legacy `@codebyplan/claude` package on npm stays un-deprecated at its last published version for backward-compat, but receives no further updates.)
 
 When the user picks `--surface=npm-package` AND the detected package is `packages/codebyplan-package`, the walkthrough runs these extra probes / scaffolds in addition to the standard npm-package configurator (see [reference/npm-package.md](reference/npm-package.md)):
 
@@ -190,38 +191,17 @@ Confirms the logged-in account has read on the `@codebyplan` org scope. If 404 /
 - Either the user does not belong to the `@codebyplan` org → STOP, request invitation from org owner
 - Or the scope is unclaimed → user creates the org at https://www.npmjs.com/org/create (org name `codebyplan`, free public-packages tier)
 
-### Scaffold 1 — release-please workflow
+### Scaffold — publish-on-main workflow
 
-If `.github/workflows/release-please.yml` is absent:
+The package autopublishes via `.github/workflows/publish.yml` (the publish-on-main model — version-change detection on merge to main, no Release PR). Scaffold it with the CLI:
 
 ```bash
-mkdir -p .github/workflows
-cp "${CLAUDE_SKILL_DIR}/../ship/templates/workflow-release-please.yml" .github/workflows/release-please.yml
-# Then replace REPLACE_WITH_INTEGRATION_BRANCH with the production branch from .codebyplan/git.json branch_config.production (typically `main`)
+codebyplan scaffold-publish-workflow
 ```
 
-The mechanics + commit-prefix → bump-tier mapping live in [../ship/reference/release-please-overview.md](../ship/reference/release-please-overview.md).
+This writes `templates/github-workflows/publish.yml` into `.github/workflows/publish.yml` (idempotent — re-running on an identical file is a no-op; pass `--force` to overwrite a divergent one, `--dry-run` to preview). `.github/` is outside the `codebyplan claude install` target (which only writes under `.claude/`), so the publish workflow has its own scaffold command rather than riding `claude install`.
 
-### Scaffold 2 — release-please-config.json at repo root
-
-If `release-please-config.json` is absent:
-
-```bash
-cp "${CLAUDE_SKILL_DIR}/../ship/templates/release-please-config.json" release-please-config.json
-# Then replace REPLACE_WITH_PACKAGE_NAME with codebyplan
-# Confirm `packages."."` block is replaced with `packages."packages/codebyplan-package"`
-```
-
-### Scaffold 3 — .release-please-manifest.json at repo root
-
-If `.release-please-manifest.json` is absent:
-
-```bash
-VERSION=$(jq -r '.version' packages/codebyplan-package/package.json)
-echo "{\"packages/codebyplan-package\": \"${VERSION}\"}" > .release-please-manifest.json
-```
-
-(Bootstrap version reads from `packages/codebyplan-package/package.json` `version` field at scaffold time.)
+The workflow needs no per-bump editing: it reads `package.json` `version` at run time, compares it to `npm view`, and publishes only when the committed version is greater. `package.json` is the sole version-of-record — there is no `release-please-config.json` / `.release-please-manifest.json`. (Repos that prefer the conventional-commit Release-PR flow can still scaffold release-please from `../ship/templates/` instead — see [../ship/reference/release-please-overview.md](../ship/reference/release-please-overview.md).)
 
 ### Verify — publishConfig.access on the package
 
@@ -249,8 +229,8 @@ Required value: `public`. If `missing` or `restricted`, instruct the user to add
       "packages/codebyplan-package": {
         "package_name": "codebyplan",
         "bin_name": "codebyplan",
-        "versioning": "release-please",
-        "publish_mode": "release-please-on-merge-to-main",
+        "versioning": "in-branch-bump",
+        "publish_mode": "publish-on-main",
         "access": "public"
       }
     }
@@ -258,7 +238,7 @@ Required value: `public`. If `missing` or `restricted`, instruct the user to add
 }
 ```
 
-After this branch completes, every merge to main with `feat:` / `fix:` / `feat!:` Conventional Commits will trigger release-please to open a version-bump PR. When the maintainer merges that PR, release-please tags the release and `npm publish` runs from the workflow (auth via `NODE_AUTH_TOKEN` GH secret or OIDC trusted publishing — see [../ship/reference/npm-publish-oidc-trusted.md](../ship/reference/npm-publish-oidc-trusted.md)). Siblings then pick up the new asset content via `npx codebyplan claude update`.
+After this branch completes, the publish loop is fully automatic: `codebyplan ship` patch-bumps the package in the feat branch (rides the single feat→main PR), and on merge to main `publish.yml` detects the committed version exceeds the npm-published version and runs `npm publish` via OIDC trusted publishing (see [../ship/reference/npm-publish-oidc-trusted.md](../ship/reference/npm-publish-oidc-trusted.md)), then tags `v{version}` + cuts a GitHub release. No separate Release PR. Siblings then pick up the new asset content via `npx codebyplan claude update`.
 
 ## Special case: Apple credentials for TestFlight
 

package/templates/skills/cbp-ship-configure/reference/npm-package.md

@@ -2,7 +2,7 @@
 
 Walkthrough for first-time npm publish setup.
 
-> **Special case** — when the package being configured is `packages/codebyplan-package` (i.e., the `codebyplan` npm package that ships `scope: org-shared` skills/agents/hooks via its `claude` asset subcommand group), the parent SKILL.md "Special case: `codebyplan` asset-publish automation" section runs additional probes (npm whoami, npm publish auth) and scaffolds (`release-please-config.json`, `.release-please-manifest.json` at repo root) on top of the generic walkthrough below. See SKILL.md for the full extra flow. (CHK-132 consolidated the prior `@codebyplan/claude` package into `codebyplan`.)
+> **Special case** — when the package being configured is `packages/codebyplan-package` (i.e., the `codebyplan` npm package that ships `scope: org-shared` skills/agents/hooks via its `claude` asset subcommand group), the parent SKILL.md "Special case: `codebyplan` asset-publish automation" section runs additional probes (npm whoami, npm publish auth) and scaffolds the publish-on-main workflow (`.github/workflows/publish.yml` via `codebyplan scaffold-publish-workflow`) on top of the generic walkthrough below. See SKILL.md for the full extra flow. (CHK-132 consolidated the prior `@codebyplan/claude` package into `codebyplan`.)
 
 ## Prerequisites
 
@@ -85,11 +85,20 @@ Surface any errors/warnings; offer to fix obvious ones (missing `files`, wrong `
 
 ```
 A) Manual — bump package.json version yourself before each release
-B) release-please — GH Action opens version-bump PRs based on conventional commits (recommended)
-C) changesets — manual changeset entries; aggregator PR (recommended for monorepos)
+B) in-branch-bump — `codebyplan ship` patch-bumps changed packages in the feat branch; merge to main auto-publishes via the publish-on-main workflow (recommended for codebyplan-CLI repos)
+C) release-please — GH Action opens version-bump PRs based on conventional commits
+D) changesets — manual changeset entries; aggregator PR (recommended for monorepos)
 ```
 
-If B, scaffold:
+If B, scaffold the publish-on-main workflow (idempotent; `--force` overwrites, `--dry-run` previews):
+
+```bash
+codebyplan scaffold-publish-workflow
+```
+
+`package.json` is the sole version-of-record — no `release-please-config.json` / `.release-please-manifest.json`. See [../../ship/reference/versioning.md](../../ship/reference/versioning.md) for the full model.
+
+If C, scaffold:
 
 ```bash
 cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/workflow-release-please.yml .github/workflows/release-please.yml
@@ -97,7 +106,7 @@ cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/release-please-config.json releas
 echo '{".":"<current version>"}' > .release-please-manifest.json
 ```
 
-If C:
+If D:
 
 ```bash
 cd "$REPO_ROOT"
@@ -134,7 +143,7 @@ The workflow uses `permissions: id-token: write` and runs `npm publish --provena
       "configured_at": "<now>",
       "packages/codebyplan-package": {
         "package_name": "codebyplan",
-        "versioning": "release-please",
+        "versioning": "in-branch-bump",
         "publish_mode": "oidc",
         "access": "public"
       }

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

@@ -48,10 +48,14 @@ codebyplan ship --body-file /tmp/cbp-ship-main-body.md --json${DRY_RUN:+ --dry-r
 
 Pass `--dry-run` through if the skill was invoked with a dry-run arg.
 
+`codebyplan ship` patch-bumps every changed workspace package and commits `chore(release): bump versions` on the feat branch BEFORE creating the PR, so the bump rides this same feat→main PR (see `cbp-ship/reference/versioning.md`, `in-branch-bump` mode). Pass `--no-bump` to skip for a single ship.
+
 ### Step 4: Report
 
 Parse JSON from Step 3. Report `pr_url`, `merge_commit`, `branch_deleted`. If `checks_failed: true`, surface `checks_failure_reason` and stop.
 
+If `bumps[]` is present with any non-skipped entry, surface a **Version bumps** line per package — `<name>: <currentVersion> → <nextVersion>` — so the user sees what this PR will publish on merge.
+
 If `branch_deleted === true`, run a conditional Supabase preview-branch teardown for the feat branch that was just merged:
 
 > Lifecycle contract: see [[supabase-branch-lifecycle]].

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

@@ -137,9 +137,7 @@ Skip the push only when nothing was committed in Step 5 AND `/cbp-merge-main` re
 
 ### Step 7: Complete Task
 
-If `CALLER_WT` is non-empty, call `complete_task(task_id, caller_worktree_id: CALLER_WT)`. Otherwise call `complete_task(task_id)` with no worktree id — the pre-guard is skipped (backwards-compat).
-
-**When calling `complete_task`**: pass `caller_worktree_id` resolved from `npx codebyplan resolve-worktree`. The MCP server's pre-guard rejects mutations from non-matching worktrees; supplying `caller_worktree_id` ensures legitimate completion succeeds. The server auto-clears `assigned_user_id` + `assigned_worktree_id` on the task; if this was the last sibling task, it also clears the parent checkpoint's assignment. (Per CHK-104 TASK-2 hard-lock.)
+Call `complete_task(task_id)`. The server resolves the caller's worktree identity from the JWT/ctx and enforces the mutate-lock (CHK-140 TASK-3 — `caller_worktree_id` input field removed). The server auto-clears `assigned_user_id` + `assigned_worktree_id` on the task; if this was the last sibling task, it also clears the parent checkpoint's assignment. (Per CHK-104 hard-lock.)
 
 ### Step 7.5: Standalone Task Branch Merge
 

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

@@ -160,9 +160,9 @@ See `dependency-vulnerability-fixes.md` "Audit Sweep at Task Start" for the sour
 
 ### Step 3.5: Worktree-Match Verification
 
-Before activating the task, verify the caller's worktree matches the assigned worktree on the target row. (Per CHK-104 TASK-2 — DB-level hard-lock prevents cross-worktree mutations.)
+Before activating the task, verify the caller's worktree matches the assigned worktree on the target row. (Per CHK-104 — DB-level hard-lock prevents cross-worktree mutations; the server resolves caller identity from the JWT/ctx.)
 
-1. Read caller worktree: `CALLER_WT=$(npx codebyplan resolve-worktree 2>/dev/null)`. If empty, the `caller_worktree_id` parameter is omitted from the MCP call entirely — the pre-guard is skipped and the update proceeds without a worktree check (backwards-compat).
+1. Read caller worktree: `CALLER_WT=$(npx codebyplan resolve-worktree 2>/dev/null)`.
 2. Determine target worktree:
    - **Checkpoint-bound tasks**: `TARGET_WT = checkpoint.worktree_id` (read from MCP `get_checkpoints`). Note: checkpoint-bound tasks may have a NULL `task.assigned_worktree_id` because the lock lives on the parent checkpoint — fall through to `checkpoint.worktree_id`.
    - **Standalone tasks**: `TARGET_WT = task.assigned_worktree_id`.
@@ -222,7 +222,7 @@ Display context summary:
 
 Use MCP `update_task(task_id, status: "in_progress")`.
 
-If worktree_id present, include `claim_worktree_id` to auto-claim the checkpoint AND `caller_worktree_id: CALLER_WT` so the MCP server's pre-guard accepts the call (CHK-104 TASK-2 hard-lock).
+If worktree_id present, include `claim_worktree_id` to auto-claim the checkpoint. The server resolves the caller's worktree identity from the JWT/ctx (CHK-140 TASK-3 — `caller_worktree_id` input field removed).
 
 ### Step 6: Auto-trigger Round Start