Onboard Repo Skill

Process steps in order. Do not skip ahead.

Add the files that run the jbaruch/coding-policy coding-rule review on a repo's pull requests — jbaruch/coding-policy holds the shared coding rules, reviewed by the coding-policy-fleet-reviewer GitHub App with the Codex CLI on a ChatGPT subscription. .github/workflows/review-trigger.yml, on each PR event, starts a review of that PR against the coding-policy rules so the result is available before merge; the .github/fleet-review-enabled marker makes the same review run on a schedule as a backstop. The consumer holds the marker, the trigger workflow, and one FLEET_DISPATCH_TOKEN secret that the workflow reads. This skill commits those files plus the Copilot-lane charter and opens a PR.

Precondition: the App is installed on the account with access to this repo (installed on all repositories).

The skill runs in one of two modes determined by the user's request:

• install (default) — the consumer hasn't run the skill before, no reviewer artifacts exist. The current behavior of every step.
• upgrade (--override) — refresh previously-installed reviewer artifacts to the current plugin version
  • Trigger phrases: "upgrade", "update", "refresh", "pull latest reviewer setup", "override"
  • Pass --override to all five scripts: preflight, branch, scaffold, commit, push
  • Branch: feat/upgrade-coding-policy-review
  • Commit message: ci(review): upgrade ...
  • Preflight skips branch-clear checks; instead refuses if a rewritable target carries uncommitted edits the upgrade could clobber
  • Scaffold snapshots and restores all target files on failure

Step 1 — Run Preflight Checks

# install mode
.tessl/plugins/jbaruch/coding-policy/skills/onboard-repo/preflight.sh

# upgrade mode
.tessl/plugins/jbaruch/coding-policy/skills/onboard-repo/preflight.sh --override

Runs every precondition (git worktree, GitHub CLI install + auth, packaged templates present, origin remote, plus mode-dependent branch/target state) and returns one JSON object: {"ok": bool, "override": bool, "failures": [...], "warnings": [...]}.

• Exit 0, empty failures — every precondition passed; proceed to Step 2.
• Exit 1, populated failures — report each failure's reason verbatim and stop. Every failure carries a concrete recovery command.
• Non-empty warnings — informational only; never affects ok or the exit code. Report each reason verbatim alongside the Step 1 outcome and remember them for Step 7's PR body. Do not stop; proceed to Step 2.

Step 2 — Refuse Overwrite (install mode only)

In install mode: if any reviewer file already exists (.github/fleet-review-enabled, .github/workflows/review-trigger.yml, or .github/copilot-instructions.md), stop and report that prior reviewer setup is present — re-run in upgrade mode to refresh it. scaffold.sh enforces this too (it refuses any pre-existing target in install mode). If none are present, proceed to Step 3.

In upgrade mode: skip this step. Preflight has verified the rewritable targets carry no uncommitted state the upgrade could clobber; scaffold.sh snapshots and restores them on failure.

Step 3 — Establish Feature Branch

# install mode
.tessl/plugins/jbaruch/coding-policy/skills/onboard-repo/branch.sh

# upgrade mode
.tessl/plugins/jbaruch/coding-policy/skills/onboard-repo/branch.sh --override

Establishes the feature branch the rest of the steps commit on. Install mode creates feat/add-coding-policy-review from origin's default branch. Upgrade mode targets feat/upgrade-coding-policy-review, probing remote and local state to handle the fresh-clone-while-upgrade-PR-open case. Idempotent: emits {"state": "already-on-branch", ...} when HEAD already matches the target. Real ls-remote/fetch errors propagate verbatim with non-zero exit. Proceed immediately to Step 4.

Step 4 — Scaffold Reviewer Artifacts

# install mode
.tessl/plugins/jbaruch/coding-policy/skills/onboard-repo/scaffold.sh

# upgrade mode
.tessl/plugins/jbaruch/coding-policy/skills/onboard-repo/scaffold.sh --override

