@nanocollective/roster 0.1.0-alpha.1

package/docs/README.md

@@ -0,0 +1,99 @@
+---
+title: "Overview"
+description: "What roster is, the shape of an agent-run org, and what it will not do for you."
+sidebar_order: 0
+---
+
+# 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 on GitHub, or in a local portal.
+
+roster is the thing that sets that up and keeps it consistent.
+
+## Guide
+
+Read in this order.
+
+| | |
+|---|---|
+| [Getting started](getting-started.md) | One command, in a browser: stand up an org, or join one that exists. |
+| [Manual steps](manual-steps.md) | Every human action, why it cannot be automated, and what breaks if you skip it. **Read this one.** |
+| [Concepts](concepts.md) | What a charter, a manifest, a surface and the ops repo are. |
+| [Choosing a coding agent](agents.md) | Claude, Codex, Nanocoder, or anything with a command line. |
+| [Writing a charter](writing-a-charter.md) | The one file nothing can generate for you. |
+| [Extending it](extending.md) | The four seams, and which one to reach for. |
+| [Memory](memory.md) | The grammar, and why deleting is the maintenance. |
+| [Commands](commands.md) | Every CLI command and flag. |
+| [The portal](portal.md) | Setup, every view, and every action. |
+| [Upgrading](upgrading.md) | How framework changes reach a tenant without eating your edits. |
+| [Troubleshooting](troubleshooting.md) | Every trap we have actually hit, and what it looks like. |
+| [Hosting the portal](hosting.md) | Local is the default, and why. |
+| [Cost](cost.md) | What this spends, and on what. |
+
+## Reference
+
+Look things up.
+
+| | |
+|---|---|
+| [`org.yaml`](org-yaml.md) | Every field in the org manifest. |
+| [`staff.yaml`](staff-yaml.md) | Every field in a staff member's manifest. |
+| [Prompts](prompts.md) | The template syntax, the context, and what to guard. |
+| [The session workflow](session-workflow.md) | Inputs, secrets, and what runs in what order. |
+| [The portal](portal.md) | Every view and every action. |
+| [`roster export`](export.md) | The JSON shape. |
+| [doctor codes](doctor-codes.md) | Every finding, what it means, what to do. |
+
+## Understanding it
+
+| | |
+|---|---|
+| [Architecture](architecture.md) | What happens during a run, and why it is shaped this way. |
+| [Security model](security.md) | What can reach what, and what stops it. |
+| [Working on roster itself](developing.md) | 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/        three 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](manual-steps.md).

package/docs/agents.md

