# The `/w` command contract

wrokin's comment interface, specified for agents that drive it. Every claim here
is drift-tested against the routing code (`pi-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`, `/wrokin`, and `/pi` — the
project's former name, which keeps working and has no removal date. They are
interchangeable: `/w review`, `/wrokin review` and `/pi review` are the same
command.

`/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).

## 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 |
| `/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 | **Private preview** — dispatches the proof-by-execution hunt workflow (default level `stakeout`) | 👀 reaction on your comment. Failure (workflow not enabled, missing permissions, not entitled) → an actionable `🛡️` comment. Unknown level → a `🛡️` comment listing valid levels |
| `/w build [patch\|feature\|expedition]` | **issue** | **Paid plans** (Pro/Team/Business), once the Builder is enabled on the repo — dispatches the Verified Builder to implement the issue on your own runner (default level `patch`). It proves the change green before proposing it: a ready PR when your suite passes, a draft marked *unproven* when it doesn't, and at `patch` an unproven change is dropped rather than opened | 👀 reaction on your comment. Not entitled, credits exhausted, workflow not enabled, or missing permissions → an actionable `🔨` comment. Unknown level → a `🔨` comment listing valid levels |

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.
- **`/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 + credits are
  checked BEFORE the runner starts — so an unaffordable 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 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.

---

*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*