arch-board
Run a board of expert minds that investigates a challenge from independent
angles, debates the cruxes, and converges on a designed solution, or on a
well-characterized disagreement worth the user's call. Its value is
diversity under discipline: several strong lenses, each reasoning alone first,
then tested against one another. A challenge with one obvious approach does not
need a board.
"Board" here means this deliberation only, not a task or issue board.
There is always exactly one team-lead who owns the reasoning: framing,
seating the roster, distilling cruxes, moderating, and writing the verdict.
Members never talk to each other; everything routes through the team-lead.
Paths below are relative to this skill's directory; resolve them to absolute
paths before running anything.
Where things live
This repository's agent configuration should have been provided to you (the
## Agent skills block pointing at docs/agents/). If it is missing, use the
defaults below and suggest the user run the setup-aclarify-skills skill.
- Scratch folder (
docs/agents/workspace.md): where the board directory
lives. Default: .scratchpad/ at the repository root, git-ignored.
- Conventions folder (
docs/agents/workspace.md): the house engineering
principles and coding standards every member weighs a design against.
Default: none; the repository's agent instructions and code are the
conventions.
- Glossary and decision records (
docs/agents/domain.md): the domain's
vocabulary and the choices already settled. Defaults: GLOSSARY.md at the
root (a multi-context repository adds GLOSSARY-MAP.md), decision records in
docs/adr/. A file that does not exist is skipped silently.
- Issue tracker (
docs/agents/issue-tracker.md): where to read the issue a
challenge came from. Default: none configured.
Which role you hold
Members are subagents, and the board runs best when they run in parallel. The
top level is the one place a parallel fan-out is guaranteed; a subagent's own
spawns often are not. So the role that spawns members sits at the top level, and
the reasoning sits in a subagent that keeps the deliberation out of the caller's
context. Pick the first case that fits:
- You are top-level, and you can dispatch subagents in parallel and continue
one you started with its context intact (the user's
/arch-board, a
top-level skill, an unattended run): you are the hands. Follow
references/handshake.md: start one team-lead
subagent, the brain, from references/team-lead.md,
spawn members when it asks, relay paths, and leave the deliberation unread.
- Your prompt names you this board's brain: reason and request; the hands
spawn. Your prompt carries the request forms; this file and
references/templates.md carry the rest.
- You can dispatch subagents but have no hands partner (another caller
invoked you as a subagent, or you cannot continue a subagent you started): you
are both team-lead and hands. Spawn members yourself, in parallel where you
can and one at a time where you cannot, and follow
references/handshake.md for the thin pointer, the
per-member check and persisting a member's
PATH: result, and
templates § Writing a board file
for when your own file is refused. Record a serial run in frame.md.
- You cannot dispatch subagents: you are the team-lead and you play each
seat yourself, one at a time. Write each member's position from its
assignment alone and place it before you start the next; never revise an
earlier position after reading a later one, because the debate is where the
seats meet. Record a single-agent run in
frame.md, and say in the verdict's
Board section that the positions were not independent.
Two placeholders recur, and every agent passes both on literally as absolute
paths, because a relative path resolves against the wrong checkout in a
subagent:
<skill-dir>: this skill's absolute directory. The hands resolve it when they
load the skill; the brain has it as SKILL DIR in its prompt.
<scratchpad>: the command prefix for the scratchpad skill's script,
bash '<absolute path to its scripts/scratchpad.sh>', with
--dir '<folder>' appended when the scratch folder is not .scratchpad/.
Whoever opens the board resolves it once and writes it into every assignment.
Never ask; return needs-input
A subagent cannot reach the user: it has no way to put a question to them and
wait. When the board meets a choice that is genuinely the user's, the brain ends
the pass with a needs-input result, and the hands carry it out. Where the
user is in the conversation, the hands ask them directly, with the board's lean:
using your structured-question tool if you have one; otherwise list numbered
options in plain text and stop until they reply. In an unattended run, the hands
take it out by whatever route their runner gives questions for a person. Either
way the question travels out rather than being settled by whichever member met
it: delegating the work never delegates a decision that was the user's.
Invocation
Inputs, parsed from how you were called rather than demanded as flags:
- Challenge (required): the bug, enhancement, question or design problem.
- Roster (optional): seats the caller named, any personas or roles at all,
used verbatim; otherwise the team-lead seats by judgement.
- Repository (optional): the checkout the design is for. Default: the
repository you were invoked from.
- Continuation (optional), one of two kinds: feedback on a prior board
directory's
BOARD-RESULT.md, which opens the next round; or an answer to
that board's NEEDS-INPUT-<q>.md, which resumes the same round.
Outputs: the board directory and the verdict summary, which repeats every
open question for the user; or a needs-input result.
The phases
The brain reasons through every phase; the hands perform the spawns it asks
for. Every board file is written by the route in
templates § Writing a board file.
- P0 · Frame (brain). Read the challenge and gather context: the target
repository's agent instructions (
AGENTS.md, CLAUDE.md or its equivalent)
and its code, the issue it came from if there is one, the decision records and
glossary that touch the area, and the conventions folder's engineering
principles. Open the session directory: load the scratchpad skill (through
your skill tool, /scratchpad, or by reading its SKILL.md), resolve
<scratchpad>, and run <scratchpad> new arch-board '<slug>' as one plain
command, never wrapped in $(…), keeping the absolute path it prints.
scratchpad finds its root from your working directory, so read THE REPO by
absolute path and stay in the checkout you started in. If scratchpad is not
installed, create <scratch folder>/arch-board/<UTC-YYYYMMDD-HHMMSS>-<slug>/
at the top of the main checkout (the first path git worktree list prints),
make sure git ignores the scratch folder, and write board files there directly.
Write frame.md: problem, domains touched, roster and why, sizing, and how
the run is staffed (parallel, serial or single-agent).
- P1 · Roster (brain). Seat the caller's roster as given, or seat by
judgement. references/board-members.md holds
example personas and the sizing heuristic, not a closed list: draw from it, or
coin any persona the challenge needs in the same brief shape. When seating by
judgement, keep its two staples and at least three seats. Write each member's
assignment, from references/member.md, to
round-N/_assignments/<member>.md.
- P2 · Independent positions (hands spawn). Each member gets a thin
pointer to its assignment, blind to its peers, and writes
round-N/01-positions/<member>.md. The file is the deliverable.
- P3 · Debate (brain moderates, hands spawn). The brain reads every
position, distills the genuine cruxes and the falsifiers members exposed, and
writes exchange
<k>'s assignments; members answer in
round-N/02-debate/<k>/<member>.md. Each exchange gets its own <k>, from 1.
Loop until the board converges or reaches a stable, well-characterized
disagreement, never a forced consensus. Often one exchange is enough.
- P4 · Synthesis (brain). Load the
conveying-clearly skill (through your
skill tool, /conveying-clearly, or by reading its SKILL.md) first and hold
the verdict to it hardest: it is written at the board's most
jargon-saturated moment for a reader who never watched the debate. Without it,
hold to the rules the schema states. Write round-N/BOARD-RESULT.md to the
schema in references/templates.md.
Done when a teammate who missed the session could act on it unaided.
- P5 · Handoff (brain, then hands to the caller). Return the verdict, the
board directory, the next step and the continuation hint, held to the same
standard as the verdict, with every open question for the user repeated in the
summary.
Persistence and continuity
The session directory is the board's memory, and the brain owns the round
structure inside it. scratchpad roots it in the main checkout's scratch
folder, so a board convened from a worktree survives that worktree. Below,
.scratchpad/ stands for whichever folder is configured:
.scratchpad/arch-board/<ts>-<slug>/
frame.md
round-1/
_assignments/<member>.md, <member>-debate-<k>.md
01-positions/<member>.md
02-debate/<k>/<member>.md
NEEDS-INPUT-<q>.md, 00-answer-<q>.md one pair per question for the user
BOARD-RESULT.md
round-2/
00-feedback.md
Feedback opens round-N+1/, re-seats as the feedback warrants, and runs
another pass. An answer resumes the same round where its question stopped
the board, through the live brain or a fresh one:
templates § Resuming on an answer.
The board directory is scratch: local to this machine and never committed. What
the board settles that must last becomes a decision record, which the verdict's
Handoff proposes and the user approves.
References
- references/handshake.md: the hands' protocol, the
thin pointer prompt, and persisting a
PATH: result.
- references/team-lead.md: the prompt that starts the
brain.
- references/member.md: the member's position and debate
assignments.
- references/board-members.md: the persona bench
and the sizing heuristic.
- references/templates.md: writing a board file, the
BOARD-RESULT.md schema, the needs-input shape, resuming on an answer.
scripts/persist-final-message.py: writes a member's PATH: final message to
the board file it names.
1---2name: arch-board3description: Convenes a board of whatever personas a design challenge needs (for example Martin Fowler, Rich Hickey, a security lens) that investigates it independently, debates the cruxes and returns a cited verdict with dissents kept. Use whenever a design fork is hard or cross-cutting, or on convene a board, get a panel to weigh in, deliberate the trade-offs, or what would <expert> think about this. Do NOT use to review an existing diff (`ocr-review-loop`), to root-cause a failure (`first-principles-investigation`), to interview the user about a plan (`grill-with-docs`), or for a change with one obvious approach.4license: MIT5compatibility: Best where the agent can dispatch subagents in parallel and continue one it started; degrades to serial members, then to one agent playing each seat. The transcript helper needs python3.6argument-hint: '<the bug, enhancement or design challenge to deliberate>'7metadata:8 source: https://skillmd.com/skills/spencermarx/arch-board9---1011# arch-board1213Run a **board of expert minds** that investigates a challenge from independent14angles, debates the cruxes, and converges on a designed solution, or on a15well-characterized disagreement worth the user's call. Its value is16_diversity under discipline_: several strong lenses, each reasoning alone first,17then tested against one another. A challenge with one obvious approach does not18need a board.1920"Board" here means this deliberation only, not a task or issue board.2122There is always exactly one **team-lead** who owns the reasoning: framing,23seating the roster, distilling cruxes, moderating, and writing the verdict.24Members never talk to each other; everything routes through the team-lead.2526Paths below are relative to this skill's directory; resolve them to absolute27paths before running anything.2829## Where things live3031This repository's agent configuration should have been provided to you (the32`## Agent skills` block pointing at `docs/agents/`). If it is missing, use the33defaults below and suggest the user run the `setup-aclarify-skills` skill.3435- **Scratch folder** (`docs/agents/workspace.md`): where the board directory36 lives. Default: `.scratchpad/` at the repository root, git-ignored.37- **Conventions folder** (`docs/agents/workspace.md`): the house engineering38 principles and coding standards every member weighs a design against.39 Default: none; the repository's agent instructions and code are the40 conventions.41- **Glossary and decision records** (`docs/agents/domain.md`): the domain's42 vocabulary and the choices already settled. Defaults: `GLOSSARY.md` at the43 root (a multi-context repository adds `GLOSSARY-MAP.md`), decision records in44 `docs/adr/`. A file that does not exist is skipped silently.45- **Issue tracker** (`docs/agents/issue-tracker.md`): where to read the issue a46 challenge came from. Default: none configured.4748## Which role you hold4950Members are subagents, and the board runs best when they run in parallel. The51top level is the one place a parallel fan-out is guaranteed; a subagent's own52spawns often are not. So the role that spawns members sits at the top level, and53the reasoning sits in a subagent that keeps the deliberation out of the caller's54context. Pick the first case that fits:5556- **You are top-level, and you can dispatch subagents in parallel and continue57 one you started with its context intact** (the user's `/arch-board`, a58 top-level skill, an unattended run): you are the **hands**. Follow59 [references/handshake.md](references/handshake.md): start one team-lead60 subagent, the **brain**, from [references/team-lead.md](references/team-lead.md),61 spawn members when it asks, relay paths, and leave the deliberation unread.62- **Your prompt names you this board's brain**: reason and request; the hands63 spawn. Your prompt carries the request forms; this file and64 [references/templates.md](references/templates.md) carry the rest.65- **You can dispatch subagents but have no hands partner** (another caller66 invoked you as a subagent, or you cannot continue a subagent you started): you67 are both team-lead and hands. Spawn members yourself, in parallel where you68 can and one at a time where you cannot, and follow69 [references/handshake.md](references/handshake.md) for the thin pointer, the70 per-member check and persisting a member's `PATH:` result, and71 [templates § Writing a board file](references/templates.md#writing-a-board-file)72 for when your own file is refused. Record a serial run in `frame.md`.73- **You cannot dispatch subagents**: you are the team-lead and you play each74 seat yourself, one at a time. Write each member's position from its75 assignment alone and place it before you start the next; never revise an76 earlier position after reading a later one, because the debate is where the77 seats meet. Record a single-agent run in `frame.md`, and say in the verdict's78 Board section that the positions were not independent.7980Two placeholders recur, and every agent passes both on literally as absolute81paths, because a relative path resolves against the wrong checkout in a82subagent:8384- `<skill-dir>`: this skill's absolute directory. The hands resolve it when they85 load the skill; the brain has it as `SKILL DIR` in its prompt.86- `<scratchpad>`: the command prefix for the `scratchpad` skill's script,87 `bash '<absolute path to its scripts/scratchpad.sh>'`, with88 `--dir '<folder>'` appended when the scratch folder is not `.scratchpad/`.89 Whoever opens the board resolves it once and writes it into every assignment.9091## Never ask; return `needs-input`9293A subagent cannot reach the user: it has no way to put a question to them and94wait. When the board meets a choice that is genuinely the user's, the brain ends95the pass with a **`needs-input`** result, and the hands carry it out. Where the96user is in the conversation, the hands ask them directly, with the board's lean:97using your structured-question tool if you have one; otherwise list numbered98options in plain text and stop until they reply. In an unattended run, the hands99take it out by whatever route their runner gives questions for a person. Either100way the question travels out rather than being settled by whichever member met101it: delegating the work never delegates a decision that was the user's.102103## Invocation104105**Inputs**, parsed from how you were called rather than demanded as flags:106107- **Challenge** (required): the bug, enhancement, question or design problem.108- **Roster** (optional): seats the caller named, any personas or roles at all,109 used verbatim; otherwise the team-lead seats by judgement.110- **Repository** (optional): the checkout the design is for. Default: the111 repository you were invoked from.112- **Continuation** (optional), one of two kinds: **feedback** on a prior board113 directory's `BOARD-RESULT.md`, which opens the next round; or an **answer** to114 that board's `NEEDS-INPUT-<q>.md`, which resumes the same round.115116**Outputs**: the board directory and the verdict summary, which repeats every117open question for the user; or a `needs-input` result.118119## The phases120121The brain reasons through every phase; the hands perform the spawns it asks122for. Every board file is written by the route in123[templates § Writing a board file](references/templates.md#writing-a-board-file).124125- **P0 · Frame** _(brain)_. Read the challenge and gather context: the target126 repository's agent instructions (`AGENTS.md`, `CLAUDE.md` or its equivalent)127 and its code, the issue it came from if there is one, the decision records and128 glossary that touch the area, and the conventions folder's engineering129 principles. Open the session directory: load the `scratchpad` skill (through130 your skill tool, `/scratchpad`, or by reading its SKILL.md), resolve131 `<scratchpad>`, and run `<scratchpad> new arch-board '<slug>'` as one plain132 command, never wrapped in `$(…)`, keeping the absolute path it prints.133 `scratchpad` finds its root from your working directory, so read THE REPO by134 absolute path and stay in the checkout you started in. If `scratchpad` is not135 installed, create `<scratch folder>/arch-board/<UTC-YYYYMMDD-HHMMSS>-<slug>/`136 at the top of the main checkout (the first path `git worktree list` prints),137 make sure git ignores the scratch folder, and write board files there directly.138 Write `frame.md`: problem, domains touched, roster and why, sizing, and how139 the run is staffed (parallel, serial or single-agent).140- **P1 · Roster** _(brain)_. Seat the caller's roster as given, or seat by141 judgement. [references/board-members.md](references/board-members.md) holds142 example personas and the sizing heuristic, not a closed list: draw from it, or143 coin any persona the challenge needs in the same brief shape. When seating by144 judgement, keep its two staples and at least three seats. Write each member's145 assignment, from [references/member.md](references/member.md), to146 `round-N/_assignments/<member>.md`.147- **P2 · Independent positions** _(hands spawn)_. Each member gets a thin148 pointer to its assignment, blind to its peers, and writes149 `round-N/01-positions/<member>.md`. The file is the deliverable.150- **P3 · Debate** _(brain moderates, hands spawn)_. The brain reads every151 position, distills the genuine cruxes and the falsifiers members exposed, and152 writes exchange `<k>`'s assignments; members answer in153 `round-N/02-debate/<k>/<member>.md`. Each exchange gets its own `<k>`, from 1.154 Loop until the board converges or reaches a stable, well-characterized155 disagreement, never a forced consensus. Often one exchange is enough.156- **P4 · Synthesis** _(brain)_. Load the `conveying-clearly` skill (through your157 skill tool, `/conveying-clearly`, or by reading its SKILL.md) first and hold158 the verdict to it hardest: it is written at the board's most159 jargon-saturated moment for a reader who never watched the debate. Without it,160 hold to the rules the schema states. Write `round-N/BOARD-RESULT.md` to the161 schema in [references/templates.md](references/templates.md#board-resultmd-schema).162 _Done when a teammate who missed the session could act on it unaided._163- **P5 · Handoff** _(brain, then hands to the caller)_. Return the verdict, the164 board directory, the next step and the continuation hint, held to the same165 standard as the verdict, with every open question for the user repeated in the166 summary.167168## Persistence and continuity169170The session directory is the board's memory, and the brain owns the round171structure inside it. `scratchpad` roots it in the main checkout's scratch172folder, so a board convened from a worktree survives that worktree. Below,173`.scratchpad/` stands for whichever folder is configured:174175```176.scratchpad/arch-board/<ts>-<slug>/177 frame.md178 round-1/179 _assignments/<member>.md, <member>-debate-<k>.md180 01-positions/<member>.md181 02-debate/<k>/<member>.md182 NEEDS-INPUT-<q>.md, 00-answer-<q>.md one pair per question for the user183 BOARD-RESULT.md184 round-2/185 00-feedback.md186```187188**Feedback** opens `round-N+1/`, re-seats as the feedback warrants, and runs189another pass. **An answer** resumes the same round where its question stopped190the board, through the live brain or a fresh one:191[templates § Resuming on an answer](references/templates.md#resuming-on-an-answer).192193The board directory is scratch: local to this machine and never committed. What194the board settles that must last becomes a decision record, which the verdict's195Handoff proposes and the user approves.196197## References198199- [references/handshake.md](references/handshake.md): the hands' protocol, the200 thin pointer prompt, and persisting a `PATH:` result.201- [references/team-lead.md](references/team-lead.md): the prompt that starts the202 brain.203- [references/member.md](references/member.md): the member's position and debate204 assignments.205- [references/board-members.md](references/board-members.md): the persona bench206 and the sizing heuristic.207- [references/templates.md](references/templates.md): writing a board file, the208 `BOARD-RESULT.md` schema, the `needs-input` shape, resuming on an answer.209- `scripts/persist-final-message.py`: writes a member's `PATH:` final message to210 the board file it names.