@@ -0,0 +1,163 @@
+---
+title: "Choosing a coding agent"
+description: "Claude, Codex, Nanocoder, or anything with a command line."
+sidebar_order: 4
+---
+
+# Choosing a coding agent
+
+roster is not a Claude harness. It composes a prompt, hands it to a coding agent, and gets out
+of the way. **Any agent with a command line that accepts a prompt works.**
+
+A runner is three facts:
+
+| | |
+|---|---|
+| `install` | a shell command that puts the agent on the runner |
+| `run` | a shell command that runs it, reading the prompt from `$AGENT_PROMPT_FILE` |
+| `token_env` | the environment variable its credential goes in |
+
+That is the whole interface. Everything else is a convenience.
+
+## Picking one
+
+In `org.yaml`:
+
+```yaml
+agent:
+  id: codex
+```
+
+Or the short form, which is the same thing:
+
+```yaml
+agent: codex
+```
+
+A staff member can override it in their own `staff.yaml`, which is worth doing when roles
+differ in kind. A research role on a long-context model and an engineering role on a coding
+model is a reasonable thing to want:
+
+```yaml
+# marketing/staff.yaml
+agent: claude
+model: claude-opus-5
+```
+
+## The presets
+
+Every command below was read off the tool's own help output or its documentation, not assumed.
+They will drift. When one does, override the field rather than waiting for us: see
+[writing your own](#writing-your-own).
+
+### `claude-code-action` (default)
+
+Claude Code through Anthropic's GitHub Action. This is the reference runner and the one this
+project is exercised against daily.
+
+```yaml
+agent: claude-code-action
+```
+
+- credential: `CLAUDE_CODE_OAUTH_TOKEN`
+- default model: `claude-opus-5`
+- tool permissions come from `allowed_tools` on the caller
+
+It is the only preset that is a GitHub Action rather than a CLI. `uses:` in a workflow cannot
+be an expression, so an Action-based runner has to be written into `session.yaml` literally.
+That is why there is exactly one of them, and why everything else goes through the generic
+path.
+
+### `claude`
+
+The same agent through its plain CLI, if you would rather not depend on the Action.
+
+```
+install:   npm install -g @anthropic-ai/claude-code
+run:       claude -p --model "$AGENT_MODEL" --allowedTools "$AGENT_TOOLS" < "$AGENT_PROMPT_FILE"
+token_env: CLAUDE_CODE_OAUTH_TOKEN
+```
+
+### `codex`
+
+OpenAI's Codex CLI.
+
+```
+install:   npm install -g @openai/codex
+run:       codex exec - --model "$AGENT_MODEL" --sandbox danger-full-access < "$AGENT_PROMPT_FILE"
+token_env: CODEX_API_KEY
+```
+
+`exec -` reads the prompt from standard input. The sandbox is opened up because the entire
+point of a session is that it edits the checkout and pushes; a sandbox that forbids writes
+produces a run that succeeds having done nothing. If you would rather keep it narrower,
+`--sandbox workspace-write` is the option to try first.
+
+### `nanocoder`
+
+```
+install:   npm install -g @nanocollective/nanocoder
+run:       nanocoder --model "$AGENT_MODEL" --mode yolo --trust-directory --plain run "$(cat "$AGENT_PROMPT_FILE")"
+token_env: NANOCODER_API_KEY
+```
+
+Three flags matter for unattended use. `run` is its non-interactive mode. `--trust-directory`
+skips the first-run directory trust prompt, which would otherwise hang the runner until it
+times out. `--plain` avoids the TUI, which has nothing to draw to in CI.
+
+Nanocoder resolves a provider from `agents.config.json` in the working directory, so you will
+want that file in the brain repo, and the provider's own key in `token_env`.
+
+## Writing your own
+
+Anything not in the list, including something that does not exist yet:
+
+```yaml
+agent:
+  id: my-agent
+  install: cargo install my-agent
+  run: my-agent --headless --model "$AGENT_MODEL" < "$AGENT_PROMPT_FILE"
+  token_env: MY_AGENT_TOKEN
+```
+
+You can also override a single field of a preset, which is the common case when a flag changes:
+
+```yaml
+agent:
+  id: codex
+  run: codex exec - --model "$AGENT_MODEL" --sandbox workspace-write < "$AGENT_PROMPT_FILE"
+```
+
+The rest of the preset still applies.
+
+## What the runner gets
+
+| Variable | |
+|---|---|
+| `$AGENT_PROMPT_FILE` | absolute path to the composed prompt |
+| `$AGENT_MODEL` | the staff member's model, or the agent's default |
+| `$AGENT_TOOLS` | the `allowed_tools` string from the caller |
+| `$GH_TOKEN` | a token for the private trackers, already authenticated |
+| `$PUBLIC_TOKEN` | a token for the public product repo, if there is one |
+| *`token_env`* | the agent's credential, under whatever name it wants |
+
+**The prompt is always a file, never an argument.** It is thousands of words and it contains
+quotes, backticks and dollar signs. Argument length limits and shell quoting are exactly the
+sort of thing that works in testing and fails at 07:00 on a Tuesday.
+
+## Requirements on the agent
+
+An agent has to do the work *and commit it*. The prompt tells it to; the session workflow does
+not commit on its behalf. Any agent that can run `git` and `gh` from a shell qualifies. One
+that only edits files and cannot run commands will produce a run that changes nothing.
+
+## Changing agent on a live org
+
+1. Set `agent:` in `org.yaml`.
+2. Put the new credential on each brain repo, named as `token_env`.
+3. `roster upgrade --apply`, then commit and push the regenerated callers.
+4. Trigger one run by hand and read the log before trusting the schedule.
+
+Step 4 is not optional. Prompts are written against a model's habits as much as its
+capabilities, and the first run on a new agent is where you find out which parts of your
+charter were load-bearing.

package/docs/architecture.md

@@ -0,0 +1,121 @@
+---
+title: "Architecture"
+description: "What happens during a run, and the constraint that decided the design."
+sidebar_order: 20
+---
+
+# Architecture
+
+What actually happens, and why it is shaped this way.
+
+## The constraint that decided everything
+
+**A reusable workflow in a private repo can only be called by repos in the same organisation.**
+
+So a tenant cannot call a workflow living in a private framework repo. Two ways out:
+
+- Publish the framework early so it can be referenced. That forces the open-source decision
+  before you are ready, and makes every tenant depend on an org they do not control.
+- **The framework never runs anything. It writes templates into the tenant's own repo.**
+
+The second is what roster does, and it is better independently of licensing. Every tenant is
+self-contained. Nothing breaks if the framework moves, goes private, or is deleted. An
+air-gapped install is a supported case rather than a special one.
+
+The cost is that framework improvements do not arrive by themselves. `roster upgrade` is what
+carries them, run by a human. See [upgrading](upgrading.md).
+
+## Three repos, three jobs
+
+```
+Nano-Collective/roster        the framework. Never a runtime dependency of anything.
+<org>/roster-ops              the org layer and the machinery. Private.
+<org>/<staff>                 one per staff member. The repo is the brain.
+```
+
+Inside the ops repo there is a second split, enforced by convention so that extraction stays a
+directory copy:
+
+- **`org/`** is the tenant's business truth. Never published, always yours.
+- **everything else** came from the framework's templates and can be regenerated.
+
+## A day in the life of a run
+
+07:00 UTC, `cto-daily.yaml` fires on cron.
+
+1. The caller passes nine inputs and five secrets to `roster-ops/.github/workflows/session.yaml`
+   and does nothing else. It is forty lines because everything that could be shared, is.
+2. The session mints a GitHub App token. **The agent posts as `acme-cto[bot]`, not as you.**
+3. It clones the ops repo, which is the only thing it can clone without having read a manifest.
+4. `runner-plan.mjs` reads `org.yaml` and the staff member's manifest and says what else to
+   clone: the brain with full history, each peer's brain, each product repo.
+5. `compose.mjs` assembles the prompt from six files: four org-level, the charter, and the
+   fragment for this kind of run.
+6. `agents.mjs` resolves which coding agent to run and how.
+7. The agent runs with a shell, `gh` already authenticated, and the whole checkout.
+8. It works, commits, pushes, opens issues, comments, and rewrites its pinned status issue.
+   **The workflow does not commit on its behalf**; the prompt tells it to and it does.
+
+Nothing is stored outside the repos. There is no database and no service.
+
+## Boot, work, hand off
+
+The prompt imposes a shape, and the shape is what makes an unattended run useful.
+
+**Boot** is reconstituting a self that has no memory of yesterday. It reads `memory/INDEX.md`
+in full, the pinned status issue, and its own charter. That is deliberately all: notes are read
+only when a fact is in play, and the decision log is not boot context at all.
+
+This is why memory is one line per fact. Boot context here went from about 52,000 words to
+about 6,000 by making that change, and the saving repeats on every run of every staff member
+forever.
+
+**Work** is one thing done properly rather than four things started.
+
+**Hand off** is the part that makes the next run possible: open the PR, rewrite the status
+issue (rewrite, not append), reconcile the tracker, update memory only if a fact changed, log
+real decisions, and write to peers if something touches their patch.
+
+## Why the memory is markdown
+
+An agent writes markdown well and writes to a schema badly. A database would need the agent to
+be careful about something it is not good at being careful about, and would put the brain
+somewhere you cannot read with `git log`.
+
+The cost is that the grammar is a convention rather than a constraint, so `roster lint`
+enforces it and the portal parses it. See [memory](memory.md).
+
+## Identities and why there are two
+
+A staff member has a private App for its own trackers, and shares a public App with everyone
+else for the product repo.
+
+The private one is unique, so work on an internal board is attributable. The public one is
+shared and deliberately anonymous, because a bot opening a pull request on a public repo is
+unremarkable and a bot signing itself with a job title is a tell.
+
+`roster doctor` treats these differently when attributing work: a solo identity names one staff
+member, a shared one names only "one of them".
+
+## What cannot be automated, and why
+
+- **Creating a GitHub App** has no API. Only the manifest flow, which needs a browser and a
+  human confirmation. `roster app` does everything either side of that.
+- **Installing an App** grants access to specific repos and GitHub asks a human which. This is
+  correct and should not be worked around.
+- **Pushing a workflow change** is impossible with an App token, in any repo. So agents can
+  never update their own workflows, and upgrades are human-run by design.
+
+See [manual steps](manual-steps.md).
+
+## Where the pieces live
+
+| Piece | In | Why there |
+|---|---|---|
+| `compose.mjs` | the tenant | a run must not depend on npm or on the framework |
+| `agents.mjs` | the tenant | same |
+| `runner-plan.mjs` | the tenant | same |
+| `session.yaml` | the tenant | private reusable workflows are same-org only |
+| the CLI | the framework | runs on your machine, when you ask it to |
+| the portal | the framework | reads the tenant's repos from disk |
+| the docs | the framework | including the copy the portal serves |

package/docs/commands.md

@@ -0,0 +1,223 @@
+---
+title: "Commands"
+description: "Every CLI command and flag."
+sidebar_order: 8
+---
+
+# Commands
+
+Every command prints a plan and changes nothing unless you pass `--apply`, except `lint`,
+`prompt`, `export` and `portal`, which never change anything at all.
+
+## `roster fix`
+
+Every scanner's findings, as one brief you paste into a coding agent working in this workspace.
+
+```
+--json      the findings as data, rather than as a brief
+--offline   skip everything needing the network
+--ops <dir> ops repo directory
+```
+
+`doctor`, the prompt audit and `lint` each already carry the sentence that fixes their own
+finding; this collects them. Two piles come out: what an agent editing files here can do, and
+what only a person can: an org permission, an App install, a credential. The second is listed
+but marked not to attempt, because an agent handed one of those invents a workaround.
+
+The brief states which files belong to the framework before it states any of the work. A fix
+applied to a vendored file is reverted by the next `roster upgrade`, and that has happened.
+
+The portal's Health screen has the same text behind a copy button.
+
+## `roster init --org <org>`
+
+Stand up a new tenant: the ops repo, the org layer, and the recorded merge base.
+
+```
+--org <name>      the GitHub organisation. Required.
+--name <text>     what the business is called. Defaults to the org.
+--human <login>   who the agents answer to. Defaults to your gh login.
+--marker <tag>    provenance tag on a fact they ruled on.
+--agent <id>      coding agent. See docs/agents.md.
+--dir <path>      where to create the workspace.
+--ops <name>      ops repo name. Defaults to roster-ops.
+--apply
+```
+
+Will not write `org/business.md`. That is yours.
+
+## `roster hire <handle>`
+
+Scaffold a staff member: repo, three callers, manifest, memory index, charter stub, labels,
+pinned status issue, and peer wiring in both directions.
+
+```
+--name <text>          role name, e.g. "Chief Financial Officer"
+--dir <name>           workspace directory and repo name
+--schedule <cron>      defaults to a slot staggered after the last one
+--model <id>
+--timeout <n>          daily ceiling, minutes
+--mention-timeout <n>
+--pr-timeout <n>
+--secret-prefix <X>    secrets become <X>_APP_ID and <X>_APP_PRIVATE_KEY
+--app <slug>           defaults to the pattern the peers use
+--public-app <slug>    the shared public identity
+--apply
+```
+
+## `roster app <handle>`
+
+Create the GitHub App and put its credentials in the brain repo's secrets.
+
+```
+--public       create the shared public identity instead
+--port <n>     localhost port for the hand-off. Default 4310.
+--no-open      print the URL rather than opening a browser
+```
+
+Cannot install the App. See [manual steps](manual-steps.md).
+
+## `roster retire <handle>`
+
+Stop a staff member without destroying anything.
+
+```
+--apply
+--ops <dir>
+```
+
+Their brain repo is their entire memory and there is no undo for deleting one, so this does
+not touch it. It disables their three workflows through the API, removes them from `org.yaml`,
+removes them from every peer's `staff.yaml`, and deletes the `from-<handle>` labels their peers
+carried for them. Everything they ever knew stays where it is, readable in the portal and on
+GitHub.
+
+Disabling rather than deleting the workflow files is what makes it reversible: the files stay,
+so re-enabling is one click, and nothing has to be regenerated from templates that have moved
+on since.
+
+It deliberately does not delete or archive the repo, close their issues, or unpin their status
+issue. All three are one click on GitHub, having thought about it.
+
+Plan-then-apply, like everything else that changes something.
+
+## `roster doctor [handle]`
+
+Check the org is wired up, and that the agents have actually been running.
+
+```
+--offline   skip everything needing the network
+--json      machine-readable findings
+```
+
+Exit 1 if anything failed. Warnings do not fail.
+
+## `roster upgrade`
+
+Carry framework changes into the tenant. See [upgrading](upgrading.md).
+
+```
+--apply
+--check               exit non-zero if anything is pending
+--baseline <git-ref>  one-time: reconstruct a merge base
+--verbose             show files that are already up to date
+```
+
+## `roster lint [handle]`
+
+Check memory against the grammar. See [memory](memory.md).
+
+```
+--quiet   print only problems
+```
+
+## `roster brief <kind> [handle]`
+
+Print a self-contained brief for authoring one of the files the agents run on. Paste it into
+whatever agent you use, or pipe it.
+
+```
+discover        write org/business.md, which every prompt is composed on top of
+charter <who>   write a staff member's CHARTER.md
+voice           revise org/voice.md, the house style every surface inherits
+amend <who>     change what a staff member is told, with the whole prompt attached
+```
+
+```
+--kind <k>      for amend: daily | mention | pr-mention  (default: daily)
+--want <text>   for amend: what you want changed
+--ops <dir>
+```
+
+```bash
+roster brief amend cto --want "stop opening decision issues for anything reversible"
+roster brief discover
+roster brief charter cto | pbcopy
+roster brief voice > /tmp/brief.md
+```
+
+`amend` is the different one. It carries the composed prompt and every file it is assembled
+from, so the agent you paste it into does not have to ask for any of them. The portal's Prompt
+screen builds the same thing, and offers it per audit finding.
+
+The other three are the only files anybody writes by hand. `org/operating.md`, `org/voice.md` and
+`org/guardrails.md` ship written; a charter and `org/business.md` cannot, because they are the
+half that is about you.
+
+Nothing in a brief is specific to any agent. Claude Code gets `/discover`, `/voice` and
+`/charter` as well, generated from these same files by `roster init` and `roster hire`. To add
+them to a tenant that predates this, redirect the brief into the file:
+
+```bash
+roster brief discover > roster-ops/.claude/commands/discover.md
+```
+
+## `roster prompt <handle>`
+
+Compose and print what a staff member is actually sent.
+
+```
+--kind daily|mention|pr-mention
+--diff <workflow.yaml>
+```
+
+`mention` and `pr-mention` need trigger context:
+
+```bash
+ROSTER_CONTEXT='{"issue_number":"1","comment_id":"1","pr_number":"1","repo":"o/r"}' \
+  roster prompt cto --kind mention
+```
+
+## `roster portal`
+
+Serve a local UI over the checked-out repositories. **`roster` with no arguments does the same**,
+which is the shortest way in.
+
+```
+--port <n>    default 4300
+--host <a>    default 127.0.0.1. Anything else exposes write actions to the network.
+--dir <path>  where a tenant would be created or checked out. Default: here.
+```
+
+**With no tenant where you started it, this is the setup screen**: it stands up a new org, or
+checks out one that already runs roster. Local only. See [the portal](portal.md).
+
+Views: Inbox, Org, Staff, Docs, and per staff member Brain, Prompt, Graph, What changed, Health.
+
+It can act as you through your own `gh`: reply, close, reopen and open issues; hire and retire;
+edit and commit the org layer, prompt fragments and charters; create a staff member's GitHub App;
+and copy a prompt for authoring the two files nothing can generate.
+
+## `roster export`
+
+The whole org as one JSON document.
+
+```
+--out <file>
+```
+
+## Common to all
+
+```
+--ops <dir>   ops repo directory. Default: found by walking up.
+```