miklschmidt/archboard / skills/archboard-plan
archboard-plan
VerifiedUse whenever to-spec, to-tickets, or implement-spec runs in a repository with an .archboard/vault directory. Load it before that skill's first step, and never run any of those three skills there without it.
Archboard Plan
Carry one Archboard proposal through a spec, its tickets and their implementation. A proposal is a draft of the architecture that the spec builds, kept beside Current in the vault. The spec shows the proposal, each ticket owns one slice of it, and each ticket merge stays inside the proposal.
Run the steps of this skill inside the steps of the skill that you run: to-spec, to-tickets or implement-spec.
That skill keeps its own process. This skill adds the architecture to it.
Before the first architecture operation, load the archboard skill. It owns every command, request schema and recovery recipe.
With to-spec
-
While you sketch the seams, author one proposal for the whole spec through the
archboardproposal recipe. Name it after the feature. Give it the spec's problem as its summary. Put every module, relationship and flow that the spec adds, changes or removes in the proposal. Bind each new module to the path that will hold its source. The footprint sees only bound modules, so an unbound new module hides every change made in it. -
Show the user the seams beside
archboard model compare --state <proposal>. A seam is a module interface. Read each one witharchboard model inspect <module> --state <proposal>. Give the user the link to the proposal (see links). Change the proposal until the user confirms the seams and the proposal together. -
Add this section to the spec, after Implementation Decisions:
Architecture Proposal
- Proposal: the proposal's name and stable ID, and the model ID.
- Link: the link to the proposal, compared with its base.
- Picture: a picture from
archboard model render --state <proposal> --out <file>, so that readers without a local server see it. - Changes: one line for each added, changed or removed subject from the comparison, in the domain language of the spec. Interface changes first.
- Commit the vault files of the proposal before you publish the spec, so that every branch and worktree reads the same proposal.
Done: the spec names the proposal, and the comparison lists every architectural change that the spec describes.
With to-tickets
-
Read the proposal and its comparison:
archboard model compare --state <proposal>. -
While you draft the vertical slices, give each ticket one slice of the proposal:
- A tracer bullet owns a flow: the path that it cuts through the modules, and the subjects on that path that change.
- A prefactor owns the modules and interfaces that it changes.
- In a wide refactor, the expand ticket owns the added subjects, and the contract ticket owns the removed subjects.
If a tracer bullet has no flow in the proposal, add the flow to the proposal first. Include both endpoint modules of each changed relationship or message in its ticket's slice. The footprint names those modules even when their own definitions stay unchanged.
-
Give each architectural change in the comparison exactly one owning ticket. If a change has no ticket, add it to a ticket or remove it from the proposal with the user's agreement. A module can appear in several slices when tickets own different changes or use it as an endpoint. State each ticket's change to that module, and order overlapping code changes through blocking edges.
-
When you quiz the user, add two lines to each ticket of the breakdown:
- Architecture: the subjects or the flow that the ticket owns.
- Link: the link to its slice (see links).
-
When you publish the approved tickets, add this section to each ticket:
Architecture
- Proposal: the proposal's name and stable ID.
- Slice: the qualified IDs of the subjects and endpoint modules, with the change that this ticket owns. Include its flow's ID.
- Link: the link to the slice.
- Gate: before this ticket merges,
archboard model footprint --base <integration-branch> --head <ticket-branch> --state <proposal-id> --model-at checkout --fail-outsideexits 0. Each module innamedAndChangedis in this slice.
Done: each architectural change has exactly one owning ticket, and each published ticket names its slice and its gate.
With implement-spec
-
Read the proposal and the Architecture section of each ticket.
-
You, the orchestrator, are the only writer of the proposal. If parallel worktrees edit the vault, their changes conflict at the merge. Tell each implementer subagent its slice. Tell it to report each module that it changed outside its slice, with the reason, and to leave the vault unchanged.
-
Before you merge a ticket branch, run its gate in the worktree of the integration branch:
archboard model footprint --base <integration-branch> --head <ticket-branch> --state <proposal-id> --model-at checkout --fail-outside--model-at checkoutreads the proposal on disk. You edit the proposal in this worktree, so the vault at the ticket branch does not hold your edits.If the command exits 2, resolve its refusal or unread source before merging, then run the gate again. Exit status 1 means that a changed module outside the proposal fails the gate. A module bound to a directory passes when each file that it changed lies in the binding of another changed module inside it. For example,
Workspaceis bound tolibs/workspaceandInstallationtolibs/workspace/src/installation.ts. A change toinstallation.tschanges both.Workspacepasses, andInstallationfails unless the proposal names it. A change tolibs/workspace/README.mdchanges onlyWorkspace, soWorkspacefails. A change to both files failsWorkspacetoo, because onlyWorkspacebindsREADME.md. Exit status 0 means that no module read by the footprint fails the gate. ComparenamedAndChangedwith the ticket's slice. A changed module absent from this ticket's slice is a deviation, even if another ticket owns it. ReadskippedandunboundFiles.unboundFileslists each changed file that no module is bound to, in each repository thatrepositorieslists with the statusread. It never fails the gate. If the ticket changed a repository thatrepositoriesdoes not list asread, read that repository's diff yourself. For each listed file, do one of these:- If the file belongs to a module of the slice, bind that module in the proposal so that its binding holds the file.
- If the file belongs to no module, such as a fixture, a document or a build file, write why on the ticket.
- If the file is a new part of the architecture, treat it as a deviation.
-
For each deviation, find the reason, and then do one of these:
- If the code is wrong, send the ticket back to its implementer.
- If the proposal is wrong or incomplete, edit the proposal so that it describes the code.
Write the reason in the edit's
--doingline, for example--doing "Deviation in <ticket>: the worker reads the queue directly, because <reason>". Archboard keeps that line in the proposal's history. It holds 140 characters at most, so put the full reason on the ticket. Add the same reason to the ticket. If the change moves a subject between slices, update both tickets. - If the change has no architectural meaning, such as a comment or a rename inside the module, the proposal stays as it is.
Record the reason through a claimed
model editwithproposal:{"type":"edit"},changes:[], and the reason in--doing. This keeps the architecture unchanged and retains the reason in the proposal history. Put the full reason on the ticket and in the merge commit. This deviation alone lets the branch merge while the gate fails. - If the change alters an interface or a decision that the user confirmed, show the user the difference and the reason. Wait for the user's decision, and continue with the other tickets meanwhile.
Run the gate again. Merge only after accounting for
skippedandunboundFiles, with exit status 0 or recorded exceptions for exit status 1. -
After the code review, read the footprint of the whole integration branch:
archboard model footprint --base <default-branch> --head <integration-branch> --state <proposal-id> --model-at checkout --fail-outside archboard check code --state <proposal-id>Resolve any exit status 2, and account for
skippedandunboundFilesas before each ticket merge. If the command exits 1, treat each module that it names as a deviation, as in step 4. Adopt only after exit status 0 or a recorded exception for each module. Explain each module innamedNotChanged: unfinished work, a planned change that needed no code, or a change outside the symbol that its binding names. Fix each finding of the code check that the work caused. -
If the user authorized the work that the spec describes, adopt the proposal on the integration branch. Use the
archboardproposal completion recipe, and commit the vault. If you open a pull request, load thearchboard-prskill for its body.
Done: every ticket passed the gate or has a recorded exception for changes without architectural meaning. Every deviation has its reason in the proposal history and on its ticket. The proposal is adopted, or the user made another decision.
Links
A link opens a reading of the proposal in the Archboard browser. If the server is not running, start it with archboard start.
The release server listens on http://archboard.localhost:4242. If ARCHBOARD_URL is set, use its address.
http://archboard.localhost:4242/?modelA=<model-id>&stateA=<proposal-id>
Add these parameters to read a slice:
focusA=<id>,<id>: show only these subjects, with their containment paths.grammarA=sequence&flowA=<flow-id>: show one flow as a sequence diagram.againstA=<state-or-checkpoint>: compare with another base than the default.
Write each # of a qualified ID as %23, because a browser reads # as the start of a fragment.
The browser reads the checkout that this machine chooses for the repository, and archboard repo list names it.
If the proposal is in another checkout or worktree, run archboard repo use <checkout>, and tell the user that you changed the choice.
Open each link once before you give it to the user, and make sure that it shows the proposal and the slice.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |