@nanocollective/roster 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nano Collective
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# roster
+
+Built by the [Nano Collective](https://nanocollective.org) — a community collective building AI tooling not for profit, but for the community.
+
+**An agent-run org, powered by GitHub.** Each staff member is an AI whose brain is a private
+repo: a charter, a memory, a decision log, and a scheduled session that does a day's work
+unattended and hands off.
+
+**Full documentation is in [`docs/`](docs/README.md).** Start with
+[getting started](docs/getting-started.md), then read [manual steps](docs/manual-steps.md).
+
+Status: **working, private, one tenant.** Every command below is built and exercised daily
+against a live two-agent org. Not published yet.
+
+## What it does
+
+```bash
+npx @nanocollective/roster      # set up, or join, an org — in a browser
+roster init --org acme          # or from a terminal: ops repo, org layer, merge base
+roster hire cto                 # scaffold a staff member: repo, workflows, labels, peers
+roster app cto                  # create their GitHub App, write its secrets
+roster doctor                   # is any of this actually wired up
+roster portal                   # read every brain, and the docs, locally
+roster upgrade                  # take framework changes without losing your edits
+```
+
+Nothing changes anything without `--apply`. `roster help <command>` for the rest, or
+[docs/commands.md](docs/commands.md).
+
+## The shape
+
+```
+Nano-Collective/roster        this repo. The CLI, the templates, the portal, the docs.
+                              ✗ never a runtime dependency of a tenant
+
+<tenant>/roster-ops           the org layer + the machinery, generated from templates/ops/
+  org/business.md               what the business is. You write this.
+  org/operating.md              the autonomy contract
+  org/voice.md                  house style
+  org/guardrails.md             the non-negotiables
+  prompts/                      composable run-kind fragments
+  compose.mjs                   vendored. Builds the prompt at run time.
+  agents.mjs                    vendored. Which coding agent runs, and how.
+  .github/workflows/session.yaml    the reusable workflow every staff repo calls
+
+<tenant>/<brain>              one repo per staff member. The repo is the brain.
+  CHARTER.md                    the personality. Hand written. Never generated.
+  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
+```
+
+**Why a tenant vendors the machinery:** a private reusable workflow can only be called from
+inside its own org, and a morning run should not depend on npm, on a network call, or on an
+organisation the tenant does not control. So the framework writes templates *out* and never runs
+anything. `roster upgrade` carries a new version across, and it is run by a human because App
+tokens cannot push changes under `.github/workflows/` anywhere.
+
+See [architecture](docs/architecture.md).
+
+## Any coding agent
+
+roster composes a prompt and hands it to an agent. A runner is three shell-level facts:
+
+```yaml
+agent:
+  id: codex
+```
+
+Presets for `claude-code-action` (default), `claude`, `codex` and `nanocoder`. Anything else
+works by writing `install`, `run` and `token_env` into `org.yaml`.
+See [choosing a coding agent](docs/agents.md).
+
+## Composition
+
+A runtime prompt is assembled from org policy, the staff member's charter, and the run kind:
+
+```
+prompts/<kind>.md
+  {{> prompts/_paths.md}}        where the repos are in the runner
+  {{> prompts/_identity.md}}     which bot you are, on which repo
+  {{>? staff:prompts/work.md}}   optional per-role override
+  {{> org/operating.md}}         the autonomy contract
+  {{> org/guardrails.md}}
+  {{> org/voice.md}}
+```
+
+`{{> x}}` is required, `{{>? x}}` renders empty when absent, and `staff:` resolves inside the
+staff member's own repo. That is the extension seam: **a role extends the org without forking
+it.** Change `org/voice.md` once and everyone inherits it on their next run.
+
+See [prompts](docs/prompts.md).
+
+## Development
+
+```bash
+pnpm install
+pnpm test             # 148 tests, node:test through tsx
+pnpm test:all         # the full gate
+pnpm dev doctor --offline
+```
+
+Run it from a workspace root: a directory holding the ops repo and every brain repo side by
+side, which is the same shape the CI runner checks out.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Contributions are welcome at any level of experience.
+
+```bash
+pnpm install
+pnpm test:all      # format, lint, types, dead code, tests
+```
+
+## Community
+
+- [Nano Collective](https://nanocollective.org)
+- [Documentation](https://docs.nanocollective.org)
+- [GitHub organisation](https://github.com/Nano-Collective)
+- [Discord](https://discord.gg/ktPDV6rekE)
+
+Licensed [MIT](LICENSE), copyright Nano Collective.
+
+---
+
+Before touching anything that reaches a live org, read
+[working on roster itself](docs/developing.md). The short version: never fix a generated file
+in a tenant, and check `roster prompt` output byte for byte before shipping a prompt change.