@nanocollective/roster 0.1.0-alpha.9 → 0.1.0-beta.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -0
- package/dist/cli.js +4189 -1971
- package/dist/worker/assets/assets/css/base.css +327 -0
- package/dist/worker/assets/assets/css/brain.css +116 -0
- package/dist/worker/assets/assets/css/diff.css +33 -0
- package/dist/worker/assets/assets/css/graph.css +39 -0
- package/dist/worker/assets/assets/css/health.css +75 -0
- package/dist/worker/assets/assets/css/home.css +114 -0
- package/dist/worker/assets/assets/css/inbox.css +199 -0
- package/dist/worker/assets/assets/css/layout.css +181 -0
- package/dist/worker/assets/assets/css/markdown.css +96 -0
- package/dist/worker/assets/assets/css/runs.css +13 -0
- package/dist/worker/assets/assets/css/search.css +48 -0
- package/dist/worker/assets/assets/css/setup.css +194 -0
- package/dist/worker/assets/assets/js/api.js +191 -0
- package/dist/worker/assets/assets/js/app.js +500 -0
- package/dist/worker/assets/assets/js/dialog.js +196 -0
- package/dist/worker/assets/assets/js/dom.js +131 -0
- package/dist/worker/assets/assets/js/homesort.js +174 -0
- package/dist/worker/assets/assets/js/icons.js +142 -0
- package/dist/worker/assets/assets/js/inflight.js +18 -0
- package/dist/worker/assets/assets/js/lightbox.js +273 -0
- package/dist/worker/assets/assets/js/md.js +406 -0
- package/dist/worker/assets/assets/js/mdedit.js +84 -0
- package/dist/worker/assets/assets/js/mention.js +264 -0
- package/dist/worker/assets/assets/js/readiness.js +70 -0
- package/dist/worker/assets/assets/js/refresh.js +197 -0
- package/dist/worker/assets/assets/js/router.js +20 -0
- package/dist/worker/assets/assets/js/search.js +366 -0
- package/dist/worker/assets/assets/js/state.js +213 -0
- package/dist/worker/assets/assets/js/textdiff.js +96 -0
- package/dist/worker/assets/assets/js/views/app.js +145 -0
- package/dist/worker/assets/assets/js/views/brain.js +260 -0
- package/dist/worker/assets/assets/js/views/changed.js +157 -0
- package/dist/worker/assets/assets/js/views/checklist.js +115 -0
- package/dist/worker/assets/assets/js/views/credential.js +84 -0
- package/dist/worker/assets/assets/js/views/docs.js +174 -0
- package/dist/worker/assets/assets/js/views/files.js +139 -0
- package/dist/worker/assets/assets/js/views/graph.js +436 -0
- package/dist/worker/assets/assets/js/views/health.js +304 -0
- package/dist/worker/assets/assets/js/views/hire.js +593 -0
- package/dist/worker/assets/assets/js/views/home.js +621 -0
- package/dist/worker/assets/assets/js/views/inbox.js +1558 -0
- package/dist/worker/assets/assets/js/views/memory.js +150 -0
- package/dist/worker/assets/assets/js/views/org.js +195 -0
- package/dist/worker/assets/assets/js/views/orgedit.js +240 -0
- package/dist/worker/assets/assets/js/views/paste.js +216 -0
- package/dist/worker/assets/assets/js/views/prompt.js +457 -0
- package/dist/worker/assets/assets/js/views/repos.js +97 -0
- package/dist/worker/assets/assets/js/views/runonce.js +94 -0
- package/dist/worker/assets/assets/js/views/runs.js +182 -0
- package/dist/worker/assets/assets/js/views/setup.js +557 -0
- package/dist/worker/assets/assets/js/views/staff.js +291 -0
- package/dist/worker/assets/assets/js/views/todo.js +62 -0
- package/dist/worker/assets/assets/js/yaml.js +134 -0
- package/dist/worker/assets/docs-images/brain.jpg +0 -0
- package/dist/worker/assets/docs-images/home.jpg +0 -0
- package/dist/worker/assets/docs-images/org.jpg +0 -0
- package/dist/worker/assets/docs-images/prompt.jpg +0 -0
- package/dist/worker/assets/docs-images/setup-org.jpg +0 -0
- package/dist/worker/assets/docs-images/setup-plan.jpg +0 -0
- package/dist/worker/assets/docs-images/staff.jpg +0 -0
- package/dist/worker/assets/index.html +82 -0
- package/dist/worker/index.js +5143 -0
- package/docs/README.md +2 -2
- package/docs/architecture.md +23 -4
- package/docs/charters/analyst.md +65 -0
- package/docs/charters/community.md +63 -0
- package/docs/charters/designer.md +65 -0
- package/docs/charters/devops.md +65 -0
- package/docs/charters/pm.md +70 -0
- package/docs/charters/qa.md +65 -0
- package/docs/charters/writer.md +63 -0
- package/docs/commands.md +36 -9
- package/docs/concepts.md +34 -21
- package/docs/cost.md +3 -3
- package/docs/developing.md +28 -10
- package/docs/doctor-codes.md +3 -1
- package/docs/export.md +2 -0
- package/docs/getting-started.md +49 -29
- package/docs/hosting.md +114 -43
- package/docs/images/brain.jpg +0 -0
- package/docs/images/home.jpg +0 -0
- package/docs/images/org.jpg +0 -0
- package/docs/images/prompt.jpg +0 -0
- package/docs/images/staff.jpg +0 -0
- package/docs/manual-steps.md +3 -2
- package/docs/memory.md +2 -1
- package/docs/org-yaml.md +3 -0
- package/docs/portal.md +144 -45
- package/docs/prompts.md +6 -0
- package/docs/security.md +70 -11
- package/docs/session-workflow.md +24 -6
- package/docs/staff-yaml.md +21 -2
- package/docs/upgrading.md +3 -3
- package/docs/writing-a-charter.md +19 -6
- package/package.json +4 -3
- package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml +20 -1
- package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml +53 -13
- package/templates/brain/CHARTER.md +2 -2
- package/templates/brain/STATE.md +16 -0
- package/templates/brain/memory/INDEX.md +1 -1
- package/templates/brain/staff.yaml +4 -1
- package/templates/briefs/amend.md +4 -3
- package/templates/briefs/priorities.md +46 -0
- package/templates/ops/.github/workflows/session.yaml +150 -3
- package/templates/ops/compose.mjs +35 -8
- package/templates/ops/org/operating.md +29 -10
- package/templates/ops/org/voice.md +2 -1
- package/templates/ops/prompts/daily.md +51 -14
- package/templates/ops/prompts/mention.md +24 -2
- package/templates/ops/run-record.mjs +5 -3
- package/templates/ops/status-week.mjs +169 -0
- package/templates/portal/css/base.css +49 -0
- package/templates/portal/css/health.css +14 -1
- package/templates/portal/css/home.css +114 -0
- package/templates/portal/css/inbox.css +21 -4
- package/templates/portal/css/layout.css +35 -3
- package/templates/portal/css/markdown.css +19 -0
- package/templates/portal/css/search.css +48 -0
- package/templates/portal/css/setup.css +79 -4
- package/templates/portal/index.html +15 -9
- package/templates/portal/js/api.js +60 -4
- package/templates/portal/js/app.js +125 -7
- package/templates/portal/js/dialog.js +36 -0
- package/templates/portal/js/homesort.js +174 -0
- package/templates/portal/js/icons.js +41 -0
- package/templates/portal/js/inflight.js +18 -0
- package/templates/portal/js/md.js +5 -2
- package/templates/portal/js/mdedit.js +84 -0
- package/templates/portal/js/readiness.js +70 -0
- package/templates/portal/js/refresh.js +10 -2
- package/templates/portal/js/search.js +366 -0
- package/templates/portal/js/state.js +11 -5
- package/templates/portal/js/views/app.js +1 -2
- package/templates/portal/js/views/brain.js +1 -1
- package/templates/portal/js/views/checklist.js +19 -4
- package/templates/portal/js/views/credential.js +42 -51
- package/templates/portal/js/views/health.js +11 -6
- package/templates/portal/js/views/hire.js +593 -0
- package/templates/portal/js/views/home.js +621 -0
- package/templates/portal/js/views/inbox.js +237 -68
- package/templates/portal/js/views/org.js +31 -111
- package/templates/portal/js/views/orgedit.js +240 -0
- package/templates/portal/js/views/paste.js +111 -66
- package/templates/portal/js/views/prompt.js +94 -40
- package/templates/portal/js/views/repos.js +10 -10
- package/templates/portal/js/views/runs.js +21 -4
- package/templates/portal/js/views/setup.js +130 -163
- package/templates/portal/js/views/staff.js +181 -301
- package/templates/portal/js/views/todo.js +62 -0
package/docs/concepts.md
CHANGED
|
@@ -6,30 +6,24 @@ sidebar_order: 3
|
|
|
6
6
|
|
|
7
7
|
# Concepts
|
|
8
8
|
|
|
9
|
-
## The
|
|
9
|
+
## The three things you need to know
|
|
10
10
|
|
|
11
11
|
Enough to set up an org and read what it does. Everything after this section is detail you
|
|
12
12
|
can learn when you need it.
|
|
13
13
|
|
|
14
|
-
1. **The org
|
|
15
|
-
|
|
16
|
-
(`org/priorities.md`), the house voice and the guardrails. Change
|
|
17
|
-
|
|
18
|
-
2. **
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
5. **The daily run.** A scheduled GitHub Actions workflow in each brain wakes the staff member,
|
|
28
|
-
hands it a prompt built from the org layer plus its charter and memory, and it does one piece
|
|
29
|
-
of work and writes down what happened. [More](#kinds-of-run).
|
|
30
|
-
6. **Mentions.** Write `@handle` in an issue or comment on a staff member's own tracker and it
|
|
31
|
-
runs to answer that, between daily runs. Nothing on a product repo wakes anybody; you ask
|
|
32
|
-
them on their tracker. [More](#kinds-of-run).
|
|
14
|
+
1. **The org files everyone shares.** One private repo, `<org>/roster-ops`, holds what every
|
|
15
|
+
staff member reads: what the business is (`org/business.md`), what matters this month
|
|
16
|
+
(`org/priorities.md`), the house voice and the guardrails. Change one and every staff member
|
|
17
|
+
has it on their next run. [More](#the-ops-repo).
|
|
18
|
+
2. **One repo per staff member.** Each staff member is a private repo, its *brain*. In it,
|
|
19
|
+
`CHARTER.md` says who they are and what they decide alone. You write it; roster never
|
|
20
|
+
generates one, because a generated charter makes a generic agent. `memory/INDEX.md` is what
|
|
21
|
+
they know, one line per fact, which they keep and you can correct. There is no database and
|
|
22
|
+
no server; the portal reads the repos. [More](#the-brain).
|
|
23
|
+
3. **The daily run, and asking.** Each weekday a scheduled run wakes them: it reads the org
|
|
24
|
+
files, their charter and their memory, does one piece of work, and hands it to you as a pull
|
|
25
|
+
request or a question. Between runs, write `@handle` on their tracker and they answer that.
|
|
26
|
+
[More](#kinds-of-run).
|
|
33
27
|
|
|
34
28
|
Everything below, and the rest of the docs, is detail: identities, peers, surfaces, the
|
|
35
29
|
prompt's layers, upgrading. None of it is needed to get a first run.
|
|
@@ -46,7 +40,7 @@ commits and pushes. A change here reaches everybody on their next run, which is
|
|
|
46
40
|
rule every staff member should follow is one edit, not one per repo.
|
|
47
41
|
|
|
48
42
|
**Everything else is machinery** and belongs to the framework: `compose.mjs`, `agents.mjs`,
|
|
49
|
-
`runner-plan.mjs`, `inflight.mjs`, `run-record.mjs`, `.github/workflows/session.yaml`. Editing these works right up until the
|
|
43
|
+
`runner-plan.mjs`, `inflight.mjs`, `run-record.mjs`, `status-week.mjs`, `.github/workflows/session.yaml`. Editing these works right up until the
|
|
50
44
|
framework changes the same file, at which point your change is a conflict at best and silently
|
|
51
45
|
reverted at worst. Fix machinery in the framework, then `roster upgrade`.
|
|
52
46
|
|
|
@@ -60,6 +54,11 @@ ranked, and what is out of scope. It is composed into every daily run, a run pic
|
|
|
60
54
|
serves it, and a PR names the priority it serves. Keep it to three priorities or fewer, and
|
|
61
55
|
rewrite it when the month turns.
|
|
62
56
|
|
|
57
|
+
In the last three days of each month the staff member `org.yaml` lists first opens a pull
|
|
58
|
+
request on the ops repo with a draft for next month, built from this month's, what shipped and
|
|
59
|
+
the other staff's status issues. It shows on Home with Merge; edit it first if you like. Until it
|
|
60
|
+
is merged, this month's stand.
|
|
61
|
+
|
|
63
62
|
Without it each staff member picks its own work from its own charter, and they drift. `roster
|
|
64
63
|
init` writes a stub; `roster doctor` warns while it is missing or still the stub. An org that
|
|
65
64
|
predates it just adds the file.
|
|
@@ -127,6 +126,20 @@ control.
|
|
|
127
126
|
| `daily` | the scheduled session. Boot, work, hand off. |
|
|
128
127
|
| `mention` | `@handle` in a comment or a new issue body. A task, not a session. |
|
|
129
128
|
|
|
129
|
+
What starts a run:
|
|
130
|
+
|
|
131
|
+
| Trigger | Runs | Counts against `max_runs_per_day` |
|
|
132
|
+
|---|---|---|
|
|
133
|
+
| the schedule | `daily` | no |
|
|
134
|
+
| **Run once now**, or Actions → Run workflow | `daily` | no |
|
|
135
|
+
| a person writing `@handle` on the staff member's tracker | `mention` | no |
|
|
136
|
+
| a peer opening an issue there with their `from-<handle>` label | `mention`, framed as a peer's ask | yes |
|
|
137
|
+
| a daily run that ended with the next step ready | `daily`, as a follow-on | yes |
|
|
138
|
+
|
|
139
|
+
A person commenting without the `@handle` wakes nobody, so people can discuss on an issue
|
|
140
|
+
among themselves. A run started by a peer may not file on another peer, and the limit (6 a day
|
|
141
|
+
unless `staff.yaml` says otherwise) stops a chain of runs that nobody asked for.
|
|
142
|
+
|
|
130
143
|
A `mention` prompt refuses to compose without trigger context, because it is written for the
|
|
131
144
|
comment that woke it. That is correct behaviour, not a bug.
|
|
132
145
|
|
package/docs/cost.md
CHANGED
|
@@ -12,9 +12,9 @@ Three separate bills, and they behave differently.
|
|
|
12
12
|
|
|
13
13
|
The largest by far, and the one that scales with how much work you ask for.
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
how Pip's staff run.
|
|
15
|
+
Roster needs access to a coding agent, not any one provider: Claude Code, Codex, Nanocoder or
|
|
16
|
+
your own. On a subscription plan it is a flat cost rather than spend per token, and what grows
|
|
17
|
+
with a session is how much of its usage you take. Pip's staff run that way.
|
|
18
18
|
|
|
19
19
|
A session's cost is roughly its length. Ours run 11 to 55 minutes of wall clock, and a longer
|
|
20
20
|
session is a bigger bill as well as a slower one. The lever that matters is not the model
|
package/docs/developing.md
CHANGED
|
@@ -12,15 +12,16 @@ npm test # the whole suite
|
|
|
12
12
|
npx tsc --noEmit # typecheck
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
Tests are `node:test` run through `tsx`. There is no build step for development, and the
|
|
16
|
-
has no build step at all.
|
|
15
|
+
Tests are `node:test` run through `tsx`. There is no build step for development, and the
|
|
16
|
+
portal's page has no build step at all. `npm run build` builds the CLI and the portal's Worker.
|
|
17
17
|
|
|
18
18
|
## Layout
|
|
19
19
|
|
|
20
20
|
```
|
|
21
21
|
src/cli.ts command table and help
|
|
22
22
|
src/commands/ one file per command
|
|
23
|
-
src/lib/ shared: workspace, memory, render, merge, gh, templates, docs
|
|
23
|
+
src/lib/ shared: workspace, memory, render, merge, gh, github, vfs, templates, docs
|
|
24
|
+
src/portal/ the portal's server: handler.ts, and the Worker that hosts it
|
|
24
25
|
templates/ops/ what a tenant's ops repo is generated from
|
|
25
26
|
templates/brain/ what a staff member's repo is generated from
|
|
26
27
|
templates/portal/ the portal: a shell, css/, and js/ as ES modules
|
|
@@ -28,14 +29,31 @@ docs/ these pages
|
|
|
28
29
|
test/ one file per area
|
|
29
30
|
```
|
|
30
31
|
|
|
31
|
-
## The portal
|
|
32
|
+
## The portal's server
|
|
33
|
+
|
|
34
|
+
`src/portal/handler.ts` answers every route that works the same on your machine and hosted. It
|
|
35
|
+
reads the org through snapshots of its repositories on GitHub (`snapshot.ts`), mounted where a
|
|
36
|
+
checkout would be by `src/lib/vfs.ts`, so the readers in `src/lib` work on either. It acts
|
|
37
|
+
through `src/lib/github.ts`, a `fetch` client holding the person's token.
|
|
38
|
+
|
|
39
|
+
- `src/commands/portal.ts` is the local server. It sends those routes to the handler and keeps
|
|
40
|
+
the ones that need a checkout: setup, the App hand-off, doctor, hire and retire.
|
|
41
|
+
- `src/portal/worker.ts` is the hosted one: the same handler behind Sign in with GitHub
|
|
42
|
+
(`session.ts`). `scripts/build-worker.mjs` builds it into `dist/worker/`, and
|
|
43
|
+
`roster portal deploy` deploys it.
|
|
44
|
+
|
|
45
|
+
`test/hosted-portal.test.ts` runs the handler against a scaffolded tenant served in the API's
|
|
46
|
+
shapes (`test/helpers/githubrepos.ts`), so it needs neither the network nor an org.
|
|
47
|
+
|
|
48
|
+
## The portal's page has no build step, on purpose
|
|
32
49
|
|
|
33
50
|
`templates/portal/` is a plain `index.html`, one stylesheet per area under `css/`, and one ES
|
|
34
51
|
module per screen under `js/views/`. `roster portal` serves them from `/assets`, reading each
|
|
35
|
-
file per request. Editing a stylesheet and reloading the page is the whole edit loop.
|
|
52
|
+
file per request. Editing a stylesheet and reloading the page is the whole edit loop. The
|
|
53
|
+
Worker serves the same files, copied as they are.
|
|
36
54
|
|
|
37
|
-
No bundler, because the browser resolves the module graph itself
|
|
38
|
-
|
|
55
|
+
No bundler for the page, because the browser resolves the module graph itself. Only the
|
|
56
|
+
Worker's server code is bundled, because a Worker is one module.
|
|
39
57
|
|
|
40
58
|
```
|
|
41
59
|
templates/portal/
|
|
@@ -51,8 +69,8 @@ templates/portal/
|
|
|
51
69
|
```
|
|
52
70
|
|
|
53
71
|
`js/icons.js` holds two dozen [Lucide](https://lucide.dev) glyphs as inlined path data, ISC
|
|
54
|
-
licensed. Vendored rather than fetched, because
|
|
55
|
-
|
|
72
|
+
licensed. Vendored rather than fetched, because an icon that needs a third party's network is an
|
|
73
|
+
icon that is sometimes a blank square. They take colour from
|
|
56
74
|
`currentColor` and size from a `--ic` custom property, so a component styles them in CSS and
|
|
57
75
|
never touches the SVG. Nothing in the UI should draw with a text character.
|
|
58
76
|
|
|
@@ -63,7 +81,7 @@ registers into at boot.
|
|
|
63
81
|
## The rule that matters
|
|
64
82
|
|
|
65
83
|
**Never fix a generated file in a tenant.** `compose.mjs`, `agents.mjs`, `runner-plan.mjs`,
|
|
66
|
-
`inflight.mjs`, `run-record.mjs` and `session.yaml` live in `templates/ops/`. Fix them there and run `roster upgrade`.
|
|
84
|
+
`inflight.mjs`, `run-record.mjs`, `status-week.mjs` and `session.yaml` live in `templates/ops/`. Fix them there and run `roster upgrade`.
|
|
67
85
|
|
|
68
86
|
A fix made in the tenant's copy goes unnoticed until the framework next touches that file, and
|
|
69
87
|
then it is a conflict. So `roster upgrade` reports an edit to a framework-owned file whether or
|
package/docs/doctor-codes.md
CHANGED
|
@@ -39,7 +39,7 @@ ran at all.
|
|
|
39
39
|
| `workflows` | No workflow in the repo is failing run after run. Reported for the ops repo here, and for each brain repo under its staff member. |
|
|
40
40
|
| `workflows.failing` | **fail.** A workflow that is not one of roster's callers has failed at least its last two runs, with the date it started. Skipped and cancelled runs are stepped over. This is the canary that goes red and stays red, because whatever would have said so broke with it. |
|
|
41
41
|
| `budget` | Trailing 30-day spend against a `budget` in `org.yaml`, for the org here and for a staff member under their name. A warning when it is past, never a failure, and only read when a budget is set. Cost comes from each run's record, so it says how many runs it could price. See [cost](cost.md#budgets). |
|
|
42
|
-
| `review-gate` |
|
|
42
|
+
| `review-gate` | Off unless `review_gate: true` is in `org.yaml`, and then a note that it is off. When on, one per product repo. **fail** when nothing requires a pull request on its default branch, or a staff App can bypass the rule; a warning when a PR is required with no approving review, when the repo is private on GitHub Free (which can't enforce the rule), or when the settings cannot be read. See [security](security.md#the-review-gate). |
|
|
43
43
|
| `upgrade` | The tenant is in sync with the framework. |
|
|
44
44
|
| `upgrade.stale` | Generated files are behind. `roster upgrade --apply`. |
|
|
45
45
|
| `upgrade.owned` | **fail.** A framework-owned file was edited in the tenant. Move the change upstream or the next upgrade reverts it. |
|
|
@@ -63,6 +63,8 @@ ran at all.
|
|
|
63
63
|
| `surfaces` | A surface declared in `staff.yaml` is not on disk. The portal renders nothing for it. |
|
|
64
64
|
| `secrets` | Every secret the callers reference exists on the brain repo, or is an organisation secret shared with it. Derived from the callers themselves, not a fixed list. |
|
|
65
65
|
| `labels` | Every label declared in `staff.yaml` exists. An agent applying a label that does not exist gets an API error mid-run. |
|
|
66
|
+
| `owned-labels` | Roster's own labels exist on the tracker: `decision`, `review`, `chore` and `keep-open`. Checked whatever `staff.yaml` declares, since the prompts apply them. The fix is the `gh label create` lines. |
|
|
67
|
+
| `ask-kind` | An open issue assigned to a human has no ask kind, or more than one. Home sorts what needs you by kind, so an ask without one lands nowhere. |
|
|
66
68
|
| `peer-labels` | The `from-<handle>` label exists on the *peer's* tracker, which is where this staff member's asks land. |
|
|
67
69
|
| `status-issue` | The declared status issue is actually pinned. If not, the place you look is not the place the agent maintains. |
|
|
68
70
|
| `runs` | A window of recent runs. See below. |
|
package/docs/export.md
CHANGED
|
@@ -35,6 +35,7 @@ that reads it gets the same view without reimplementing the memory grammar.
|
|
|
35
35
|
| `statusIssue` | pinned issue number |
|
|
36
36
|
| `schedule` | cron |
|
|
37
37
|
| `mention` | what wakes them |
|
|
38
|
+
| `icon` | the icon set by `icon:` in staff.yaml, if any |
|
|
38
39
|
| `bots[]` | every App login, `[bot]` suffix stripped |
|
|
39
40
|
| `soloBots[]` | identities unique to this staff member |
|
|
40
41
|
| `sharedBots[]` | identities shared with others |
|
|
@@ -99,6 +100,7 @@ Only surfaces that exist on disk appear. A declared surface that is missing show
|
|
|
99
100
|
|---|---|
|
|
100
101
|
| `workflows[]` | filenames under `.github/workflows/` |
|
|
101
102
|
| `hasCharter`, `hasManifest` | |
|
|
103
|
+
| `charterStub` | `CHARTER.md` is absent or still the scaffold, the same test as doctor's `charter.stub` |
|
|
102
104
|
| `missingSurfaces[]` | declared, not on disk |
|
|
103
105
|
| `memoryBytes` | size of `INDEX.md` |
|
|
104
106
|
| `notesBytes` | total size of `memory/notes/` |
|
package/docs/getting-started.md
CHANGED
|
@@ -22,15 +22,16 @@ hour is the part not to rush.
|
|
|
22
22
|
|
|
23
23
|
## Before you start
|
|
24
24
|
|
|
25
|
-
- **`gh`, [signed in](https://cli.github.com)**, as someone who owns the organisation.
|
|
26
|
-
|
|
25
|
+
- **`gh`, [signed in](https://cli.github.com)**, as someone who owns the organisation. Setting
|
|
26
|
+
up, hiring and the GitHub Apps go through your own `gh`, and the portal on your machine uses
|
|
27
|
+
its token to act as you. roster keeps no token of its own.
|
|
27
28
|
- **A GitHub organisation.** GitHub has no API for creating one, so if you need one, make it on
|
|
28
29
|
github.com first. Brains are private repos; on GitHub Free that works, with one difference in
|
|
29
30
|
step 5.
|
|
30
31
|
- **A credential for your [coding agent](agents.md).** For Claude Code, run
|
|
31
32
|
`claude setup-token` and keep the token it prints for step 5.
|
|
32
33
|
|
|
33
|
-
You only need [the
|
|
34
|
+
You only need [the three things in Concepts](concepts.md#the-three-things-you-need-to-know) to follow
|
|
34
35
|
this. Everything else can wait.
|
|
35
36
|
|
|
36
37
|
## 1. Say which organisation, then read the plan
|
|
@@ -51,7 +52,8 @@ can call its workflow. Without that every run fails with "workflow not found". I
|
|
|
51
52
|
(it needs admin on the repo), the page says why and links to the setting to click instead.
|
|
52
53
|
|
|
53
54
|
The rest of the steps stay on the same page. Reload it and the portal opens on **Getting
|
|
54
|
-
started**, which keeps them in the sidebar until they are done, with hiring first.
|
|
55
|
+
started**, which keeps them in the sidebar until they are done, with hiring first. The sidebar
|
|
56
|
+
counts them: three for the org, five for each staff member.
|
|
55
57
|
|
|
56
58
|
## 2. Say what the business is
|
|
57
59
|
|
|
@@ -71,49 +73,61 @@ See [concepts](concepts.md#priorities).
|
|
|
71
73
|
|
|
72
74
|

|
|
73
75
|
|
|
74
|
-
**Staff
|
|
75
|
-
|
|
76
|
-
|
|
76
|
+
**Staff**, then pick a role: CTO, CMO, Support, or **Something else** with a name and a sentence
|
|
77
|
+
about what they do. With nobody hired yet the Staff screen opens on the picker. The role fills
|
|
78
|
+
in the handle, name and repo; they are under **Advanced** if you want to change them.
|
|
77
79
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
80
|
+
The role opens a numbered list: hire, create their GitHub App, write their charter, add your
|
|
81
|
+
agent credential, run once now. The steps after the hire say *Hire first* until it is done.
|
|
82
|
+
|
|
83
|
+
Step 1 says in one sentence what the hire creates and when they run. **Show details** has the
|
|
84
|
+
full plan: the repo, the schedule and why, and the commits it will make **as you** in repos that
|
|
85
|
+
already exist: each peer's `staff.yaml`, and `org.yaml`. Nothing is left uncommitted on disk.
|
|
86
|
+
|
|
87
|
+
For the first hire there is nobody to copy an App name from, so **Advanced** also has two:
|
|
88
|
+
this staff member's App, and the shared public App, filled in as `<org>-<handle>` and
|
|
89
|
+
`<org>-robot`. Names are unique across GitHub, so keep the org prefix. The public one only
|
|
90
|
+
matters if a product repo is public.
|
|
82
91
|
|
|
83
92
|
Product repos come from `org.yaml`. Mark one on the setup screen, or later with **Org → Add a
|
|
84
93
|
product repo**.
|
|
85
94
|
|
|
95
|
+
After **Hire** the list stays on the same staff member, now on step 2. Leave and come back later
|
|
96
|
+
with **Finish setting up** on their card.
|
|
97
|
+
|
|
86
98
|
## 4. Create the App, and confirm the install
|
|
87
99
|
|
|
88
|
-
**
|
|
100
|
+
**Create the App**, in step 2. GitHub has no API that creates an App, so a tab opens and you
|
|
89
101
|
confirm. The App's id and private key go straight into the repo's secrets and never touch disk.
|
|
102
|
+
The public App is offered too when a product repo is public.
|
|
90
103
|
|
|
91
104
|
Then **Install it**. The install page opens with the organisation and every repo this staff
|
|
92
105
|
member needs already ticked: its brain, the trackers of its peers, and the product repos. Check
|
|
93
106
|
the list and confirm. That confirmation is yours by design: installing grants access, and GitHub
|
|
94
107
|
asks a person.
|
|
95
108
|
|
|
96
|
-
## 5.
|
|
109
|
+
## 5. Write the charter
|
|
97
110
|
|
|
98
|
-
**
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
111
|
+
Step 3. **Let an AI interview you** is the same copy-a-prompt loop as step 2 of this guide, aimed
|
|
112
|
+
at `CHARTER.md`, carrying the org layer, the peers' charters and, where the role matches one, a
|
|
113
|
+
[worked example](writing-a-charter.md#worked-examples) to model the shape on. **Start from the
|
|
114
|
+
template** opens that example in an editor with your business's name in it; edit it so it fits
|
|
115
|
+
before saving. **Edit the file** is the file as it is. roster never generates a charter, because
|
|
116
|
+
a generated one makes exactly the generic agent this whole arrangement exists to avoid.
|
|
102
117
|
|
|
103
|
-
|
|
104
|
-
instead, and the page says so. It is still one paste now; a later hire needs it once more.
|
|
118
|
+
## 6. Store the agent credential, once
|
|
105
119
|
|
|
106
|
-
|
|
120
|
+
Step 4, shown only while no credential is stored. It is also on the card and on the setup
|
|
121
|
+
screen. Paste the token from `claude setup-token` (or your agent's key; the box says where to
|
|
122
|
+
get one). It is stored as one organisation secret, shared with the brain repos, and each later
|
|
123
|
+
hire is added to it. It is not asked for again.
|
|
107
124
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
[worked example](writing-a-charter.md#worked-examples) to model the shape on. The brief
|
|
111
|
-
interviews you; the charter is yours. roster never generates one, because a generated charter
|
|
112
|
-
makes exactly the generic agent this whole arrangement exists to avoid.
|
|
125
|
+
On GitHub Free an org secret does not reach private repos, so there it goes on each brain repo
|
|
126
|
+
instead, and the page says so. It is still one paste now; a later hire needs it once more.
|
|
113
127
|
|
|
114
128
|
## 7. Run it once
|
|
115
129
|
|
|
116
|
-
**Run once now**, on the card
|
|
130
|
+
**Run once now**, step 5, also on the card and on **Health**. It starts the daily workflow, follows it, and
|
|
117
131
|
tells you how it ended, with the log.
|
|
118
132
|
|
|
119
133
|
**A workflow that has never run has proved nothing**: not that the App is installed on the right
|
|
@@ -144,9 +158,13 @@ member on their next run.
|
|
|
144
158
|
|
|
145
159
|
The same road, command by command. Each prints its plan and changes nothing without `--apply`.
|
|
146
160
|
|
|
161
|
+
`roster` below means `npx @nanocollective/roster@latest`, unless you have installed it with
|
|
162
|
+
`npm install -g @nanocollective/roster`.
|
|
163
|
+
|
|
147
164
|
```bash
|
|
148
165
|
roster init --org acme --apply # the ops repo, and its Actions access
|
|
149
|
-
roster brief discover # a brief for org/business.md
|
|
166
|
+
roster brief discover # a brief for org/business.md
|
|
167
|
+
roster brief priorities # a brief for org/priorities.md
|
|
150
168
|
roster hire cto --apply # the brain, the wiring, the commits as you
|
|
151
169
|
roster app cto --apply # the App, its secrets, and a pre-ticked install link
|
|
152
170
|
roster credential --apply # the agent credential, once for the org
|
|
@@ -165,8 +183,10 @@ each.
|
|
|
165
183
|
|
|
166
184
|
- **A second staff member**: Staff → Hire someone, then GitHub App, the charter and one run. The
|
|
167
185
|
credential is already there.
|
|
168
|
-
- **Answering your agents**: [
|
|
169
|
-
|
|
186
|
+
- **Answering your agents**: [Home](portal.md#home) is what needs you, who is working and
|
|
187
|
+
what you asked for. Replies and merges go out as you.
|
|
170
188
|
- **A framework update**: `roster upgrade`, or the same from the portal. See
|
|
171
189
|
[upgrading](upgrading.md).
|
|
172
190
|
- **The whole portal**, screen by screen: [the portal](portal.md).
|
|
191
|
+
- **The portal on your own URL**, so you can answer your staff from anywhere, your phone
|
|
192
|
+
included: `roster portal deploy`. See [hosting the portal](hosting.md).
|
package/docs/hosting.md
CHANGED
|
@@ -1,72 +1,143 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Hosting the portal"
|
|
3
|
-
description: "
|
|
3
|
+
description: "The portal on your own URL, behind Sign in with GitHub, redeploying itself."
|
|
4
4
|
sidebar_order: 11
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Hosting the portal
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
repositories from disk, needs no authentication, hits no API rate limits, and works offline.
|
|
9
|
+
The portal runs in two places, and it is the same code in both.
|
|
11
10
|
|
|
12
11
|
```bash
|
|
13
|
-
roster portal
|
|
14
|
-
roster portal --
|
|
12
|
+
roster portal # on your machine, http://localhost:4300
|
|
13
|
+
roster portal deploy --domain roster.acme.com # on the web, on Cloudflare Workers
|
|
15
14
|
```
|
|
16
15
|
|
|
17
|
-
|
|
16
|
+
Both read the org from GitHub, so neither needs the repos checked out to show it. Both act on
|
|
17
|
+
GitHub as the person using them. The hosted one adds a sign-in in front, and leaves out the
|
|
18
|
+
few screens that need a checkout.
|
|
18
19
|
|
|
19
|
-
|
|
20
|
-
repository secrets, and none of that belongs behind a tunnel or an access proxy. Everything below
|
|
21
|
-
is about a portal over an org that already exists.
|
|
20
|
+
## What you get, and what stays on your machine
|
|
22
21
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
22
|
+
Hosted, you get everything you use day to day: Home, the trackers, threads and replies, pull
|
|
23
|
+
requests (approve and merge), Runs, the brains, prompts, the org files and their editors, and
|
|
24
|
+
the docs.
|
|
26
25
|
|
|
27
|
-
|
|
26
|
+
These stay on your machine, and the hosted page says so where they would be:
|
|
28
27
|
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
|
|
32
|
-
- an `Origin` header, if present, must be localhost
|
|
28
|
+
- **Setup**: standing up an org, the GitHub Apps, the agent credential
|
|
29
|
+
- **Hiring and retiring**
|
|
30
|
+
- **Doctor and the Health checklist**, which read the checkout and the org's secrets
|
|
33
31
|
|
|
34
|
-
|
|
35
|
-
|
|
32
|
+
They create repositories and Apps and write secrets, which is the most privileged thing roster
|
|
33
|
+
does. That is not something to put behind a public URL.
|
|
36
34
|
|
|
37
|
-
##
|
|
35
|
+
## Who can get in
|
|
38
36
|
|
|
39
|
-
|
|
37
|
+
Only the people listed under `humans:` in `org.yaml`, signed in with their own GitHub account.
|
|
40
38
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
39
|
+
- Sign-in is GitHub's own OAuth flow, through an OAuth App your org creates for the portal.
|
|
40
|
+
The token it hands back is that person's, scoped `repo` and `notifications`, the same kind
|
|
41
|
+
`gh` holds on their machine.
|
|
42
|
+
- Everything they do is as themselves. A reply is theirs, a merge is theirs, and what they can
|
|
43
|
+
read is what GitHub lets them read.
|
|
44
|
+
- Somebody who signs in and is not one of the humans, or cannot read the ops repo, is turned
|
|
45
|
+
away and their token revoked. Somebody removed from `humans:` stops getting in within a few
|
|
46
|
+
minutes.
|
|
47
|
+
- A sign-in lasts fourteen days. Signing out revokes the token on GitHub.
|
|
44
48
|
|
|
45
|
-
|
|
46
|
-
|
|
49
|
+
See [security](security.md#the-hosted-portal) for what is held where.
|
|
50
|
+
|
|
51
|
+
## Talking to your staff from Claude
|
|
52
|
+
|
|
53
|
+
The hosted portal is also an MCP server, at `/mcp`. Add it to Claude as a custom connector with
|
|
54
|
+
the URL `https://roster.acme.com/mcp`. Claude sends you to sign in with GitHub, the same check
|
|
55
|
+
against `humans:` as the portal, and then to a page that says what it will be able to do, with
|
|
56
|
+
**Allow**.
|
|
57
|
+
|
|
58
|
+
Then you can ask Claude things like "what needs me today?", "what did the CTO do?" or "tell the
|
|
59
|
+
CMO to draft this week's post". The tools:
|
|
60
|
+
|
|
61
|
+
| Tool | Does |
|
|
62
|
+
|---|---|
|
|
63
|
+
| `brief` | The last day's reports, what needs you (with each decision's default), your requests, what was closed today |
|
|
64
|
+
| `read_thread` | One issue or pull request with every reply |
|
|
65
|
+
| `reply` | A reply as you, optionally closing the issue |
|
|
66
|
+
| `ask_staff` | A new issue on a staff member's tracker with their mention, which starts them |
|
|
67
|
+
| `ask_for_report` | Asks a staff member for a report on their status issue |
|
|
68
|
+
| `read_brain` | `STATE.md`, `CHARTER.md`, `memory/INDEX.md`, `log/decisions.md` or `staff.yaml` |
|
|
69
|
+
|
|
70
|
+
It cannot merge, approve, hire, or change the org: those stay on Home, where you see the diff
|
|
71
|
+
or the plan first. Everything it posts is posted as you.
|
|
72
|
+
|
|
73
|
+
Nothing to set up beyond the portal itself: the connector signs in through the same OAuth App,
|
|
74
|
+
on a callback under the one you registered (`/auth/callback/mcp`), which GitHub accepts.
|
|
75
|
+
|
|
76
|
+
## Deploying it
|
|
77
|
+
|
|
78
|
+
You need a Cloudflare account with the domain on it, and wrangler signed in to it. If your
|
|
79
|
+
login can see more than one account, pass `--account <id>` with the one that has the domain, and
|
|
80
|
+
it is pinned in the config so a later deploy cannot land anywhere else:
|
|
47
81
|
|
|
48
82
|
```bash
|
|
49
|
-
|
|
83
|
+
npx wrangler login
|
|
84
|
+
roster portal deploy --domain roster.acme.com # says what it will do
|
|
85
|
+
roster portal deploy --domain roster.acme.com --apply # does it
|
|
50
86
|
```
|
|
51
87
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
88
|
+
The first time, it stops for the one thing only you can do: **create the OAuth App**. It prints
|
|
89
|
+
the link and the three fields:
|
|
90
|
+
|
|
91
|
+
| Field | Value |
|
|
92
|
+
|---|---|
|
|
93
|
+
| Application name | `<org> roster` |
|
|
94
|
+
| Homepage URL | `https://roster.acme.com` |
|
|
95
|
+
| Authorization callback URL | `https://roster.acme.com/auth/callback` |
|
|
96
|
+
|
|
97
|
+
Register it, generate a client secret, and paste the two values when asked. The secret is not
|
|
98
|
+
shown as you type.
|
|
99
|
+
|
|
100
|
+
Then it deploys the Worker, stores the App's secret and a fresh session key as Worker secrets,
|
|
101
|
+
and commits two files to the ops repo:
|
|
55
102
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
unauthenticated URL is not an option even if nobody knows it.
|
|
103
|
+
- `portal/wrangler.jsonc`: the Worker's name, the domain, the org. Nothing secret.
|
|
104
|
+
- `.github/workflows/portal.yaml`: redeploys it.
|
|
59
105
|
|
|
60
|
-
|
|
61
|
-
GitHub App of its own, a session layer, and a credible answer to "what can this thing do if
|
|
62
|
-
someone reaches it". None of that exists, and the local server plus a tunnel gets you the same
|
|
63
|
-
outcome with none of it.
|
|
106
|
+
## Keeping it up to date
|
|
64
107
|
|
|
65
|
-
|
|
108
|
+
The workflow redeploys the portal when its config changes, every morning, and when you run it
|
|
109
|
+
by hand. Each deploy uses the newest roster, so updates arrive by themselves.
|
|
66
110
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
111
|
+
It needs two secrets on the ops repo:
|
|
112
|
+
|
|
113
|
+
| Secret | Where from |
|
|
114
|
+
|---|---|
|
|
115
|
+
| `CLOUDFLARE_API_TOKEN` | Cloudflare dashboard → API Tokens → the **Edit Cloudflare Workers** template |
|
|
116
|
+
| `CLOUDFLARE_ACCOUNT_ID` | the Workers page of the dashboard |
|
|
117
|
+
|
|
118
|
+
Without them the portal still runs; it only stops updating itself.
|
|
119
|
+
|
|
120
|
+
The portal reads GitHub fresh as you use it, so there is nothing to sync. It asks whether
|
|
121
|
+
anything has moved every few seconds, and an answer of "no" costs nothing against GitHub's
|
|
122
|
+
hourly limit.
|
|
123
|
+
|
|
124
|
+
## The cache
|
|
125
|
+
|
|
126
|
+
The portal keeps what it has read from GitHub: file contents by their hash, each commit's file
|
|
127
|
+
dates, and finished runs' costs. All of it is immutable, so it is never stale.
|
|
128
|
+
|
|
129
|
+
On your machine it is `~/.cache/roster`. On Cloudflare it is the edge cache, which needs no
|
|
130
|
+
setup. To keep it everywhere rather than per data centre, bind a KV namespace as `CACHE` in
|
|
131
|
+
`portal/wrangler.jsonc`.
|
|
132
|
+
|
|
133
|
+
## On your machine
|
|
134
|
+
|
|
135
|
+
`roster portal` binds to `127.0.0.1` and acts as whoever `gh` is signed in as. To open an org
|
|
136
|
+
you have never cloned:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
roster portal --org acme
|
|
140
|
+
```
|
|
70
141
|
|
|
71
|
-
|
|
72
|
-
|
|
142
|
+
`--host` overrides the bind address and prints a warning. The local server has no sign-in, so
|
|
143
|
+
use the hosted portal instead of exposing it.
|
package/docs/images/brain.jpg
CHANGED
|
Binary file
|
|
Binary file
|
package/docs/images/org.jpg
CHANGED
|
Binary file
|
package/docs/images/prompt.jpg
CHANGED
|
Binary file
|
package/docs/images/staff.jpg
CHANGED
|
Binary file
|
package/docs/manual-steps.md
CHANGED
|
@@ -45,8 +45,9 @@ hand. roster says so if it happens.
|
|
|
45
45
|
## 3. Confirm the App's install
|
|
46
46
|
|
|
47
47
|
**Do:** press **Install it** in the portal, or open the link `roster app` prints. The page opens
|
|
48
|
-
with the organisation and the repos this staff member needs already selected: its brain,
|
|
49
|
-
peer's tracker, and the product repos. Check the
|
|
48
|
+
with the organisation and the repos this staff member needs already selected: its brain, the
|
|
49
|
+
ops repo (every run checks it out first), each peer's tracker, and the product repos. Check the
|
|
50
|
+
list and confirm. Choosing **All repositories** instead also works.
|
|
50
51
|
|
|
51
52
|
**Why not automated:** installing is a grant of access to specific repositories, and GitHub asks
|
|
52
53
|
a person to confirm it. That is correct and should not be worked around.
|
package/docs/memory.md
CHANGED
|
@@ -69,7 +69,8 @@ hand-off and make pruning that run's job when it is over.
|
|
|
69
69
|
- **How a thing works.** That is a draft or a strategy document.
|
|
70
70
|
- **An idea not yet acted on.** That is one line in `strategy/ideas.md`, and it becomes an issue
|
|
71
71
|
only when it needs a ruling.
|
|
72
|
-
- **What is outstanding.** That is the
|
|
72
|
+
- **What is outstanding.** That is `STATE.md`, the handover each daily run rewrites. The pinned
|
|
73
|
+
status issue is the same picture written for you.
|
|
73
74
|
|
|
74
75
|
Nothing is copied between them. Four places, four jobs, and a fact that appears in two of them
|
|
75
76
|
will disagree with itself within a month.
|
package/docs/org-yaml.md
CHANGED
|
@@ -39,6 +39,7 @@ defaults:
|
|
|
39
39
|
mention_timeout_minutes: 90
|
|
40
40
|
|
|
41
41
|
budget: 300
|
|
42
|
+
review_gate: true
|
|
42
43
|
|
|
43
44
|
staff:
|
|
44
45
|
- { handle: cto, dir: technology, name: Chief Technology Officer, schedule: "0 7 * * 1-5" }
|
|
@@ -61,6 +62,7 @@ repos:
|
|
|
61
62
|
| `ops_dir` | no | Directory name of the ops repo in the runner checkout. Defaults to `roster-ops`. |
|
|
62
63
|
| `experiment_private` | no | Whether the fact that this org is agent-run is itself private. Read by the guardrails fragment. |
|
|
63
64
|
| `budget` | no | USD over any trailing 30 days, for the whole org. See [below](#budget). |
|
|
65
|
+
| `review_gate` | no | `true` to have GitHub require a reviewed pull request before anything merges into a product repo. Off by default, because private repos need a paid plan for it. See [security](security.md#the-review-gate). |
|
|
64
66
|
|
|
65
67
|
### `human` and `humans`
|
|
66
68
|
|
|
@@ -124,6 +126,7 @@ Fallbacks for staff members who do not set their own.
|
|
|
124
126
|
| `model` | Model id passed to the agent. |
|
|
125
127
|
| `timeout_minutes` | Ceiling on a daily session. `90` if unset. |
|
|
126
128
|
| `mention_timeout_minutes` | Ceiling on a mention run. Falls back to `timeout_minutes`, then `90`. |
|
|
129
|
+
| `max_runs_per_day` | What a new hire's `max_runs_per_day` starts at. `6` when unset. |
|
|
127
130
|
| `allowed_tools` | Claude's own spelling of a permission level, kept because it predates `agent.permissions` and still wins for the agents that take a tool list. Nothing translates it for the others: a list written for one agent is not a permission level for another. Prefer [`agent.permissions`](agents.md#permissions), which every agent understands. |
|
|
128
131
|
|
|
129
132
|
### `memory`
|