| name | project-onboarding |
| description | Tune this generic scaffold to a concrete target project — inventory the repo, interview only the gaps, verify every command by actually running it, fill or remove every CUSTOMIZE block, and deliver one evidence-backed onboarding PR. Use this whenever the scaffold lands in a new or existing project, whenever `scripts/tuning-status.sh` reports markers, whenever commands in CLAUDE.md are unverified or drift from CI, and whenever a user says "tune/onboard/set up this scaffold for project X". |
Project Onboarding
This scaffold ships generic on purpose: project truth is injected once, here,
by procedure — not sprinkled ad hoc. Onboarding succeeds when an agent that
knows nothing about the project can work from CLAUDE.md
alone and every stated command demonstrably runs.
Two invariants govern everything below:
- The Sync Pair.
CLAUDE.md (validated commands) and
.github/workflows/ci.yml (gates) must state the same toolchain and
commands. Any edit to one is an edit to both.
- Evidence or it does not land. A command enters the Sync Pair only after
it has been executed in a clean environment during this onboarding, with
its output (or failure + workaround) captured for the PR.
Procedure
P0 — Status
Run scripts/tuning-status.sh. Exit 0 → already tuned; run in re-tune mode
(see Re-tuning) only if something changed. Otherwise the report is your
worklist.
P1 — Inventory (read-only)
Detect before you ask. Scan for: manifests and lockfiles (package.json,
pyproject.toml/requirements*.txt, go.mod, Cargo.toml, pom.xml,
platformio.ini, Dockerfile, Makefile, Taskfile*), existing CI under
.github/workflows/, test directories and runners, formatters/linters
configs, monorepo workspaces, and hardware markers (board envs in
platformio.ini). Produce an inventory table: area → stack → candidate
build/lint/test commands → confidence.
P2 — Interview (gaps only)
Ask the human only what P1 could not answer, in one batch. Question bank
(pick applicable, keep ≤10):
- Which areas are in active development vs frozen?
- Exact commands you trust for build / lint / test per area, if any?
- Firmware: target envs, and which machine physically hosts devices
(routes
exec:ide work)?
- Runtime versions to pin (Node/Python/etc.)?
- Paths that agents must never touch (extend rulesets / File-ownership
defaults)?
- Secrets/credentials policy; anything that must stay local
(
local model tier)?
- Org-level issue types / Project board to attach? (Projects v2 boards are
always user/org-owned;
scripts/setup-project.sh init links the board to
the repo so it shows in the repo's Projects tab — an org/user board URL
is expected, not a misconfiguration.)
- Larger runners needed for the cloud agent?
- Existing docs to seed
docs/context/ with (do NOT distill them here)?
- Anything the last CI lied about (flaky/slow gates)?
P3 — Verify by running
In a clean checkout, execute candidate commands in dependency order. Record
for each: exact command, environment prerequisites, runtime, result. Failures
are content: capture the error and the working workaround — these notes go
into CLAUDE.md so no agent rediscovers them. Never promote an
unrun command.
P4 — Apply
- Fill every
CUSTOMIZE block in the Sync Pair files (and
.claude/rules/) with P3-verified content; delete the placeholder
steps/warnings they replace.
- Path-scoped rules: fix
paths globs; delete inapplicable examples
(e.g., .claude/rules/firmware.md when there is no firmware); add one
rule file per detected area that has real rules (one concern per file).
- Repository layout map in CLAUDE.md: make it match reality.
- Run
scripts/setup-labels.sh if labels are missing.
- Seed provided documents into
docs/context/<topic>/ with provenance
headers (context-collection skill). Do not write agreements —
distillation is a separate, human-gated phase.
- Do not touch
AGENTS.md (Budget rule; behavior is project-independent).
P5 — Prove
scripts/tuning-status.sh exits 0; the new CI gates run green once end to
end (or documented-red with a linked issue); and one shakedown
delegation completes — dispatch one small ai:ready task end-to-end
(plan comment → implementation → draft PR → green checks) and link its PR
in the evidence. Tuned = all three; the evidence PR merge plus that
shakedown is the license merge (README, The Three Merges).
P6 — Record
One PR titled scaffold: onboard <project>: the Sync Pair diffs, the
inventory table, the interview answers, and the P3 evidence log in the
description. Append a docs/agreements/retro-log.md row (failure class:
onboarding). List any project-agnostic improvements you noticed as
upstream candidates (see the retro skill, Upstreaming).
Existing codebase path (legacy)
Legacy code is code without tests (Feathers' working definition), and
automated checks are the ceiling on agent autonomy (verification skill) —
so on an existing codebase the first work order is not a feature. It is a
characterization-tests Task: fix the current behavior in executable
form, as-is, bugs and all. Characterization tests are the test-first
pattern's special case (the expected value is whatever the code does
today), and they are ideally delegable — self-contained, verifiable,
patient reading work. Every suite added raises the autonomy ceiling and
widens what the license merge can safely delegate: onboard the scaffold,
license the foundation, then grow delegation one characterization suite at
a time instead of attempting a rewrite or a big-bang adoption.
Re-tuning
Re-run P1→P6 (scoped to the delta) when: a new manifest/lockfile type
appears; CI and CLAUDE.md disagree; or a retro identifies stale commands.
Drift between the Sync Pair files is itself a retro trigger.
Must NOT
- Invent agreements, requirements, or ADRs.
- Weaken or delete existing gates to make onboarding "pass".
- Leave a command in the Sync Pair that was not executed in P3.
- Introduce non-English durable artifacts.
