onboard · diff
git:20260920.d282a91 to git:20260922.eb75731
65 added, 19 removed. Audit A to A.
---
name: onboard
description: >
Onboard a new member onto a project team: the access list, the environment setup verified by a
command that actually runs, a map of the codebase by ownership, the team's working agreements, and
- a first-week plan ending in a real merged change.
+ a first-week plan ending in a real contribution the team reviews.
Use when someone joins the project, moves between teams, or returns after a long absence.
Triggers on: "onboarding", "onboard", "người mới", "hướng dẫn thành viên mới", "new joiner",
"getting started for the team", "オンボーディング", "新メンバー", "ramp up", "/atk:onboard".
- argument-hint: "[--role dev|qa|sre|ba] [--refresh|--audit] [--lang <code>] [--out <path>]"
+ argument-hint: "[--role dev|qa|sre|ba|<role>] [--refresh|--audit] [--lang <code>] [--out <path>]"
---
# Team Onboarding (`atk:onboard`)
- Produces the document that gets a new member to a merged pull request in their first week. Every
- setup step is verified against the repository, so the guide does not send a new joiner to a script
- that no longer exists.
+ Produces the document that gets a new member to a real, reviewed contribution in their first week.
+ Every setup step is verified against the repository, so the guide does not send a new joiner to a
+ script that no longer exists.
## Scope
Handles: deriving setup from the actual repository, listing access and accounts with who grants
them, mapping the codebase by area and owner, recording team working agreements, and building a
first-week plan with a real starter task.
Does NOT handle: granting access, writing the conventions themselves (`atk:convention`), setting the
project up for the kit (`atk:init`, which runs once per project rather than once per joiner), or
teaching the business domain in depth, which belongs to the project's domain documentation.
## Roles
Tech Lead assigns a buddy. PM owns access requests. The buddy owns the first week and is named in
the document. The new member owns reporting what the document got wrong. See `shared/team-roles.md`.
## Invocation
```bash
/atk:onboard # Build or update the onboarding document from the repository
- /atk:onboard --role qa # Tailor the path to a role
+ /atk:onboard --role qa # Vary the access list and the first week for a role
+ /atk:onboard --role designer # Any role, not only the four the kit wrote rows for
/atk:onboard --refresh # Re-verify an existing document against the current repository
/atk:onboard --audit # Report what is stale or missing, change nothing
/atk:onboard --lang vi # Write in Vietnamese
/atk:onboard --out <path> # Override the default output path
```
## Workflow
```
[1. Derive setup] -> [2. Verify] -> [3. Access list] -> [4. Code map] -> [5. First week]
```
Before step 1, read `.atk/overrides/onboard.md` when it exists, per rule 7 of `shared/team-roles.md`.
### 1. Derive the setup from the repository
Read the package manifests, runtime version files, `Dockerfile` and compose files, `.env.example`,
migration and seed commands, and the scripts the CI actually runs. The CI workflow is the most
honest description of how the project builds.
### 2. Verify every step
Each setup step states the command and the expected output or success signal. Mark a step
- `UNVERIFIED` when it could not be checked rather than presenting it as working. A step referencing a
- file that does not exist is a defect to report, not to copy.
+ `UNVERIFIED` when it could not be checked rather than presenting it as working. A step the
+ repository gets wrong about itself is a defect to report, not to copy: a command in no manifest, a
+ file the instructions name and the tree does not have, an order of operations nothing records.
+ The line between the two is who is at fault. `UNVERIFIED` is about this run: the step needs a
+ credential, a network, or a machine the run does not have, and it may well be correct. A defect is
+ about the repository: the run could check it and the project's own claim did not hold. A step that
+ runs and fails for a reason the documentation should have warned about is a defect, not an
+ `UNVERIFIED`, because the next person hits it too.
+
+ Report it to `docs/derived/onboarding/setup-defects.md`, per `shared/artifact-paths.md`, and not
+ into the onboarding document. The two have different readers: the defect is fixed by whoever owns
+ the script or the document that is wrong, and the onboarding document is read on a first morning by
+ the one person on the team who can do nothing about it. One file, carrying no date, rewritten whole
+ on every run: a defect somebody has fixed is then gone from it, instead of going stale in a document
+ that is updated in place. A run that finds nothing writes nothing. Under `--audit` nothing is
+ written either, because that flag promises to change nothing; the defects are named in the session
+ instead. Either way the session is told where the file is, or that none was written, and whether
+ the project tracks that path at all.
+
+ Each entry says what the project claims, what actually happens, and where the claim lives. Describe
+ the failure rather than pasting the output. A setup step that fails is exactly where a connection
+ string, a token, or a password reaches the terminal, and the rule against putting one in the
+ onboarding document holds for this file too. Name the person who owns each defect where the
+ repository answers it. Turning any of them into a tracker issue is the `## Ticket` section below, on
+ request.
+
### 3. Access list
- Repository, tracker, CI, cloud, VPN, database, monitoring, chat channels, shared drives, and design
- tools. For each: who grants it, how long it usually takes, and whether it blocks day one. Never
- include a credential, a token, or a connection string; name where they are stored instead.
+ Repository, tracker, CI, cloud, VPN, database, the environments the team tests and releases
+ against, monitoring and the on-call rota, chat channels, shared drives, and design tools. For each:
+ who grants it, how long it usually takes, and whether it blocks day one. Never include a
+ credential, a token, or a connection string; name where they are stored instead.
+ `--role` decides which items block day one. It does not decide which items appear: every row above
+ is listed for every role. See `references/roles.md`.
+
### 4. Code map
The areas of the codebase, what each does, its owner, and one entry-point file per area. Add the
parts that surprise newcomers: the non-obvious build step, the service that must run first, the
naming that means something other than it appears to.
### 5. First week plan
- Day by day, ending in a merged change. Day one is environment plus a read-only tour. The starter
- task is real, small, reviewed normally, and picked from the tracker rather than invented. State the
+ Day by day, ending in the contribution `references/roles.md` names for the role, which is a merged
+ change for a developer and something of that role's own for everyone else. Where neither `--role` nor the
+ request names a role, ask which one before step 3 rather than picking one quietly. Day one is
+ environment plus a
+ read-only tour. The starter task is real, small, reviewed normally, and picked from the tracker
+ rather than invented. `--role` moves the ending and nothing else about the week. State the
team's working agreements too: ceremony times, core hours, review turnaround, how to ask for help
and after how long, and the definition of done.
## Output
- Written to `docs/onboarding.md` per `shared/artifact-paths.md`. Where a project README already
- covers setup, link to it rather than duplicating it.
+ Written to `docs/onboarding-<role>.md` under `--role`, and to `docs/onboarding.md` when no role was
+ named, per `shared/artifact-paths.md`. One document per role, so onboarding a QA engineer never
+ overwrites the developer's, and `--refresh` and `--audit` reach the right one by taking the same
+ `--role`. Where a project README already covers setup, link to it rather than duplicating it.
+ A run that found a defect in step 2 leaves a second file, the report at
+ `docs/derived/onboarding/setup-defects.md`. It is derived rather than reference: a project may keep
+ `docs/derived/` out of git, and where it does, the report reaches nobody unless the run says so. Name
+ its path in the session, say whether the project tracks it, and offer the tracker below when it does
+ not.
+
Putting it where the team can see it is `atk:git`, which follows the artifact section of
`shared/finalize-steps.md`: the branch, the commit, and the judgement about whether this one belongs
in a pull request for its approver to read. Whether it is committed at all is the persistence group
it falls into, per `shared/artifact-paths.md`.
## Ticket
- Follow `shared/ticket-adapters.md`. Access requests and the starter task can become issues when the
- user asks.
+ Follow `shared/ticket-adapters.md`. Access requests, the starter task, and each defect from step 2
+ can become issues when the user asks. A defect is the one of the three that often has nowhere else
+ to go, because the report holding it may sit in an untracked directory.
## Definition of done
- [ ] Every setup step was verified against the repository, or is marked `UNVERIFIED`.
- - [ ] No credential or token appears in the document.
+ - [ ] No credential or token appears in the onboarding document or in the defect report.
- [ ] Every access item names who grants it and whether it blocks day one.
- [ ] Each code area names an owner and an entry-point file.
- - [ ] The first-week plan ends in a real, merged change, and a buddy is named.
+ - [ ] The first-week plan ends in the contribution `references/roles.md` names for the role, and a
+ buddy is named.
+ - [ ] Every defect found in step 2 is in the report, and none of them is in the onboarding document.
+ - [ ] The session was told where the defect report is and whether the project tracks that path.
+ - [ ] Under `--audit`, no file was modified.