codebyplan 1.13.52 → 1.13.53

package/templates/skills/cbp-setup-ci/reference/github-actions.md

@@ -0,0 +1,100 @@
+# GitHub Actions CI Reference
+
+Workflow anatomy, required status check setup, and troubleshooting for the
+`codebyplan ci` scaffold.
+
+## Overview
+
+GitHub Actions CI runs on every push and pull request. The `codebyplan ci scaffold-workflow`
+command writes `.github/workflows/ci.yml` from a bundled template. The workflow installs
+the Node + pnpm environment, caches dependencies, and runs a single job named
+**Lint + typecheck + test + build** that gates every PR.
+
+Workflow triggers:
+
+```yaml
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+```
+
+## ci.yml Structure
+
+Key sections of the scaffolded workflow:
+
+| Section | What it does |
+| ------- | ------------ |
+| `on: push/pull_request` | Triggers on main pushes + all PRs targeting main |
+| `pnpm/action-setup` | Installs pnpm at `{{PNPM_VERSION}}` (default: 10) |
+| `actions/setup-node` | Installs Node.js at `{{NODE_VERSION}}` (default: 20) |
+| pnpm store path + `actions/cache` | Caches the pnpm store keyed on lockfile hash |
+| `pnpm install --frozen-lockfile` | Clean dep install — fails on lockfile drift |
+| Job step: run checks | `pnpm -w lint && pnpm -w typecheck && pnpm -w test && pnpm -w build` |
+
+The job `name:` field is `Lint + typecheck + test + build`. This string is what GitHub
+registers as the required status check. **Changing this name breaks branch protection until
+the required check entry is updated to match.**
+
+Custom versions:
+
+```bash
+npx codebyplan ci scaffold-workflow --pnpm-version 9 --node-version 22
+```
+
+## Required Status Checks
+
+GitHub branch protection can require a named CI check to pass before any PR merges.
+`codebyplan ci enforce-check` automates this via the GitHub API (`gh api`).
+
+The check name in branch protection is matched against `jobs.<job-id>.name` in the workflow
+YAML. The exact string must match — capitalisation and whitespace matter. The default
+scaffolded name is `Lint + typecheck + test + build`.
+
+**Idempotency**: once enforced, `ci.json` records `workflow.required_check_enforced: true`.
+Re-running `enforce-check` reads this flag and skips the API call.
+
+## Manual Setup (GitHub UI)
+
+Use when `enforce-check` cannot run (missing `gh auth`, insufficient API permissions):
+
+1. Open the repository on GitHub.
+2. Go to **Settings** → **Branches**.
+3. Under **Branch protection rules**, click **Add rule** (or edit the existing rule for `main`).
+4. In **Branch name pattern**, enter `main`.
+5. Check **Require status checks to pass before merging**.
+6. In the search box type `Lint + typecheck + test + build` and select it.
+   (The check must have run at least once for it to appear in the list — push a
+   commit to trigger the workflow first if the search returns nothing.)
+7. Optionally check **Require branches to be up to date before merging**.
+8. Click **Save changes**.
+
+## Troubleshooting
+
+**Required check stuck pending** — almost always a name mismatch. Compare the `name:`
+field under your job in `ci.yml` with the required check name registered in branch
+protection. They must be byte-identical.
+
+**Workflow not triggering on a PR** — verify `on.pull_request.branches` includes the PR's
+base branch. PRs targeting branches not in the list skip the workflow entirely.
+
+**pnpm cache miss on every run** — confirm the cache key uses the lockfile hash:
+
+```yaml
+key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+```
+
+**`gh api` 403 on enforce-check** — the token needs admin write on the repo. For
+fine-grained PATs, set the "Administration" repository permission to Read and write.
+Otherwise use the Manual Setup path above.
+
+## Provider Roadmap
+
+Additional CI provider reference docs are planned:
+
+- `reference/gitlab-ci.md` — GitLab CI/CD pipelines (`.gitlab-ci.yml` structure, required
+  pipeline gates, caching strategy)
+- `reference/circleci.md` — CircleCI (`config.yml`, orbs, required workflow status checks)
+
+These will follow the same structure as this document when authored.

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

