codebyplan 1.13.51 → 1.13.53

package/package.json

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

package/templates/agents/cbp-security-agent.md

@@ -1,4 +1,5 @@
 ---
+scope: org-shared
 name: cbp-security-agent
 description: Security review specialist. Checks for OWASP top 10 vulnerabilities, hardcoded secrets, SQL injection, XSS, CSRF, and dependency vulnerabilities.
 tools: Read, Glob, Grep, Bash
@@ -101,7 +102,14 @@ For API routes and server actions:
 
 ### Phase 7: Dependency Audit
 
-Run `pnpm audit --json 2>&1` from the **monorepo root** (not an app subdirectory). This ensures root-level `pnpm.overrides` are reflected in the audit results. Parse output and report critical/high findings.
+Resolve the audit command from `.codebyplan/ci.json`, then run from the **monorepo root** (so root-level `pnpm.overrides` are reflected):
+
+```bash
+CI_AUDIT_CMD=$(npx codebyplan ci resolve audit 2>/dev/null || echo "pnpm audit --json")
+cd /path/to/monorepo/root && ${CI_AUDIT_CMD} 2>&1
+```
+
+Fallback: if `.codebyplan/ci.json` is absent, `codebyplan ci resolve audit` still returns the central default (exit 0). The `|| echo` guard handles repos where the `codebyplan` binary is unavailable. Parse output and report critical/high findings.
 
 For transitive vulnerabilities, note the standard fix path: add `"package": ">=X.Y.Z"` to `pnpm.overrides` in root `package.json`. For direct vulnerabilities, suggest bumping the dependency in the consuming package.
 

package/templates/agents/cbp-testing-qa-agent.md

@@ -1,4 +1,5 @@
 ---
+scope: org-shared
 name: cbp-testing-qa-agent
 description: Combined testing, QA generation, and default checklists. Runs build/lint/types/unit-tests/audit, generates auto QA items, applies default production checklists. Does NOT consume e2e screenshots or frontend-ui findings.
 tools: Read, Glob, Grep, Bash, AskUserQuestion
@@ -150,6 +151,19 @@ E2E (Playwright / Maestro / WebDriverIO / XCUITest / vscode-test) is NEVER run b
 
 **CRITICAL: Within your profile's allowed check set (see Profile Gate Matrix above), every applicable command MUST be executed. No skipping an in-scope check without an explicit, logged reason.**
 
+**Step 0: Resolve check commands from ci.json (absent-fallback safe)**
+
+After detecting `$PLATFORM` in Step 1, resolve per-category commands from `.codebyplan/ci.json`:
+
+```bash
+CI_BUILD_CMD=$(npx codebyplan ci resolve build --platform "$PLATFORM" 2>/dev/null)
+CI_TYPES_CMD=$(npx codebyplan ci resolve typecheck --platform "$PLATFORM" 2>/dev/null)
+CI_UNIT_CMD=$(npx codebyplan ci resolve unit_test --platform "$PLATFORM" 2>/dev/null)
+CI_AUDIT_CMD=$(npx codebyplan ci resolve audit 2>/dev/null)
+```
+
+Fallback: if `.codebyplan/ci.json` is absent, `codebyplan ci resolve` returns the central default command (exit 0). If the binary is unavailable, the variable is empty and the `${CI_*_CMD:-<literal>}` guards in the command cells below activate the hardcoded fallback, keeping non-migrated repos working.
+
 **Step 1: Determine project root and platform** — read `.claude/docs/architecture/testing-matrix.md` (when present) for platform-specific commands. Find the correct app directory and detect platform:
 
 | Signal | Platform | Unit Runner |
@@ -171,9 +185,9 @@ For each check below, you MUST:
 
 | Check | Command | Hard Fail | Skip Conditions | Skip when profile= |
 |-------|---------|-----------|-----------------|-------------------|