Copies the opt-in files from the packaged template tree into the consumer, and documents the operator secret:

• .github/fleet-review-enabled — the opt-in marker; while present, the coding-policy review also runs on a schedule as a backstop
• .github/workflows/review-trigger.yml — on each PR, starts a review of that PR against the coding-policy rules
• .github/copilot-instructions.md — the Copilot complementary-lane charter
• .env.example — appends a FLEET_DISPATCH_TOKEN entry carrying the repo's Actions-secrets settings URL (no-secrets rule); append-or-create, never overwrites prior variables

Install mode refuses if any of the three template targets already exists; upgrade mode overwrites them. .env.example is always append-or-create in both modes and is skipped when the secret is already documented. Emits a JSON summary on success (per-file action is created|overwritten|appended|unchanged); on failure it exits non-zero with a stderr diagnostic and restores every target to its prior contents. Idempotent: a re-run that changes nothing is a no-op. Proceed immediately to Step 5.

Step 5 — Apply tessl-artifact hygiene

.tessl/plugins/jbaruch/coding-policy/skills/onboard-repo/tessl-hygiene.sh

Sets every jbaruch/* dependency in tessl.json to "version": "latest" (third-party pins unchanged) and appends the tessl-generated-artifacts block to .gitignore when its marker is absent. AGENTS.md / CLAUDE.md / GEMINI.md are not ignored. Emits {"tessl_json":"pinned-latest|unchanged|absent","gitignore":"created|appended|unchanged"}. Idempotent; takes no --override flag and runs the same in both modes. Proceed immediately to Step 6.

Step 6 — Commit

# install mode
.tessl/plugins/jbaruch/coding-policy/skills/onboard-repo/commit.sh

# upgrade mode
.tessl/plugins/jbaruch/coding-policy/skills/onboard-repo/commit.sh --override

Stages the reviewer files (.github/fleet-review-enabled, .github/workflows/review-trigger.yml, .github/copilot-instructions.md, and .env.example) plus the Step 5 hygiene changes (tessl.json, .gitignore) when present, and commits with the canonical message — ci(review): add jbaruch/coding-policy PR review setup in install mode, ci(review): upgrade jbaruch/coding-policy PR review setup in upgrade mode. Idempotent: emits {"state": "no-op", …} when the working tree already matches a prior successful run. If a pre-commit hook rejects the commit, the script exits non-zero — fix the hook's finding and re-run; do not --no-verify. Proceed immediately to Step 7.

Step 7 — Push

# install mode
.tessl/plugins/jbaruch/coding-policy/skills/onboard-repo/push.sh

# upgrade mode
.tessl/plugins/jbaruch/coding-policy/skills/onboard-repo/push.sh --override

Pushes the appropriate branch (feat/add-coding-policy-review in install mode, feat/upgrade-coding-policy-review in upgrade mode) to origin with upstream tracking. Idempotent: emits {"state": "up-to-date", …} if origin already matches local HEAD. Proceed immediately to Step 8.

Step 8 — Open PR

gh pr create with title ci(review): add jbaruch/coding-policy PR review setup (install mode) or ci(review): upgrade jbaruch/coding-policy PR review setup (upgrade mode), and a body that follows the required content blocks (what this PR commits, how the review runs, the load indicator, conditional warnings section) defined at:

skills/onboard-repo/PR_BODY_TEMPLATE.md

In upgrade mode, also include a brief diff line in the PR body naming the outgoing and incoming plugin versions so the human reviewer sees what's being refreshed.

Return the PR URL. If Step 1 emitted any warnings, surface them inline in your user-facing summary too (not only in the PR body). Surface the one operator secret in your summary: .github/workflows/review-trigger.yml reads a FLEET_DISPATCH_TOKEN repo secret (a fine-grained token with Actions: Read and write on jbaruch/coding-policy). Set it before the first PR after merge, or the trigger will not run; the scheduled backstop still reviews. Finish here — the operator sets the secret and merges.