Skip to main content

Runbook — creating a new fleet repository

The fleet's repo-creation procedure. A new repository is not "created" when the repo exists on GitHub — it is created when the surfaces the fleet runs on are stood up inside it. Four of the steps below are mandatory, with no exceptions, under the owner's standing rules: the docsite project record (owner rule, 2026-09-29), the llm-wiki estate (owner rule, 2026-10-10 — "a wiki in every repo, without question"), the llm-kanban board where the repo carries fleet story work, and the closing verification.

Order matters. Step 1 (the project record) is the first step when an initiative is queued, before any other work in or on the new repo.

Step 1 — Open the docsite project record (mandatory)​

Create docs/03-projects/<slug>/work-record.md in the docsite for the initiative the repo serves, through the prepublish gate (the finance desk's one-command validator: frontmatter id present, the repo's own validator with the exact CI invocation). The record states what the repo is for, its owner-facing purpose, and its status; it stays current as work lands from this point on. No initiative — and therefore no new fleet repo — starts without this record.

Step 2 — Create the repository​

Create the repo under the owner's account with the visibility the initiative requires (private by default; a public site repo only where the initiative is a public site, e.g. cmsmakers). Seed it with a README that names the project, points at the Step 1 work record, and states the repo's domain in one paragraph — that paragraph is the seed of the Step 3 wiki SCHEMA. Never commit secrets, tokens, or generated build output at creation or later.

Step 3 — Stand up the llm-wiki estate (mandatory)​

Per the codified llm-wiki skill (v2.1.0; library entry docs/15-skills/research/llm-wiki.md; workspace skill llm-wiki), stand up the estate at the repo's wiki/ root:

  • wiki/SCHEMA.md — declares THIS repo's domain (what the wiki covers and what it never carries: work state belongs to the board, product state to the app), its conventions, and its tag taxonomy.
  • wiki/index.md — the catalog (Entities / Concepts / Comparisons / Queries).
  • wiki/log.md — with a creation entry recording the owner's standing rule as the reason the estate exists.
  • The three-layer shape: wiki/raw/ (sources layer), wiki/entities/, wiki/concepts/, wiki/comparisons/, wiki/queries/.
  • Seed at minimum the repo's own entity page, compiled from the Step 2 README paragraph and the project record, with full frontmatter and at least two wikilinks.
  • Run the pattern's lint before publishing (links resolve, index complete, frontmatter whole); record the lint result in the creation entry.

Wiki roots are per-repo. A repo's wiki is never a folder inside another repo's wiki.

Step 4 — Stand up the llm-kanban board (mandatory where the repo carries fleet story work)​

If the fleet will work stories in this repo, stand up its in-repo board before the first story files:

  • Board root inside the repo (kanban/ or a named sub-root such as kanban/it/ where the repo hosts several boards), following the llm-kanban runbook and schema standard: project charter, board AGENTS.md, agents.yaml naming every agent that may claim, story files, sprint files, renders.
  • Allocate the story prefix (e.g. AF-, CM-, IT-) — unique across the fleet, recorded in the board's charter and in the Step 1 work record.
  • Boards live INSIDE each project repo; the agent-orchestration board carries only its own program.
  • Gate: the board must validate with 0 errors before any story is filed on it.

If the repo carries no fleet story work, state that in the work record instead of standing up an empty board.

Step 5 — Registry and agents surfaces (mandatory where the repo hosts agents)​

If an agent will live in, claim from, or be registered against this repo, complete the registration package in the same change-set:

  • The repo's agents.yaml (board surface) carries the agent.
  • The docsite agent registry, the fleet roster, and FLEET.md name the agent with the same facts (the sweeper's daily pass cross-checks these surfaces against each other; divergence is a finding).
  • Where a new role is involved: the skills vocabulary (validator + index builder + tag taxonomy) and the generated skills index and role manifests regenerate in the same commit.
  • Hosted-repo specifics (branch protection, deploy keys) follow the repo's own record; nothing in this step widens any agent's authority.

Step 6 — Closing verification (mandatory)​

Verify, and record the results in the Step 1 work record:

  1. Wiki present and lint-clean — wiki/ on main with SCHEMA/index/log and the three-layer shape; lint result recorded.
  2. Record published and gate-clean — the work record is on docsite main, validator 0 errors, CI green.
  3. Board validates (where Step 4 applied) — 0 errors, prefix recorded.
  4. Surfaces agree (where Step 5 applied) — registry, roster, FLEET.md, and agents.yaml carry the same facts.
  5. Report completion to the chief of staff, naming each surface's commit. A step that cannot be verified is a step not done — report the gap, never paper over it.

Precedent​

The 2026-10-10 catch-up applied this procedure retroactively to the repos that predated the standing rules: fleet wikis stood up in agent-orchestration, docsite, cmsmakers, and inbox-triage (the dashboard estate already stood from the Inbox Triage stand-up the same day), each seeded from its repo's own records and linted clean at publish.