Onboard

Onboard (a repo → a configured lifecycle)

Every other skill here reads how this repository works from eight files under .agents/. This skill writes them. Nothing else in the plugin knows anything about your repo, which is the whole reason it is installable.

Three passes, in this order. The order is the point: each pass is only cheap because the one before it ran.

When NOT to use

• .agents/ already exists and is current → read it. Re-running to fix one answer is fine, but say which file you are changing and change only that.
• To decide whether to adopt the lifecycle at all. That is a conversation, not a config run.

Pass 1 — Observe. Never ask what you can read.

Every question you ask that the repo already answers spends the user's attention on your laziness. Sweep in one batch, then draft.

Then read the CI definition properly, end to end. It is the one file that cannot lie about the gate, and the most common install defect is a .agents/gates.md that lists the commands a human would run instead of the ones that block a merge.

Draft all eight files from the templates in templates/, and mark every line with where it came from:

`.agents/gates.md`      drafted from azure-pipelines.yml:44-71 + Directory.Build.props
`.agents/forge.md`      drafted from git remote (dev.azure.com)
`.agents/naming.md`     drafted from git log — 58 of 60 subjects match <type>(<scope>): <imperative>
`.agents/docs.md`       NOT FOUND — no architecture docs; needs an answer

A gap is a finding, not a guess. Write NOT CONFIGURED and carry it into pass 2. A drafted line you invented is worse than a missing one, because every later run trusts it.

Pass 2 — Ask what evidence cannot settle

Policy, not fact. These have no answer in the repository because nobody wrote one down.

Ask the whole set in one round, numbered, each with your recommendation. Never drip-feed.

1. Board writes. May a skill write to the issue tracker unasked? If yes, which writes exactly? Recommend: claim the ticket when work starts, comment the agreed design, comment the shipped link. Nothing else, and never a status that reports an outcome.

2. Unattended work. May a run continue without you watching, and between which hours? Recommend: name your working hours and forbid anything unattended outside them. A run that finishes at 02:00 with a question nobody answers has stalled, not succeeded.

3. Autonomy line. What must stop and ask, whatever else is decided alone? Recommend: user-visible behaviour the spec does not settle and is expensive to reverse — a persisted schema, a wire contract, a permission boundary. Everything else is the agent's.

4. Review lenses. Which of the lens catalogue apply here? (pass the list from ../build/prompts.md) Recommend: spec alignment, correctness, over-engineering, test gaps, repo standards — always; plus UI patterns and security only when the diff touches them. Ask which lenses are relevant here; question 6 decides how many are affordable. They are different questions, and a lens dropped for cost is recorded differently from one that never applied.

5. Loop caps. How many fix rounds per ticket before a finding is parked, and how many re-plans before a human is fetched? Recommend: three fix rounds, one re-plan. Both are places this loop gets cheaply stuck.

6. Which plan is paying for this, and how much may one call cost? Ask the plan first — Pro, Max 5x, Max 20x, or API billing — then offer the matching profile from plan-profiles.md and let them adjust it. The profile sets the tier, the reasoning effort, the output ceiling, the wave width and the lens list in one answer, which is why it is one question rather than five. Recommend: take the profile for their plan unchanged. It is calibrated on a real project, and every dial in it interacts with the others.

   The plan is a fact you cannot read off the repo, and it changes the right answer more than anything else in this file. On Pro the full lens set is not affordable and pretending otherwise means discovering it halfway through a wave. Ask; do not assume Max.

   Two things to say out loud while asking, because both surprise people:

   • The ceiling is an instruction, not a limit. Nothing truncates a reply. A callee that cannot finish inside its budget is told to say so and escalate rather than return a shallow pass — which is the only version of a budget that does not quietly cost quality.
   • Reasoning effort is separate from the tier. A cheap tier at high effort and an expensive tier at low effort are different trades, and the review lenses are the place where effort earns more than tier does.
   • Cut scope before you cut tier. A cheap model on design-carrying work takes two or three times the turns and fails its gates, so downgrading it is the most reliable way to spend more. Narrow the wave and drop lenses first — plan-profiles.md has the cut order, ranked by value per token.

7. Frozen ground. Which directories are history that must never be edited or cited as current?

8. The glossary. Is there a vocabulary document, and does it beat a spec's wording? Recommend: yes, and yes — two words for one thing is the cheapest bug to fix now and the most expensive later, because it reaches code, tests, tickets and commit subjects.

Then sweep the edges of the install itself. The seven below are about this repo's shape, and each one that goes unasked shows up later as a skill doing something surprising.

Sweep these seven every time, and lose none of them. The brief states the happy path; the cost sits in what it left unsaid.

• Boundary, empty and limit values — zero, empty, maximum, very large; first and last item; ranges that are off by one.
• Absent or partial data — null, missing, not-yet-set fields; an optional relationship that does not exist.
• Concurrency and ordering — two users acting at once, the action repeated, steps out of order, a double submit.
• Failure and rollback — a dependency fails midway. What state remains, what the user sees, whether it is retryable.
• State and lifecycle transitions — the entity is already in the target state, archived, deleted or locked; the action fired twice.
• Permissions and roles — a role the brief never mentioned reaching this path.
• Locale, formatting and units — time zones, currencies, decimal and thousands separators.

Every edge case you find gets exactly one of two homes. Either it is a decision only the product owner can make — then it is a question — or you settle it yourself and write it under ## Assumptions with the handling you chose and why. Nothing is dropped. An edge case that vanishes into prose is one an implementer will settle alone, silently, at 200k context.

The test for "the product owner must decide this": the answer changes what is built rather than how; a developer cannot settle it from the code, the conventions or the domain; and getting it wrong means reworking shipped behaviour rather than refactoring. If any of the three fails, settle it and record the assumption. Better to ask one too few than to flood them with developer-answerable questions.

Pass 3 — Propose where the way of working should change

This is the pass that earns its keep. The lifecycle assumes things. Where this repo does not work that way, say so plainly, say what it costs, and let the user decline.

Do not smuggle these in. A convention adopted without the user agreeing to it is one they will fight with for weeks without knowing why.

For each, offer two options and a recommendation, and one line on the cost of the cheaper one. Record every declined proposal in .agents/working-agreement.md under Deliberately not adopted, with the date and the reason. That entry is what stops the next run re-arguing it.

One is a genuine blocker, not a preference: a repo that cannot be checked out twice cannot run /build's parallel waves. Say so, and set the wave width to 1 in .agents/lifecycle.md rather than pretending. Everything else degrades gracefully.

Step 4 — Write the eight files

Into .agents/ at the repository root. Flat, so a repo with no docs/ convention still has a home for them.

Rules for what you write:

• Every command exactly as it must be typed. A paraphrased gate is a broken gate.
• Say which commands are weaker locally than in CI, and name the CI form. This is the single most valuable line in gates.md.
• No prose the repo does not need. A file that says "this project values quality" costs tokens on every run and decides nothing. If a section has no answer, write NOT CONFIGURED and one line on what would have to be true to fill it.
• Link, never mirror. Where a convention is already written down in CONTRIBUTING.md or docs/, point at it. A copy drifts.

Then add the pointer so a human and a fresh agent both find it. In CLAUDE.md (and AGENTS.md if the repo has one), one stanza:

## How this repo works, for agents

`.agents/` describes this repository to the `lifecycle` plugin's skills — the gates, the tracker, the
forge, the naming grammar, the working agreement. **It is authority.** Start at
[`.agents/README.md`](.agents/README.md).

Commit it as one change, message chore(agents): describe this repo to the lifecycle skills. It is reviewable, and being reviewable is most of the point of putting it in the repo.

Step 5 — Prove the install

A config nobody ran is a config that is wrong in a way you have not found yet.

Run frame on one small, real ticket and read what comes back. It reads .agents/docs.md, .agents/tracker.md and .agents/lifecycle.md, so a wrong answer in any of the three surfaces here for the price of one cheap run.

Then say, in the report, which of the eight files that run actually exercised — and which are still unproven.

What you report

`.agents/` written · 8 files · committed as <sha>

Observed        <n> answers from evidence — build system, gate, forge, branch model, naming
Asked           <n> questions, all answered
Proposed        <n> changes · <n> adopted · <n> declined (recorded in working-agreement.md)
NOT CONFIGURED  <the files or sections with no answer, by name>
Proven          /frame on <ticket> exercised gates.md, docs.md, tracker.md
Unproven        forge.md, naming.md — nothing has shipped yet

Next            /frame <ticket> to start work · /onboard again to change an answer

Name the unproven files. An install reported as complete when half of it has never executed is the failure mode of this skill.

Notes

• Read a config file, never reconstruct it. After this run, no skill infers the build system again; the file is the answer even when the tree looks different.
• This skill deliberately does not read .agents/. It writes it. If it read its own output it would happily agree with a mistake it just made.
• Re-running is cheap and safe. It re-observes, shows a diff of what changed, and asks before overwriting an answer a human edited.