Documentation — Roster

An agent-run organisation, powered by GitHub.

A staff member is a private repository. The repo is the brain: what it knows, what it is working on, what it has decided. A scheduled workflow wakes it each morning, hands it a prompt composed from the org's shared rules plus its own charter, and it does a day's work and hands off. You read the result in a local portal, or on GitHub.

roster is the thing that sets that up and keeps it consistent.

Guide

Read in this order.


Getting started	One command, in a browser: stand up an org, or join one that exists.
The portal	Where the work happens: setup, every screen, every action.
Manual steps	Every human action, why it cannot be automated, and what breaks if you skip it. Read this one.
Concepts	What a charter, a manifest, a surface and the ops repo are.
Choosing a coding agent	Claude, Codex, Nanocoder, or anything with a command line.
Writing a charter	The one file nothing can generate for you.
Extending it	The four seams, and which one to reach for.
Memory	The grammar, and why deleting is the maintenance.
Upgrading	How framework changes reach a tenant without eating your edits.
Troubleshooting	Every trap we have actually hit, and what it looks like.
Hosting the portal	Local is the default, and why.
Cost	What this spends, and on what.
Commands	Every CLI command and flag, for when you want the terminal.

Reference

Look things up.


`org.yaml`	Every field in the org manifest.
`staff.yaml`	Every field in a staff member's manifest.
Prompts	The template syntax, the context, and what to guard.
The session workflow	Inputs, secrets, and what runs in what order.
`roster export`	The JSON shape.
doctor codes	Every finding, what it means, what to do.

Understanding it


Architecture	What happens during a run, and why it is shaped this way.
Security model	What can reach what, and what stops it.
Working on roster itself	Layout, template classes, and the rules that matter.

The shape of it

Nano-Collective/roster          the framework. Never a runtime dependency of anything.
  ├── src/                      the CLI
  ├── templates/ops/            what a tenant's ops repo is generated from
  ├── templates/brain/          what a staff member's repo is generated from
  └── portal/                   the local web UI
 
<your-org>/roster-ops           the org layer and the machinery. Private.
  ├── org/business.md           what the business is. You write this.
  ├── org/voice.md              house style, inherited by everyone
  ├── org/guardrails.md         non-negotiables, inherited by everyone
  ├── org/operating.md          the autonomy contract
  ├── prompts/                  composable prompt fragments
  ├── compose.mjs               builds the prompt at run time
  ├── agents.mjs                which coding agent runs, and how
  └── .github/workflows/session.yaml    the reusable workflow every staff repo calls
 
<your-org>/<staff>              one per staff member. The repo is the brain.
  ├── CHARTER.md                the personality. Hand written.
  ├── staff.yaml                the machine-readable half of the charter
  ├── memory/INDEX.md           one line per fact, read at every boot
  ├── memory/notes/             the argument behind a fact, read on demand
  └── .github/workflows/        two callers, about forty lines each

The framework never runs anything. It writes templates out; a tenant runs its own copies. That is not tidiness, it is forced: a reusable workflow in a private repo can only be called from inside its own organisation, so a tenant cannot call the framework's. It turns out to be the better design anyway. Nothing breaks if the framework repo moves, goes private, or is deleted, and an air-gapped install is a supported case rather than a special one.

What it will not do for you

Write the charter. It is the personality and it decides everything else. A generated one produces a generic agent, which is the failure this whole arrangement exists to avoid.
Write org/business.md. Everything the staff say is downstream of it.
Install a GitHub App. Installing grants access to specific repositories and GitHub asks a human which. See manual steps.

None of those is a dead end. roster holds no model credential, so for the first two the portal does both halves of the round trip instead: it copies a brief that carries every file it refers to, and turns the reply you paste back into a file with a diff and a save button. For the third it runs everything either side of the confirmation GitHub insists a human gives, and tells you exactly which repositories to grant.

Overview

Guide

Reference

Understanding it

The shape of it

What it will not do for you