|
| 1 | +--- |
| 2 | +name: onboard-project |
| 3 | +description: >- |
| 4 | + Use FIRST, when pointed at a repo this team hasn't worked before (or to re-check a |
| 5 | + repo's readiness) — BEFORE decomposing or dispatching any feature. Scans the repo |
| 6 | + for the preconditions a coding-agent loop needs, AUTO-FIXES the safe/deterministic |
| 7 | + gaps (beads workspace, ignored agent scratch, the build/test gate) by delegating to |
| 8 | + the coder, and BOARDS the judgment gaps (a project grounding doc, PR CI) as |
| 9 | + features. Ends with a readiness report + a human gate. Do NOT use to plan features |
| 10 | + or write code — that's `decompose-project` and the coder. |
| 11 | +tools: |
| 12 | + - read_file # scan the repo (read-only) |
| 13 | + - list_dir |
| 14 | + - find_files |
| 15 | + - delegate_to # hand the safe in-repo init (br init, gitignore) to the coder — you have no shell |
| 16 | + - board_create_feature |
| 17 | + - board_mark_ready |
| 18 | + - board_list |
| 19 | + - request_user_input # the readiness human gate |
| 20 | + - write_file # optional: write the readiness report into the tree |
| 21 | +--- |
| 22 | + |
| 23 | +# Onboard a project (readiness before the loop) |
| 24 | + |
| 25 | +The board's loop assumes a **prepared** repo. When it isn't, the failures aren't the |
| 26 | +coder's fault — they're readiness gaps: the board writes to the wrong beads db, the |
| 27 | +coder's scratch leaks into PRs, the gate is undeclared, or the coder fabricates a |
| 28 | +convention it was never told. This skill prepares the repo so the team can be let |
| 29 | +loose. **You orchestrate**: you scan, you *delegate* the in-repo hands-on work to the |
| 30 | +coder (you have no shell of your own), and you *board* the work that needs judgment. |
| 31 | + |
| 32 | +## What "ready" means — the checklist |
| 33 | + |
| 34 | +| # | Item | Ready when | |
| 35 | +|---|---|---| |
| 36 | +| 1 | **Board** | a `.beads/` workspace exists in the repo (so the board pins here, not a parent dir) | |
| 37 | +| 2 | **Hygiene** | `.gitignore` ignores the coding agent's **per-session scratch** (for proto: `.proto/memory/`, `.proto/session-notes.md`, `.proto/repo-map-cache.json` — **not** all of `.proto/`, whose `evolve/` holds versioned skills) **and** the build output dir | |
| 38 | +| 3 | **Gate** | the repo's real build/test command is known and set as `project_board.local_gate_cmd` | |
| 39 | +| 4 | **Grounding** | a context doc the coder reads: conventions, where shared deps/assets live, build/run/test, do/don'ts | |
| 40 | +| 5 | **Git posture** | a remote + default branch exist, the repo **homepage** points at the deployed URL (`gh repo edit --homepage`), and ideally **PR CI** verifies PRs independently | |
| 41 | +| 6 | **Report** | each item is PASS / FIXED / BOARDED, with the gate command — confirmed at a human gate | |
| 42 | + |
| 43 | +## Procedure |
| 44 | + |
| 45 | +1. **Scan (read-only).** With `read_file` / `list_dir` / `find_files`, detect: |
| 46 | + - the **stack + check command** — `package.json` scripts, `pyproject.toml`/`Makefile`/`justfile`, or a CI workflow (the most reliable source of "the real command"); |
| 47 | + - whether `.beads/` exists; whether `.gitignore` ignores agent scratch + the build output dir; |
| 48 | + - a grounding doc — by convention `PROTO.md` (or its `CLAUDE.md` / `AGENTS.md` pointers, or a conventions section in the README); |
| 49 | + - the git remote, default branch, whether the repo **homepage** is set to the |
| 50 | + deployed-site URL (`gh repo view --json homepageUrl`), and any PR-triggered CI workflow. |
| 51 | + |
| 52 | +2. **Auto-fix the safe, deterministic gaps** — one `delegate_to(coder, …)` with a precise brief to, only as needed: |
| 53 | + - `br init` (and commit) if there is no `.beads/` — **this is a bootstrap step, not a board feature** (the board can't hold a feature until beads exists); |
| 54 | + - add the coding agent's **per-session scratch** to `.gitignore` (commit) — for proto: |
| 55 | + `.proto/memory/`, `.proto/session-notes.md`, `.proto/repo-map-cache.json`. Do **not** |
| 56 | + blanket-ignore `.proto/`: its `evolve/` holds protoCLI-managed skills that should be |
| 57 | + versioned. (Don't add scratch dirs for tools this repo doesn't use.) Plus the build |
| 58 | + output dir. |
| 59 | + These are fast and judgment-free, so the coder does them directly rather than through a PR. |
| 60 | + |
| 61 | +3. **Declare the gate.** Record the check command found in step 1. Ensure |
| 62 | + `project_board.local_gate_cmd` is set to it (e.g. `npm ci && npm run build`, |
| 63 | + `uv run pytest -q`). If you can't write the host config yourself, state the exact |
| 64 | + value for the operator to set — the gate is what makes the coder's PRs open |
| 65 | + already-green instead of bouncing through CI. |
| 66 | + |
| 67 | +4. **Board the judgment gaps** — `board_create_feature` (+ `board_mark_ready`) for the |
| 68 | + work that needs real authoring + review, so it ships through the normal |
| 69 | + worktree→gate→PR loop: |
| 70 | + - a **grounding doc** — by convention **`PROTO.md`** (the canonical agent-instructions |
| 71 | + file; add thin `CLAUDE.md` + `AGENTS.md` pointers to it): conventions, the |
| 72 | + build/run/test commands, and — critically — **where shared dependencies/assets live |
| 73 | + and the rule to use the real source, never fabricate a lookalike.** This is the |
| 74 | + single highest-leverage item; it prevents the largest class of coder mistakes. |
| 75 | + - **PR CI** if missing, so PRs are verified independently, not only by the local gate. |
| 76 | + |
| 77 | +5. **Human gate.** Summarize readiness (PASS / auto-FIXED / BOARDED feature ids) and |
| 78 | + call `request_user_input` to confirm before the team starts feature work. |
| 79 | + |
| 80 | +6. **Report.** Output the checklist table with each item's status and the gate command. |
| 81 | + |
| 82 | +## Rules |
| 83 | + |
| 84 | +- **Never run the in-repo fixes yourself.** You have no shell; the coder carries file + |
| 85 | + shell access inside the repo/worktree. Delegate br init and gitignore edits to it. |
| 86 | +- **Grounding beats gating.** A clear context doc prevents more failures than any gate — |
| 87 | + treat item 4 as required, not optional. The fabricated-asset / wrong-convention class |
| 88 | + of bug is a *grounding* gap, and `goal_verify` won't catch it if the acceptance |
| 89 | + criteria don't name the real source. |
| 90 | +- **beads init is a bootstrap**, done via a direct coder delegate, before any feature — |
| 91 | + not a board feature (chicken-and-egg). |
| 92 | +- **Idempotent.** Re-run whenever `loop-retro` surfaces a recurring failure a readiness |
| 93 | + item would have prevented — onboarding and retro are the two halves of the learning |
| 94 | + loop: retro finds the gap, onboarding encodes the fix so the next repo never hits it. |
0 commit comments