-| **Build** | `cd {app_dir} && npm run build 2>&1` | YES | Only if no app code changed | claude_only, or per app-type exclusion above |
+| **Build** | `cd {app_dir} && ${CI_BUILD_CMD:-npm run build} 2>&1` | YES | Only if no app code changed | claude_only, or per app-type exclusion above |
 | **Lint** | `cd {app_dir} && npm run lint 2>&1` | YES | Only if no app code changed | claude_only |
-| **Types** | `cd {app_dir} && npx tsc --noEmit 2>&1` | YES | Only if no app code changed | claude_only |
+| **Types** | `cd {app_dir} && ${CI_TYPES_CMD:-npx tsc --noEmit} 2>&1` | YES | Only if no app code changed | claude_only |
 
 **Lint scope expansion on config change (MANDATORY)**: when ANY entry in `files_changed[]` matches `eslint.config.*` / `.eslintrc.*` / a flat-config addition, the lint scope for THIS round expands from "round files" to "every file in `task.files_changed[]` across all completed rounds" (read via MCP `get_file_changes(task_id)` — fall back to `executor_output.files_changed` aggregated with prior-round files from `task.context.cumulative_files_changed[]` if available).
 
@@ -194,12 +208,12 @@ Run the unit-test runners detected in Step 1:
 
 | Platform | Unit Command |
 |----------|-------------|
-| Next.js | `cd {app_dir} && npx vitest --run 2>&1` |
-| NestJS | `cd {app_dir} && npx jest 2>&1` |
-| Tauri | `cd {app_dir} && npx vitest --run 2>&1` AND `cd {app_dir}/src-tauri && cargo test 2>&1` |
-| Expo | `cd {app_dir} && npx jest 2>&1` |
-| VS Code | `cd {app_dir} && npx vitest --run 2>&1` |
-| Package | `cd {pkg_dir} && npx vitest --run 2>&1` |
+| Next.js | `cd {app_dir} && ${CI_UNIT_CMD:-npx vitest --run} 2>&1` |
+| NestJS | `cd {app_dir} && ${CI_UNIT_CMD:-npx jest} 2>&1` |
+| Tauri | `cd {app_dir} && ${CI_UNIT_CMD:-npx vitest --run} 2>&1` AND `cd {app_dir}/src-tauri && cargo test 2>&1` |
+| Expo | `cd {app_dir} && ${CI_UNIT_CMD:-npx jest} 2>&1` |
+| VS Code | `cd {app_dir} && ${CI_UNIT_CMD:-npx vitest --run} 2>&1` |
+| Package | `cd {pkg_dir} && ${CI_UNIT_CMD:-npx vitest --run} 2>&1` |
 
 **Hard fail conditions:**
 - Unit tests: YES — when source files in files_changed
@@ -288,7 +302,7 @@ Mandatory dependency vulnerability scan:
 
 > **Vulnerability fix tasks**: If the current task title matches `/GHSA-|CVE-|vulnerabilit/i`, the audit result IS the primary test. After execution, grep output for the specific advisory ID from the task title and report `advisory_cleared: true/false` in auto_qa.
 
-1. **Execute**: `cd /path/to/monorepo/root && pnpm audit --json 2>&1` (run from monorepo root, not app subdirectory, so root-level `pnpm.overrides` are reflected)
+1. **Execute**: Run from the monorepo root (so root-level `pnpm.overrides` are reflected): `cd /path/to/monorepo/root && ${CI_AUDIT_CMD:-pnpm audit --json} 2>&1`
 2. **Parse** JSON output, categorize by severity: critical, high, medium, low
 3. **Determine pass/fail**:
    - Critical or high found → `fail`, set `totals.hard_fail = true`

package/templates/github-workflows/ci.yml

