AGENTS.md git:20261023.5713e74A

Immutable. This exact content never changes and is served at /api/v1/blob/340b19b10a4f2c79.

# AGENTS.md

Conventions of the swarmstorm repository: the decisions a fresh agent would otherwise
guess differently. A rule may be deviated from at a specific site with a comment
beginning `AGENTS EXCEPTION (rule N):` and the reason; without one, deviation is a
review finding. When a decision made during a session would pass the five filters of
the `write-conventions` skill (contested, recurring, consequential, checkable, not
tool-enforceable), say so in chat before the session ends and propose the rule, in
that skill's shape; it is written here only on the person's yes.

## Architecture (context you must not break)

Every skill is one folder under `skills/`, opening on a `SKILL.md`; supporting files
sit beside it, situational ones under `references/`. `project/` holds what a project
has once and keeps, `verify/` its verification skill and the validation with the person, `workbench/` the pages worked on
with the person during development and the project skills that feed them; the loop's phases group the rest,
`architecture/`, `ui/`, `plan/`, `execute/`, `review/`; `interview/`, `orchestrate/`, `swarm/`, `brainswarm/` and `whiteboard-defense/` sit at the root;
`companions/` holds the two tools, shipped as versioned bundles so an install never builds:
aiview (`skills/companions/aiview/`), a CLI, the document server and the one UI, drawing the
documents and the board; and swarm (`skills/companions/swarm-board/`, the board every plan
runs on), a CLI, a board server and one link per member, with no page of its own. The board
server alone opens swarm's store; each member's link carries its calls over one WebSocket to
it. aiview reads the board only through `skills/companions/swarm-board/src/client/reader.ts`, a
client of that server, bundled into aiview's `dist-cli/`; never `board.ts` or SQL, and swarm
never imports aiview. The plugin sees a group only through the `skills`
list in `.claude-plugin/plugin.json`: the default scan reads one level under `skills/`,
so a group left off the list ships none of its skills, and `claude plugin validate`
passes all the same. What runs for a user is the plugin cache, not this checkout; a
change reaches anyone only through a release (`RELEASING.md`). Documents the skills
produce live in the data home, never here.

**This checkout is the only place this repository is edited.** The plugin cache under
`<claude home>/plugins/marketplaces/swarmstorm` is a clone of the same remote, with the
same branches and the same push rights, which is exactly the trap: work committed there
is real, is pushed, and leaves this checkout silently behind. It happened on 2026-09-10
— three releases were made in the cache, and this checkout then lacked a skill whose
file the person was looking for. Refresh the cache with
`claude plugin marketplace update swarmstorm`; never write to it.

## Skills

1. **MUST reference another skill by its name alone, the `<name>` skill.** The harness resolves a skill by name wherever it is installed; a path, relative or absolute, breaks on the next layout and is paid for at every load. A file inside another skill is named as that skill's `references/<topic>.md` or `scripts/<name>`.

2. **MUST keep in `SKILL.md` only what every use of the skill needs, and put what one situation needs in `references/<topic>.md`, named in `SKILL.md` at the point where the situation arises, with the condition to read it stated there.** Everything in `SKILL.md` is paid for at every load, and a condition written inside a reference is read only by an agent that has already opened it. `skills/companions/aiview/references/`, `skills/execute/execute-plan/references/`, `skills/ui/design-prototype/references/`.

3. **MUST write a description as the trigger and nothing else: what activates the skill, what it produces, what it excludes.** Method, mechanics and instructions to a loaded agent belong in the body, and the body carries no "when to use" section of its own. The router reads only the description; the agent reads the body only after.

4. **MUST give a protocol one owner and have every other skill point at it, never restate it.** Two copies drift, and the reader has to work out which lies. The tracker is `skills/execute/execute-plan/references/tracker.md`; diagram discipline is `skills/architecture/write-diagrams/`; the interview is `skills/interview/`; the index contract is `skills/companions/aiview/`; the board protocol is `skills/companions/swarm-board/`; a seat swarm's phases are `skills/brainswarm/`; the orchestrator's charter, dispatch, briefs, roles and watching are `skills/orchestrate/`.

8. **MUST write a skill, its examples included, only in terms every project has, never a file, module or name from the project the change came from.** A skill loads in every project; a foreign name reads as a fact about the current codebase, and the agent looks for it. Abstract the case to the rule it taught, and the counterweight it needed.

9. **MUST put a protocol used by more than one kind of work in a skill named for no kind, never in the first kind that needed it.** A plan-named owner reads as plan-only, and the next kind copies it instead.

10. **MUST let a CLI verb's answer carry the next step it asks for, and have the skill say only to read that answer and why.** A step written in both drifts, and the agent follows whichever it read last. The swarm-board skill's `references/plan-worker.md` names the verbs and their exits; the commands to run next are in their output.

11. **MUST NOT ship a harness hook (`hooks/hooks.json`, a `hooks` key in the plugin manifest, any PreToolUse, PostToolUse, Stop or other event hook), nor write to the person's harness settings (`settings.json`, `settings.local.json`, user or project).** A plugin hook runs in every session on the machine, in every project, whether or not a skill of this collection is in use, and a settings change outlives the session that made it. What a skill needs from the agent goes through the skill, its CLI's answers and the agent's own tools. A swarm member hears the board through its own listener or its own wait, and the orchestrator may always message a member directly; no skill forbids that.

## aiview

5. **MUST bundle a new runtime dependency into `dist-cli/` through `skills/companions/aiview/build.mjs`, never require `node_modules` at runtime.** An installed plugin has no `node_modules`; a bare import fails only for users. `parse5` and `mermaid` are bundled this way, the checker as its own bundle.

6. **MUST bump `version` to the same value in `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`, rebuild, and commit `dist/` and `dist-cli/` before pushing `main`.** Without the bump no existing user receives the change, and without the build they receive the old viewer. The sequence is `RELEASING.md`.

## Documents

7. **MUST NOT commit a board, spec, plan, mockup or report to this repository.** They are working material and go to the data home through `aiview path`; a document in the tree gets reviewed, goes stale and outlives its use. The README and `RELEASING.md` are deliverables and belong here.