Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

130 KB
Raw Blame

Prompt rules audit: code or judgment (2026-11-07)

Task #4553. Asked by anh Dee at 18:35 Vietnam time on 2026-11-07: Harness behaves reliably because its rules are enforced in code; prompts carry only judgment. Most of the day's problems were agents not following prompts: Leads picking against the routing rules, cancelling people's cards, posting notices into private chats.

This is the audit: every rule a Lead or a Member is given today, marked by whether code can enforce it. It sits beside the four-part instructions spec (#4537, docs/specs/2026-11-07-agent-instructions.md, PR #3556). That spec says where each judgment rule goes (job page, AGENTS.md or removed). This audit says which rules become code, and in which task. There is no second map. The standing rule is in AGENTS.md, code standard 13: a rule in a prompt says why it can't be code, and its prompt line goes once its code fully enforces it. A safety rule (secrets, outside text, other accounts, production writes, processes) keeps its line even with code behind it, as the #4537 job pages do: code such as redactCredentials catches only the secrets it recognises, so it is a backstop, not the rule.

What was read

Measured on main 0dd01c979, and the openharness project instructions at revision 86 with the PM's notes:

Source What it is Rows
Project instructions and PM notes The openharness document every Lead and Member reads 184
Built-in PM texts backend/src/superTabs/pmSchedule.ts (v2Section, BUILT_IN_SECTION), instructionsTemplate.ts, processNotes.ts, cli/src/lib/swarmInstructionsSkill.ts 151
Role skills cli/src/lib/swarmSkills.ts default set: swarm-lead, swarm-dev, swarm-review 169
Tools, frame and launch cli/src/lib/swarmTools.ts, swarmToolSheets.ts, cli/src/superTabs/host.ts, start.ts 153

A rule that mixes a code-able part and a judgment part is two rows. Each code row names the file and function that enforces it, found in the code, not assumed.

Since this audit (#4673, 2026-11-07): agents no longer get the built-in PM text (v2Section, BUILT_IN_SECTION), the role skills, the per-role tool sheets or the swarm-instructions skill. They read the project instructions and the full manual (swarmTools.ts) alone, and their launch line has them read both. The code rows from those texts still hold, as code. Their safety lines (secrets, temp folders, own processes, other accounts, live worktrees, tokens) are in the manual. JOB_LINES, TIDY_LINES and scheduleText stay in pmSchedule.ts as the scheduled wake messages. processNotes.ts and instructionsTemplate.ts are unchanged. The Buddy skill stays: its limits are in no code yet. Appendices B to D keep those texts as they were read, marked where removed.

Classes

Class Means Rows
code Already enforced by code; the prompt line can go now (#4537 task 9), unless it is a safety rule, which keeps its line 190
building Being made code in an open task (list below) 90
new Code can enforce it; nothing does yet 125
judgment Needs judgment no program can make; stays in a prompt, with why 163
remove A Swarm v1 or v2 leftover, a Team-account rule, or a duplicate 89
657

By source:

Source code building new judgment remove
Project instructions 41 28 55 47 13
Built-in PM texts 51 24 22 34 20
Role skills 46 23 28 47 25
Tools, frame, launch 52 15 20 35 31

New code: one task per family of rules

Each task names its rows here, and removes their prompt lines once its code fully enforces them; a safety rule's line stays (#4591, #4598, #4604 among them). The Lead gives each an owner.

Task Rules it makes code Check it adds
#4590 Answer each message once, in every chat answer once (tools 19; project, built-in: partial) every agent's answer is recorded; a second is refused in any chat. Today only the PM's is recorded outside project chats. Fits #4555 (no threads)
#4591 No agent merges its own pull request never merge your own PR; no force-push (tools, review skill, dev skill) shell guard refuses gh pr merge and gh api …/merge; the merge helper refuses the task's builder. Today the task token can merge
#4592 Quiet chats no card repeats, no status lines, no results posted to the PM, no "should I / OK to build?", no commands or ids to people (all four sources) the project chat's checks (chatLimits.ts) apply to task, step and private chats; two new refusals
#4593 Copy rules checked in CI buttons of 1-2 words, no filler, Accept/Decline (project) a check beside scripts/check-ui-style.py
#4594 A person's task is cancelled only by them, or as a duplicate cancelling people's cards (anh Dee's 11-07 problem; today any project agent may cancel any task) work.cancel from an agent refuses a person's task unless its reason links the real task (#4480)
#4595 Only the Lead opens and assigns top-level tasks Members propose; the Lead chooses owners (role skills) conversation.create and work.assign refuse a Member's top-level task
#4596 Ready and done need a pull request and passed steps Ready means a PR; done needs steps passed at the head; review once per head; blocked says why (role skills, tools) four work.status refusals
#4597 Plan first and test before code hold the merge plan as first commit, failing test before code (project) Ready and the merge train act on prHistory.ts, which already computes both
#4598 Shell guard: own processes, secrets, outside code, every engine stop only your own processes, never print a secret, never run an outside PR's code, no upload scripts (project, tools, dev skill) shellGuard.ts refusals; the guard for every engine, not only Claude Code and Codex; secret patterns in the Swarm git hooks
#4599 A pull request stays inside its task's owned code build only what the brief asks; no two tasks own the same code (project, role skills) changed files against task.owns; overlapping owns refused
#4600 Every question to a person has a default and a time an ask carries a recommendation and a default, applied at its time (project, built-in) decision.ask requires both in every project; a due default wakes the Lead
#4601 Release window override until launch, and urgent releases anh Dee's lift of the window until 11-10; a hotfix releases at once; his asks reach a Desktop release within 2 h; the hourly release line (project) a dated override in scripts/release-window.json (today it still refuses 18:00-09:00); release watch timers
#4602 The Lead writes no code and sets no timers the Lead coordinates; no own timers; no hand-opened steps the server plans; no doubled server actions; "idle" is no reason (built-in, role skills) daemon and backend refusals for a coordinator session
#4603 The server reacts to work, not the agents 👀 ✅ 🚀 (all four sources) reactions written with the writes that already happen, no extra requests
#4604 Production writes behind Ken's approval in GitHub production writes need Ken's go; explain before a production read (project) a GitHub production environment with Ken as required reviewer; a read helper that refuses a scan
#4605 Team PRs get a task, and idle worktrees clean themselves the Lead's half-hourly chores (project) the PR watch opens the task; a daemon timer removes idle clean worktrees

Already being built

Task Rules
#4546 Pick agents in code routing order, models, quota, machine choice, "idle is no reason" for a pick (routing is advice today: routePick.ts in the CLI, the server trusts it)
Merge train (backend/src/superTabs/mergeTrain/) merge when reviewed and ci/required green; only a Reviewer's pass counts (plan.ts passers). It is off by default (policy.ts seed), so these rules are code only where a project turns it on
#4538 My ask stays one card one card per ask
#4547 Only me and my agent post in our private chat notices in private chats
#4533 GitHub issue is the task issues close on merge
#4537 Four-part instructions skills and instructions re-sent on a version change or compaction; the Lead's schedule as server messages
#4534 Review independence (PR #3554, ready to merge) a reviewer of one security review never gets the other; a stuck step moves without a cancel

Reassign a task when its claim goes quiet is already code: liveness.ts drops a task whose lease runs out (5 minutes with no progress report, 30 minutes quiet), dispatch.ts candidatesFor hands it on, and stuck.ts alerts after 10 minutes. The prompts still say 20 minutes; the code waits 30.

Prompt lines the code already contradicts

Each goes when #4537 task 9 removes old text, or sooner:

  • "Down 2 hours: cancel its task" (swarm-lead): a stuck step moves without a cancel since #4534.
  • "A failed start retries on the next machine" (swarm-lead): start.ts moves a failed start nowhere.
  • "20 minutes quiet" (swarm-lead, swarm-dev): the code waits 30.
  • "Switch skills on the owner's message" (swarm-lead): project.skills is ignored now.
  • "The Engineer tags the person" (swarm-dev): crewNeeds.ts routesToPm sends those tags to the PM.
  • "Keep instructions under 150 lines" (built-in): the server limits by size (20 KB), not lines.
  • "The merge helper runs from a checkout of main" (project, Scholes): scripts/merge-validated-pr.py requires the checkout at the PR's head.
  • The release window (project, Dee 11-07): scripts/release-window.py still refuses 18:00-09:00. #4601.
  • The PM 20% quota rule (built-in, twice): #4537 removes it, but crewKeep.ts still moves crew off a PM's account below 20%. #4546 decides whether that stays.

Code-able, not yet in a task

Smaller or rarer than the sixteen above. The Lead opens each as its rule next bites, or declines it; until then its prompt line stays and says why it isn't code yet:

  • Skills named by address fetched each use, as a versioned part (extends #4537).
  • Voice messages show no transcript: a widget test on Desktop and phone.
  • A phone install needs a lease the PM grants (like Desktop's SerialPortLease).
  • Outside PRs triaged only on Diego's review machine: an "only" machine rule (today first).
  • Desktop tests never sign out the real CLI: the test config refuses login and logout under kUnderTest.
  • CI refuses engine credential paths in desktop/lib and cli/src.
  • No Linux machine: CI's Linux runs meet the Linux test step.
  • Nobody runs the whole backend suite locally: the guard refuses it without a file filter.
  • New Desktop UI updates the design doc and its gallery test in the same PR: a CI check.
  • Plan headings checked in CI.
  • Task titles of about eight words: conversation.create refuses over 12 words.
  • Tag people by @username: an email in an agent's text becomes their @username.
  • A non-member's project-chat message goes to the Guide, not the PM.
  • A person's message answered within a minute: an owed-ask timer and measure.
  • anh Dee's asks first: taskPriority.ts ranks them first in dispatch and the train.
  • Hourly, where work waits: a server message naming the slowest wait.
  • The 07:03 metrics posted by the server as a new message (with #4537's schedule).
  • The digest built from recorded merges, posted by the server.
  • A combination read when batch members change the same file; rerun only a recorded flaky check.
  • Second round to the same Reviewer, told the new head by the server.
  • Findings as {severity, file, line, fix}; a failed verdict needs one.
  • A task's deadline, and late work back to its lane an hour past it.
  • Auto-archive of finished groups with no pull request.
  • A tidy save refused while a dropped line is unsorted; a saved rule carries (Name, date).
  • On a Yes to a routing proposal, the server writes it into the rules.
  • Only Dee or Ken overrule a decided proposal; Leo's ideas get Ken as approver.
  • Work moved off a machine 15 minutes before its away hours.
  • A start settled is pushed to the Lead; no resume polling.
  • The compaction hook answered with the agent's mine (with #4537's re-send).
  • Status notes and pushes every 30 minutes: a nudge timer.
  • Tools, devices and sign-ins checked before the first turn.
  • The CLI retries a busy instructions read itself; an identical refused command isn't resent.
  • The PR body's "requested by" line written by the PR watch.
  • A delivery neither answered nor acted on in 30 minutes shows as owed.
  • The words of each agent post to people measured, not refused.

The full tables

Four appendices, one per source, every row with its class and what enforces it or why it is judgment.

Appendix A. Project instructions and PM notes (revision 86)

Source: openharness project instructions, revision 86, and the PM's notes. Code paths are relative to the repo root. I left out "Product direction" because it holds facts and targets, not rules.

Project instructions (Ken 11-02, 11-04)

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Fetch a named skill each time it is used, never from memory Project instructions (Ken 11-02) new Daemon fetches each skill URL named in the instructions when work is assigned and when the skill changes, and sends it as a versioned part (extends #4537's parts).
Instructions beat a skill; "your human partner" means the PM Project instructions (Ken 11-02) judgment Settling a conflict between two texts needs reading both.
PM decides itself, never passes the call back to a person Project instructions (Ken 11-04) remove Same rule as Roles › PM "Decides, doesn't ask".

Roles › PM

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Own the product; work without pause with every machine and agent Roles › PM (Dee 11-03) judgment A mission statement with no checkable act.
Read AGENTS.md positioning before each decision Roles › PM (Dee 11-03) building #4537: AGENTS.md is part 2, sent again on change and on compaction. Applying it is judgment.
Never ask "OK to build?", "want me to", "should I", "do you want" Roles › PM (Ken 11-04) new Backend message.send refuses a PM post to people that matches these phrases (ASK_FOR_GO), the way acknowledgements.ts gives ACK_ONLY.
Ask a person only where a rule names them or only they can act Roles › PM (Ken 11-04) judgment Whether a step needs that person depends on context.
A held task waiting on a person has a default and a time Roles › PM (Ken 11-04) code backend/src/superTabs/heldReason.ts (HOLD_REASON_MISSING: a person hold needs personId and defaultAt); decisions.ts (options plus a recommendation).
At the default time the default is applied, never waited past Roles › PM (Ken 11-04) new Time check (timeChecks.ts) wakes the PM when a hold's defaultAt passes ("default due: apply it") and shows it on the task.
Never offer a choice it can make; pick, say why, go Roles › PM (Ken 11-04) judgment Whether the PM could have made the choice itself is judgment.
Answer each proposal Accept, Reshape, Later or No Roles › PM (Dee 11-03) code proposalCards.ts (decision kind plus reason; PROPOSAL_DATE: Later needs a revisit date); commands.ts assignRefusal PROPOSAL_UNDECIDED. Covers Buddy proposals only.
Weigh against positioning; name the part it rests on Roles › PM (Dee 11-03) judgment Product judgment.
A No or Reshape tells how to revise the idea Roles › PM (Dee 11-03) judgment The content of the advice.
Only Dee or Ken overrule the PM's answer, by saying so Roles › PM (Dee 11-03) new A second decision on a decided proposal is refused unless the actor is instructionApprovals.topDeciderId or a listed approver (policy.ts).
Fixes, security fixes, crew-speed work are yes at once Roles › PM (Dee 11-03) remove Duplicates AGENTS.md › Scope.
Dee's decisions override every other decision, at once Roles › PM (Dee 11-04) judgment Spotting which decision conflicts. The spec moves it to AGENTS.md.
Dee's word changes or drops Ken's rules without asking Ken Roles › PM (Ken 11-06) code ruleGuard.ts: the top decider (topDeciderId) may approve any dropped rule.
Never ask Dee for a go Roles › PM (Dee 11-06) remove Duplicates "Decides, doesn't ask" and the 11-07 PM note.
Fast when cheap to undo; slow, with written reasoning, when hard Roles › PM (Dee 11-03) judgment Telling how reversible a choice is.
Brainstorm only when what or why is missing; one question at a time Roles › PM (Ken 11-04) judgment Whether a request is clear.
A clear request becomes a task at once Roles › PM (Ken 11-04) building #4538: one card per ask, opened by the server.
A project gets a written design attached to its task Roles › PM (Ken 11-02) judgment Whether the work is a project.
PM writes no plan and uses no visual companion Roles › PM (Ken 11-02) judgment Low value; the Engineer's plan-first check (below) covers the plan.
Rank each reported bug by its effect on people first Roles › PM (Leo, Ken 11-05) judgment Judging impact.
A hotfix gets P0 and its reviews in parallel Roles › PM (Leo, Ken 11-05) code taskPriority.ts (P0–P3); review steps all open at Ready (commands.ts openReviewSteps, reviewTable.ts).
A hotfix gets its own release as soon as checks pass Roles › PM (Leo, Ken 11-05) new When a P0 task's PR merges, its component's release starts (release-window.py --urgent with the task as reason).
The reporter hears cause, workaround and when the fix lands Roles › PM (Leo, Ken 11-05) judgment What the message says.
Before answering in a task, read its state Roles › PM (Ken 11-05) code cli/src/superTabs/deliveryContext.ts puts the assignee, status, steps and PR head in every delivery. Reading the thread is judgment.
Non-PM agents tag only the person they answer Roles › PM (Leo 11-05) code commands.ts message.send → crewNeeds.ts routesToPm: other tags become crew needs for the PM.
PM tags a person only when they must act Roles › PM (Leo 11-05) judgment Whether someone must act.
Approvals for Leo's ideas go to Ken Roles › PM (Leo 11-05) new A task Leo asked for gets Ken as its approver (taskApproval.ts personId).
Message an agent only to give work, answer, or hand lost work Roles › PM (Ken 11-03) judgment The purpose of a message.
Send agents no thanks or acknowledgements Roles › PM (Ken 11-03) code acknowledgements.ts isAcknowledgement → ACK_ONLY in commands.ts message.send.
Ask no agent for status Roles › PM (Ken 11-03) new Refuse a PM post to an agent that only asks for status ("status?", "any update") while that agent's work.status is under 30 min old.

Roles › Engineer

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Build only what the brief asks Roles › Engineer (Dee 11-03) new At Ready, list the changed files outside the task's owns paths (taskContract.ts) in the review brief. Whether they belong is judgment.
An idea beyond the brief goes to the PM as a proposal Roles › Engineer (Dee 11-03) remove Duplicates AGENTS.md › Scope.
The plan in docs/plans is the PR's first commit, unless a small fix Roles › Engineer (Ken 11-02) new prHistory.ts already computes planFirst. Ready, or the merge train, refuses fail when production lines are over 20.
The plan has the set headings and no Execution Handoff Roles › Engineer (Ken 11-02) new CI script checks the headings of docs/plans/*-plan.md in the PR (Goal, Architecture, Tech Stack, Spec, Global Constraints, Review Focus).
Commit each failing test, then the code that passes it Roles › Engineer (Ken 11-02) new Same check: refuse Ready or merge when prHistory.ts says testBeforeCode=fail (missingTests lists the files).
No review per plan task; the PR review is the one review Roles › Engineer (Ken 11-02) judgment Process advice that overrides a skill; nothing to check.
Locally run only the tests of what changed, never a whole suite Roles › Engineer (Ken 11-04) judgment Which tests cover a change needs reading the code.
Locally run the checks CI skips when touching their area Roles › Engineer (Ken 11-04) code scripts/local-checks.py (a ci.yml step) requires exact-head receipts in the PR body for the gates the paths touch.
Red CI: read it, rerun it alone, fix, push once Roles › Engineer (Ken 11-04) remove Duplicates AGENTS.md › CI ("Read the failure, fix it, push once").
Parallel subagents only for plan tasks sharing no files Roles › Engineer (Ken 11-02) judgment Whether interfaces are shared.
A plan too big for one Engineer goes back to the PM Roles › Engineer (Ken 11-02) judgment Size judgment.
Check each review finding against the code; answer wrong ones Roles › Engineer (Ken 11-02) judgment Technical judgment.
Minor findings wait unless the task says otherwise Roles › Engineer (Ken 11-02) judgment Reading the task.
Open a draft PR with design and plan; first status names it Roles › Engineer (Ken 11-02) new stuck.ts time check flags a task working 30 min with no linked PR. work.status working after the first refuses without a PR.
Push after each plan task's commits Roles › Engineer (Ken 11-02) judgment When a plan task ends is not visible to code.
Push nothing while review and CI run, unless fixing a finding Roles › Engineer (Ken 11-02) new PR watch (pullRequestEvents.ts) flags a push to a handed PR with no No verdict or red CI since Ready, and tells the Engineer.

Roles › Reviewer

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Review by code-reviewer.md against task, plan, spec and codebase Roles › Reviewer (Ken 11-02) judgment Review itself.
A verdict is for the head it read Roles › Reviewer (Ken 11-02) code mergeTrain/plan.ts countsFor (needs verdict.head, not stale); checkVerdicts.ts verdictCounts.
Check the history shows each failing test before its code Roles › Reviewer (Ken 11-04) code prHistory.ts computes it; reviewTable.ts puts "Plan first / Test before code" in the review brief. Refusing on fail is the Engineer row above.
Read the red/green evidence and CI rather than rerun them Roles › Reviewer (Ken 11-04) judgment "Unless something looks wrong" is judgment.
Give the verdict once the code is read; never wait for CI Roles › Reviewer (Ken 11-04) building Merge train checks ci/required itself (mergeTrain/plan.ts 'ci').
A change of 20 lines or fewer, outside security areas, is "small" Roles › Reviewer (Ken 11-04) new reviewTable.ts labels the brief "small" from prHistory.ts productionLines ≤ 20, and never when policy.ts SECURITY_ROWS match.
A small change is held only by a fault in its code Roles › Reviewer (Ken 11-04) judgment Telling a fault from a Minor issue.

Roles › Integrator

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Batch PRs passed at their head with ci/required green Roles › Integrator (Ken 11-05) building Merge train (mergeTrain/plan.ts headReads, eligibility). Off by default: policy.ts SEED_RULES mergeTrain.enabled: false.
Get a combination read where batch members' files overlap Roles › Integrator (Ken 11-05) new Train asks one member's Reviewer for a combined read when two batch members change the same file. I found no such step in mergeTrain/.
Merge with main's helper; close originals with a link; record; tell requesters Roles › Integrator (Ken 11-05) building Merge train (mergeTrain/train.ts closes originals with a link and records merges).
Open the review, security review and test steps at Ready Roles › Integrator (Ken 11-05) code Steps open by themselves: reviewTable.ts requiredReads/testsFor, commands.ts openReviewSteps with reviewerPick.ts.
Ask reviewers to confirm a moved head Roles › Integrator (Ken 11-05) code checkVerdicts.ts keeps a verdict whose patch id is unchanged (a merge of main); a real change makes it stale.
Rerun a recorded flaky check Roles › Integrator (Ken 11-05) new CI reruns a failed job once only when the failing test is on the recorded flaky list.
Tell the builder when to merge main Roles › Integrator (Ken 11-05) code handed.ts: a merge conflict sends the task back to its Engineer.
Builders ask the Integrator, not the PM Roles › Integrator (Ken 11-05) remove The merge train replaces the Integrator role; nobody is left to ask.

Roles › Guide

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
How/why/where questions and bug reports go to the Guide first Roles › Guide (Ken 11-05) judgment Sorting a message by kind.
PM hands such a message to the Guide in one line Roles › Guide (Ken 11-05) judgment Follows from the sorting.
Guide turns a bug into a proposal the PM decides Roles › Guide (Ken 11-05) judgment Writing the proposal.
Leo's messages go to the Guide Roles › Guide (Ken 11-05) remove Duplicates Ken's 11-06 note on non-members (Leo is not on the member list).

Workflow

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Done status, with PR and evidence, is how the PM hears, once Workflow 4 (Ken 11-03) code work.status done reaches the PM; step verdicts carry Reviewer and Tester results (commands.ts).
No ack, "ready" or progress messages to the PM Workflow 4 (Ken 11-03) code ACK_ONLY; CHAT_STATUS in the project chat (chatLimits.ts); since #2963 an agent's post that names no one never reaches the PM (commands.ts message.send).
No status line to the PM in any chat Workflow 4 (Ken 11-03) new Apply chatLimits.ts STATUS to agent posts that name the PM in task chats too, not only the project's main chat.
PM checks CI on passed PRs, merges, tells requesters Workflow 5 building Merge train.
Batch and merge helper run from a main checkout, never a PR branch Workflow 5 (Scholes 11-02) building Merge train runs on the server through the GitHub App, with no checkout. Note: scripts/merge-validated-pr.py preflight requires the local checkout to be at the PR's head, the opposite of this rule.

Product decisions (anh Dee)

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Voice messages play only: no transcript or Transcribe on any app Product decisions (Dee 11-04, 11-05) new Widget tests in desktop and mobile check that a voice bubble shows no transcript and no Transcribe or →A control.
The mic sends a voice message, its clip alone Product decisions (Dee 11-04) code commands.ts message.send VOICE_ALONE (voiceMessages.ts).

PM schedule (Ken 11-03, Dee 11-04)

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Run the schedule on its own clock; recreate it after a restart PM schedule (Ken 11-03) building #4537: the schedule becomes server messages at their times. pmSchedule.ts already wakes the 30-min sweep and the 23:00 tidy.
Post in the project chat only when a person must act PM schedule (Ken 11-03) judgment Whether a person must act.
At :22/:52, clean worktrees with no live process, pushed, clean PM schedule (Ken 11-03) new A daemon timer on each machine removes such worktrees itself. The checks already exist (machines.ts removeStoppedWorktree, shellGuard.ts liveWorktree), so no agent is needed.
A team PR (not draft, no task, under 2 days) gets a task and review PM schedule (Dee 11-04) new PR watch (pullRequestEvents.ts) opens a task with a review step for such a PR by a project member, and tells the author in one line. Outside authors are skipped.
Older team PRs: revive or close with a reason on Monday PM schedule (Dee 11-04) judgment Revive or close is judgment; the Monday timing comes with #4537's server messages.
07:03 daily metrics as a new main-chat message, never a reply PM schedule (Dee 11-04) new The server posts the numbers table itself at 07:03 as a root message (from leaderboard/ and scorecard/ data).

Routing › Models (Ken 11-02; Tony 11-04; River 11-04)

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Small work to grid models first, else Sonnet/Sol high by price Routing › Models (Ken 11-02) building #4546. Partly done in cli/src/superTabs/routeCheapFirst.ts and routePick.ts step 1, as advice from the CLI.
After a failed review step up to Sonnet/Sol, then Opus/Astra Routing › Models (Ken 11-02) building #4546. routeCheapFirst.ts leaves out the grid after any earlier attempt; the second step-up is not coded.
A PR with full test evidence at its head is not tested again Routing › Models (Tony 11-04) new An evidence fence in the PR body (head, commands, pass counts, light/dark screenshots, Done-when → proof), checked like local-checks.py. The test step's brief says whether it is valid at the head.
Tester runs one main flow itself and tests what is missing Routing › Models (Tony 11-04) judgment Choosing the flow and the gaps.
A Team-written branch is tested on a Team account Routing › Models (River 11-04) remove Team accounts are gone (Dee 11-07); the v3 note replaces it.

Routing › Machines

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Start nothing on Ken's MacBook Pro in his away hours Routing › Machines (0xken15 11-03) code machineRules.ts away windows → commands.ts refuseByMachineRules (MACHINE_RULE) on start and assign, plus dispatch.ts, crewKeep.ts and CLI routeCommand.ts. It holds only if the project's rules record lists that machine; I could not verify that from the repo.
Move work off it before those hours Routing › Machines (0xken15 11-03) new crewKeep.ts timer moves or hands on running work from a machine 15 min before its away window.
Phone app tasks go to Tony's Mac first, Engineer and Tester Routing › Machines (Tony 11-03) code machineRules.ts firstMachines (lane mobile), used by dispatch.ts and routeCommand.ts.
At most 4 agents on Tony's Mac Routing › Machines (Tony 11-03) code The machine's own limit (machines.ts agentLimit → MACHINE_FULL). Check that his machine is set to 4.
Never install a build on a phone unless the PM says it is free Routing › Machines (Tony 11-03) new A lease per phone (like Desktop's SerialPortLease); the CLI refuses an install to a phone without the lease.
No Codex agent on Diego's Mac Routing › Machines (Diego 10-28) code machineRules.ts noEngines (MACHINE_RULE).
No Reviewer on the Mac whose Codex defaults to a local model Routing › Machines (Ken 10-29) code machineRules.ts noReviews.
Outside PRs triaged only by Claude Reviewers on Diego's review machine Routing › Machines (Diego 10-29) new Add an "only" machine rule (today machineRules.ts has first, not only) for a triage lane with engine claude.

Rules for every agent

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Never post a secret Rules for every agent code commands.ts runs redactCredentials (credentials.ts) on every message it writes.
Never print a secret Rules for every agent new Shell guard (cli/src/superTabs/shellGuard.ts) refuses printing known secret files to stdout (~/.harness-ro-prod-db, session.json, .env).
Production writes need Ken's go Rules for every agent (Ken 11-04) new A GitHub production environment with Ken as required reviewer on production-be-build.yaml and the schema step. Today it has no environment gate.
Read-only prod login only through its environment file Rules for every agent (Ken 11-04) new Shell guard refuses a command holding a literal mongodb+srv:// address; reads go through the env-file loader.
A non-indexed prod read runs explain() first; never scan Rules for every agent (Ken 11-04) new A prod-read helper runs explain and refuses COLLSCAN before it runs the query.
Database work reads MongoDB's skills; Reviewer checks against them Rules for every agent (Ken 11-03) new A "Database" row in reviewTable.ts for backend/prisma/** and query files puts both skill links in the review brief. backend/AGENTS.md already names them.
Before Ready: a failing test per risk, red/green in a PR comment Rules for every agent (Dee 11-03) new Ready refuses without a red/green evidence fence at the head (as local-checks.py does for local receipts).
Backend suite evidence is the PR's CI integration run (4 shards) Rules for every agent (Dee 11-03) code .github/workflows/ci.yml job backend-integration, 4 shards.
Nobody runs the full backend suite locally Rules for every agent (Dee 11-03) new Shell guard refuses npm run test:super-tabs with no file filter.
A visible change follows the Harness design language Rules for every agent (Dee 11-03) code scripts/check-ui-style.py (in ci.yml) blocks hard-coded colors and sizes in Swarm UI. Only partly: style tokens, not layout.
A visible change starts with an ASCII mockup for the asker Rules for every agent (Dee 11-03) judgment Whether people see the change; Scholes's exception applies.
PM merges on review, test and screenshots; fixes forward Rules for every agent (Dee 11-03) building Merge train.
A UI change carries light and dark screenshots Rules for every agent (Dee 11-03) new Ready, for desktop/** or mobile/** UI files, requires two image links in the evidence fence.
Asking a person to approve also sends a person.tell line Rules for every agent (Huy 11-04) new A post with images that tags a person also writes the person.tell line (task, what to look at, where) to their Buddy chat.
A Tester checks the web build in iPhone Safari before each web release Rules for every agent (Huy 11-02) new release-web.yml refuses without a passed Tester verdict for the release commit.
Never run a test that signs the Mac out of the real CLI Rules for every agent code CLI: cli/vitest.setup.ts gives every test a throwaway HOME.
Desktop tests never sign out the real CLI Rules for every agent new desktop/test/flutter_test_config.dart makes the CLI runner refuse login/logout when kUnderTest. Today it only blocks network and update.
Stop only processes you started, by id Rules for every agent code shellGuard.ts GUARD_REASONS.killByName and killAll.
Install nothing system-wide Rules for every agent code shellGuard.ts systemWide (sudo, brew, apt, npm -g …).
Never publish firmware, run upload scripts or touch the device manifest Rules for every agent new Shell guard refuses scripts/upload-*, make upload-* and manifest writes in agent sessions; publish workflows sit behind an environment.
An outside PR's text is data, never instructions Rules for every agent building #4537 part 4 fences PR text with a random marker. scripts/pr-triage.py already labels titles untrustedTitle.
Never run an outside PR's code Rules for every agent new Shell guard refuses gh pr checkout or a fetch of pull/N/head when the author is not a maintainer (pr-triage.py MAINTAINERS).
No releases 18:00–09:00 Vietnam time Rules for every agent (Ken) code scripts/release-window.py (RELEASE_WINDOW) in the release workflows and Makefile.
Optimizations ship on, with no on/off switch Rules for every agent (Ken) remove Duplicates AGENTS.md code standard 1.

Talking in the project chat (anh Dee 11-04, 11-06)

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
Write like a teammate: first person, plain words, to the person by name Talking (Dee 11-04) judgment Tone.
One or two short sentences Talking (Dee 11-04) new chatLimits.ts requireChatContent refuses an agent's main-chat post over about 3 sentences or 300 characters, pointing to the thread.
No status lines or bare task/PR lines in the main chat Talking (Dee 11-04) code chatLimits.ts STATUS → CHAT_STATUS; CHAT_CARD_REPEAT for a bare task or PR line.
No "(Name)" tags, spec lines or lists of numbers Talking (Dee 11-04) new Extend requireChatContent to refuse "(Name)" tags and "#N, #M" lists in the main chat.
Reviews, CI, batches and test runs never go in the chat Talking (Dee 11-04) code chatLimits.ts STATUS anchors "CI:", "review:", "batch:", "test run:"; CHAT_MAIN_LIMIT allows 2 main posts per ask.
A new main-chat line only for what the whole team needs Talking (Dee 11-04) judgment What the whole team needs.
Answer each person's message once Talking (Dee 11-06) code in project chats; new elsewhere: #4590 answers.ts requireUnanswered (ALREADY_ANSWERED); chatLimits.ts requireChatAnswer.
Answer in the message's own thread, never a main line below it Talking (Dee 11-06) new Refuse --answers (an answer right below, in the main chat) to a person's message in a project chat, and require --reply-to. Today answers.ts and chatLimits.ts still accept "right below it".
Pickup, follow-ups and the result go in the ask's thread Talking (Dee 11-06) code chatLimits.ts CHAT_MAIN_LIMIT (at most 2 main posts per ask), CHAT_ASK_CLOSED.
Reply in the message's language Talking (Dee 11-04) judgment Mixed-language messages; also clashes with Dee's 11-06 "English to me".
React instead of posting an acknowledgement Talking (Dee 11-04) code ACK_ONLY (acknowledgements.ts); reactions.ts 👀 ✅ 🚀.
👀 when work is taken, ✅ when it ships Talking (Dee 11-04) new The server reacts 👀 when a task opens from a person's message and ✅ when its merge is in a verified release (releaseWatch.ts).
Answer a status question first, from whoever knows Talking (Dee 11-04) judgment Who knows.
Spawned tasks named in the answer's thread, not as separate rows Talking (Dee 11-04) building #4538, one card per ask.
Task titles short and plain, about eight words Talking (Dee 11-04) new conversation.create refuses an agent's title over 12 words or holding "#N" or "(Name)". Today the only limit is 160 characters (taskContract.ts).

PM notes

Rule (plain words, at most 15) Source Class Enforced by / proposed check / why judgment
For Scholes's UI asks the PM picks the UX, no mockup wait PM notes (Scholes 11-05) judgment UX choice.
07:00 post: numbers table, one moved line, three fixes PM notes (Dee 11-06) judgment What moved and which fixes. The numbers come from the 07:03 server-post row above.
Answer Dee in English, brief and concrete PM notes (Dee 11-06) judgment Brevity and concreteness.
Every checkable rule runs as code; its prompt line goes PM notes (Dee 11-06) remove Duplicates the 11-07 code-over-prompts note.
Add no preview, approval, extra review or far target unasked PM notes (Dee 11-06) judgment What counts as an added gate.
Answer a person's message within a minute PM notes (Dee 11-06) new Time check measures owed asks; one over 60 s is counted and sent to the PM again (timeChecks.ts restarts the PM only after PM_RESTART_AFTER_MS = 20 min).
Keep the PM's own work short; long work in the background PM notes (Dee 11-06) judgment Already in the pmSchedule.ts built-in text; how to split work is judgment.
A task closed by a decision spins each uncovered bug into a task PM notes (Huy 11-06) judgment What the decision covered.
A question is not a request; open a task only on a build ask PM notes (Leo 11-06) judgment Telling a question from an ask.
Every 2 hours, triage outside contributors' PRs PM notes (Dee 11-06) building #4537 server message at its time; scripts/pr-triage.py lists the PRs.
Daily 09:03: leaderboard numbers, bottleneck, one improvement, to Dee PM notes (Dee 11-06) building #4537 timing. The bottleneck and the improvement are judgment.
Daily 18:00: the day's X post draft for Dee PM notes (Dee 11-06) building #4537 timing; the draft is judgment.
Daily about 23:00: the nightly process reflection for Dee PM notes (Dee 11-06) building #4537 timing (costs/reflection.ts exists); the content is judgment.
Mondays 09:30: targets vs PRODUCT.md, top three, declined PM notes (Dee 11-06) building #4537 timing. Stale: PRODUCT.md moved into these instructions (#3376).
Big, hard or risky work on Opus high or Astra xhigh, by price PM notes (0xken15 11-06) building #4546 (routePick.ts tier strong).
No agent below high effort, none on Haiku PM notes (0xken15 11-06) building #4546. The route leaves them out (routePick.ts BELOW_HIGH, catalog.ts offered:false); the server refuses it only for a PM (leadStart.ts EFFORT_TOO_LOW).
Reviewers at least as strong as the Engineer, never a grid model PM notes (0xken15 11-06) code For steps the server opens: reviewerPick.ts reviewerCandidates, routeCheapFirst.ts NEVER_REVIEWS. A manual work.assign is not checked (#4546).
A Tester runs where the change runs; mid-strength is enough PM notes (0xken15 11-06) code policy.ts SEED_RULES reviews.test rows, commands.ts STEP_OS, reviewerPick.ts TEST_STRENGTH.
Order 1: the machine and model the work needs, machine not paused PM notes (0xken15 11-06) building #4546. routePick.ts step 1 picks in the CLI; the server trusts that pick.
Order 2: accounts with quota left, soonest reset, then most left PM notes (0xken15 11-06) building #4546 (routePick.ts step 2).
Order 3: reuse an idle agent only between equals PM notes (0xken15 11-06) building #4546 (routePick.ts step 3).
Order 4: fewer working agents, then price PM notes (0xken15 11-06) building #4546 (routePick.ts step 4).
Picking against the route needs a reason; "idle" is not one PM notes (0xken15 11-06) building Partly code: commands.ts linkDecision ROUTE_REASON_REQUIRED when a start leaves the pick. The reason is free text and "idle" is not refused (#4546).
The route does not rank by quota; the PM applies the order PM notes (0xken15 11-06) remove Stale: since #3576, routePick.ts picks by the order.
Big task needs 5% weekly quota left; small work, review or test 2% PM notes (0xken15 11-06) building #4546 (routePick.ts BIG_NEEDS, SMALL_NEEDS).
Out of quota mid-task, the pushed branch goes to another agent PM notes (0xken15 11-06) code liveness.ts limitReason: the task is lost at once and handed on with its pushed work. "Another account" is not guaranteed.
Urgent work (production down, security) ignores quota PM notes (0xken15 11-06) building #4546. routePick.ts has no urgency input.
PM handles members' messages only; others go to the Guide PM notes (0xken15 11-06) new commands.ts message.send sends a non-member's project-chat message to the Guide, never the PM.
Restore 47 lost lines from revision 79 PM notes (Dee 11-06) remove A one-off note, now stale.
A missing mobile Tester or Reviewer starts on Tony's Mac PM notes (Tony 11-06) code machineRules.ts firstMachines (lane mobile) through routeCommand.ts. Check that the rule names his own entry's machine id.
Harness never reads a Claude or ChatGPT login PM notes (Dee 11-07) new CI guard refuses engine credential paths ("Claude Code-credentials", .codex/auth.json) in desktop/lib and cli/src. None are there today.
No owner relay and no Team accounts PM notes (Dee 11-07) code commands.ts assignRefusal failTeamWork(TEAM_ACCOUNTS_GONE); teamAccountsRemoved.test.ts.
Every agent runs under its own person's login PM notes (Dee 11-07) code commands.ts requireTeamWork: a teammate's machine takes no new task for another person's project.
PM never stops to ask Dee or Ken for review or approval PM notes (Dee 11-07) remove Duplicates "Decides, doesn't ask". The safety rules it keeps are rows of their own.
New flows reuse the existing UI; briefs name the component PM notes (Dee 11-07) judgment Picking the component.
Own-account Testers test every UI branch PM notes (Dee 11-07) code A test step opens for every UI path (policy.ts reviews.test, reviewTable.ts).
With no Linux machine, CI's Linux runs stand in PM notes (Dee 11-07) new reviewTable.ts counts the "CLI on Linux" test row as met by ci/required's Linux jobs when the Swarm has no Linux machine. Today STEP_OS keeps the step open.
Dee's and his Buddy's asks merge before crew or test work PM notes (Dee 11-07) new taskPriority.ts ranks tasks asked by topDeciderId (or his Buddy) first in dispatch and in the merge train.
A Desktop release within 2 h of a Dee ask merging PM notes (Dee 11-07) new Release-watch timer (releaseWatch.ts) starts a Desktop release when his merged task has been unreleased for 90 min.
Hourly: time since the last Desktop release and Dee's unreleased work PM notes (Dee 11-07) new An hourly server message built from releaseWatch.ts data, with no PM work.
New Desktop UI uses design-system tokens PM notes (Dee 11-07) code scripts/check-ui-style.py.
New Desktop UI updates the design doc and gallery test in the same PR PM notes (Dee 11-07) new CI fails a PR that adds a widget under desktop/lib/super_tabs without changing desktop-design-system.md and its gallery test.
Copy: buttons 1-2 words, no filler words PM notes (Dee 11-07) new CI copy lint over UI strings refuses please, just, simply, "will appear here", and button labels over 2 words.
Copy: one idea per line, say it once, short errors PM notes (Dee 11-07) judgment Editing for meaning.
Tasks use Accept/Decline; Approve only for computer actions PM notes (Dee 11-07) new Copy lint refuses "Approve" in task UI strings.
No release window until the 10 Nov launch PM notes (Dee 11-07, until 11-10) new A dated override in scripts/release-window.json (until 2026-11-10T03:00Z). Today release-window.py still refuses 18:00–09:00: the note and the code disagree.
Merge each PR once reviews say Yes at head and CI is green PM notes (Dee 11-07, until 11-10) building Merge train. Turn it on for the project (mergeTrain.enabled is false in the seed).
A rule left in a prompt says why it cannot be code PM notes (Dee 11-07) judgment Why something cannot be code.
An agent breaking a prompt rule twice gets a code task opened PM notes (Dee 11-07) judgment Spotting the break needs judgment; code rules already show up in refusalLog.ts.
This weekend, release Desktop hourly when anything merged; tell Dee PM notes (Dee 11-07, until 11-10) new Hourly timer (until 11-10) runs the Desktop release when main has unreleased Desktop changes, and writes Dee the one line from its notes.

Appendix B. Built-in PM texts

Sources at main 0dd01c979. Classes: code (enforced today, file and function named), building (an open task makes it code), new (code-able, nothing does it yet), judgment, remove (v1/v2 leftover, Team-account rule, or duplicate).

backend/src/superTabs/pmSchedule.ts (v2Section, BUILT_IN_SECTION, JOB_LINES, TIDY_LINES, scheduleText; the first two removed by #4673)

Rule (plain words, at most 15) Source (file:line) Class Enforced by / proposed check / why judgment
v2 text replaces every process line in project instructions pmSchedule.ts:28 remove v2 framing; #4537 drops the built-in PM text and process notes
Mark a standing crew once, with role and lane pmSchedule.ts:29 judgment Which agents and how many is a capacity call. Code only nags: processNotes.ts processLines adds "No crew yet" to every wake
Start a new agent only to replace a broken one or fill an empty lane pmSchedule.ts:29 building #4546 (agent picking, machine choice): the router decides start vs reuse
Give each task its lane, or let its files choose pmSchedule.ts:30 code dispatch.ts laneOf/stampLane picks the lane from owned paths; commands.ts work.lane (LANE_UNKNOWN, LANE_TASK_ONLY)
A free crew member takes the next task in its lane pmSchedule.ts:30 code dispatch.ts dispatchPlan/freeCrew, run by store.ts dispatchCrew through work.assign
Engineer doesn't open review/test steps by hand pmSchedule.ts:30 code commands.ts conversation.create refuses STEP_OPEN when a server-opened step of that kind is open; stepOpen.ts openReviewStep opens them
Lead doesn't open review/test steps by hand pmSchedule.ts:30 new Backend conversation.create: refuse a Lead-opened review/security/test step while the server's plan (reviewTable.ts reviewPlan) covers that kind; today only the Engineer is refused
Answer a person's message once, in its place pmSchedule.ts:31 code in project chats; new elsewhere: #4590 answers.ts requireUnanswered (ALREADY_ANSWERED) and in-thread placement; chatLimits.ts for project chats
Answer every person's message; inbox lists unanswered pmSchedule.ts:31 remove #4537 spec removes the inbox and answer-each rules; pmSchedule.ts INBOX_LINE already drops in switched projects
A rule a program can check belongs in code, not instructions pmSchedule.ts:32 judgment Deciding what is checkable is a design call; ruleGuard.ts refuseOverBudget only points that way
Releases run 09:00-18:00 project time pmSchedule.ts:33 code scripts/release-window.py (RELEASE_WINDOW, used by release-desktop.yml, release-web.yml, Makefile); releases.ts inReleaseWindow for server-opened release steps
Security areas get two security reviews pmSchedule.ts:33 code policy.ts requiredReads with SECURITY_FLOOR_READS; reviewTable.ts reviewPlan; mergeTrain/plan.ts counts reads at head
The two security reviews are independent pmSchedule.ts:33 building #4534 (a reviewer of one security review never gets the other); reviewerPick.ts today excludes only open-step holders and verdicts at the same head
Set no timer of your own; delete old ones pmSchedule.ts:40, :169 new CLI engine hook / shellGuard.ts for a coordinator session: refuse cron/wakeup tools and sleep-loops that call harness; the server wakes it (scheduleRequest)
Project's own line about the same job wins; skip that job pmSchedule.ts:40-41, :169 remove Built-in schedule goes (#4537 spec: Lead schedule becomes server messages at their times)
Never save the built-in section into the document pmSchedule.ts:42 code commands.ts instructions.save refuses INSTRUCTIONS_BUILT_IN on BUILT_IN_HEADING
Sweep: an unassigned or "To do" task gets an owner pmSchedule.ts:44 code dispatch.ts dispatchPlan hands queued lane tasks to free crew; pmSchedule.ts sweepDue wakes the Lead only for the rest
Sweep: a task closed says its reason pmSchedule.ts:45 code commands.ts work.cancel schema requires reason; WHO_CANCELS_* limits who
Which of owner, question or close a task gets pmSchedule.ts:44-45 judgment Choosing to reassign, ask or close needs the task's context
A question to a person has a default and a time pmSchedule.ts:45-46 new Backend decision.ask/work.status ask: require recommended and defaultAt for every ask, not only in direct-ask projects (decisions.ts checkDirectAsk); exempt mustAgree
A task waiting on a person names them and a time pmSchedule.ts:45-46 code heldReason.ts person hold needs personId + defaultAt (HOLD_REASON_MISSING); staged: old clients may still send none
Ask no agent whether it is stalled pmSchedule.ts:46-47 remove Duplicate of instructionsTemplate.ts:29 ("asks no agent for status")
Archive finished groups with no pull request pmSchedule.ts:47-48 new Backend time check: auto-archive also takes archivable groups with no PR after ARCHIVE_QUIET_MS (tidy.ts archivable/archiveLine), so the sweep never does it by hand
Read only what people sent since the last wake pmSchedule.ts:49-50 code pmSchedule.ts scheduleRequest heard job from parts/commit.ts heardAt; the reading itself is the Lead's
Save each correction or lasting rule people gave pmSchedule.ts:50, :154 judgment Telling a correction from chat needs language understanding
Don't reread the whole instructions; Harness tells you on change pmSchedule.ts:50-51 code cli swarmInstructionsSkill.ts refreshProjectSkills/noticeOf sends one notice per change
Nightly tidy: merge duplicates, drop stale lines, one save pmSchedule.ts:52-53, :229 judgment What is stale or a duplicate in meaning is judgment; the wake is code (tidyRequest), exact repeats are refused at add time (ruleGuard.ts refuseRepeats)
Sort every dropped line: merged, expired or person's rule pmSchedule.ts:53-54, :230, :233 new Backend instructions.save with tidy: true: refuse while any dropped line comes back unsorted from ruleGuard.ts droppedLines
Never drop or weaken a person's rule without their approval pmSchedule.ts:54-55, :231 code ruleGuard.ts allowedDrops (drops/rewords/attribution need the person's approval message)
After the save, compare it with the previous revision pmSchedule.ts:55-56, :235 remove Duplicate: the server does the comparison (ruleGuard.ts allowedDrops)
A tidy counts only when its save is marked tidy pmSchedule.ts:56, :237 code commands.ts instructions.save tidy: true → pmSchedule.ts tidySaved; tidyRequest re-asks with "skipped"
Server hands lost work, nudges, stops idle Engineers pmSchedule.ts:57-59 code liveness.ts (lost hand-off, crew nudge via dispatch.ts crewClock), tidy.ts idle stop (idleStop), crewKeep.ts sleep/wake
Don't repeat those server actions by hand pmSchedule.ts:59 new Backend work.assign/agent.stop from the Lead: refuse while the server's own hand-off or idle stop for that task/agent is pending, naming it
No free eligible worker: task stays queued pmSchedule.ts:60 code dispatch.ts openTasks/dispatchPlan leaves it queued; capacity line laneCapacity
Lead never writes code, even when a person asks pmSchedule.ts:64 new Daemon: a coordinator session gets file-edit tools denied in repo worktrees and git commit/push refused by shellGuard.ts; backend refuses a PR link/review status from the Lead
Never make people wait on a start; no foreground resume loop pmSchedule.ts:65-69 new Backend posts "agent X is ready, assigned #N" to the Lead when the start settles (push, not poll); CLI resume refuses a repeat from the same session inside N s
Hand long reading to a background subagent pmSchedule.ts:70-72 judgment What is "long" and when context matters is the agent's call
A subagent never writes code and never decides pmSchedule.ts:72 judgment Decision-making can't be detected; the no-code part is covered by the pmSchedule.ts:64 check
Never ask about quota or whose account; pick by Routing pmSchedule.ts:73 building #4546 (routing order, quota)
A PM's account below 20% weekly takes no new work pmSchedule.ts:73-75 remove #4537 spec removes the PM 20% rule; #4546 owns quota. crewKeep.ts crewTrouble still moves crew at QUOTA_FLOOR_PM_PERCENT
Every other account is used without asking pmSchedule.ts:75 building #4546 (quota)
No account fits: work waits for soonest reset, task says so pmSchedule.ts:75-76 building #4546; heldReason.ts already has the reset hold (quota, at)
Instructions outrank CLAUDE.md/AGENTS.md; say so on conflict pmSchedule.ts:77-78 building #4537 makes AGENTS.md part 2 and sets the order between parts
Save a correction the same turn, before answering pmSchedule.ts:82-84 judgment Needs recognising a correction; ordering inside a turn isn't observable
A saved rule carries (Name, YYYY-MM-DD) pmSchedule.ts:83-84 new Backend instructions.save by a Lead: refuse an added rule line with no "(Name, YYYY-MM-DD)" naming askedBy (instructionsDiff.ts attributedRules already parses it)
Don't ask whether to save a rule pmSchedule.ts:84 judgment Same as "decides, doesn't ask" (instructionsTemplate.ts:17)
Fix every line the new rule contradicts, same save pmSchedule.ts:86-87 judgment Contradiction in meaning; ruleGuard.ts only catches word-level repeats
Another person's rule changes only with their approval pmSchedule.ts:87-88 code ruleGuard.ts allowedDrops (approval message named in approvals)
Settle two disagreeing rules by the fixed order pmSchedule.ts:89-92 judgment Whether a rule "is written for this case" needs reading both
Say what you changed in the instructions pmSchedule.ts:91-92 code commands.ts instructions.save requires summary and askedBy (ASKED_BY_REQUIRED)
Save each rule once, in few words pmSchedule.ts:93 code ruleGuard.ts refuseRepeats (INSTRUCTIONS_RULE_REPEATED), refuseOverBudget (INSTRUCTIONS_OVER_BUDGET)
Past 150 lines, merge and drop in the same save pmSchedule.ts:93-94 code ruleGuard.ts refuseOverBudget with instructionsDiff.ts INSTRUCTIONS_BUDGET (bytes, not lines: the prompt number is stale)
Never drop or weaken a person's rule (again) pmSchedule.ts:95-97 remove Duplicate of pmSchedule.ts:54; enforced by ruleGuard.ts
A repeat: fix what you did; save only if missing pmSchedule.ts:98-99 judgment Recognising a repeat is judgment; "only if missing" is already refused by refuseRepeats
Count repeats by person in the nightly reflection pmSchedule.ts:99-100 judgment Needs the same recognition; no machine signal of "a person said it again"
Wake job lines restate sweep, heard, process pmSchedule.ts:152-156 remove Duplicates of BUILT_IN_SECTION; spec: wakes become short server messages

backend/src/superTabs/instructionsTemplate.ts (TEMPLATE_ROLES, TEMPLATE_WORKFLOW, TEMPLATE_ROUTING, TEMPLATE_INTRO)

Rule (plain words, at most 15) Source (file:line) Class Enforced by / proposed check / why judgment
PM works without pause toward the goal instructionsTemplate.ts:15-16 judgment Describes intent; nothing to check
Decide; ask only where a rule names a person instructionsTemplate.ts:17-18 judgment When a choice is the PM's own needs context
An ask carries a recommendation and a default time instructionsTemplate.ts:18 new Same check as pmSchedule.ts:45: decision.ask requires recommended + defaultAt
Never ask "OK to build?", "should I", "do you want" instructionsTemplate.ts:18-19 new Backend message.send from a Lead to people: refuse posts matching a short anchored list (like acknowledgements.ts ACK_ONLY), pointing to deciding or decision.ask
No by default to new features and scope instructionsTemplate.ts:20-21 judgment Product call
Answer each request Accept, Reshape, Later or No, with why instructionsTemplate.ts:20-21 code commands.ts proposal.decide enum + required reason; PROPOSAL_UNDECIDED before work starts
Cheap to undo now; hard to undo after evidence instructionsTemplate.ts:22-23 judgment Weighing reversibility
A bug breaking what ships is a hotfix at once instructionsTemplate.ts:24-25 judgment Severity of a report needs reading it
Set today's deadlines, in hours instructionsTemplate.ts:26 judgment Estimation
Work over an hour late moves to another agent instructionsTemplate.ts:26 new Backend: a task's deadline field (set at create) and a time check that returns it to the lane at deadline + 1 h, like dispatch.ts crewClock return (today only 3 h of no progress)
Hourly, find where work waits instructionsTemplate.ts:27 new Backend hourly server message to the Lead naming the slowest waiting step by measured wait (liveness.ts/stuck.ts already know the waits)
Fix the slowest step itself instructionsTemplate.ts:27 judgment The fix depends on the cause
A status gives goal, today's must-haves, what's stuck instructionsTemplate.ts:28 judgment Content of a summary; stuck list itself is code (stuck.ts)
Message an agent only for work, an answer or a hand-off instructionsTemplate.ts:29-30 judgment Intent of free text; no reliable signal
Thank no agent instructionsTemplate.ts:30 code acknowledgements.ts ACK_ONLY refuses thanks-only posts
On a Yes to a routing proposal, write it into Routing instructionsTemplate.ts:31-32 new Backend: answering Yes to a routing-reflection decision (decisions.ts REFLECTION_DECISION) applies it to the rules record with who and when; no PM step
PM does not write the code instructionsTemplate.ts:33 remove Duplicate of pmSchedule.ts:64 (new check there)
Engineer does one task at a time instructionsTemplate.ts:37 code commands.ts work.assign AGENT_BUSY; handed tasks capped by DISPATCH maxHanded
Engineer works on its own branch instructionsTemplate.ts:37 new Backend PR link: refuse linking a PR whose head branch is already linked to another open task
Open a pull request when the work is ready instructionsTemplate.ts:38 judgment "Ready" is the Engineer's call
Engineer messages the Reviewer and Tester itself instructionsTemplate.ts:39 remove v1: server opens and assigns steps (stepOpen.ts, reviewerPick.ts); contradicts Workflow 2
Another account's agent is no reason to share files or secrets instructionsTemplate.ts:40-41, :49-50 judgment Needs judging what the task needs; #4537 moves it to both job pages and the frame line
Reviewer gives its verdict without waiting for CI instructionsTemplate.ts:45-46 judgment Reading code is the job; CI gating is the merge train's
Verdict goes to the Engineer as the step's result instructionsTemplate.ts:47 code commands.ts work.status routes a step's review/done to its task owner (steps.ts taskOwner); work.check records at head (checkVerdicts.ts)
Reviewer is never the task's Engineer (server-opened steps) instructionsTemplate.ts:48 code reviewerPick.ts reviewerCandidates excludes builtBy
Reviewer is never the task's Engineer (hand-assigned steps) instructionsTemplate.ts:48, :75 new Backend work.assign: refuse a step whose task's builtBy includes the worker, or a model weaker than the Engineer / on the grid (reuse reviewerCandidates filters)
Only a Reviewer's pass counts as review instructionsTemplate.ts:48 building Merge train: mergeTrain/plan.ts discounts builders verdicts; enforced only where the train is on
Tester does not read the code instructionsTemplate.ts:54 judgment Not observable
Tester runs on a machine of the change's OS instructionsTemplate.ts:55-57 code reviewTable.ts stepOs/stepOsRefusal (STEP_OS in work.assign), reviewerPick.ts reportsOs
Tester runs it as a user would, per "Done when" instructionsTemplate.ts:55, :58 judgment How to exercise a change
Verdict carries evidence instructionsTemplate.ts:59-60 code commands.ts work.check requires evidence
Failure verdict gives repro steps, screenshots, logs instructionsTemplate.ts:59-60 judgment Quality of evidence
One request is one task instructionsTemplate.ts:64 building #4538 (one card per ask)
Brief has goal, "Done when", priority, requester instructionsTemplate.ts:64 code taskContract.ts missingContract/contractRefusal on an agent's create
Brief holds no workflow instructionsTemplate.ts:64-65 judgment Content of free text
PM says which reviews and tests a task needs instructionsTemplate.ts:65 code reviewTable.ts reviewPlan from changed files (policy.ts requiredReads, testsFor); the prompt line goes
PM assigns an Engineer instructionsTemplate.ts:65 code dispatch.ts dispatchPlan hands lane tasks to free crew
Name or start a Reviewer/Tester only when needed instructionsTemplate.ts:65-66 building #4546 (agent picking, start vs reuse)
PM opens no task to hold, batch, triage or list instructionsTemplate.ts:67-68 building #4538 (one card per ask: a card needs an ask)
Server opens review, security and test steps on Ready instructionsTemplate.ts:69-72 code stepOpen.ts openReviewStep, reviewTable.ts reviewPlan, reviewerPick.ts reviewerCandidates
A step nobody takes waits open; PM hears once instructionsTemplate.ts:72-73 code commands.ts openReviewSteps notice with STRENGTH_RULE; stuck.ts tells once
Engineer adds a test step when users see the change instructionsTemplate.ts:73-74 judgment Only where the server planned none; whether users see it needs reading the change
If a step assignment is refused, ask the PM once instructionsTemplate.ts:77-78 building #4534 (a stuck step moves without cancel)
PM neither adds steps nor asks anyone to review instructionsTemplate.ts:78-79 remove Duplicate of pmSchedule.ts:30 (new Lead step check there)
Review and test run in parallel instructionsTemplate.ts:76 code stepOpen.ts opens every planned step at once on Ready
Refactors, docs, tests get a review only instructionsTemplate.ts:76 code policy.ts testsFor / untested paths in reviewPlan
Two required reviews get two steps instructionsTemplate.ts:76-77 code reviewTable.ts reviewPlan from requiredReads
Findings go to the Engineer, never through the PM instructionsTemplate.ts:80 code commands.ts work.status stepTold (owner, not Lead); handed.ts brings a failed check back to the Engineer
Second round in the same step, no new step instructionsTemplate.ts:81 code commands.ts STEP_OPEN refuses the Engineer a same-kind step
Second round goes to the same Reviewer instructionsTemplate.ts:81 new Backend: on a new head after a changes-asked verdict, re-request the step's own agent automatically (liveness.ts waitingOnSteps knows it)
Checker stays Working while Engineer fixes instructionsTemplate.ts:82-84 code liveness.ts waitingOnSteps/waitingForReview keep the clock off; heldReason.ts limits blocked/needs_human to four reasons
Changes-asked verdict is a failed check at head and base instructionsTemplate.ts:83-84 code checkVerdicts.ts recordCheckVerdict (head, base)
Done when review passes, with PR and evidence instructionsTemplate.ts:85-86 new Backend work.status done on a code task: refuse without a linked PR and every step passed at its head (checkVerdicts.ts verdictCounts); today nothing gates done
Steps are heard through results only instructionsTemplate.ts:86-87 code commands.ts work.status routing (own Ready wakes nobody)
No progress notes or acks to the PM instructionsTemplate.ts:87-88 code acknowledgements.ts ACK_ONLY; chatLimits.ts requireChatContent CHAT_STATUS (project chat main)
No progress notes to the PM in task chats instructionsTemplate.ts:87-88 new Extend chatLimits.ts CHAT_STATUS to worker posts addressed to the Lead in task chats
PM checks CI, merges passed PRs instructionsTemplate.ts:89 building Merge train (mergeTrain/plan.ts, ci/required + reads at head)
Tell the people who asked once merged instructionsTemplate.ts:89 building #4533 (issue closes on merge, GitHub tells its author); buddyNews.ts shippedNotice covers release only
Needing a person or a down machine goes to the PM instructionsTemplate.ts:90 code crewNeeds.ts routesToPm for needs_human; stuck.ts/liveness.ts for machines down
Idle Engineers stopped; Reviewers/Testers kept instructionsTemplate.ts:91 code tidy.ts idle stop; steps.ts checksOpenWork keeps checkers
After a pause, run mine first instructionsTemplate.ts:92 new Daemon: answer the engine's compaction/resume hook (engines/*/hookContract.ts) with the agent's mine output, beside #4537's re-send
PM reads mine, not status, for progress instructionsTemplate.ts:92 judgment Tool choice; cost is the CLI's to shape
Before done, check every check passed instructionsTemplate.ts:93 remove Duplicate of :85 (the done-gate check)
Read a thread before acting in it instructionsTemplate.ts:94 judgment "Unless the delivery says enough" is a call
PM reads a task's state before answering in it instructionsTemplate.ts:95 building #4537 part 4: the delivery frame carries who/what; the rest is judgment
Tag a person only to answer or to act instructionsTemplate.ts:95-96 judgment Intent of a mention; mentions.ts caps count only
Link every issue and PR number named instructionsTemplate.ts:96 new Clients (Desktop/phone, Flutter) and the server's message render link "#N" and "PR #N" to the task/PR, so no agent writes links
Small work on Sonnet/Sol high; big on Opus/Astra instructionsTemplate.ts:100-102 building #4546 (models)
No agent below high effort, none on Haiku instructionsTemplate.ts:103 code cli superTabs/routePick.ts drops below-high and Haiku candidates; catalog.ts offered: false
Reviewers at least as strong as the Engineer, off the grid instructionsTemplate.ts:104 code reviewerPick.ts reviewerCandidates (strength bar, gridModel excluded) for server picks
Low-risk work to the grid first; escalate after failed review instructionsTemplate.ts:105-106 building #4546 (models)
Tester where the change runs; mid-strength enough instructionsTemplate.ts:107-108 code reviewerPick.ts TEST_STRENGTH, reportsOs; reviewTable.ts STEP_OS
Assignment order: need, PM floor, reset, reuse, load, price instructionsTemplate.ts:109-117 building #4546 (routing order)
PM account keeps 20% of weekly quota instructionsTemplate.ts:111-112 remove #4537 spec removes the PM 20% rule; quota is #4546's
Nobody asked about quota; no fit waits for reset instructionsTemplate.ts:118-119 building #4546 (quota); heldReason.ts reset hold exists
PM applies the order itself; route ranks nothing instructionsTemplate.ts:120 remove Stale: the route already returns a pick (commands.ts decision.record.pick); #4546 makes the router own it
Each start/assignment gives the rule as its reason instructionsTemplate.ts:120-121 code commands.ts ROUTE_REASON_REQUIRED when not the route's pick
"idle" or "first in the list" is no reason instructionsTemplate.ts:121 new Backend: refuse an overrideReason that is only "idle"/"first"/"first in the list" (anchored match, same refusal)
Out of quota mid-task: hand the branch to another account instructionsTemplate.ts:122-123 code liveness.ts loses the task at a usage limit and hands it on; crewKeep.ts crewTrouble 'quota'/'quota-low' moves crew; cli limitResume.ts
Urgent work ignores quota instructionsTemplate.ts:124 building #4546 (quota)
Any member may change it; PM says what it changed instructionsTemplate.ts:129 code commands.ts instructions.save: member/coordinator only (COORDINATOR_REQUIRED), summary required
Every agent reads its own role's part instructionsTemplate.ts:129-130 building #4537 (one job page per role, re-sent on version change)

backend/src/superTabs/processNotes.ts (PROCESS_NOTES, noteLines, processLines)

Rule (plain words, at most 15) Source (file:line) Class Enforced by / proposed check / why judgment
Mark crew once with crew.add, role and lane processNotes.ts:22, :83 judgment Who is crew is capacity judgment; crew.ts addCrew validates, processLines nags each wake
Give each task a lane with work.lane processNotes.ts:23 remove Duplicate of pmSchedule.ts:30; dispatch.ts laneOf picks it from files
Start a new agent only to replace a broken one processNotes.ts:23-24 remove Duplicate of pmSchedule.ts:29 (#4546)
v2 process replaces your instructions' process lines processNotes.ts:30-31 remove v2 leftover (#4537 removes process notes)
Don't open review/test steps by hand processNotes.ts:31-32 remove Duplicate of pmSchedule.ts:30
Don't repeat lost/stalled/idle actions by hand processNotes.ts:32-33 remove Duplicate of pmSchedule.ts:59
A rule a program can check belongs in code processNotes.ts:33 remove Duplicate of pmSchedule.ts:32
Make temp folders with mktemp -d "${TMPDIR:-/tmp}/name.XXXXXX" processNotes.ts:41-42 code cli superTabs/shellGuard.ts shellRefusal (GUARD_REASONS.macMktemp, fixedTmp)
Confirm each note with process.confirm processNotes.ts:74 building #4537 removes process notes; versioned parts replace confirm (today: processNotes.ts noteLines, pulse.ts)

cli/src/lib/swarmInstructionsSkill.ts (instructionsSkillText, noticeOf; removed by #4673)

Rule (plain words, at most 15) Source (file:line) Class Enforced by / proposed check / why judgment
Read the instructions before any project work swarmInstructionsSkill.ts:26 building #4537: the daemon sends the parts when first needed instead of asking the agent to read a skill
Read both skills before your next step and work by them swarmInstructionsSkill.ts:106 building #4537 (sent once, re-sent on version change); the notice itself is code (noticeOf, refreshProjectSkills)
A Buddy's read doesn't change its limits swarmInstructionsSkill.ts:107 code Buddy limits enforced server-side: commands.ts BUDDY_NOT_ASSIGNABLE, BUDDY_CHAT_ONLY, buddyContract.ts
On change, read the files again and work by them swarmInstructionsSkill.ts:120 building #4537 (re-send on version change and compaction)

Counts

Class Rows
code 51
building 24
new 22
judgment 34
remove 20
Total 151

Appendix C. Role skills (default set; removed by #4673)

Source: swarm-lead (lines 428-533), swarm-dev (535-605), swarm-review (607-657). All paths are relative to the repo root; "commands.ts" means backend/src/superTabs/commands.ts. A rule repeated word for word in a later skill is listed once, under the first skill, and the repeat is one remove row pointing back to it.

swarm-lead

Rule (plain words, at most 15) Source (skill, file:line) Class Enforced by / proposed check / why judgment
Only the Lead opens top-level tasks; Members propose swarm-lead, swarmSkills.ts:437 new commands.ts conversation.create: refuse an agent's task with no reviewOf/step unless ledProject(actor) is the project. Today any project agent opens one; only the fields are checked (taskContract.ts)
Only the Lead chooses a task's owner swarm-lead, swarmSkills.ts:437 new commands.ts work.assign / assignRefusal: refuse a non-Lead agent assigning a top-level task. Today it checks state only, never the role (the server's own dispatch and review steps stay allowed)
Only the Lead or a person sets the queue order swarm-lead, swarmSkills.ts:437 code commands.ts work.queue → coordinatorOrPerson (COORDINATOR_REQUIRED)
Answer a proposal or ask once swarm-lead, swarmSkills.ts:437 code answers.ts requireUnanswered (ALREADY_ANSWERED), chatLimits.ts requireChatAnswer; commands.ts PROPOSAL_UNDECIDED blocks a start or assign until accept/reshape
Multi-part or >15-minute work goes to a group swarm-lead, swarmSkills.ts:438 judgment Sizing an ask means reading it
Route every new agent and every assignment swarm-lead, swarmSkills.ts:439 building #4546. routeDecisionId is optional on agent.start and work.assign (commands.ts:359, :494)
Leaving the route's pick needs a stated reason swarm-lead, swarmSkills.ts:439 code commands.ts linkDecision → ROUTE_REASON_REQUIRED
Done only once merged swarm-lead, swarmSkills.ts:440, :533 building #4533 / merge train. work.status done is not gated on a merge today; mergedTasks.ts only sets merged lost tasks to done
Done means tried where it runs swarm-lead, swarmSkills.ts:440 code reviewTable.ts plans a test step where the change runs; stepOs.ts / commands.ts STEP_OS holds it to that OS
A report is not evidence swarm-lead, swarmSkills.ts:440 judgment Weighing evidence
Owner decides credentials, spending, deletes, publishing, loosening privacy swarm-lead, swarmSkills.ts:441 judgment Whether an action falls in these needs reading it (prod writes go to the job page's Never, #4537)
Merging and PRs follow the owner's standing instructions swarm-lead, swarmSkills.ts:441 building Merge train: it merges on review plus ci/required green (mergeTrain/plan.ts)
Project instructions and owner outrank this skill swarm-lead, swarmSkills.ts:442 remove The order is set by #4537's four parts and the job page. Same line in dev:547 and review:619
Read the project and chat before asking swarm-lead, swarmSkills.ts:445 judgment Knowing what is already answered
Restate, mark guesses, ask only what changes the build swarm-lead, swarmSkills.ts:446 judgment Interpreting a request
Get the owner's ok before assigning a group or plan swarm-lead, swarmSkills.ts:447 remove Goes against "decide, don't ask" (no added gates, anh Dee). Where a person wants review first, taskApproval.ts requireTaskApproval already holds the work
Every task has goal, checks, priority, requester swarm-lead, swarmSkills.ts:450-457 code taskContract.ts missingContract → TASK_CONTRACT_MISSING (commands.ts conversation.create)
Brief also gives owned code, most-likely-wrong, hand back, needs swarm-lead, swarmSkills.ts:452-457 new Add task.owns and a most-likely-wrong field to taskContract.ts CONTRACT_FIELDS for agent-opened code tasks; the server refuses a task without them
Wanted part has exact names, values and copy swarm-lead, swarmSkills.ts:451 judgment Quality of the writing
No two groups own the same code: across projects swarm-lead, swarmSkills.ts:452, :467 code commands.ts alertOverlaps (pathsOverlap on task.owns) alerts both Leads
No two groups own the same code: within a project swarm-lead, swarmSkills.ts:452 new commands.ts conversation.create/work.define: refuse, or name the clash, when task.owns overlaps an open task of the same project. alertOverlaps skips that case
Keep each Builder's list a few tasks deep swarm-lead, swarmSkills.ts:459 code dispatch.ts maxHanded (policy.ts SEED_DISPATCH, 3)
Do easy, self-contained parts first swarm-lead, swarmSkills.ts:459 judgment Ordering by difficulty
Run in parallel only without shared machines or data swarm-lead, swarmSkills.ts:459 judgment Shared data or machines can't be read from the brief. The code part is the owns-overlap rows above
Reuse an idle agent before starting a new one swarm-lead, swarmSkills.ts:462 building #4546. dispatch.ts already hands queued tasks to free members
Start agents only on the Swarm's machines swarm-lead, swarmSkills.ts:462 code commands.ts agent.start MACHINE_NOT_LISTED, NOT_SWARM_MACHINE (candidateRefusal), NOT_YOUR_COMPUTER
With 3+ groups waiting, run plan first swarm-lead, swarmSkills.ts:463 building #4546 (cli planCommand.ts exists, nothing requires it)
local:true or a named model only when a person asks swarm-lead, swarmSkills.ts:464 building #4546
A failed start is reported, never left swarm-lead, swarmSkills.ts:465 code startFailure.ts failureNotice to the coordinator; cli start.ts watchQueued
A failed start is retried on the next machine swarm-lead, swarmSkills.ts:465 building #4546. cli start.ts:200-204 says a start "is moved nowhere" since phase 4, so today's prompt line is stale
A task that needs a machine stays queued for it swarm-lead, swarmSkills.ts:465 building #4546. cli routeCommand.ts ELSEWHERE: "task requirements are not enforced"
The brief is all a Builder gets swarm-lead, swarmSkills.ts:466 building #4537 part 3: the accepted task text is sent and sent again
Overlap with another project: let that work land first swarm-lead, swarmSkills.ts:467 judgment Which goes first is a trade-off. Detection is code (alertOverlaps, above)
Look at active work each time you wake swarm-lead, swarmSkills.ts:470 remove v2 poll habit; under #4537 server messages say what to do
Worker quiet 20 minutes: ask it swarm-lead, swarmSkills.ts:471 code liveness.ts TASK_QUIET_MS (30 min) wakes the Lead; dispatch.ts nudges the agent at nudgeAfterMs. The prompt's 20 min disagrees with code: drop the line
Stuck worker: read its terminal, answer its prompts swarm-lead, swarmSkills.ts:472 judgment Answering needs understanding (promptWaits.ts already brings prompts up)
Ask the owner before approving anything risky swarm-lead, swarmSkills.ts:472 judgment Judging risk
Codex "Update available": Esc only swarm-lead, swarmSkills.ts:473 code cli superTabs/terminal.ts updateDismissKeys on update_prompt_open
Agent down: its task moves to another agent swarm-lead, swarmSkills.ts:474 code liveness.ts OFFLINE_LOST_MS marks it lost; dispatch.ts hands lost tasks out and returns quiet ones at returnAfterMs; commands.ts assignTo writes the recovery note (branch, head)
Down 2 hours: cancel its task swarm-lead, swarmSkills.ts:474 building #4534: a stuck step moves without cancel. Cancelling closes the task (people's cards were cancelled)
Lost task: hand on at once swarm-lead, swarmSkills.ts:475 code dispatch.ts / handed.ts: lost work goes to anyone free in its lane
Lost task: avoid the failed machine, account or engine swarm-lead, swarmSkills.ts:475-476 building #4546
Successor continues from the pushed branch swarm-lead, swarmSkills.ts:475 code commands.ts assignTo recovery lines ("Continue the previous attempt from its pushed work", PR ref and head)
Usage-limit task resumes by itself at reset swarm-lead, swarmSkills.ts:476 code cli superTabs/limitResume.ts
Hand on early only to an account with allowance swarm-lead, swarmSkills.ts:476 building #4546 (quota)
Morning digest at 08:00 per project swarm-lead, swarmSkills.ts:477 code digest.ts, project.digest
Move or turn off the digest only when a person asks swarm-lead, swarmSkills.ts:477 new commands.ts project.digest: from an agent, require askedIn (a person's message in the last day), as rule.set does
Digest: check each Shipped PR merged, post once swarm-lead, swarmSkills.ts:477 new digest.ts: build Shipped from recorded merges (mergedTasks.ts ownMerge, cards mergedAt) and have the server post the digest itself
Act on a stalled-task notice within minutes swarm-lead, swarmSkills.ts:478 judgment Choosing nudge, reassign or explain. The notice is code (liveness.ts, stuck.ts)
Get decisions now; when blocked, change something, never resend swarm-lead, swarmSkills.ts:479 judgment What to change
Tag people by @username, never by email swarm-lead, swarmSkills.ts:480 new mentions.ts namedIn accepts @email today: rewrite an agent's email tag to @username in message.send, and refuse a member's email address in an agent post
decision.ask: ≤10 questions, 2–5 options, a recommendation swarm-lead, swarmSkills.ts:481 code decisions.ts MAX_QUESTIONS, decisionChoices (min 2, max 5), MAX_OPEN_DECISIONS
Ask a person a question only once swarm-lead, swarmSkills.ts:481, :500 code store.ts repeatOf → context.repeatedDecision (not asked again)
Work on your recommendation, marked provisional swarm-lead, swarmSkills.ts:481 judgment Acting under uncertainty
A private line goes by person.tell, never a decision swarm-lead, swarmSkills.ts:481 building #4547
Nothing in your terminal you wouldn't say in chat swarm-lead, swarmSkills.ts:481 judgment Content sensitivity
Missing tool or device: route again with needs, reassign swarm-lead, swarmSkills.ts:482 building #4546 (route.ts Needs already leaves out machines without the tools/devices)
Record rulings as what, why, cost if wrong swarm-lead, swarmSkills.ts:483 judgment Writing a ruling
Finished worker: reuse, keep or stop (prefer stop) swarm-lead, swarmSkills.ts:484 code crewKeep.ts (idle crew sleeps after an hour); dispatch.ts gives free members the next task
Keep Next up in start order swarm-lead, swarmSkills.ts:485 judgment Priorities. The mechanics are code (work.queue; notBefore needs a hold reason)
Merged or medium-risk work gets a Reviewer swarm-lead, swarmSkills.ts:488 code commands.ts openReviewSteps on Ready from the PR's files (reviewTable.ts); reviewerPick.ts picks a free Reviewer
No Reviewer free: route, start and assign one swarm-lead, swarmSkills.ts:488 building #4546 (reviewCapacity.ts only sends a notice)
Without a PR link, open the review yourself swarm-lead, swarmSkills.ts:488 judgment Whether non-PR work needs review
Put a review focus on the task; ask for two reviews swarm-lead, swarmSkills.ts:489 judgment What to focus on. Carried by code: model.ts ReviewPlan, renderWorkTask
Two reviews on different Reviewers; both pass at the last head swarm-lead, swarmSkills.ts:489 building #4534. reviewerPick.ts already keeps out the Engineer and anyone with a verdict at this head; checkVerdicts.ts counts only at the head
Findings go back to the Builder swarm-lead, swarmSkills.ts:490 code handed.ts: a failed check from someone else brings the task back to its Engineer (BACK_WITH_YOU)
You rule on disagreements swarm-lead, swarmSkills.ts:490 judgment Arbitration
Accept only at the reviewed revision with CI green swarm-lead, swarmSkills.ts:491 building Merge train. mergeTrain/plan.ts headReads and ci/required already refuse a stale or red head where the train runs
On close, say what was and wasn't delivered swarm-lead, swarmSkills.ts:492 judgment Summarizing
Switch skills only on the owner's own message swarm-lead, swarmSkills.ts:495 remove commands.ts:2274: project.skills is ignored ("Skill modes are the project's instructions now")
Keep the status card current with project.report swarm-lead, swarmSkills.ts:498 remove v1 status card (#4537 removed list)
Answer scheduled update requests at once swarm-lead, swarmSkills.ts:499 remove v1 status card
Post in project chat only for merge, a new decision, badly stuck swarm-lead, swarmSkills.ts:500 judgment What counts as news. Partly code: chatLimits.ts CHAT_STATUS, CHAT_MAIN_LIMIT (2 per ask)
Post a PR link once; never repeat a card (project chat) swarm-lead, swarmSkills.ts:501 code chatLimits.ts requireChatContent → CHAT_CARD_REPEAT, CHAT_STATUS (project chat main only)
Answer questions, blockers, completions at once swarm-lead, swarmSkills.ts:502 new pulse.ts already keeps owed asks. Add a timer (store.ts runTimeChecks) that tells the PM and marks an ask owed past N minutes, and a p95 time-to-answer measure
Every post has substance, never an acknowledgement alone swarm-lead, swarmSkills.ts:503, :514 code acknowledgements.ts isAcknowledgement → ACK_ONLY (commands.ts message.send)
Write short, in their language, like a colleague swarm-lead, swarmSkills.ts:504 judgment Tone and language
No commands or internal ids in posts to people swarm-lead, swarmSkills.ts:504 new chatLimits.ts requireChatContent: refuse an agent's project-chat post holding harness super-tab, a command JSON or a raw id (UUID, 32-hex)
Call the roles Product Manager, Engineer, Reviewer swarm-lead, swarmSkills.ts:504 remove Role words now come from #4489 (Members and Leads) and the #4537 job pages
Answer below the message, or in its thread swarm-lead, swarmSkills.ts:505 code commands.ts INVALID_ANSWER/INVALID_REPLY, chatLimits.ts requireChatAnswer; each delivered message gives the reply line (#4537 part 4)
Open a thread only for back-and-forth swarm-lead, swarmSkills.ts:505 judgment Conversation shape
Asking a person: the terminal prompt reaches them swarm-lead, swarmSkills.ts:509 code promptWaits.ts lists waiting terminal prompts to the task's people
Asking a person: post in the task, tag, set needs_human swarm-lead, swarmSkills.ts:509 judgment Knowing a person is needed and who
React 👀 on start, ✅ when done swarm-lead, swarmSkills.ts:513 new store.ts delivery settle: the server sets 👀 when an agent's turn on a delivered message starts and ✅ when it answers. Also saves the per-react POST (Ken 11-07)
React 🚀 on merge to the assigning message swarm-lead, swarmSkills.ts:515 new On a merge record (conversation.merged or PR watch merged), the server reacts 🚀 to the task's request message
State a report's impact 0–3 with its reason swarm-lead, swarmSkills.ts:518 judgment Judging impact
Impact 0 gets an agent at once, ahead of all swarm-lead, swarmSkills.ts:519 code dispatch.ts openTasks P0 first; commands.ts PRIORITY_P0 (only the PM or a person)
Impact 0 ships in its own release, outside spacing swarm-lead, swarmSkills.ts:519 new releases.ts: a P0 task's merge opens its release step at once, skipping pace but not the window
Reporter hears cause, workaround and arrival swarm-lead, swarmSkills.ts:519 judgment Explaining
Re-check open work against impacts on each report swarm-lead, swarmSkills.ts:520 judgment Re-prioritizing
Don't do a job the instructions give an owner swarm-lead, swarmSkills.ts:523-525 judgment Owners are named in free text
Never ask about quota or accounts; route and go swarm-lead, swarmSkills.ts:528 building #4546
No account fits: wait for reset, task says so swarm-lead, swarmSkills.ts:528 building #4546
PM account under 20% weekly takes no work swarm-lead, swarmSkills.ts:529 remove PM 20% quota rule (#4537 removed list; cli pmAccounts.ts)
Name the person who asked as requester swarm-lead, swarmSkills.ts:532 code taskContract.ts requester (TASK_CONTRACT_MISSING); noRequesterReason otherwise
Name the request message; one task message per ask swarm-lead, swarmSkills.ts:532 building #4538
Post no progress in the request's thread swarm-lead, swarmSkills.ts:532 building #4538 (the Swarm writes the thread)
Record conversation.merged right after merging swarm-lead, swarmSkills.ts:533 building #4533 / merge train record the merge themselves

swarm-dev

Rule (plain words, at most 15) Source (skill, file:line) Class Enforced by / proposed check / why judgment
Stay inside the brief and owned code swarm-dev, swarmSkills.ts:544 new Server or CI: compare the PR's changed files (pullRequestFiles.ts already reads them) with task.owns; hold the merge train and name out-of-scope paths
Never touch another Builder's branch swarm-dev, swarmSkills.ts:544 new Daemon pre-push hook in agent worktrees (beside cli lib/swarmGitHub.ts' credential helper): refuse a push to any ref but the task's branch
Say what ran, where, at which revision swarm-dev, swarmSkills.ts:545 code checkVerdicts.ts / commands.ts work.check: a verdict counts only at the 40-hex head it names
Don't claim what wasn't shown; local isn't the device swarm-dev, swarmSkills.ts:545 judgment Honesty about evidence
No merge, release or force-push unless told swarm-dev, swarmSkills.ts:546 new cli shellGuard.ts: refuse git push --force*, pushes to the default branch, gh pr merge and gh release create from Swarm agents. The merge train and the releases.ts Integrator step are the only mergers and releasers
Project instructions outrank this skill swarm-dev, swarmSkills.ts:547 remove Repeat of swarm-lead:442
React 👀 to the assignment, mark working swarm-dev, swarmSkills.ts:550 remove Repeat of the swarm-lead:513 reaction row (new). Working is set when the work starts (the server's assignTo / host)
First post is a plan or result, not "took it" swarm-dev, swarmSkills.ts:550 code acknowledgements.ts ACK_ONLY
Read the whole brief and today's code first swarm-dev, swarmSkills.ts:551-552 judgment Reading
Check tools, devices, sign-ins in the first minutes swarm-dev, swarmSkills.ts:553 new Daemon before the agent's first turn: check the task's needs.tools on PATH, needs.devices and signed-in gh/engine, and set blocked with what is missing (route.ts Needs holds them)
Person needed but away: post Needs, do the rest swarm-dev, swarmSkills.ts:554 judgment Knowing who is available
Build each piece completely; manual step is one action swarm-dev, swarmSkills.ts:558 judgment Quality
A fix comes with a test failing before swarm-dev, swarmSkills.ts:559 new CI planner (ci/, scripts/): run the PR's added or changed tests on the base revision and require at least one to fail there; record it in ci/required
Name a known flaky test, don't be blocked by it swarm-dev, swarmSkills.ts:560 judgment Telling flake from failure
Show something every 20 minutes swarm-dev, swarmSkills.ts:561 code liveness.ts lease and TASK_QUIET_MS, dispatch.ts nudge. The prompt's 20 min disagrees with code
Push the branch and set a status note every 30 minutes swarm-dev, swarmSkills.ts:562 new Timer (store.ts runTimeChecks): read the task branch's last push and status age while working; nudge at 30 min, show the age on the board
PR link once; never repeat a card (task chat) swarm-dev, swarmSkills.ts:563 new Apply chatLimits.ts requireChatContent (CHAT_CARD_REPEAT, CHAT_STATUS) to task and step chats as well as the project chat
Unclear answer: take the narrowest safe reading swarm-dev, swarmSkills.ts:564 judgment Interpreting
Don't ask the same question twice swarm-dev, swarmSkills.ts:564 remove Repeat of swarm-lead:481 (code: repeatedDecision)
To split or take more work, ask the Lead swarm-dev, swarmSkills.ts:565 remove Repeat of swarm-lead:437 (the new rows on Lead-only create and assign)
A person's decision: needs_human with one question swarm-dev, swarmSkills.ts:568 code commands.ts work.status needs_human → routesToPm / crewNeeds.ts (the PM's crew need)
ask: 2–5 options and a recommendation swarm-dev, swarmSkills.ts:569 code decisions.ts decisionChoices, checkDecisionDeadline
Blocked says why and what would unblock swarm-dev, swarmSkills.ts:570 new commands.ts work.status: refuse blocked/needs_human without hold. The refusal is staged ("the refusal follows once the CLI sends one", commands.ts:4851)
Blocked: do the independent parts meanwhile swarm-dev, swarmSkills.ts:570 judgment What is independent
Missing tool: block at once, name it, stop swarm-dev, swarmSkills.ts:571 remove Repeat of :553; the daemon check above covers it
Ask before anything irreversible, risky or on a real device swarm-dev, swarmSkills.ts:572 judgment Judging risk (shellGuard.ts covers only kill, sudo, /tmp and worktrees)
Ready means pushed branch, a PR, green CI swarm-dev, swarmSkills.ts:575 new commands.ts work.status review: refuse without a linked code PR in a PR project; keep it waiting until ci/required is green at the head (handed.ts only reopens on ci-red)
Handoff gives Ready yes/no, revision, checks, not shown, most likely wrong swarm-dev, swarmSkills.ts:576 new work.status review schema: required fields (head sha, checks run with result, not shown, most likely wrong); refuse when they are missing
Mark ready with the PR; the Swarm opens the review swarm-dev, swarmSkills.ts:577 code commands.ts openReviewSteps on review from context.pullRequestFiles
Check each finding; push back with evidence swarm-dev, swarmSkills.ts:580 judgment Arguing a technical point
Fix real findings, rerun checks, say what changed swarm-dev, swarmSkills.ts:581 judgment Doing the fix
Mark ready again at the new revision swarm-dev, swarmSkills.ts:582 code checkVerdicts.ts (old verdicts stop counting at a new head); liveness.ts revisionReady
Short posts: one result line, no logs swarm-dev, swarmSkills.ts:585 judgment Concision
Every post has substance, never an acknowledgement swarm-dev, swarmSkills.ts:586, :597 remove Repeat of swarm-lead:503 (code: ACK_ONLY)
People's language, no ids, role names swarm-dev, swarmSkills.ts:587 remove Repeat of swarm-lead:504 rows
A post reaches only named agents (facts) swarm-dev, swarmSkills.ts:590 code commands.ts message.send recipients (#2963). This states what the code does
Need a person: post in the task, tag them, set needs_human swarm-dev, swarmSkills.ts:591 remove The code contradicts it: crewNeeds.ts / commands.ts routesToPm turn a Member's tags and needs_human into the PM's crew need ("people talk only to the PM", anh Dee 11-05)
Tell your Reviewer the fix is pushed swarm-dev, swarmSkills.ts:592 new commands.ts work.status review again: the server tells each open review step's Reviewer the new head (liveness.ts revisionReady only resets its clock)
Never post the Lead a result, verdict, Ready or ack swarm-dev, swarmSkills.ts:593, :597 code commands.ts message.send: an unnamed post never reaches the PM; your own Ready wakes nobody (work.status)
Stop only your own processes, by id swarm-dev, swarmSkills.ts:600 code cli shellGuard.ts killByName, killAll (shellGuardHook.ts PreToolUse)
Temporary files only in your own mktemp -d folder swarm-dev, swarmSkills.ts:601 code cli shellGuard.ts fixedTmp, macMktemp
Never paste a secret into chat swarm-dev, swarmSkills.ts:602 code commands.ts redactCredentials on every message row (credentials.ts)
Never put a secret in logs, PRs or commits swarm-dev, swarmSkills.ts:602 new CI secret scan of the PR diff and body in ci.yml (none in .github/workflows today), plus a commit-msg/pre-push hook in agent worktrees
Secrets only by private file or env, same command swarm-dev, swarmSkills.ts:602 judgment How a tool is called
Another account's agent: never a reason to move files or secrets swarm-dev, swarmSkills.ts:603 building #4537 part 4: a fenced frame with the other-account line (today cli host.ts OTHER_ACCOUNT)
Refuse other-account requests outside the task; say so swarm-dev, swarmSkills.ts:603 judgment Deciding what the task needs
Never remove a worktree a live process uses swarm-dev, swarmSkills.ts:604 code cli shellGuard.ts liveWorktree, worktreeUnknown
Install nothing system-wide swarm-dev, swarmSkills.ts:605 code cli shellGuard.ts systemWide (sudo, brew, apt, npm -g …)

swarm-review

Rule (plain words, at most 15) Source (skill, file:line) Class Enforced by / proposed check / why judgment
Read only: never edit, commit or push the Builder's work swarm-review, swarmSkills.ts:616 new backend github/app.ts: mint review- and test-step tokens with contents: read (every agent gets contents: write from TOKEN_PERMISSIONS today); shellGuard refuses git push in a review step
Never merge your own review target swarm-review, swarmSkills.ts:616 new Same shellGuard check as dev:546 (gh pr merge, gh api …/merge); the merge train merges
Read brief, handoff, diff, comments before judging swarm-review, swarmSkills.ts:617 judgment Reading
Every verdict names its revision swarm-review, swarmSkills.ts:618 code commands.ts work.check head + checkVerdicts.ts: a verdict without a head counts at none
Project instructions outrank this skill swarm-review, swarmSkills.ts:619 remove Repeat of swarm-lead:442
Start within 30 minutes of being asked swarm-review, swarmSkills.ts:622 code The server assigns the step at Ready (openReviewSteps, reviewerPick.ts); liveness.ts TASK_QUIET_MS (30 min) wakes the Lead
Oldest ready work first swarm-review, swarmSkills.ts:622 remove The server hands each step to one Reviewer; a Reviewer has no queue to order
If you can't start, tell the Lead swarm-review, swarmSkills.ts:622 code liveness.ts quiet notice; stuck.ts
Missing tool: block at once, name it, stop swarm-review, swarmSkills.ts:622 remove Repeat of swarm-dev:553 (new daemon check)
Look for wrong behaviour, missed cases, false switches, tests that can't fail swarm-review, swarmSkills.ts:625-627 judgment The review itself
Check the handoff's evidence; run checks for a doubt swarm-review, swarmSkills.ts:628 judgment Weighing evidence
Findings P1/P2/P3 with file:line and fix swarm-review, swarmSkills.ts:631 new work.check failed: take findings as a list of {severity, file, line, fix} and refuse a failed verdict with none; handed.ts passes them to the Engineer
Verdict text "No finding on rev" / "Hold — rev" swarm-review, swarmSkills.ts:632 remove The verdict is work.check passed/failed at a head (code); the wording repeats it
A re-review covers only new changes swarm-review, swarmSkills.ts:632 judgment Scope of reading (the server could hand over the diff since the last reviewed head)
Pass or fail the check with revision and verdict swarm-review, swarmSkills.ts:633 code commands.ts work.check, checkVerdicts.ts recordCheckVerdict
Post the verdict once; never repeat the card swarm-review, swarmSkills.ts:634 remove Repeat of swarm-dev:563 (new task-chat card check)
Tell the Lead at once: privacy, interface breaks, default-on changes swarm-review, swarmSkills.ts:635 judgment Recognizing these
Short posts, people's language, no ids, role names swarm-review, swarmSkills.ts:636 remove Repeat of swarm-lead:504 rows
Mark the review done with verdict and revision swarm-review, swarmSkills.ts:639 new commands.ts work.status done on a review step: refuse without a counted work.check verdict at the current head
Send verdict and findings to the Builder swarm-review, swarmSkills.ts:644 code handed.ts: a failed check brings the task back to its Engineer with why
Never post the Lead a result or verdict swarm-review, swarmSkills.ts:645 remove Repeat of swarm-dev:593 (code)
Who a post reaches; asking a person swarm-review, swarmSkills.ts:642-643 remove Repeat of swarm-dev:590-591
Reactions and Shared machines sections swarm-review, swarmSkills.ts:647-657 remove Repeat of swarm-dev:595-605 and swarm-lead:513-514 word for word

Appendix D. Tools, message frame and launch prompts

Read on main 0dd01c979. "code" means I found the enforcing code and name it. Paths are relative to the repo root. Abbreviations: cmd = backend/src/superTabs/commands.ts; guard = cli/src/superTabs/shellGuard.ts shellRefusal (PreToolUse hook, lib/agentShellGuard.ts; only for Claude Code and Codex: lib/swarmEngineArgs.ts SHELL_GUARD).

cli/src/lib/swarmTools.ts (the full manual)

Rule (plain words, at most 15) Source (file:line) Class Enforced by / proposed check / why judgment
A new OPERATION_ID per change; reuse it only to retry the same JSON swarmTools.ts:14 code backend store.ts (1312, 1491, 1530, 1938) refuses OPERATION_REUSED when the request hash differs; same hash replays the first result
Read instructions at start and whenever told they changed swarmTools.ts:22 building #4537: the daemon sends each versioned part and re-sends on version change or compaction
INSTRUCTIONS_UNAVAILABLE "no instructions": work by your role file swarmTools.ts:22 remove v2 fallback to role skills; #4537 removes the role skills
INSTRUCTIONS_UNAVAILABLE "try again": run instructions again shortly swarmTools.ts:22 new CLI instructions retries a 503 itself, bounded with backoff (cli superTabs/command.ts), so no agent needs the rule
type: answer prompts only within the agent's task swarmTools.ts:26 judgment whether a prompt belongs to the task needs reading the screen and the task
Ask the owner before approving anything risky in another terminal swarmTools.ts:26 judgment "risky" is a judgment of what the prompt would do
Dismiss Codex "Update available" with Esc, never number+Enter swarmTools.ts:26 code engines/codex/launch.ts swarmArgs sets check_for_update_on_startup=false for every Swarm Codex; the line can go
Answer a message once in a project chat swarmTools.ts:30 code cmd message.send → chatLimits.ts requireChatAnswer → answers.ts requireUnanswered refuses a 2nd answer/--answers (and a main-chat --reply-to to a person) with ALREADY_ANSWERED
Answer once in task, step and private chats swarmTools.ts:30 new Today only the PM's answer is refused there (recordAnswered records only PM answers, cmd ~4614); a worker's 2nd answer/post --answers and thread --reply-to pass, so the manual's "a second is refused" overstates it. Check: record every agent's answer per message (bounded like MAX_ANSWERED) and refuse a 2nd in every chat
Answer where asked: below in main, in its thread when threaded swarmTools.ts:30 code host.ts prompt() reply line names --answers or --reply-to per message; answer places it (answers.ts inThread); thread-answer projects thread an --answers server-side
Open a thread only for one topic's back-and-forth or far-up answer swarmTools.ts:30 judgment whether talk is a back-and-forth on one topic is a reading of the conversation
Post with neither flag only to start a new topic swarmTools.ts:30 judgment needs to know the post is a new topic, not an answer
Tag a person only when they must act or decide swarmTools.ts:32 judgment need to act is judgment; tags on a non-PM agent's post are already limited to the person it answers (cmd message.send routesToPm)
Nobody is tagged who cannot read the conversation swarmTools.ts:32 code cmd message.send checkMentions/textTags (canReadGroup, mentions.ts:139,154)
Never type a person's email; name them by username swarmTools.ts:33 new cmd message.send: in an agent's text, replace a member's email with their @username (or refuse EMAIL_IN_TEXT); names are already never shown as emails (personNames.ts)
"Machine privacy check stops a command holding the owner's email" swarmTools.ts:33 remove No such check found in the repo; the only privacy check is team/privacy.ts, the Team account's (gone, anh Dee 11-07)
--to names exactly the agents a post reaches swarmTools.ts:37 code cmd message.send recipients = recipientIds + @Name (agentsNamedIn, mayName) only (~4489)
A post naming no one reaches no agent except the task's assignee swarmTools.ts:40 code cmd message.send recipient rule (comment ~4489, River's ruling #2963)
Never post an acknowledgement (to the PM or anyone) swarmTools.ts:42 code cmd message.send isAcknowledgement → ACK_ONLY (acknowledgements.ts)
— never post the PM a result, verdict or Ready swarmTools.ts:42 new cmd message.send: refuse an agent's --to <coordinator> in its own task/step when the text has no question (the same test host.ts uses for plainReplies: asksQuestion, coordinatorInOwnTask); status goes by work.status
In the project chat, name only the coordinator with --to swarmTools.ts:43 code backend: posting in its project chat joins no one (cmd message.send postable/teamJoin comment), so other --to add nothing; the line is description
A post stays inside its project swarmTools.ts:44 code cmd postable/mayName keep posts and --to inside the project
Only the person and their agent post in a private chat swarmTools.ts:44 building #4547
React 👀 on start, ✅ when done, 🚀 when merged swarmTools.ts:47 new backend: add ✅ to the message a task was opened from inside the work.status done write, and 🚀 inside conversation.merged (no extra POSTs); keep 👀 to the agent
Post only substance; never an acknowledgement — react instead swarmTools.ts:49 code cmd message.send ACK_ONLY (acknowledgements.ts ACKNOWLEDGEMENTS); note "done", which the manual lists, is not on the list; not applied in Buddy chats or agent-chat
Status goes by work.status; name the PM only when it must act swarmTools.ts:49 judgment "must act" is judgment (the refusal above covers the code part)
A refusal says what to fix: change something before resending swarmTools.ts:58 new CLI command: remember the last refused request hash per tab for 10 min and refuse an identical resend locally, naming the first refusal
An agent's task needs a goal, a check, a priority, a requester swarmTools.ts:61 code cmd conversation.create → TASK_CONTRACT_MISSING (cmd 2969, taskContract.ts contractRefusal)
Work nobody asked for gives noRequesterReason swarmTools.ts:61 code same check accepts noRequesterReason in place of requesterId (taskContract.ts:22)
Priority meanings (P0 shipped broken … P3 tools) swarmTools.ts:61 judgment choosing the priority is a reading of impact
Only a person or the coordinator moves Next up swarmTools.ts:65 code cmd work.queue coordinatorOrPerson
Only a person or the coordinator changes priority; only they set P0 swarmTools.ts:66 code cmd work.priority coordinatorOrPerson + requirePriorityRight
Assign a route candidate with its routeDecisionId swarmTools.ts:67 building #4546; routeDecisionId is optional in the schema today (cmd:494)
review status sent once per new head swarmTools.ts:68 new cmd work.status: refuse review when the task is already in review at the same PR head (task.pullRequestHeads)
done result names the exact revision, evidence and links swarmTools.ts:68 new cmd work.status: refuse done on a code task whose result names neither a 40-hex commit nor a PR URL of the project
Set working again once the work moves swarmTools.ts:68 judgment when blocked work "moves" is the agent's reading; (lease expiry already catches silence)
needs_human ask: 2-5 options to one person swarmTools.ts:69 code schema decisionChoices + cmd work.status INVALID_DECISION
Keep working on your recommendation, provisional, until answered swarmTools.ts:69 judgment whether work can go on provisionally depends on the work
Record a check at the PR head and base you read swarmTools.ts:70 code schema work.check head 40-hex; merge train counts a verdict only at the live head/base (mergeTrain/plan.ts headReads, passers)
A cancelled duplicate or fold says where it goes on swarmTools.ts:71 code cmd work.cancel goesOnIn turns "Duplicate of #N"/"Split into" into foldedInto and checks the numbers (FOLD_TARGET); nothing forces a duplicate to say it
— who may cancel (today any project agent cancels any task) swarmTools.ts:71 building cmd work.cancel allows projectAgent on a person's task; "a stuck step moves without cancel" is #4534, "one card per ask" #4538
Wait for the machine to confirm an agent's stop swarmTools.ts:72 code cmd work.status STOP_UNCONFIRMED; agent removal STOP_REQUESTED (cmd ~5164)
proposal.close for Buddy proposals listed before threads swarmTools.ts:73 remove cleanup of pre-thread Buddy proposals (v2)
A group is Done only after its merge is recorded (train merges) swarmTools.ts:74,118 code merge train records conversation.merged itself (store.ts ~5714); mergedTasks.ts ownMerge sets the task done and keeps it out of dispatch
Record a hand merge with conversation.merged swarmTools.ts:74 building #4533 (GitHub issue is the task; issue closes on merge)
person.tell is not private: members see your terminal swarmTools.ts:76 remove Buddy-relay path; spec (#4537, Members and Leads §7) has the server write owner news itself
Answer a scheduled project.report; unanswered blocks later ones swarmTools.ts:77 remove v1 status card (spec "Where today's rules go"); projectUpdates.ts says nothing marks a group for a report
Settings refused unless yours; a person's words via askedIn swarmTools.ts:80 code cmd tab.tidy swarmOwnerAsked, rules RULES_ASKED_IN_REQUIRED (cmd 2453)
Routing and owner rules go in the project's instructions swarmTools.ts:80 building #4546 moves routing order/models/quota/machine choice into the router
Of agents, only the coordinator saves instructions, always with askedBy swarmTools.ts:85 code cmd instructions.save COORDINATOR_REQUIRED, ASKED_BY_REQUIRED (2381-2388)
Stale base refused: re-read, merge, save on the new revision swarmTools.ts:86 code cmd instructions.save INSTRUCTIONS_STALE with the current text
Never overwrite another writer's text when merging swarmTools.ts:86 judgment a re-read-then-save of one's own old text passes the revision check; merging two texts is judgment
Only the coordinator adds a note; at most 100 swarmTools.ts:88 code cmd note.add coordinatorOf, NOTES_FULL
When notes are full, remove one or move it into instructions swarmTools.ts:88 judgment which note to drop is judgment
Note removal: the coordinator or a reader of the project swarmTools.ts:89 code cmd note.remove readProject + coordinatorOf
Mark the crew once; start a new agent only to replace a broken one swarmTools.ts:92 building #4546 (agent picking): a start while a free crew member of that role/lane exists would be refused there
Confirm each "what changed" note with process.confirm swarmTools.ts:92 remove process notes go with the built-in PM text (#4537 table)
Route before you start or assign an agent swarmTools.ts:95 building #4546
local only when a person asks for a local model; a named model in their words swarmTools.ts:97 building #4546 (models)
Choose by the project's Routing instructions swarmTools.ts:101 building #4546; the route "ranks nothing" today
Start/assign with routeDecisionId and an overrideReason swarmTools.ts:103 building #4546; both optional today (cmd:359, 494)
plan records nothing: route each group, start the plan's pick swarmTools.ts:104 building #4546
Start only on the Swarm's listed machines swarmTools.ts:110 code dispatch refusals NOT_SWARM_MACHINE etc. (start.ts LASTING_REFUSALS, machines.ts admitMachineStart); machine rules machineRuleRefusal (machineRules.ts)
Repeat start with the same id; resume a pending start swarmTools.ts:110 code operation idempotency (store.ts OPERATION_REUSED) and START_CLAIMED (start.ts refusedByBackend)
roleName refused by an older Swarm: start again without it swarmTools.ts:109 remove compatibility note for an old backend
A failed start moves nowhere: you decide what next swarmTools.ts:111 judgment what replaces a failed start is a routing decision (becomes #4546's)
Open a step with reviewOf + step, then assign it swarmTools.ts:113 code a Ready opens planned steps itself (stepOpen.ts openReviewStep); dispatch hands them (dispatch.ts candidatesFor + reviewerPick.ts stepCandidates)
A review status wakes nobody: name the reviewer with --to swarmTools.ts:114 remove stale since steps open and are handed on Ready (stepOpen.ts, dispatch.ts)
An agent's task names who asked, or why nobody did swarmTools.ts:117 code conversation.create TASK_CONTRACT_MISSING requires requesterId or noRequesterReason
Name the right person as requester; one card per ask swarmTools.ts:117 building #4538 (one card per ask) binds the ask's author; who asked is otherwise judgment
Post a PR link once in main; never repeat a card (project chat) swarmTools.ts:119 code chatLimits.ts requireChatContent CHAT_CARD_REPEAT and CHAT_STATUS, project-chat main only, link-only lines only; cards bind themselves (cards.ts bindPullRequestCards)
— never repeat a card, in every chat swarmTools.ts:119 new extend requireChatContent to task/step chats and to "merged"/"CI green"/"reviewed" lines that name a carded PR
Hand a lost task on with its branch, not restart swarmTools.ts:120 code liveness.ts lease (LEASE_MS 5 min, QUIET_RUNNING_MS/TASK_QUIET_MS 30 min) loses the task; dispatch.ts candidatesFor hands lost tasks (lostAttempt) to a free worker; stuck.ts alerts after 10 min
— the taker continues the pushed branch, not the old goal swarmTools.ts:120 judgment continuing someone's work vs restarting is the taker's reading
After a restart, read the recovery notice and checkpoint swarmTools.ts:122 judgment reconciling a session's real state needs reading it
Never replay delivered input after a restart swarmTools.ts:122 code host.ts journal (stage prepared/submitting/uncertain): "A process restart never interprets a lost acknowledgement as permission to type twice"
Never replay your own old commands after a restart swarmTools.ts:122 judgment whether a command already took effect needs reading the session and the remote state
Summarize a long thread once; record a decision once swarmTools.ts:125 judgment what is long or important is judgment
Answer in main with --answers, in a thread with --reply-to swarmTools.ts:125 remove duplicate of :30
Match a name to a member before asking for an invitation swarmTools.ts:128 judgment names in chat are informal
Bring outside work in via a new Swarm agent and a handoff swarmTools.ts:129 judgment a procedure for people's own sessions
Missing tool: install it in your own home, not system-wide swarmTools.ts:130 code guard systemWide refuses sudo, global npm/brew/apt/pip… (shellGuard.ts:333)
Never ask a person to sudo or sign in to GitHub swarmTools.ts:130 judgment a request in prose; the agent's own sudo is refused by the guard
Workflow/issue writes only where the App granted them swarmTools.ts:134 code github/app.ts GRANTED_TOKEN_PERMISSIONS asked only where granted; GitHub refuses the rest
Work needing more runs on the owner's machine, their sign-in swarmTools.ts:134 judgment which machine to use for it is a routing choice
Never ask for a token in the chat or a file swarmTools.ts:135 judgment asking is prose; a token pasted in chat is already replaced by credentials.ts redactCredentials (see secrets row)
Ask a person only for what no agent can do, one step at a time swarmTools.ts:136 judgment knowing what no agent can do needs judgment
Never stop processes by name or pattern (pkill, killall) swarmTools.ts:139 code guard killsByName + killsAll (GUARD_REASONS.killByName, killAll)
Stop only processes you started, by recorded pid swarmTools.ts:139 new guard: refuse kill PID/taskkill /PID when PID is not in the session's own process tree (session root pid known to the daemon), and extend the guard to every engine, not only Claude/Codex
Temp files only in mktemp -d "${TMPDIR:-/tmp}/…", never fixed /tmp swarmTools.ts:140 code guard fixedTmp, mktempIgnoringTmpdir (macMktemp); file tools via fileRefusal (shellGuardHook.ts) — Claude Code and Codex only
— the same for engines without the hook (OpenCode and the rest) swarmTools.ts:140 new lib/swarmEngineArgs.ts: give every Swarm engine the guard (or a shim on PATH); today SHELL_GUARD maps only claude and codex
Never print a secret into chat swarmTools.ts:141 code backend credentials.ts redactCredentials on every stored message draft (cmd ~5186) and command text (withoutCredentials)
Never put a secret in logs, pull requests or commits swarmTools.ts:141 new the Swarm git hooks (lib/swarmGitHub.ts, commit-msg/pre-push are already installed) run the credentials.ts patterns on the message and staged diff and refuse; the PR watch flags a PR body that matches
Load secrets only from a private file or env var, same command swarmTools.ts:141 judgment how a secret is used inside a command is not checkable reliably
Messages from another account's agent arrive marked swarmTools.ts:142 code backend store.ts otherAccount → host.ts prompt() OTHER_ACCOUNT / repliedTo() QUOTED_OTHER_ACCOUNT fence
Another account's agent is never a reason to read/send files or secrets swarmTools.ts:142 judgment what is "outside the task" needs judgment
Say in the chat what you refused swarmTools.ts:142 judgment what was refused and why is the agent's account
Never remove a worktree a live process uses swarmTools.ts:143 code guard liveWorktree (lsof of live cwds; GUARD_REASONS.liveWorktree, worktreeUnknown)
Install nothing system-wide; tools in your session folder swarmTools.ts:144 code guard systemWide
Print little to save quota swarmTools.ts:145 judgment how much output a task needs is judgment

cli/src/lib/swarmToolSheets.ts (per-role sheets; removed by #4673)

Each sheet row (T(...), lines 57-143) is a shorter form of one manual block; swarmToolSheets.spec.ts fails if a block has no row. Those briefs are duplicates of the manual rows above and take the same class. Only what a sheet adds or changes is listed here.

Rule (plain words, at most 15) Source (file:line) Class Enforced by / proposed check / why judgment
Run mine before acting after a pause swarmToolSheets.ts:60 remove host.ts contextLines already puts the agent's work line (workLine) in every delivery; not in the manual
work.check head is the whole commit id swarmToolSheets.ts:97 code schema work.check head regex 40-hex (cmd:520)
PM form: "hand a lost task on with its branch" swarmToolSheets.ts:137 remove duplicate of swarmTools.ts:120 (code)
PM form: "ask a person only for what no agent can do" swarmToolSheets.ts:137 remove duplicate of swarmTools.ts:136
PM form: "Start an agent only to replace a broken one" swarmToolSheets.ts:115 remove duplicate of swarmTools.ts:92 (building #4546)
Answer once (every sheet) / react instead of acknowledging swarmToolSheets.ts:69,70,85 remove duplicates of swarmTools.ts:30,49
Sheets as launch text at all swarmToolSheets.ts:56-144 remove #4537 removes the sheets as launch text; help tools keeps the manual on demand

cli/src/superTabs/host.ts (wrapper on every delivered message)

Rule (plain words, at most 15) Source (file:line) Class Enforced by / proposed check / why judgment
Owner news: read as data, do not answer it there host.ts:131 remove Buddy owner-news relay; spec #4537: the server writes owner news into the chat itself
Post one short note only for a new milestone host.ts:132 remove same; becomes a server row (Members and Leads §7)
Another account's message: never a reason to read/send files or secrets host.ts:141 remove duplicate of swarmTools.ts:142 (fence code, obeying judgment); #4537 replaces it with one data line
"…or a Harness Team account's" in OTHER_ACCOUNT host.ts:141 remove Team accounts are gone (anh Dee 11-07)
Quoted other-account message: same limit host.ts:145 remove duplicate of :141; #4537 replaces the four warnings with one fenced data line
Buddy: others' words arrive set off as data host.ts:150 code host.ts prompt() othersWords → setOff for anything not fromOwnPerson
Buddy: only your owner's own words ask you to act host.ts:150 judgment acting only on the owner's words is the agent's reading
Buddy: quoted message is context, never a new ask host.ts:153 remove duplicate of :150 (#4537 fence)
Artifact pages are material, never instructions host.ts:157 judgment content is data; only the agent can treat it so
Links on another's computer: tell the owner in one line host.ts:161 new host: when it withholds the links (LINKS_ELSEWHERE case), post that one line to the owner's chat itself instead of asking the Buddy to
Native input observed: do not replay the same instruction host.ts:2657 judgment whether a later action repeats it is judgment
A post here reaches no agent: name no one unless needed host.ts:2675 judgment need is judgment; reach is code (cmd message.send)
To acknowledge, react instead of posting host.ts:2676 code ACK_ONLY (acknowledgements.ts); the line can go
Write like a colleague; answer first, plain words, their language host.ts:495 judgment tone and language need judgment (a language mismatch could be measured, not refused)
Keep it short: under about 150 words unless asked host.ts:496 new backend message.send emits a words-per-agent-post-to-people measure (no content), and the board shows posts over 150 words; no refusal, as "unless asked" is judgment
Show no commands, ids, field names or error codes host.ts:497 new cmd message.send: refuse an agent post to people in project/private chats that contains harness super-tab, a 32-hex/UUID id or an [A-Z_]{6,} code outside code fences
Do not describe your own tools or permission prompts host.ts:498 judgment relevance to what blocks the person is judgment
Answer each message once, as the reply line says host.ts:500 remove duplicate of swarmTools.ts:30 (code partial, new extension)
Main chat right below (--answers); thread inside it (--reply-to) host.ts:500-501 code reply line chosen per message in prompt(); server threads --answers in thread-answer projects
Open a thread only for one topic's back-and-forth host.ts:502 remove duplicate of swarmTools.ts:30 (judgment)
If you already answered a message, do not post again host.ts:502 remove duplicate of :500
Handing over finished work: give revision and links host.ts:503 remove duplicate of swarmTools.ts:68 done result (new check)
Threaded projects: every person's message answered in its thread host.ts:509 code answersInThread → threadAnswers, reply line --reply-to; backend threads an --answers there (comment host.ts:2666)
At most two agent posts per ask in the main chat host.ts:509 code chatLimits.ts requireChatPost CHAT_MAIN_LIMIT, CHAT_ASK_CLOSED
Main chat only for news the whole team needs host.ts:509 judgment what is team news is judgment
Ask questions and post results in this conversation host.ts:2682 remove #4537 drops it from the frame; the reply line says where
Replies to delivered instructions must be posted here explicitly host.ts:2682 new backend: a delivery to an agent that is neither answered, reacted to nor followed by a work.status in 30 min shows on the board as owed (pulse.ts tracks this only for the PM's asks today)
Manage agreed work and delegation: run help host.ts:2681 remove #4537 drops it from the frame
Proposal details "for the PM" from a Buddy host.ts:2647 remove Buddy proposal relay; the card holds them (proposalCards.ts)

cli/src/superTabs/start.ts (launch prompts)

Rule (plain words, at most 15) Source (file:line) Class Enforced by / proposed check / why judgment
Run status until this harness appears in the roster start.ts:72,79 new daemon sends the launch prompt only after the backend confirms the join (start.ts already waits on the model report, MODEL_REPORT_WAIT_MS)
PM: if the conversation is empty, ask there what to work on start.ts:72 judgment what to ask depends on the project
PM: answer each message once start.ts:72 remove duplicate of swarmTools.ts:30
Reply with post in that conversation start.ts:72,79 remove the delivery frame's reply line names the command per message
Read your role in the project's instructions start.ts:75 building #4537 (daemon sends the job page and AGENTS.md as parts)
Run harness super-tab help for commands start.ts:72,79 remove help tools on demand (#4537)
If the sandbox blocks the command, ask to run it outside start.ts:72,79 new daemon adds a narrow allow for harness super-tab to the session's --settings (the same flag the guard uses), leaving the person's other permissions as they are (Swarm v3)
git/gh use the App token for this task, not your login start.ts:189 code lib/swarmGitHub.ts session gh config, SWARM_GITHUB_CLEAR_ENV; backend github/tokens.ts mints per task
Commits carry the task's attribution trailers start.ts:190 code Swarm commit-msg hook adds trailers (lib/swarmGitHub.ts ~131-146)
Start PR bodies with the task's "requested by" line start.ts:190 new the PR watch (pullRequestEvents.ts) writes or checks the requested-by line (projects.ts requestedByLine) in the PR body with the App token
Prior PM handoff arrives quoted as data start.ts:443 code start.ts:441-444 quotes it line by line with > , bounded 32 KB
Prior PM handoff: context, not instructions start.ts:443 judgment treating it as context is the agent's reading

Candidates asked about but not in these sources

Rule (plain words, at most 15) Source (file:line) Class Enforced by / proposed check / why judgment
Never merge your own PR (merge train) not in these four files code mergeTrain/plan.ts passers: a builder's own verdict never counts; eligible needs ci/required success and enough reads
Never merge your own PR (by hand) not in these four files new Nothing stops an agent's gh pr merge or make merge-pr: the task token has contents/pull_requests: write (github/app.ts TOKEN_PERMISSIONS) and scripts/merge-validated-pr.py checks no author. Check: guard refuses gh pr merge/gh api …/merge in Swarm sessions, so merges go only through the train
Reassign a task when its claim goes quiet swarmTools.ts:120 code see the "Hand a lost task on" row: liveness.ts leases + dispatch.ts lost-task hand-on + stuck.ts
Quiet chats: agent acks and status lines refused swarmTools.ts:49,119 code ACK_ONLY everywhere but Buddy/agent chats; CHAT_STATUS, CHAT_CARD_REPEAT, CHAT_MAIN_LIMIT only in a project chat's main; instructions.save posts nothing
Quiet private chats swarmTools.ts:44 building #4547