mr-onion

Working agreements

Rewritten 2026-10-26. The previous version of this file was test-assist’s working agreement, copied in with the skills work on 2026-09-16; it described TA-NNN tickets, TESTASSIST_BACKLOG.md and a deployed browser build, none of which exist here. Its two hard-won lessons live on as the dont-stub-what-you-prove and find-the-hidden-platform skills.

How work on Mr Onion is decided, built, checked and recorded. Gates, evidence rules and the verification checklist are in QUALITY_GATES.md; this document is the process around them. Review it when the way of working changes, and at least at every phase completion (see Docs that must stay true).


Decision vocabulary

Documents and code say what kind of decision or permission something is, not whose name is attached to it. A name records who decided; it is not the rule. A reader, a new contributor or a coding agent has to be able to tell from the words alone whether they may proceed.

Term Meaning What an agent does
Owner decision A choice between valid options that only the project owner makes: scope, product direction, a gate ruling, a trade-off. Sets out the options, the evidence and a recommendation, then stops. The decision is recorded with its date in a decision record.
Confirmation required An action the agent may prepare but must not perform without an explicit go-ahead in the current session. Approval does not carry over to later actions or sessions. Prepares the action, says exactly what it will do, waits for a clear yes.
Independent review A review by someone who did not produce the work: a separate verifying session, or an outside reviewer at a stage gate. Hands over the work and the criteria, not the reasoning that produced it.
Recorded rationale Why a past decision was taken. Cites it by reference, e.g. Phase 42 Decision 8 (2026-10-12), rather than restating it.

Confirmation required, standing list. These need a go-ahead every time, whatever permission mode the session runs in:

In product code and product docs, the person approving is the tester (or “the user” in UI copy) — Mr Onion is meant for other people’s sites and teams. Code and README text never name a maintainer as the approver.

Where names still belong:

Roles

Role Who, today Does
Owner Emil Makes owner decisions; gives confirmations; rules at gates.
Reviewer Martin Independent review at stage gates; proposes skills and direction.
Planning session Claude in chat or Cowork Decision records, backlogs, handovers, reviews, doc updates. Never edits code or commits.
Implementing session Claude Code in VS Code Builds tickets, runs checks, writes commit messages, commits and pushes. The only git driver on the repo.
Verifying session A fresh session that did not build the work Runs QUALITY_GATES.md §5 with the agent-report-verification skill.

The table is the only place names are mapped to roles. Everywhere else, use the role or the vocabulary above.


The loop

owner decision ─► decision record ─► tickets ─► handover ─► build ─► verify ─► gate ruling ─► record
   (planning)       (planning)       (planning)  (planning)  (implementing) (verifying) (owner)  (planning)
  1. Decide in a decision record. A phase is locked by docs/decisions/phase-NN-*-decision-record.md before it is built (phase-decision-record skill). Its Acceptance criteria must be checkable; if they can’t be written, the work isn’t understood well enough to start.
  2. Break it into tickets. TFP-NNN, in the record or a backlog file beside it (implementation-backlog skill). Each ticket has a problem it solves, scope, acceptance criteria and explicit dependencies. Before allocating numbers, check the highest TFP- in the repo — two sessions can be writing tickets at once.
  3. Hand over. One current docs/HANDOVER_TO_CLAUDE_CODE_<date>-<topic>.md per workstream. A new handover deletes the one it replaces in the same commit; its history stays in git. The owner points Claude Code at the file; nobody pastes its contents into chat.
  4. Build. Claude Code builds one ticket at a time, runs its checks, and shows evidence, not assertions (QUALITY_GATES.md §1).
  5. Verify. A fresh session checks the report against the ticket before the next ticket starts at a gate, and on the highest-risk ticket of a phase.
  6. Rule. At each gate the owner rules on the measured results. The ruling and its table are recorded under the gate in the decision record.
  7. Record. The record’s status line, product-roadmap.md, the deferred-work register and the test plan are updated in the same commit as the work they describe.

