# The `/w` command contract

wrokin's comment interface, specified for agents that drive it. Every claim here
is drift-tested against the routing code (`wrokin-backend`), so what this page says
is what production does. Machine-readable product facts: https://wrok.in/capabilities.json

## Reaching the router

A command is any PR or issue comment on a repo where wrokin is installed that
either **@mentions the app** (`@wrokin …`) or **starts with a wrokin prefix** at
the start of the comment or after whitespace (case-insensitive). Everything else
is never processed.

**Accepted prefixes:** `/w` (canonical), `/wrok` and `/wrokin`. They are
interchangeable: `/w review`, `/wrok review` and `/wrokin review` are the same
command. The project's former prefix, `/pi`, has been dropped: a `/pi …` comment
is ordinary text and is never processed.

`/work` and `/workin` are deliberately **not** accepted. A bare prefix is a valid
command, so they would fire on ordinary English ("/work in progress") and on
ordinary paths pasted from logs ("/work/src/index.ts") — starting a review nobody
asked for, on your key.

Two gates, and **failing either is silent** — no error comment, no reaction. If a
command draws no response at all, check these before anything else:

1. **Bot authors are ignored**, including wrokin's own comments.
2. **Trust gate:** the commenter's `author_association` must be `OWNER`,
   `MEMBER`, or `COLLABORATOR`. On a public repo a third party cannot spend the
   installer's tokens or quota; have a member issue the command instead.

The same trust gate applies to automatic triggers (the PR or issue author).
GitHub reports App bots (`sentry[bot]`, `dependabot[bot]`, …) as outside
authors, so their PRs are not reviewed automatically unless the repo names them
under **Bot pull requests** on its Team page in the dashboard. That list is empty by
default, changing it needs repo write access, and it only covers PRs from branches
in the repo itself, not forks.

## Precedence

Commands are matched in this order; the first match wins and is exclusive —
one comment never triggers two things.

1. `/w hunter [level]` — handled first, never falls through to a review.
2. `/w wrong <reason>` — a metrics write, not agent work; never falls through
   (without this, the word "wrong" would route to a review and spend tokens).
3. Role routing, most specific phrase first:

   | Phrase in the comment | Routes to | Constraint |
   |---|---|---|
   | `security audit` (or `audit security`; hyphens ok) | security-audit | PR only — on an issue it falls through to Warden below |
   | `audit` · `posture` · `repo audit` | repo-audit (Warden) | any thread |
   | `triage` | issue-triage | any thread |
   | `review` | code-review | PR only |
   | *none of the above* (bare `@wrokin` / `/w`) | code-review on a PR, issue-triage on an issue | — |

## Commands and their acknowledgements

