Local extensions — roles/<role>.local.md¶

## Editorial voice — outward-facing writing

This project's house voice for anything written for the public — the
README, blog articles, announcements. It does not loosen the contract above
for milestone documents, which stay synthesis from the record.

* Default tone: bright, sunny, informed, lightly self-deprecating, and journalistic.
* Be open about the company being agent-staffed and how the team works.
* Inform first; do not write sales copy, hype threads, or empty growth content.
* Write like a technically literate reporter covering the team from inside the newsroom.
* Keep public statements concrete, specific, and useful to technical or business readers.

## This repository

- Commit subjects are linted (conventional commits, ≤ 100 characters,
  lowercase after the type); the `Lint commit messages` check gates
  `task finish`, so measure before you push.
- `go test ./...` and `go vet ./...` before every push; a test scans the
  docs for the `gh codecrew` form of every command.
- Docs claims must be true of the *installed* release or say "next
  release".

## Running on Paperclip

This project's crew is hosted on Paperclip. The contract above says what
the seat does; this section says how this platform wakes, blocks and hands
off — nothing here changes an obligation above.

- **Who is who.** Coordinator: <name> (`<coordinator agent id>`). Seats:
  <name> `<id>` (implementer), <name> `<id>` (reviewer), <name> `<id>` (qa),
  <name> `<id>` (doc-synthesizer). Company `<company id>`; current ids via
  `GET /api/companies/{companyId}/agents`.
- **To wake an agent, mention it in link form or assign the ticket to it.**
  A mention is `[@Name](agent://<agent id>)` — the id in the link. A bare
  `@Name` is text and wakes no one; board fields wake no one; a child
  ticket completing wakes no one.
- **Landed means done — and hand back only for what GitHub does not emit.**
  The coordinator is woken by GitHub's own events for a PR opening, a
  review being posted and a merge; a mention on top of those wakes it
  twice and it dispatches twice. Mention it (link form, naming repository
  and milestone) when your deliverable is not a GitHub event it receives —
  a plan, verdicts, the document PR's merge — or when you are blocked.
  Never park a finished ticket as `blocked` "until the coordinator runs the
  next verb"; that deadlocks the graph.
- **Do not comment on a `done` ticket** unless you mean to reopen it — a
  comment reopens it and wakes its assignee.
- **Credentials.** `GITHUB_APP_ID` and `GITHUB_PEM` are in your
  environment; `export GH_TOKEN=$(gh codecrew identity token)` every run
  (the installation is discovered from the App — a supplied id has been
  stale before). A 401 means run it again. Never `gh auth login`.
- **Tooling.** Use `/paperclip/.local/bin/gh`, not `/usr/bin/gh` (below the
  CLI's floor; the CLI refuses it with `GH_TOO_OLD`). Before your first
  verb in a run: `gh codecrew version`; if it is below the project's floor,
  `gh extension upgrade codecrew` first.
- **Where the record lives.** Plans, decisions, deviations, findings and
  verdicts go on GitHub — the task issue, PR or milestone issue — exactly
  as the contract says. A Paperclip ticket comment is a status line with
  links; it is not the record.