Commits go to main in small, reviewable commits, in Conventional Commits form (conventional-commits skill): the body carries the why, the alternatives rejected and what the change does not do. A commit that completes a GitHub issue ends with Closes #N; progress on one with Refs #N. GitHub issues hold outside reports and work that needs visibility; TFP- tickets in docs/decisions/ stay the design record, and an issue that becomes a ticket carries its TFP- number in its title. Each known limitation in TEST_PLAN.md has an open issue (known-limitation), closed by the work that changes it; each phase from Phase 39 on has a tracking issue (phase), opened when its record locks, its gate rulings added as comments, closed by the commit that completes the phase (TFP-262).


Running Claude Code

These follow from the Claude Code team’s current guidance (Boris Cherny’s and Cat Wu’s practices, 2026) where they fit how Mr Onion is built.

Auto mode for ticket implementation. Auto mode is Claude Code’s starting permission mode, when no permissions.defaultMode is set, from v2.1.284 in the terminal and VS Code (v2.1.283 only on third-party providers or with telemetry off): a separate classifier reviews actions and blocks risky ones instead of prompting for each. A locked ticket already has its plan — the decision record — so the implementing session goes straight to building; plan mode is for work that isn’t ticketed yet, or a change that can’t be described in a sentence. Auto mode does not replace the confirmation-required list above: the classifier decides what is risky, the list decides what needs the owner.

A correction becomes a rule, the same day. When the owner corrects Claude Code on something that would recur, the session proposes a one-line addition to CLAUDE.md (or to the skill that should have caught it) in its next commit. A lesson that lives only in a decision record is invisible to the next session. Keep CLAUDE.md short: for each line, removing it should cause a mistake. Ticket-specific rulings stay in the records.

Context is the scarce resource.

Red before green. A bug fix starts with a test that reproduces the bug and is shown failing; a behaviour change’s tests are shown failing with the change removed; anything that can’t be shown red says why (QUALITY_GATES.md §1, owner decision 2026-11-02).

Check before reporting. Before a ticket is reported done, the session runs its own checks, then a fresh-context review of the diff against the ticket (Claude Code’s /code-review, or a subagent given the ticket’s Acceptance section). Gate verification is still a separate session.

Parallel work in worktrees — only when it’s safe. Independent tickets can run in separate git worktrees, one Claude Code session each. Only when:


Routines

Recurring checks run on a schedule rather than when someone remembers.

Routine Cadence What it does State
Unit suite, template check, advisory audit and dead-code check Nightly 02:00 UTC, plus manual dispatch .github/workflows/nightly.yml Running
Nightly summary email After the nightly run Quick-view summary with a link to results, on the run’s page and by email (.github/workflows/nightly.yml, notify) Running
Living-docs check Weekly Checks APPLICATION_OVERVIEW.md, README.md and this file against the code and the roadmap (repo-claim-audit skill) and reports what is false or stale Scheduled task, set up 2026-10-26
Nightly-failure triage After a red nightly Reads the failing job and drafts an issue with the failing test, the first bad commit and a reproduction Ticketed (see docs/decisions/workflow-and-ci-backlog-2026-10-26.md)

A routine only reports or drafts. Anything it finds goes through the loop like any other work.


Docs that must stay true

Doc Says Update when
README.md How to set up and use Mr Onion, and its security model A user-visible behaviour, setting or command changes
docs/APPLICATION_OVERVIEW.md What Mr Onion is and does now, for a new reader Every phase completion
docs/decisions/product-roadmap.md Every phase, in order, with its status Every lock, gate and completion
docs/decisions/deferred-work-register.md Everything deferred, its build order and standing rules Whenever a record defers or picks up work
TEST_PLAN.md Feature status, known limitations, and the index of test-case areas In the commit that changes the behaviour
docs/test-plan/<area>.md Case-by-case status, one file per area (GEN, RUN, …) In the commit that changes the behaviour
docs/QUALITY_GATES.md Gates, evidence and verification When a gate or check changes
This file How work is done When the loop changes; reviewed at each phase completion

Each of these should carry its last-reviewed date near the top (the overview and this file do; TFP-255 and TFP-256 add the rest). The weekly living-docs check reports any that is older than the last phase completion.