miklschmidt/archboard / docs/design/skill-evals/baseline/archboard
archboard
VerifiedDiagram real code as archboard semantic boards with the archboard CLI: create an architecture diagram (parts, containment, relationships) or a sequence diagram (an ordered exchange) from source, edit an existing board, propose an architectural change as a variant and compare it, bind parts to code, render SVGs and PNGs. Use when asked to document, explain or change a system's architecture, a request or data flow, or a board in the vault.
Archboard
An agent states what an architecture IS; archboard draws it. A board is one document in the vault holding a family of variants (the current architecture and proposals derived from it). There is no layout to author: every picture is rendered from meaning. Fix a semantic error in that meaning; when the saved meaning matches the source and the picture does not, report a renderer defect.
Two diagram types, one board:
- Architecture diagram: nodes (with a configured
kind, a clear shortresponsibility, optionalparentcontainment,groups, a codebinding), directed relationships (edges) between them, and board-ownedviewsthat read a region of it. Use it to answer "what are the parts and how are they wired". - Sequence diagram: a
flow(participants in column order, ordered steps with a message kind) drawn through adata-flowview. Use it to answer "what happens, in what order, for one request or job". A flow lives on the same board as the parts it moves between.
Use a variant for a proposed evolution of the same diagram, and a separate linked board for a different subject or level of detail.
Write responsibilities as clear prose that usually reads over two or three
card lines. Newlines are optional: the renderer wraps and shows the complete
value, and rendered line count is not a validation limit. Put longer detail in
description.
Essentials
- The CLI is the only way a board changes. Every board is a file the
server owns; you never read one to edit it and never write one. Its ids,
version, timestamps,lifecycle,adoptionsandreconciliationare the product's outcome of your writes, not fields you author or repair. When a write is refused, repair the payload from what the refusal says; a second attempt needs new evidence, not a retry. When no supported command can do what was asked, leave the board valid as it is and report the requirement you could not meet. - Environment. The repository's
AGENTS.md/CLAUDE.mdsetup block namesARCHBOARD_VAULT(andEXPRESS_SERVER_URLwhen the canvas is not on the default port). Everyarchboardcommand reads them; the canvas starts itself when nothing answers. Inside the archboard checkout,./bin/canvasstands in forarchboard. - Vocabulary. Read
$ARCHBOARD_VAULT/.archboard/config.yamlonce: it defines the boardlevels, thenodeKinds, therelationshipKindsand thegroups. Use those keys; a new unknown key is refused. Extend the file only when the request is about vocabulary (schemas links its JSON Schema); then runarchboard check. - Reads.
archboard semantic show <board>prints the whole family: every variant with itslifecycle,parent,contentand the boardversion.archboard semanticlists the boards. - Writes.
semantic newneeds--doing "<present-tense line>". Every later write (edit,branch,resolve,adopt) also needs--expect-version <n>with the version you read; a moved board refuses the write (exit 5) and you read again and redo the change on what is there now. One requested change is one batch. The answer to a write is the saved family with its newversionand every minted id, so take ids and the version from it rather than reading again. - References. Inside a payload, name a node by its
nameor itsid; a relationship or step, which has no name, byidor by a same-write handleas. New subjects leaveidout. A restated subject replaces its previous definition whole, so restate the fields you keep. A relationship restated without itsidis a new relationship, however familiar its endpoints: to change one property of an existing relationship (its traffic, its label), restate it with theidyou read, and never remove it to add it again. - Verification. Read the write's answer back against the checks you wrote
down before writing (below). When the picture is the deliverable, draw it
and look at it:
semantic rasterize <board> --out <file.png>and open the PNG, orsemantic render <board> --out <file.svg>and open the SVG in a viewer. Reading the SVG's text is not looking at a diagram.archboard checkis for after a vocabulary edit or when an answer carrieswarnings. - Open questions. A question about the product (a field, a selector, what
a refusal means, what a command accepts) is answered by the references
below, the generated JSON Schemas under
references/generated/, andarchboard <command> --help. When none of them answers it, say so in your final message, naming the question; that report is how the skill gets the answer added. - Claims. For work of several writes,
archboard claim --board <board> --reason "<campaign>"first andarchboard release --board <board>after. A person can take the claim back: your next write is then refused once, nothing is rolled back, and you stop and say so.
Evidence before a write
Reading the right guidance and the right source is not enough: a relationship is a claim about code, and the failures that recur are claims nobody checked. Do this in proportion to the request. A rename needs one line of it; a new board needs all of it.
- Turn the request into checks. Before the payload, write down what a
correct answer must show: the board and the
versionyou read; the target variant (a proposal names it invariant; a batch withoutvariantedits the current architecture, so a proposal-only request lands nothing there); the ids and fields that must survive; and for a view, its exactgrammarandscopeselectors: namingedgesisolates those relationships and draws no other, while namingnodesalone draws every relationship among them. After the write, read the answer against that list. - Prove each relationship and step from source. For every
edgeand every flow step keep a one-line record:from→to, the semantic kind, and the source file and function or symbol that prove the mechanism. For a call (a function or method call, a hook, a component rendering another),fromis the part whose body makes it andtois the part whose body runs, inside itsparent; a container is an endpoint only when the source addresses the whole module. A part you draw with children is a container whatever its kind: once a module, class or component is drawn holding its functions, methods or child components, a call into it lands on the child whose body runs, not on the container, and giving an existing part children moves every relationship that landed on it to the child whose body runs. For a return or a non-call relationship, state the directional claim in words and make the endpoints follow it (for example, A returns to B, A reads from B, A emits an event B handles, A resolves a promise B awaits, A passes B a callback or props, or A depends on B). Sibling calls are not a chain: whenapply()callsvalidate()and thenpersist(), the source shows two relationships fromapply, and none fromvalidatetopersist, whatever order they run in. For a sequence also check the order the source runs them in, which steps return to their caller, which branch and under what condition (say it in anote), and whether a repeat count is in the source at all (a loop,mapor retry over a list the source fixes, such as two candidate file names, is arepeatof that count; a loop over a list of unknown length is anote, not arepeat). - Find the boundaries on purpose. Before deciding the parts, look for what calls into this code (a server, a scheduler, a shell, a user event in a browser, a message consumer), the external libraries and services it depends on, the callbacks, hooks, handlers and plugins the application registers into it, and where it persists or publishes (a store, a queue, a socket, an event bus, a stream). Include the ones the board's question needs and leave the rest out deliberately; a boundary you never looked for is an omission, one you chose to omit is scope.
- Bind to the owner. A
bindingnames the file that implements the node's stated responsibility, not a file that imports, registers or calls it. A planned part or an implementation unavailable for inspection stays unbound. An implementation in another checkout may bind after you inspect its owner and register that repository. When a node's responsibility spans files, narrow the responsibility or split the node rather than bind to the wrong one.
Everything the code shows
A request names the question, the level and a few names. It does not list the semantics; knowing the product is your job, and a board that stops at the parts and calls the request happened to mention leaves out what the code showed you. Before every write that creates or extends a board, walk this catalogue against the source you read, in this vocabulary (the grader uses the same words); every row the source justifies goes in the payload, and your answer says which rows you used and which you judged not to apply.
| Row | When the source shows | You author |
|---|---|---|
external | a caller, library, service, shell or hypothetical part outside the checkout | a node of kind external, unbound |
binding | the file whose body implements a part's responsibility | binding: { repo, path } to that file; nothing for a part you could not inspect |
containment | a part defined inside another (a function of a module, a method of a class, a child component, a closure inside its factory) | parent |
relationship | a call, render, read, event, message, dependency or publication one body makes to another | an edge of the configured kind, its label the message or mechanism |
traffic | the path a request or event takes at runtime, as against setup, registration or teardown | traffic on those relationships ({}, or speed/volume to contrast a hotter path); none elsewhere |
emphasis | the few lines the board exists to show, and lines that are only context | emphasis: "hero" on the few, "muted" on the context |
repeat | a loop over a list the source fixes, or a retry limit | repeat with that count on the step |
note | a branch and its condition, a data-dependent loop, an environment variable, a caveat | note on the step |
groups | a part whose concern is a configured group id in config.yaml (read them before every write) | groups on each member, explicit, across containers |
flow | an ordered exchange the question is about (handling a request, a user interaction, a pipeline run, starting up, a lifecycle) | a flow and a data-flow view over it |
view | a subset a reader wants alone: one path, one container's internals, the two sides of a change | a board view |
walkthrough | a why the code enforces (an ordering, an invariant, a lock held around a write) | a walkthrough beat whose subjects are the parts, relationships or steps it explains |
drillDown | a part whose internals already have a board (archboard semantic lists them; check first) | drillDown to that board instead of its parts again |
description | a mechanism a one-line responsibility cannot hold | description on the node or relationship |
A row the source does not support stays out: an added relationship without a line of evidence is a wrong board, not a complete one.
Which recipe
Every request is one of four workflows, and each has one recipe holding the payload shape, a worked example from archboard's own source and the checks to read the answer against. Read the recipe before the first command of that workflow; it is the one reference a common path needs beyond this file.
| The request asks you to | Read |
|---|---|
| describe code as parts and their wiring, at a level, on a new board | create an architecture diagram |
| explain one request, job or startup as an ordered exchange | create a sequence diagram |
| change, extend, correct or repair what an existing board says | edit an existing board |
| propose a change as a variant, compare it, settle its disagreements, or adopt it | propose and compare a change |
| answer a question from a saved board and change nothing | semantic show and semantic inspect in authoring |
A request that combines them (extend the vocabulary, then create; link a detail board, then propose) reads each recipe it needs, in the order the request runs them.
Keep it true
- Author meaning. When the picture is wrong and the meaning is right, report the renderer defect; the architecture stays as the code has it.
- Every relationship and step has a line of source evidence; a picture that needs a relationship the source does not have is a wrong picture.
- Use the configured vocabulary and levels; extend
config.yamlonly when the request is about vocabulary. - Reuse an existing detail board; link to it with
drillDowninstead of duplicating its parts. - Fewer, truer parts: every node has a responsibility the source supports, and a binding only to the file that implements it.
- Traffic (
"traffic": {}, orspeed/volume) is authored intent, never a measurement: choose it from what the source says runs per request, not from numbers you do not have. A still picture shows the marks at rest and proves nothing about motion. - A refusal is repaired from its reason. Never edit the vault to get past one, never invent an id, and when the CLI cannot do what was asked, say what remains open rather than approximate it.
When to read more
| Read | When |
|---|---|
| create an architecture diagram | the recipe: level, registration, one payload with parts, containment, relationships and bindings, and its checks |
| create a sequence diagram | the recipe: participants, message kinds, repeat and note, the data-flow view, and its checks |
| edit an existing board | the recipe: continuing, replacement and untouched subjects, one batch at the read version, and its checks |
| propose and compare a change | the recipe: branch, variant-targeted edit, both pictures through one view, the comparison report, adoption |
| authoring | groups and semantic inspect, bindings with branch/commit, drill-down, traffic, emphasis, removals, refusals |
| sequences, views and walkthroughs | view scopes and grammars, message kinds, repeat/note, walkthrough beats and their identity |
| variants | what a comparison counts, edge identity, flow/step identity, reconciliation and resolve, adoption, claims |
| schemas | the exact JSON Schemas of the payloads, the persisted document and config.yaml; vault setup and installation |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |