@a-t-h-i/bot-lobby 0.6.4 → 0.6.6

package/README.md

@@ -2,7 +2,11 @@
 
 A [Pi](https://pi.dev) extension that turns Pi into a multi-agent software team.
 
-`/bot-lobby <request>` starts a task. Your Pi session becomes the **Master**
+![The Lobby tab: your conversation with the oracle, the activity log of every agent, and their latest thoughts](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/gallery.png)
+
+`/bot-lobby <request>` (or a request typed in the lobby) starts a task, unless
+one agent can simply do it: then it goes to the [quick-fix agent](#quick-fix-or-the-team).
+For a task, your Pi session becomes the **Master**
 (the "oracle"): it scouts the codebase, proposes a plan, and delegates the
 work to three domain agents — **Designer+Frontend**, **Backend** and **QA** —
 each running in its own isolated `pi` process. QA's reviewer is the quality
@@ -12,6 +16,10 @@ The rule: **LLMs decide, the engine enforces.** Agents propose; the
 extension validates every state change, permission and approval through one
 `orchestrate` tool.
 
+The oracle is meant to be your most capable model; the agents can be smaller
+and cheaper ones. So it never assumes they are as capable as it is: it makes
+every decision itself and [briefs each agent in full](#briefing-the-agents).
+
 ## Install
 
 ```bash
@@ -31,7 +39,7 @@ tool names.
 
 1. `/bot-lobby add a login page` — starts a task; the lobby opens.
 2. Answer the Master's questions, then approve its proposal.
-3. Watch the agents work in the lobby (`alt+l` shows or hides it).
+3. Follow the agents in the lobby (`alt+l` shows or hides it): what they do, and what they think.
 
 `/bot-lobby settings` sets each agent's model, thinking level, time limit and
 extra instructions.
@@ -41,7 +49,7 @@ extra instructions.
 | Command | Does |
 | --- | --- |
 | `/bot-lobby` | Open the lobby (`alt+l`) |
-| `/bot-lobby <request>` | Start a task (`--task` if it begins with a command word, `--auto` to run unattended, `--budget 90m` to give it a time budget) |
+| `/bot-lobby <request>` | Start a request: a [quick fix](#quick-fix-or-the-team) when one agent can do it alone, else a task (`--task` to always make it a task, also when it begins with a command word; `--auto` to run unattended, `--budget 90m` to give it a time budget, `--fast` / `--full` to pick its [track](#fast-track-or-full-workflow)) |
 | `/bot-lobby budget [90m\|off]` | Show or set this session's task time budget |
 | `/bot-lobby status \| tasks \| runs [id]` | Current task, all tasks, recent agent runs |
 | `/bot-lobby approve \| amend <text> \| decline` | Answer the proposal |
@@ -54,15 +62,106 @@ extra instructions.
 | `/bot-lobby knowledge` | Knowledge file sizes |
 | `/bot-lobby minimize \| restore` | Hide bot-lobby in this session (`ctrl+shift+m`) |
 
+## Quick fix or the team
+
+Before any task exists, bot-lobby asks whether **one agent can just do it**:
+in one file or one area, with nothing to agree between frontend and backend,
+no unfamiliar codebase to survey, nothing risky and no decision you must make
+first. [Jev](#the-classifier-jev) answers when it is on (`classifier.thresholds.quickFixAt`,
+0.7); plain rules answer otherwise, and whenever Jev is unsure. A request that
+says it is self-contained ("a single page", "in one html file") counts even
+when it is rich.
+
+When it reads that way, the oracle confirms in one step, without reading
+files or planning (`route_request`), and says so: *this looks like a quick
+feature, the quick-fix agent is on it*. The lobby then hands the request to
+the quick-fix agent and switches to the **Quick fix** tab, where you follow
+it. No scouts, proposal, plan or QA. A quick feature (bigger than a small
+change, but in one place) runs on its builder's model, thinking and time limit
+(DESIGN's for a page) instead of the quick-fix defaults.
+
+Everything else, or anything the oracle judges needs the team, starts as a
+task below. `--task` always makes a task; `workflow.routeQuickFixes: false`
+turns routing off. Without the lobby (a background session, RPC mode) every
+request is a task.
+
 ## How a task runs
 
 ```
-request → clarify → scout → propose → approve → plan → implement → QA gate → complete
+full workflow:  request → clarify → scout → propose → approve → plan → implement → QA gate → complete
+fast track:     request → implement (only the agents it needs) → QA, if it needs tests → complete
 ```
 
+### Fast track or full workflow
+
+The moment a task starts, bot-lobby reads the request and decides how serious
+it is: its size, who has to take part, and whether it takes the **fast
+track** or the **full workflow**. The read is instant and costs no tokens
+(plain rules, refined by [Jev](#the-classifier-jev) when that is on).
+
+| The request… | Who takes part |
+| --- | --- |
+| changes anything that runs in the browser: screens, components, styles, copy, canvas or three.js graphics | DESIGN (frontend) |
+| changes an API, the database, auth, jobs or other server-side code | DEV (backend) |
+| needs tests: asks for them, fixes a bug, or changes backend logic | QA |
+| depends on outside facts: latest versions, docs, standards, third-party APIs | RESEARCH |
+
+A **small, clear, low-risk** request takes the fast track: the oracle hands
+it straight to those agents, with no scouts, no proposal to approve and no
+plan document (the engine keeps a short plan whose steps are the
+delegations, so the checklist still works). QA takes part only when the
+change needs tests (its worker writing and running them as the last step, or
+the QA gate); without it the task completes as soon as the work is in and
+checked. A copy change is one agent run.
+
+Everything else takes the full workflow below: anything **medium or large**
+(a new page, flow or endpoint, a refactor, an upgrade, a vague or
+many-part request), **serious** whatever its size (security, auth,
+passwords, payments, migrations, production, personal data), or **unclear**
+(too short, vague, or asking to investigate first).
+
+- The oracle glances at the read once and acts on it, or corrects it with
+  `orchestrate action=track`: the full workflow for a change bigger than it
+  reads, the fast track for one that is smaller (before its work is planned),
+  or a member added or dropped.
+- Once work is under way a track only gets stricter: the full workflow or
+  more members, never QA dropped. A fast task whose worker asks for a new
+  dependency or an architecture change gets QA.
+- `/bot-lobby --fast <request>` or `--full <request>` decides it yourself;
+  the oracle never moves a `--full` task to the fast track.
+  `workflow.fastTrack: false` puts every task on the full workflow.
+- The track shows in the lobby's activity log, the task's details on the
+  Tasks tab, and `/bot-lobby status`.
+
+### Briefing the agents
+
+Every agent may run on a smaller, cheaper model than the oracle's, one that
+follows instructions well but does not infer intent. So the oracle writes
+each delegation (`implement`, `scout`, `research`) as a self-contained brief
+and settles every design and architecture decision itself first:
+
+- **Goal**, the exact **Files**, numbered **What to do** with names, shapes
+  and values, the **Contracts** shared with other agents (repeated in full in
+  each brief), **Constraints**, **Done when** (checkable criteria and the
+  commands to run) and **If stuck**.
+- Plan steps are written to the same standard, so a brief is the plan step
+  made explicit, never a new decision.
+- Every agent is told to follow its brief and the approved plan exactly, use
+  the given names letter for letter, and report what does not match instead of
+  guessing. Workers end their report with a **Brief Check**: each "Done when"
+  item, met or not, with evidence.
+- The oracle holds each report to its brief. Drift, a skipped criterion or a
+  guessed choice comes back as a fix step with a more explicit brief.
+- The engine backs it up: a delegation that names nothing concrete (or a long
+  one with no done criteria) is sent back to the oracle once before any agent
+  starts. Sending the same text again goes through, so a short task that is
+  complete as written is never stuck. `workflow.briefCheck: false` turns it off.
+
+### The full workflow
+
 - **Scouts** (read-only) investigate the domains the request touches.
 - The Master **proposes** a short bullet list; nothing is built until you
-  approve it. Small single-domain changes may skip scouting and the proposal.
+  approve it.
 - **Workers** implement plan steps, one domain each. Several can run in
   parallel; they share files through a **file desk** (claim a file, queue for
   a busy one, hand it over with a note).
@@ -117,16 +216,54 @@ everything. `workflow.freshContext: false` in the config turns this off.
 ## The lobby
 
 A full-screen view with a prompt at the bottom that talks to whatever tab is
-open. `alt+h` lists every key.
+open. `alt+h` lists every key. It is text only: no animations, just the
+conversation, the activity log and the thoughts, and a one-line status in Pi's
+footer.
 
 | Tab | What it is |
 | --- | --- |
-| **1 Lobby** | The task's status, your conversation with the oracle, an activity log of every tool call, and each agent's latest thought |
+| **1 Lobby** | Your conversation with the oracle, an activity log of every agent's steps, and each agent's latest thought |
 | **2 Tasks** | Every task and saved plan as a checklist. `s` starts a plan in a new session, `h` here; `c` comments on a plan; `a` archives, `d` deletes |
 | **3 Plan** | Plan a task with a panel of agents before building it (below) |
-| **4 Quick fix** | One agent makes a small change right away, beside any running task |
+| **4 Quick fix** | One agent makes a change right away, beside any running task; requests the oracle [routes here](#quick-fix-or-the-team) show up too |
 | **5 Metrics** | Run time, success rate, tokens and cost per model and agent |
 
+### Lobby
+
+![The Lobby tab](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/gallery.png)
+
+Your conversation with the oracle on the left, the activity log of every
+agent's steps on the right, and the agents' latest thoughts below. `alt+c`,
+`alt+a` and `alt+k` hide any of the three; the prompt steers the running turn.
+
+### Tasks
+
+![The Tasks tab](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/lobby-tasks.png)
+
+Every task as a checklist, with its track, plan progress, the approved plan
+and your comments on it.
+
+### Plan
+
+![The Plan tab](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/lobby-plan.png)
+
+The panel's questions, with recommended options, on the left; the draft plan
+on the right. See [Planning](#planning).
+
+### Quick fix
+
+![The Quick fix tab](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/lobby-quickfix.png)
+
+One agent's jobs, each with its live steps, the files it edited and its
+report. See [Quick fix or the team](#quick-fix-or-the-team).
+
+### Metrics
+
+![The Metrics tab](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/lobby-metrics.png)
+
+Run time, success rate, cost and tokens per model and agent, so you can see
+which cheaper models hold up.
+
 Common keys: `tab` switches tabs, `esc` browses (arrows, single-key
 commands), `ctrl+f` searches, `ctrl+s` saves the plan, `alt+o` browses
 sessions, `alt+n` starts a task in a new session, `alt+s` opens settings.
@@ -236,7 +373,8 @@ else TypeSafe.
 | Planning seats | Each round, only the seats the idea or your latest answers touch sit; `1`–`4` pins a seat |
 | Obvious answers | Answers a question itself when the conversation already makes the recommended option clearly right (≥ 0.9); listed under Assumptions |
 | File hints | Agents start with a short list of the files they most likely need, and get a `find_relevant_files` tool |
-| Task triage | The Master gets hints (size, domains, research needed); a quick fix that is really a task is held (`r` run anyway, `t` make it a task) |
+| Quick fix or task | Whether one engineer can do a new request alone decides whether it goes to the [quick-fix agent](#quick-fix-or-the-team) (the oracle confirms) |
+| Task triage | The task's [track](#fast-track-or-full-workflow) and roster use its read (size, domains, research, ambiguity), and the Master gets it as hints; a quick fix that is really a task (large, and not one engineer's work) is held (`r` run anyway, `t` make it a task) |
 | Effort routing | Simple steps run one thinking level lower; trivial ones on a **cheaper model** you pick. A routed run that falls short re-runs on your normal settings |
 
 **It never gets in the way:** any failure, timeout or missing key means
@@ -264,7 +402,7 @@ the result.
   "scout": { "model": "anthropic/claude-haiku-4-5-20251001", "timeoutMs": 480000 },
   "planner": { "thinking": "high", "timeoutMs": 300000 },
   "lobby": { "planningPanel": ["backend", "designer", "qa", "researcher"], "maxPlanningRounds": 5 },
-  "workflow": { "maxReviewIterations": 2, "maxParallelWorkers": 3, "stallTimeoutMs": 300000, "wrapUpAt": 0.75, "taskBudgetMinutes": 0 },
+  "workflow": { "maxReviewIterations": 2, "maxParallelWorkers": 3, "stallTimeoutMs": 300000, "wrapUpAt": 0.75, "taskBudgetMinutes": 0, "fastTrack": true, "briefCheck": true, "routeQuickFixes": true },
   "classifier": { "enabled": false, "provider": "auto", "effort": { "cheapModel": "inherit" } }
 }
 ```
@@ -283,11 +421,11 @@ the result.
 | Rule | How |
 | --- | --- |
 | Steps happen in order | A state machine validates every action |
-| Nothing is built before approval | `implement` refuses earlier states |
+| Nothing is built before approval | On the full workflow `implement` refuses earlier states; only a fast-track task (small, clear, low-risk) starts straight away |
 | Scouts and the QA gate can't edit code | Scouts get read-only tools; the QA gate adds only `bash` for tests |
 | New dependencies and architecture changes need approval | Parsed from worker reports; the domain is blocked until resolved |
 | Only the Master writes knowledge | Agents can only propose it |
-| "Done" is earned | Needs a plan, a passing QA gate that ran checks (or your explicit acceptance), and no open blockers |
+| "Done" is earned | Needs a plan, a passing QA gate that ran checks (or your explicit acceptance), and no open blockers; on the fast track, a finished worker step, and QA's part only when the change needs tests |
 | Parallel workers don't clobber files | Edits need a file-desk claim |
 | A crash doesn't corrupt a task | State is on disk; tasks resume from their state |
 

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "@a-t-h-i/bot-lobby",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Structured multi-agent software engineering orchestrator for Pi",
   "type": "module",
   "license": "Apache-2.0",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "multi-agent",
+    "subagents",
+    "orchestrator",
+    "code-review",
+    "web-search"
   ],
   "repository": {
     "type": "git",
@@ -25,7 +33,8 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/gallery.png"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/prompts/backend.md

@@ -2,7 +2,9 @@
 
 You own backend engineering: API, business logic, data models, database,
 authentication, authorization, integrations, backend architecture, security,
-reliability and backend performance.
+reliability and backend performance. Code that runs in the browser — pages,
+client-side logic, canvas and WebGL/three.js graphics — is the designer's,
+however much logic it holds.
 
 ## API design
 

package/prompts/designer.md

@@ -2,7 +2,9 @@
 
 You own UI/UX and frontend engineering: user experience, interaction design,
 visual consistency, frontend implementation, responsive behavior,
-accessibility, frontend performance and the design language.
+accessibility, frontend performance and the design language. Everything that
+runs in the browser is yours, including client-side logic and canvas,
+WebGL/three.js graphics.
 
 You have real visual taste. Your work is calm, considered and quietly
 delightful: the understated, crafted aesthetic of Anthropic's latest models,
@@ -66,6 +68,27 @@ one-off values.
 - **No magic numbers:** every size, space, color, radius, shadow and duration
   comes from a token or the existing scale.
 
+## Graphics and 3D
+
+When the work is a scene (canvas, WebGL, three.js), how it looks is the
+product, and a generic render is a failed one.
+
+- **Light it like a photograph:** image-based lighting (an environment map,
+  e.g. PMREM with `RoomEnvironment`) plus one key light with soft shadows;
+  ACES or AgX tone mapping and sRGB output. Never flat ambient light.
+- **Physical materials:** `MeshPhysicalMaterial` with values from the real
+  thing — glass with transmission, thickness, IOR about 1.5 and a faint tint;
+  wood, brass or stone with sensible roughness and metalness. Liquids and
+  grains read by their own color, sheen and scale, not by a texture.
+- **Proportions and framing:** model the object after a real reference; frame
+  it so it fills most of the view at rest, on every screen size, with a quiet
+  backdrop (a soft gradient, a floor that fades out). No default grey planes,
+  giant ground discs or horizon lines cutting through the shot.
+- **Restraint:** fewer effects done well beat many done badly; hold 60fps on a
+  phone with quality tiers rather than dropping detail everywhere.
+- **Look at it:** render a frame when the project has a headless browser, and
+  fix what you see; otherwise say in your report that it was not seen.
+
 ## Interaction and motion
 
 You like interactive UIs that give the user subtle, fun feedback — never

package/prompts/global.md

@@ -15,6 +15,24 @@ Perform your assigned responsibility precisely and remain within your domain.
 - Do not invent requirements; ask when they are genuinely ambiguous.
 - Report conclusions, evidence, decisions, findings and blockers concisely.
 
+## Following your brief
+
+The Master that instructs you plans the work and knows the whole task; you may
+be a smaller model that sees only your part. Your brief and the approved plan
+are your authority, so:
+
+- Read the whole brief and the plan before acting, and do exactly what it
+  says, in its order. Do not add features, refactors or "improvements", and do
+  not skip steps because they look unnecessary.
+- Use the names, paths, shapes and wording the brief gives you, letter for
+  letter. Where it leaves a detail open, choose the simplest option that
+  follows the existing code, and say what you chose in your report.
+- Never guess at something that matters (a contract, a file that is not there,
+  a conflict between the brief and the code). Stop that part, finish the rest,
+  and report it under Blockers or Pushback with what you found.
+- Check your own work against the brief's "Done when" list before you report,
+  criterion by criterion, and say honestly which are met and which are not.
+
 ## Hard rules
 
 - Do not add dependencies without approval.

package/prompts/master.md

@@ -17,32 +17,55 @@ validates every step — state transitions, role permissions, approval gates and
 completion authority. If it rejects an action, read the error and adjust; never
 work around it. Do not rely on prompts to enforce permissions or state.
 
+## Task track
+
+Every task starts on a track the engine read from the request (the `Track`
+line in your context): how serious it is, and so who takes part and how much
+process it gets. Fewer steps win whenever the result is the same.
+
+- **Fast track** — a small, clear, low-risk change. No scouts, no proposal,
+  no plan document: delegate straight away with `orchestrate action=implement`,
+  opening each task with `Step N:` (the engine keeps the plan and the
+  checklist). Only the roster takes part: DESIGN for frontend work, DEV for
+  backend work, QA when the change needs tests (its worker writing and
+  running them as the last step, or the QA gate), and the researcher when a
+  decision needs outside facts (summon it first). Several domains: one
+  `implement` with `assignments`, each task stating the contract between
+  them. When the work is in, check `git diff --stat` and the report, then
+  `complete`; without QA on the roster there is no QA gate.
+- **Full workflow** — everything else: the steps below, ending with the QA
+  gate.
+
+The read is quick and can be wrong, so glance at it once and move on: confirm
+it by acting on it, or correct it with `orchestrate action=track` (`track`,
+`roster`, `reason`). Go full when the change is bigger, riskier (security,
+money, data, migrations, production) or less clear than it reads; take the
+fast track when a full-workflow task turns out small and clear (before its
+work is planned). Add a member the roster is missing, or drop one it does not
+need, before delegating. Once work is under way a track only gets stricter:
+the full workflow or more members, never QA dropped; a fast task whose worker
+asks for a dependency or an architecture change gets QA added. The user's
+`--full` and a disabled fast track keep the full workflow.
+
 ## Before implementation
 
-For feature-level work: understand the request; clarify with
+For full-workflow work: understand the request; clarify with
 `orchestrate action=clarify` when necessary; challenge it when there is a real
 technical, security, reliability, UX or maintainability concern; select and run
 relevant Scouts; review findings and target-verify important claims against the
 repository; synthesize and present a short `- ` bullet-list proposal; then wait for
-approval, amendment, or decline. Do not start feature implementation before
-approval.
-
-For a trivial, single-domain request you may skip the Scout round and the
-proposal ceremony: state the short plan, delegate the step, and verify the diff
-directly. The engine allows `clarifying -> awaiting_approval -> planning`, so no
-state override is needed. Skip only when the change is small, obvious and
-confined to one domain.
+approval, amendment, or decline. Do not start full-workflow implementation
+before approval.
 
 ## Classifier hints
 
 When the classifier is on, your task context carries a **Classifier
 triage**: a fast model's read of the request (size, the domains it touches,
 whether it needs outside research, whether it is ambiguous, its kind, likely
-files) and a suggested path. Use it to skip reasoning you do not need —
-scout only the domains it marks (0.5 or more), skip scouting when the task
-is trivial or small in one domain and likely files are named, skip the
-researcher when research is not needed, clarify only when it reads the
-request as ambiguous — and overrule it whenever the repository says
+files) and a suggested path; the task's track was chosen with it. Use it to
+skip reasoning you do not need — scout only the domains it marks (0.5 or
+more), skip the researcher when research is not needed, clarify only when it
+reads the request as ambiguous — and overrule it whenever the repository says
 otherwise. It is a hint, never a rule.
 
 When you `clarify` with options, put your recommended option first and mark
@@ -119,17 +142,94 @@ Assign work to the correct domain; never ask one domain to do another's. A
 cross-domain dependency is reported to you, and you decide whether another
 domain needs a task.
 
+Assign by where the code runs, not by how much logic it holds. Everything that
+runs in the browser — pages, components, client-side state and logic, canvas,
+WebGL/three.js scenes, shaders, client-side physics — is DESIGN's
+(Designer+Frontend); DEV (backend) owns server-side code, data, APIs and
+integrations. One file has one owner: never split a file between domains, and
+never give DESIGN only the styling of something another domain built —
+whoever builds a visual thing owns how it looks.
+
 Write the plan's steps as a numbered list under a `## Steps` heading, and open
 each `implement` task with its step number (`Step 3: ...`, or `Steps 3-4: ...`
 when one delegation covers several) so the user's checklist tracks progress
 exactly.
 
+## Briefing the agents
+
+You are usually a far more capable model than the agents you delegate to. Scouts,
+workers, the researcher and the reviewer may run on smaller, cheaper models
+that follow instructions well but do not infer intent, fill gaps sensibly or
+know what you know. Never assume they are as capable as you. Whatever you leave
+unsaid, they will guess, and a wrong guess costs a whole agent run. Your plan
+and every brief are how your goal reaches the code, so write them for a
+capable but literal reader who has read nothing but the brief and the
+repository.
+
+Every `implement` task (each assignment in a parallel batch), `scout` and
+`research` instruction is a self-contained brief with these parts, in this order:
+
+1. **Goal** — the outcome this step must produce and how it serves the user's
+   request and the approved plan, in one or two sentences. Name the step
+   number(s).
+2. **Files** — the exact paths to create or change, and the ones to leave
+   alone. When you do not know a path, say what to search for and where.
+3. **What to do** — numbered, concrete actions in the order to do them: names
+   of functions, components, endpoints, fields, types, CSS classes, strings,
+   values. Give the exact signature, shape or wording wherever it matters.
+   Write "use X", not "use a suitable library"; when a choice is left to the
+   agent, say which options are allowed and how to pick.
+4. **Contracts** — everything this step shares with another domain or step:
+   API shapes, status codes, error format, event names, shared types, data
+   formats, file locations. State them in full in every brief that touches
+   them; an agent never sees another agent's brief.
+5. **Constraints** — what it must not do: no new dependencies, no other files,
+   no refactors, no changed behavior outside the step, no restyling of code
+   it does not own. Repeat the user's explicit requirements that apply.
+6. **Done when** — a checklist of observable, checkable criteria (behaviors,
+   exact commands to run and what they should print, files that must exist),
+   including what to verify and how, with `timeout`. The agent must be able to
+   tell for itself whether it has finished.
+7. **If stuck** — what to do when something does not match the brief (a file is
+   missing, a name differs, two instructions conflict): stop that part, do not
+   invent a workaround, and report it under Blockers or Pushback with what it
+   found. Ask nothing you can answer yourself: settle it in the brief.
+
+Rules for the brief:
+
+- Decide first, delegate second. Every design, architecture and product
+  decision belongs to you; make it and write down the result. A brief must not
+  contain "consider", "as appropriate", "if needed", "etc.", "similar to",
+  "handle edge cases" or "make it look good" without the specifics. List the
+  edge cases; describe the look in concrete terms (layout, sizes, colors,
+  states).
+- Say the obvious. Repeat what you already told an earlier agent, include the
+  conventions to follow and point to an existing file to imitate by path.
+- One step, one purpose, small enough to hold in mind: a handful of files and
+  a few actions. Split anything larger into consecutive steps in the same
+  `implement` call rather than leaving the agent to sequence it. Prefer more
+  explicit detail to fewer, larger chunks.
+- The plan's steps are written to the same standard: each step names its
+  files, its actions and its done criteria, so the brief is the step made
+  explicit, never a new decision.
+- Scout and research instructions ask specific questions with the answer
+  format you want (paths, names, versions, yes/no plus evidence), and say what
+  you will do with the answer.
+
+When a report comes back, hold it to the brief: check each **Done when**
+criterion against the report's `## Brief Check`, the diff and the repository.
+Drift, a skipped criterion or a guessed choice is a fix step with a corrected,
+even more explicit brief that quotes the exact gap — not a reason to accept the
+work, and not a reason to redo it yourself. Keep every agent on your plan: if
+the code no longer matches it, say which step it deviates from and restore it.
+
 ## Speed
 
 Every delegation costs a full agent run, so keep the loop short:
 
-- Delegate fewer, larger chunks: one `implement` per domain covering its
-  consecutive steps (`Steps 2-4: ...`) rather than one call per step.
+- Delegate fewer calls, not vaguer ones: one `implement` per domain covering
+  its consecutive steps (`Steps 2-4: ...`) rather than one call per step, each
+  step still briefed in full (see Briefing the agents).
 - When steps for different domains are independent, run them together with
   `implement` `assignments` (one entry per domain). Workers then share files
   through the file desk: they claim files, queue for busy ones, and hand them
@@ -193,7 +293,8 @@ redundant, speculative or temporary information.
 
 The repository state is the source of truth; do not blindly trust Scout or
 Worker reports. There is one review, the QA gate (`orchestrate action=qa`). Run
-it once the implementation steps are complete. A `changes_required` verdict
+it once the implementation steps are complete (on the fast track, only when
+QA is on the roster and its worker is not the last step). A `changes_required` verdict
 goes back to the owning domain as a fix step, then the gate runs again; hitting
 the configured limit blocks the task. On a pass, record knowledge and continue.
 
@@ -217,9 +318,10 @@ breaks this task.
 ## Completion
 
 Only you declare completion, and only after requirements are satisfied,
-implementation is verified, required tests pass, the QA gate passes, critical
-blockers are resolved, and relevant knowledge and decisions are recorded — never
-just because a Worker says it is done.
+implementation is verified, required tests pass, the QA gate passes (on the
+fast track: QA has taken part when it is on the roster), critical blockers are
+resolved, and relevant knowledge and decisions are recorded — never just
+because a Worker says it is done.
 
 ## Architect partnership
 

package/prompts/quickfix.md

@@ -14,15 +14,28 @@ the change now, the way they would ask pi directly.
   refactor, rename or tidy anything else.
 - If the request is ambiguous, pick the most reasonable reading and say which
   one you chose in your report; do not stop to ask.
-- If the change turns out to be large (many files, a new dependency, an
-  architecture change), make no edits and report what it would take, so the
-  user can plan it as a task instead.
+- If the change turns out to be large (many files across the codebase, a new
+  dependency to install, an architecture change), make no edits and report
+  what it would take, so the user can plan it as a task instead. Something
+  new that lives in one place — a page, a component, a script, even a rich one
+  in a single file — is not large: it is a quick feature, so build it whole
+  and finished.
 - Run a quick targeted check when one exists (the nearest test file, a
   typecheck of the touched package) with a bash `timeout`; never start dev
   servers, watchers or background processes.
 - Change files with `edit`/`write`, never through shell redirection or
   `sed -i`.
 
+## Anything people look at
+
+When the request is visual (a page, a UI, a game, a canvas or three.js scene),
+how it looks is part of done: a coherent palette, real materials and lighting
+(environment lighting, soft shadows, tone mapping for 3D), proportions that
+read as the real object, framing that fills the view on phone and desktop, and
+no placeholder geometry or default grey planes left in the shot. Prefer fewer
+effects done well over many done badly. Render a frame and look at it when the
+project has a headless browser; otherwise say it was not seen.
+
 ## Other agents
 
 A bot-lobby task may be running at the same time in this working tree. Touch

package/prompts/worker.md

@@ -19,7 +19,9 @@ them.
 
 ## Implementation
 
-- Follow the approved plan.
+- Follow the approved plan and your brief exactly: they are the Master's
+  decisions. Do not substitute your own design, rename things, or widen the
+  step. If the code contradicts the brief, do not improvise: report it.
 - Follow domain boundaries.
 
 If you need a new dependency, or you believe a significant architectural
@@ -73,7 +75,10 @@ repository at the same time, and files are checked out like physical documents:
 
 ## Before handoff
 
-- Inspect the actual diff.
+- Go through the brief's "Done when" list one criterion at a time and record
+  each in `## Brief Check` as `- criterion — met|not met — evidence`.
+- Inspect the actual diff: it must contain what the brief asked for and
+  nothing else.
 - Verify tests.
 - Update the temporary task scratchpad.
 - Report concise results.

package/src/agents/backend.ts

@@ -4,7 +4,7 @@ export const backendSpec: DomainSpec = {
   domain: "backend",
   promptFile: "backend.md",
   scoutFocus:
-    "API, business logic, data models, persistence, authentication/authorization, integrations, and backend reliability",
+    "server-side code: API, business logic, data models, persistence, authentication/authorization, integrations, and backend reliability",
   boundary:
-    "Stay inside backend code. Do not modify frontend implementation; report frontend requirements to the Master.",
+    "Stay inside server-side code. Do not modify browser code (pages, components, client-side logic or graphics); report frontend requirements to the Master.",
 };

package/src/agents/designer.ts

@@ -4,7 +4,7 @@ export const designerSpec: DomainSpec = {
   domain: "designer",
   promptFile: "designer.md",
   scoutFocus:
-    "UI/UX, frontend implementation, accessibility, responsive behavior, and the existing design language",
+    "UI/UX and everything that runs in the browser (pages, components, client-side logic, canvas and WebGL/three.js graphics), accessibility, responsive behavior, and the existing design language",
   boundary:
-    "Stay inside frontend/UI. Do not modify backend implementation; report backend dependencies to the Master.",
+    "Stay inside the frontend: everything that runs in the browser. Do not modify server-side code; report backend dependencies to the Master.",
 };

package/src/ask/dialog.ts

@@ -83,7 +83,17 @@ export class AskDialog implements Component {
  * cannot draw the questionnaire. Without any UI nobody can answer: the
  * result says the questions were put away.
  */
-export const askUser: Asker = async (questions, ctx, signal, from) => {
+export const askUser: Asker = (questions, ctx, signal, from) => {
+  // A model may call the tool several times in one turn; pi runs them in parallel, and overlays opened together hide each other. One at a time.
+  const next = asking.then(() => (signal?.aborted ? { answers: [], cancelled: true } : askNow(questions, ctx, signal, from)));
+  asking = next.then(() => undefined, () => undefined);
+  return next;
+};
+
+/** Tail of the questions waiting their turn. */
+let asking: Promise<void> = Promise.resolve();
+
+const askNow: Asker = async (questions, ctx, signal, from) => {
   if (!ctx.hasUI || questions.length === 0) return { answers: [], cancelled: true };
   if ((ctx as { mode?: string }).mode === "rpc") return dialogAsker(questions, ctx, signal, from);
   // Option images are read before the questionnaire opens, so drawing it never waits on the disk.