| Command | Where | Effect | Expected ack |
|---|---|---|---|
| `/w review` | PR | Code review of the diff | Comment headed `🤖 wrokin — Code Review`, typically within a couple of minutes |
| `/w security audit` | PR | Security-focused diff review | Comment headed `🤖 wrokin — Security Audit` |
| `/w triage` | issue | Structured triage | Comment with labels, priority, duplicate check |
| `/w audit` (or `/w posture`) | PR or issue | Warden repo-setup audit — deterministic, no model call, no key needed | Posture report comment: the full report on a private repo; counts and a dashboard link on a public one (or when visibility can't be read) |
| `/w wrong [comment-link] <reason>` | PR | Records a **false-claim verdict**, with the reason. Target a specific review comment by pasting its link (Copy link → `…#issuecomment-<id>`) or bare id; without a target it binds to the **latest** wrokin review comment on the PR | Confirmation comment naming the comment the verdict attached to. A target that isn't a wrokin review comment on this PR is **refused with guidance** — never silently rebound. On an issue thread: a guidance reply, no verdict |
| `/w hunter [foray\|stakeout\|expedition]` | PR | **Paid plans** (Pro/Team/Business), once the Hunter is enabled on the repo — dispatches the proof-by-execution hunt workflow (default level `stakeout`). Debits agent credits | 👀 reaction on your comment. Failure (workflow not enabled, missing permissions, not entitled, credits exhausted) → an actionable `🛡️` comment. Unknown level → a `🛡️` comment listing valid levels |
| `/w build` | **issue** | **On demand only** — not included in catalog plans. When enabled for your engagement, dispatches the Builder to implement the issue on your own runner with your Cruise key. The action runs your tests itself after the agent finishes: a ready PR when they pass, a draft when they fail or there are none | 👀 reaction on your comment. Every run ends in a `wrokin Builder` comment on the issue: the PR it opened, or why it opened none (never silence). Not entitled, workflow not enabled, or missing permissions → an actionable `🔨` comment (on-demand / contact the team when not enabled) |
| `/w fix` | PR | **On demand only** (Builder family) — reworks an existing PR using review comments and failing checks, pushing fixes directly to the branch | 👀 reaction on your comment. Every run ends in a summary comment on the PR. Not entitled, workflow not enabled, or missing permissions → an actionable `🔨` comment |

When a review or triage run **fails** (a transient provider error, an exhausted
credit balance), the failure notice ends with a **re-run checkbox** — anyone with
write access ticks it and the same on-demand run is dispatched, no command to
remember. The equivalent command is always named beside the box.

Notes an operating agent needs:

- **A bare `/w wrong`** (no reason) still records the verdict; the reason is
  optional but is the valuable part.
- **A reason that starts with a number is safe** — only a full comment link or a
  bare id of ≥9 digits reads as a target, so `/w wrong 401 is handled` stays a
  reason about HTTP 401.
- **wrokin's inline review comments are targets too, against the scan.** A
  `…#discussion_r<id>` or `/files#r<id>` link on GitHub, or a `#note_<id>` link to an
  inline note on GitLab, records the verdict against wrokin's deterministic diff scan
  (`wrokin/grounding`), never a model: the scan wrote that comment, whichever agent's run
  posted it. A comment wrokin didn't post is refused. Any other fragment on a PR or issue
  link is refused too. Neither is ever rebound to the latest review. A blob line link
  (`…/x.ts#L10`) or a bare PR link at the start stays part of the reason.
- **`/w build` runs on an ISSUE, not a PR** — the issue text is the task. On a PR it
  replies with guidance rather than building something you didn't describe.
- **`/w build` is debounced per issue for 90 seconds**, and entitlement is checked
  BEFORE the runner starts — so a refused build costs you no Actions minutes. A failed dispatch clears the debounce so a corrected retry works at once.
- **"build" must be the command word.** `/w build` starts one; `/w review the build
  output` does not. Ordinary sentences mentioning your CI never trigger it.
- **`/w fix` runs on a PR, not an issue** — the PR diff, review comments, and failing checks form the rework task. On an issue it replies with guidance.
- **`/w fix` is debounced per PR for 90 seconds**, and entitlement is checked
  BEFORE the runner starts — so a refused fix costs you no Actions minutes. A failed dispatch clears the debounce so a corrected retry works at once.
- **"fix" must be the command word.** `/w fix` starts a fix; talking *about* fixing
  never triggers it.
- **`/w hunter` is debounced per PR for 90 seconds** — a repeat inside the
  window gets the 👀 ack but starts nothing new. A failed dispatch clears the
  debounce so a corrected retry works immediately.
- **"hunter" must be the command word too.** `/w hunter` starts a hunt; `/w wrong
  … the hunter comment is mistaken` records a verdict and starts nothing. Talking
  *about* the hunter never dispatches one.
- **Missing API key** does not fail silently: the run posts a self-diagnosing
  comment naming the provider and the fix.
- **Quota:** BYOK runs (review, security audit, triage) and Warden runs count
  against the plan's monthly run quota, once per triggering event. The Hunter
  never draws down the run quota — it is metered separately.
- **Opting a PR out: the `skip-bot-review` label.** Add it to a pull request and
  wrokin will not review it automatically on push. Add it BEFORE pushing — the
  check happens when the push arrives, so a label added afterwards does not
  recall a review already under way. Intended for a branch being iterated, where
  the same diff would otherwise be re-reviewed on every rework.
- **You don't have to spell the label exactly.** Anything that reads as "don't
  review this" is accepted: a negative (`skip`, `no`, `disable`, `suppress`,
  `without`, `dont`), optionally who (`bot`, `ai`, `agent`, `llm`, `auto`,
  `automated`, `code`, `wrokin`), then `review` or `reviews` — with any
  separator and any case. So `skip-review`, `no-bot-reviews`, `Skip_AI_Review`,
  `disable-automatic-code-review` and `no-review-needed` all work.
  Labels that ask for the OPPOSITE never match: `needs-review`,
  `ready-for-review`, `awaiting-review` and `no-reviewers` all still get a
  review, because silently skipping those would be the expensive mistake.
  - **`/w review` still works.** The label suppresses the automatic run only; a
    direct request is answered, so you can review on demand while iterating.
  - **Merge-time capture still happens.** Closing the PR still harvests review
    verdicts and 👍/👎 reactions — that spends nothing, and the reactions cannot
    be collected once the PR is closed.
  - Remove the label to resume automatic reviews on the next push.

## Feedback commands are part of the contract

After a review lands, wrokin measures whether it was *right*, per model:

- React **👍/👎** on the review comment — harvested **once, when the PR
  closes** (collaborators only; reactions added after close are never read).
- Reply **`/w wrong <comment-link> <reason>`** to pin the verdict on the exact
  review comment; omit the link only when the refuted comment is still the newest
  wrokin comment on the PR.
- On a **code-review or security-audit** comment, `/w wrong` then **re-checks** the
  findings against the code that review read, with your reason as a lead, and edits
  its "Recorded" reply in place: **Confirmed** (a finding is contradicted by a cited
  `path:line`), **Partly confirmed**, **Not confirmed** (the code still supports the
  findings), or **Couldn't re-check** (with why). A comment that lists no findings — a
  clean review, where what you are correcting is its requirements check or its summary —
  has nothing to re-check: the reply says so at once and no model is called. Your verdict is recorded either way;
  the re-check is stored beside it, never instead of it. It is one short model call on
  that agent's own model and key, counts against neither the run quota nor managed
  credits, and is skipped when the agent's `claimCheck` is `"off"`. Name the file that
  settles it in the reason: the files a reason names are read too.

## On GitLab

The same prefixes work in a merge request or issue note; GitLab leaves them in the
note because they are not GitLab quick actions. The author needs Developer access or
higher; anyone else is ignored silently.

- `/w review`, `/w security audit` and a bare `/w` run on a merge request.
- `/w triage` (and a bare `/w` on an issue) labels and summarises; new issues are triaged
  as on GitHub.
- `/w audit` posts the posture report. On a project that is not private it posts the
  counts only, since anyone could read the details; ask in a confidential issue for the
  full report. GitLab CI, protected branches and approval rules are checked in place of
  GitHub's Actions and branch protection.
- `/w wrong [note-link] <reason>` records a verdict; the link ends `#note_<id>`.
- `/w hunter`, `/w build` and `/w fix` answer that they are not available on GitLab yet.
- `@mention` works only when the project posts as a project or group access token, by
  that token's bot username. When it posts as the connecting person the name is a
  colleague's, so mentioning them is ordinary conversation and only `/w` is a command.

---

*Integration manual: https://wrok.in/agents.md · Machine-readable summary:
https://wrok.in/llms.txt · Capability manifest: https://wrok.in/capabilities.json ·
Config schema: https://wrok.in/config.schema.json*