@@ -0,0 +1,63 @@
+# Generated by: codebyplan ci scaffold-workflow
+#
+# This workflow runs lint, typecheck, tests, and build on every pull request.
+# It is intentionally generic and works as-is for any pnpm + Turborepo project.
+#
+# By design this gates on FULL-REPO GREEN: `pnpm turbo <task>` runs the task
+# across every package with no `--filter`, so a shallow checkout (fetch-depth:1)
+# is fine — git history is not needed for affected-package detection. Per-package
+# / changed-path scoping (`scope: per_app_changed` in .codebyplan/ci.json) is
+# applied by the local CodeByPlan round/testing skills, NOT by this workflow.
+# Do not add turbo `--filter=[HEAD^]` here without also setting fetch-depth: 0.
+#
+# Two values you can adjust via `codebyplan ci scaffold-workflow`:
+#   --pnpm-version <v>   pnpm version (current: {{PNPM_VERSION}})
+#   --node-version <v>   Node.js version (current: {{NODE_VERSION}})
+
+name: CI
+
+on:
+  pull_request:
+
+# Cancel an in-progress run when a newer commit is pushed to the same PR/ref,
+# so superseded full-repo runs don't queue up and waste runner minutes.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    name: Lint + typecheck + test + build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: "{{PNPM_VERSION}}"
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "{{NODE_VERSION}}"
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm turbo lint
+
+      - name: Typecheck
+        run: pnpm turbo typecheck
+
+      - name: Test
+        run: pnpm turbo test
+
+      - name: Build
+        run: pnpm turbo build

package/templates/github-workflows/publish.yml

@@ -1,34 +1,16 @@
-# Generated by: codebyplan scaffold-publish-workflow
-#
-# This workflow publishes the codebyplan npm package on every merge to main
-# where the committed package.json version exceeds the version currently on npm.
-# It also auto-publishes prerelease versions (e.g. 1.14.0-beta.1) from feat/**
-# branches to a scoped dist-tag (e.g. --tag beta) — see the beta channel docs
-# for the full workflow. No release PR, no conventional-commit parsing — the
-# version committed in the feat branch is the version that ships.
-#
-# Two values a consuming repo must adjust:
-#   1. paths: — set to the package directory whose package.json drives versioning
-#              (current value: 'packages/codebyplan-package/**')
-#   2. npm view <package-name> — replace `codebyplan` with the actual package name
-#              in the "Check version vs published" and exact-version check steps
-#
-# Everything else (OIDC auth, pnpm 10.12.4, Node 20, build:npm → publish) is
-# intentionally generic and works as-is for any single-package npm publish.
-
 name: Publish codebyplan to npm
 
 on:
   push:
     branches:
       - main
-      - "feat/**"
+      - 'feat/**'
     paths:
-      - "packages/codebyplan-package/**"
+      - 'packages/codebyplan-package/**'
   workflow_dispatch:
     inputs:
       dry_run:
-        description: "Print what would be published without actually publishing"
+        description: 'Print what would be published without actually publishing'
         type: boolean
         default: false
 
@@ -182,7 +164,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: pnpm
 
       - name: Install dependencies
@@ -210,11 +192,10 @@ jobs:
       # short-lived publish token. Requires a Trusted Publisher configured for
       # this repo + workflow on npmjs.com.
       #
-      # NO --provenance by default: npm provenance attestation only supports
-      # PUBLIC source repositories (the registry returns E422 "Unsupported
-      # source repository visibility: private" otherwise). This works for both
-      # public and private repos. If your source repo is PUBLIC and you want
-      # supply-chain attestation, add `--provenance` to the command below.
+      # NO --provenance: npm provenance attestation only supports PUBLIC source
+      # repositories (registry returns E422 "Unsupported source repository
+      # visibility: private" otherwise). This repo is private, so provenance is
+      # omitted. Re-add `--provenance` only if the source repo becomes public.
       #
       # --tag: routes stable publishes to "latest" and prerelease publishes to
       # the prerelease id (e.g. "beta", "rc"). C1 guarantee: betas never land on

package/templates/github-workflows/release-desktop.yml