@@ -110,6 +110,27 @@ If ALL detected surfaces are unconfigured AND the user picks Skip/Mark for all,
 
 ### Step 3 — Build the shipment plan
 
+**cd.json pre-read (when present)**: before selecting deploy variants, read
+`.codebyplan/cd.json` if it exists:
+
+```bash
+cat .codebyplan/cd.json 2>/dev/null
+```
+
+When present, use its per-surface policy to inform variant selection:
+
+| cd.json field | Effect on variant selection |
+| ------------- | --------------------------- |
+| `trigger` | `"push-to-main"` → confirm auto-deploy variant; other values surface as notes |
+| `environment` | Non-empty → note the GitHub Environment name in the plan (approval gate may apply) |
+| `approval_required: true` | Flag the surface as requiring manual approval in the plan summary |
+| `oidc_auth: true` | Note that OIDC auth is used (no long-lived token secret to verify) |
+| `credentials.env_var_names[]` | List expected secrets so the user can verify they are set in the repo |
+| `version_gate: true` | Skip the surface when no version bump detected this checkpoint |
+
+If `.codebyplan/cd.json` is absent (un-migrated repo), fall back to the existing
+filesystem surface detection — no behavior change. Run `/cbp-setup-cd` to migrate.
+
 For each surface with `configured: true`, determine the deploy variant:
 
 | Surface           | Variants                                                                                                                                                                                               |

package/templates/skills/cbp-standalone-task-testing/SKILL.md

@@ -86,13 +86,22 @@ Read every non-deleted file in the aggregated list. Build a mental model of the
 
 Capture stdout and stderr for each check.
 
+**ci.json command resolution (absent-fallback safe):** Before running the checks below, resolve commands from `.codebyplan/ci.json`:
+
+```bash
+CI_TYPES_CMD=$(npx codebyplan ci resolve typecheck 2>/dev/null)
+CI_UNIT_CMD=$(npx codebyplan ci resolve unit_test 2>/dev/null)
+```
+
+Fallback: if `.codebyplan/ci.json` is absent, `ci resolve` returns the central default (exit 0). If the binary is unavailable, the variable is empty and the `${CI_*_CMD:-<literal>}` guards in the table below activate the hardcoded fallback.
+
 **Hard-fail tests** (block completion):
 
 | Category | Command | Condition |
 |----------|---------|-----------|
 | Full-repo lint | `pnpm -w lint` | Always |
-| Full-repo types | `pnpm exec tsc --noEmit` | Source files changed |
-| Full-repo unit tests | `pnpm test --run` | Source files in aggregated_files |
+| Full-repo types | `${CI_TYPES_CMD:-pnpm exec tsc --noEmit}` | Source files changed |
+| Full-repo unit tests | `${CI_UNIT_CMD:-pnpm test --run}` | Source files in aggregated_files |
 | Per-package E2E | `pnpm --filter <pkg> e2e:test` | UI files in aggregated_files |
 
 These are the workspace-wide / cross-package checks only — per-app build/lint/types, the `console.log`/debug scan, the OWASP/secret grep, and `pnpm audit` already ran per-round inside `testing-qa-agent` and are NOT repeated here.

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

@@ -1,4 +1,5 @@
 ---
+scope: org-shared
 name: cbp-task-testing
 description: Run comprehensive task-level testing after /cbp-task-check passes
 argument-hint: [chk-task]
@@ -275,3 +276,4 @@ Waiting for user to run `/cbp-task-create`.
 - **Writes**: `codebyplan task update` (CLI write-through; MCP `update_task` break-glass)
 - **Triggers**: `cbp-task-complete` (auto via Skill tool, when ALL PASS — `ask`-tier, permission prompt IS the human gate); `cbp-round-input` (auto via Skill tool, on minor problems — `allow`-tier, fires silently)
 - **Triggered by**: `cbp-task-check` auto-triggers this skill via Skill tool on READY verdict; `cbp-task-testing` is `allow`-tier and fires silently (no permission prompt)
+- **ci.json awareness**: `codebyplan check --scope task --json` 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.