@@ -0,0 +1,215 @@
+name: Release Desktop App
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "apps/desktop/**"
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+
+jobs:
+  check-version:
+    name: Check if release needed
+    runs-on: ubuntu-latest
+    outputs:
+      should_release: ${{ steps.check.outputs.should_release }}
+      version: ${{ steps.check.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check version tag
+        id: check
+        run: |
+          VERSION=$(jq -r '.version' apps/desktop/src-tauri/tauri.conf.json)
+          TAG="desktop-v${VERSION}"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+          if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q "${TAG}"; then
+            echo "Tag ${TAG} already exists - skipping release"
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Tag ${TAG} does not exist - will release"
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
+          fi
+
+  build:
+    needs: check-version
+    if: needs.check-version.outputs.should_release == 'true'
+    # `secrets` is not allowed in `if:` expressions — map presence to a job-level
+    # env (where `secrets` IS permitted) and test that in the step condition.
+    env:
+      HAS_WINDOWS_CERT: ${{ secrets.WINDOWS_CERTIFICATE != '' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: macos-latest
+            target: aarch64-apple-darwin
+            label: macOS (Apple Silicon)
+          - platform: macos-latest
+            target: x86_64-apple-darwin
+            label: macOS (Intel)
+          - platform: windows-latest
+            target: x86_64-pc-windows-msvc
+            label: Windows (x86_64)
+
+    name: Build ${{ matrix.label }}
+    runs-on: ${{ matrix.platform }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Write Apple API key to file
+        if: runner.os == 'macOS'
+        run: |
+          mkdir -p ~/private_keys
+          printf '%s' "$APPLE_API_KEY_CONTENT" > ~/private_keys/AuthKey.p8
+        env:
+          APPLE_API_KEY_CONTENT: ${{ secrets.APPLE_API_KEY_CONTENT }}
+
+      - name: Build desktop app
+        # Pinned for supply-chain safety. Review before bumping:
+        # https://github.com/tauri-apps/tauri-action/releases
+        #
+        # Windows leg skipped when WINDOWS_CERTIFICATE secret is absent — lets
+        # macOS-only notarized releases ship while the Windows EV cert is being
+        # procured. When the secret is present but the build fails for any other
+        # reason (network, tauri-action bug, etc.), the step still fails loudly.
+        if: ${{ runner.os != 'Windows' || env.HAS_WINDOWS_CERT == 'true' }}
+        uses: tauri-apps/tauri-action@84b9d35b5fc46c1e45415bdb6144030364f7ebc5 # action-v0.6.2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Tauri updater artifact signing (required for latest.json signatures on all platforms)
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+          # Apple Developer signing (macOS only — empty on Windows, tauri-action ignores)
+          APPLE_CERTIFICATE: ${{ runner.os == 'macOS' && secrets.APPLE_CERTIFICATE || '' }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ runner.os == 'macOS' && secrets.APPLE_CERTIFICATE_PASSWORD || '' }}
+          APPLE_SIGNING_IDENTITY: ${{ runner.os == 'macOS' && secrets.APPLE_SIGNING_IDENTITY || '' }}
+          APPLE_API_ISSUER: ${{ runner.os == 'macOS' && secrets.APPLE_API_ISSUER || '' }}
+          APPLE_API_KEY: ${{ runner.os == 'macOS' && secrets.APPLE_API_KEY || '' }}
+          APPLE_API_KEY_PATH: ${{ runner.os == 'macOS' && '~/private_keys/AuthKey.p8' || '' }}
+          # Windows code signing (Windows only — empty on macOS, tauri-action ignores)
+          WINDOWS_CERTIFICATE: ${{ runner.os == 'Windows' && secrets.WINDOWS_CERTIFICATE || '' }}
+          WINDOWS_CERTIFICATE_PASSWORD: ${{ runner.os == 'Windows' && secrets.WINDOWS_CERTIFICATE_PASSWORD || '' }}
+        with:
+          projectPath: apps/desktop
+          tauriScript: pnpm tauri
+          args: --target ${{ matrix.target }}
+          tagName: desktop-v${{ needs.check-version.outputs.version }}
+          releaseName: "CodeByPlan Desktop v${{ needs.check-version.outputs.version }}"
+          releaseBody: |
+            ## CodeByPlan Desktop v${{ needs.check-version.outputs.version }}
+
+            Download the appropriate installer for your platform:
+            - **macOS Apple Silicon** (.dmg) - For M1/M2/M3/M4 Macs
+            - **macOS Intel** (.dmg) - For older Intel-based Macs
+            - **Windows** (.msi) - For Windows 10/11 x64
+
+            ### Installation
+
+            **macOS:**
+            1. Download the `.dmg` file for your Mac
+            2. Open the `.dmg` and drag CodeByPlan to Applications
+            3. Launch CodeByPlan from Applications
+
+            **Windows:**
+            1. Download the `.msi` file
+            2. Run the installer and follow the prompts
+            3. Launch CodeByPlan from the Start Menu
+          releaseDraft: false
+          prerelease: false
+          includeUpdaterJson: true
+
+  notify:
+    needs: [check-version, build]
+    if: needs.check-version.outputs.should_release == 'true' && needs.build.result == 'success'
+    runs-on: ubuntu-latest
+    name: Register Release
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download latest.json from GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.check-version.outputs.version }}
+        run: |
+          TAG="desktop-v${VERSION}"
+          gh release download "${TAG}" --pattern "latest.json" --dir .
+
+      - name: Post release metadata to API
+        env:
+          CBP_API_KEY: ${{ secrets.CODEBYPLAN_API_KEY }}
+          VERSION: ${{ needs.check-version.outputs.version }}
+        run: |
+          TAG="desktop-v${VERSION}"
+          REPO="${{ github.repository }}"
+          BASE_URL="https://github.com/${REPO}/releases/download/${TAG}"
+
+          # Read the latest.json generated by tauri-action
+          MANIFEST=$(cat latest.json)
+          echo "Manifest: ${MANIFEST}"
+
+          # Build download URLs (for website download page)
+          AARCH64_DMG_URL="${BASE_URL}/CodeByPlan_${VERSION}_aarch64.dmg"
+          X86_64_DMG_URL="${BASE_URL}/CodeByPlan_${VERSION}_x64.dmg"
+          WINDOWS_X86_64_MSI_URL="${BASE_URL}/CodeByPlan_${VERSION}_x64_en-US.msi"
+
+          # Extract updater data from latest.json and merge with installer URLs
+          PLATFORMS=$(echo "${MANIFEST}" | jq \
+            --arg aarch64_dmg "${AARCH64_DMG_URL}" \
+            --arg x86_64_dmg "${X86_64_DMG_URL}" \
+            --arg windows_x86_64_msi "${WINDOWS_X86_64_MSI_URL}" '
+            .platforms | to_entries | map(
+              .value += (
+                if .key == "darwin-aarch64" then { "dmg_url": $aarch64_dmg }
+                elif .key == "darwin-x86_64" then { "dmg_url": $x86_64_dmg }
+                elif .key == "windows-x86_64" then { "msi_url": $windows_x86_64_msi }
+                else {}
+                end
+              )
+            ) | from_entries
+          ')
+
+          NOTES=$(echo "${MANIFEST}" | jq -r '.notes // "CodeByPlan Desktop v'"${VERSION}"'"')
+          PUB_DATE=$(echo "${MANIFEST}" | jq -r '.pub_date // empty')
+          if [ -z "${PUB_DATE}" ]; then
+            PUB_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+          fi
+
+          # POST to our API
+          curl -fL -X POST \
+            "https://www.codebyplan.com/api/desktop/releases" \
+            -H "Content-Type: application/json" \
+            -H "x-api-key: ${CBP_API_KEY}" \
+            -d "$(jq -n \
+              --arg version "${VERSION}" \
+              --arg notes "${NOTES}" \
+              --arg pub_date "${PUB_DATE}" \
+              --argjson platforms "${PLATFORMS}" \
+              '{version: $version, notes: $notes, pub_date: $pub_date, platforms: $platforms}'
+            )"

package/templates/settings.project.base.json

@@ -133,6 +133,8 @@
       "Skill(cbp-round-start)",
       "Skill(cbp-round-update)",
       "Skill(cbp-session-start)",
+      "Skill(cbp-setup-cd)",
+      "Skill(cbp-setup-ci)",
       "Skill(cbp-setup-e2e)",
       "Skill(cbp-setup-eslint)",
       "Skill(cbp-ship-configure)",
@@ -249,7 +251,11 @@
       "Bash(codebyplan e2e:*)",
       "Bash(npx codebyplan e2e:*)",
       "Bash(codebyplan arch-map:*)",
-      "Bash(npx codebyplan arch-map:*)"
+      "Bash(npx codebyplan arch-map:*)",
+      "Bash(codebyplan ci:*)",
+      "Bash(npx codebyplan ci:*)",
+      "Bash(codebyplan cd:*)",
+      "Bash(npx codebyplan cd:*)"
     ]
   },
   "attribution": {

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

@@ -157,5 +157,6 @@ Checks: name matches directory, frontmatter parses, no invalid fields, arg-hint
 - Rendered `SKILL.md` content enters the conversation once when invoked and stays until compaction — write standing instructions, not one-time steps
 - Preloaded subagent skills cannot have `disable-model-invocation: true`
 - `context: fork` is only meaningful when the skill body contains an actionable task; otherwise the subagent receives guidelines with no prompt
+- `context: fork` ALSO disqualifies fan-out / spawn-then-route / inline-by-design / consumed-inline skills — they run in the main context for a reason; see [reference/fork-eligibility.md](reference/fork-eligibility.md) for the eligibility test + the CBP classification of which skills may fork and which must stay inline
 - Descriptions front-load key use case: `description` + `when_to_use` cap at 1,536 chars in the skill listing
 - `paths:` scoping applies when Claude reads files matching the globs, not on every tool use

package/templates/skills/cbp-build-cc-skill/reference/fork-eligibility.md

@@ -0,0 +1,78 @@
+# `context: fork` Eligibility — when to fork a skill, and when not to
+
+`context: fork` runs the **entire SKILL.md body in a forked subagent** — it inherits the
+parent conversation and, per the runtime, **runs in the background by default**. It is
+isolation for a *whole skill*, not a way to delegate one sub-step. A forked body therefore
+cannot drive the main pipeline: it can't `AskUserQuestion`, can't auto-trigger another
+skill, and can't run an inline-fallback that the orchestrator depends on.
+
+So forking only helps a narrow shape of skill. The canonical eligible example is
+[examples/fork-skill.md](../examples/fork-skill.md): a single self-contained analytical task
+that reads, reasons, and returns a summary — nothing else.
+
+## Eligibility test
+
+A skill is **fork-eligible** only when ALL hold:
+
+1. Its whole body is **one** self-contained analytical/generative task (read → reason → return).
+2. It is **non-interactive** — no `AskUserQuestion`, no user decision gates.
+3. It does **not route** — no auto-trigger of another skill, no close-out directive that must
+   fire in the main context.
+4. It does **not fan out** — it does not spawn multiple subagents and coordinate them.
+5. It has **no inline-fallback** contract the orchestrator relies on.
+
+Fail any one → the skill stays **inline** (main context). Inline skills still get clean
+context isolation the right way: by delegating their heavy step to a dedicated **agent**
+(e.g. `cbp-task-check`, `cbp-improve-round`, `cbp-round-executor`). The agent is the
+isolation boundary; the skill stays in the main thread to orchestrate, route, and interact.
+
+## When NOT to use `context: fork` (the disqualifying patterns)
+
+| Pattern | Why it can't fork | Example skills |
+|---------|-------------------|----------------|
+| **fan-out** | spawns multiple agents in parallel and coordinates them | `cbp-round-execute`, `cbp-checkpoint-check`, `cbp-map-architecture`, `cbp-refresh-arch-map` |
+| **spawn-then-route** | spawns one agent, then `AskUserQuestion` / auto-triggers the next skill / runs inline-fallback | `cbp-task-check`, `cbp-standalone-task-check`, `cbp-round-start`, `cbp-round-end`, `cbp-checkpoint-plan` |
+| **inline-by-design** | interactive Q&A or stepwise writes that must stay in the main context | `cbp-task-create`, `cbp-task-complete`, `cbp-round-update`, `cbp-merge-main` |
+| **consumed-inline** | invoked *by* an agent (e.g. round-executor) and applies fixes synchronously into that context | `cbp-frontend-design`, `cbp-frontend-ui`, `cbp-frontend-ux` |
+| **doc-ref-only** | mentions subagents/fork only as documentation; runs inline authoring | the `cbp-build-cc-*` authoring skills, `cbp-supabase-migrate` |
+
+## CHK-220 audit — classification matrix
+
+Every skill whose `SKILL.md` touches the subagent/fork boundary — by spawning a subagent, by
+being invoked inline by an agent, or by documenting the feature — was classified against the
+eligibility test. **Result: 0 of 25 are fork-eligible** — none were migrated, because every
+one either already isolates heavy work in a dedicated agent (the correct boundary) or depends
+on inline orchestration/interaction that a background fork would break.
+
+| Skill | Pattern | Fork-eligible |
+|-------|---------|:---:|
+| cbp-round-execute | fan-out | no |
+| cbp-checkpoint-check | fan-out | no |
+| cbp-map-architecture | fan-out | no |
+| cbp-refresh-arch-map | fan-out | no |
+| cbp-round-start | spawn-then-route | no |
+| cbp-round-end | spawn-then-route | no |
+| cbp-task-check | spawn-then-route | no |
+| cbp-standalone-task-check | spawn-then-route | no |
+| cbp-checkpoint-plan | spawn-then-route | no |
+| cbp-round-update | inline-by-design | no |
+| cbp-task-create | inline-by-design | no |
+| cbp-standalone-task-create | inline-by-design | no |
+| cbp-task-complete | inline-by-design | no |
+| cbp-standalone-task-complete | inline-by-design | no |
+| cbp-merge-main | inline-by-design | no |
+| cbp-task-testing | inline-by-design | no |
+| cbp-standalone-task-testing | inline-by-design | no |
+| cbp-frontend-design | consumed-inline | no |
+| cbp-frontend-ui | consumed-inline | no |
+| cbp-frontend-ux | consumed-inline | no |
+| cbp-supabase-migrate | doc-ref-only | no |
+| cbp-build-cc-skill | doc-ref-only | no |
+| cbp-build-cc-agent | doc-ref-only | no |
+| cbp-build-cc-settings | doc-ref-only | no |
+| cbp-build-cc-mode | doc-ref-only | no |
+
+If a **new** skill is authored that passes the eligibility test above, fork it: add
+`context: fork` + `agent: <Explore|Plan|general-purpose|custom>` (use `--fork` in
+`/cbp-build-cc-skill`). Do not retrofit fork onto any skill in the table — their inline
+shape is load-bearing.

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

@@ -20,6 +20,10 @@ Source: official Claude Code skills spec. All fields are optional; `description`
 | `paths` | Globs that auto-load the skill when matching files are in play |
 | `shell` | `bash` (default) or `powershell` for `!`-commands |
 
+> `context: fork` / `agent` are right for only a narrow shape of skill — a single
+> non-interactive analytical body. See [fork-eligibility.md](fork-eligibility.md) for the
+> eligibility test and the CBP classification of which skills may fork (and which must stay inline).
+
 ## Character budget
 
 Combined `description` + `when_to_use` truncates at **1,536 characters** in the skill listing. Front-load the key use case.

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

@@ -1,4 +1,5 @@
 ---
+scope: org-shared
 name: cbp-checkpoint-check
 description: Full re-evaluation of a checkpoint with before/after comparison
 argument-hint: [CHK-NNN]
@@ -83,7 +84,14 @@ Aggregate QA from all tasks and rounds:
 | TASK-[N] | READY | all_pass | [N] |
 ```
 
-Re-run build/lint/types on current codebase to verify nothing regressed across tasks.
+Re-run build/lint/types on the current codebase to verify nothing regressed across tasks. Detect `$PLATFORM` from the project type (same signal table as `cbp-testing-qa-agent.md` Step 1), then resolve commands from `.codebyplan/ci.json`:
+
+```bash
+CI_BUILD_CMD=$(npx codebyplan ci resolve build --platform "$PLATFORM" 2>/dev/null)
+CI_TYPES_CMD=$(npx codebyplan ci resolve typecheck --platform "$PLATFORM" 2>/dev/null)
+```
+
+Run: `${CI_BUILD_CMD:-npm run build}` and `${CI_TYPES_CMD:-npx tsc --noEmit}`. For lint use the whole-repo command (`pnpm -w lint`). Fallback: if `.codebyplan/ci.json` is absent, `ci resolve` returns the central default; if the binary is unavailable the `${CI_*_CMD:-<literal>}` guard uses the hardcoded fallback.
 
 ### Step 5b: Whole-Checkpoint E2E
 

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

@@ -96,7 +96,11 @@ Runtime deployment for the base branch is handled in Step 7 by `/cbp-ship` (whic
 
 ### Step 7: Runtime Shipment via `/cbp-ship`
 
-After branch promotion to main completes, invoke `/cbp-ship` to deploy every configured surface:
+After branch promotion to main completes, invoke `/cbp-ship` to deploy every configured surface.
+`/cbp-ship` reads `.codebyplan/cd.json` when present to inform per-surface deploy variant
+selection (trigger, environment, approval gate, OIDC auth, credential env-var names). Repos
+without `cd.json` fall back to filesystem surface detection — no behavior change. Run
+`/cbp-setup-cd` to set up `cd.json` for a repo that has not yet migrated.
 
 - Vercel auto-deploy verification
 - Mobile shipment (asks user: skip / EAS internal TestFlight / EAS external TestFlight)

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

@@ -1,4 +1,5 @@
 ---
+scope: org-shared
 name: cbp-round-check
 description: Run automated checks standalone for the current round
 effort: low
@@ -129,4 +130,5 @@ If soft failures only: `Run /cbp-round-start to trigger auto-fix, or fix manuall
 - **Writes (checkpoint KIND)**: `codebyplan round update` (qa field). Break-glass: MCP `update_round`.
 - **Writes (standalone KIND)**: MCP `update_standalone_round` (qa field). (Standalone KIND still uses MCP until a later task.)
 - **Runner**: `codebyplan check --scope round --json` (whole-repo + baseline via `turbo run`; runs gate6 + lint + typecheck + tests; `--files` is accepted but ignored in whole-repo mode)
+- **ci.json awareness**: `codebyplan check` is turbo-native — it runs `turbo run lint|typecheck|test` directly and does NOT read `.codebyplan/ci.json`. ci.json command resolution (via `npx codebyplan ci resolve <category> [--platform <slug>]`) is used by non-check consumers (`cbp-testing-qa-agent`, `cbp-security-agent`, `cbp-standalone-task-testing`, `cbp-checkpoint-check`), with a central-default fallback ensuring exit 0 even when ci.json is absent.
 - **Standalone**: Can be run independently at any time