@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.
Files changed (151) hide show
  1. package/README.md +6 -0
  2. package/dist/cli.js +4189 -1971
  3. package/dist/worker/assets/assets/css/base.css +327 -0
  4. package/dist/worker/assets/assets/css/brain.css +116 -0
  5. package/dist/worker/assets/assets/css/diff.css +33 -0
  6. package/dist/worker/assets/assets/css/graph.css +39 -0
  7. package/dist/worker/assets/assets/css/health.css +75 -0
  8. package/dist/worker/assets/assets/css/home.css +114 -0
  9. package/dist/worker/assets/assets/css/inbox.css +199 -0
  10. package/dist/worker/assets/assets/css/layout.css +181 -0
  11. package/dist/worker/assets/assets/css/markdown.css +96 -0
  12. package/dist/worker/assets/assets/css/runs.css +13 -0
  13. package/dist/worker/assets/assets/css/search.css +48 -0
  14. package/dist/worker/assets/assets/css/setup.css +194 -0
  15. package/dist/worker/assets/assets/js/api.js +191 -0
  16. package/dist/worker/assets/assets/js/app.js +500 -0
  17. package/dist/worker/assets/assets/js/dialog.js +196 -0
  18. package/dist/worker/assets/assets/js/dom.js +131 -0
  19. package/dist/worker/assets/assets/js/homesort.js +174 -0
  20. package/dist/worker/assets/assets/js/icons.js +142 -0
  21. package/dist/worker/assets/assets/js/inflight.js +18 -0
  22. package/dist/worker/assets/assets/js/lightbox.js +273 -0
  23. package/dist/worker/assets/assets/js/md.js +406 -0
  24. package/dist/worker/assets/assets/js/mdedit.js +84 -0
  25. package/dist/worker/assets/assets/js/mention.js +264 -0
  26. package/dist/worker/assets/assets/js/readiness.js +70 -0
  27. package/dist/worker/assets/assets/js/refresh.js +197 -0
  28. package/dist/worker/assets/assets/js/router.js +20 -0
  29. package/dist/worker/assets/assets/js/search.js +366 -0
  30. package/dist/worker/assets/assets/js/state.js +213 -0
  31. package/dist/worker/assets/assets/js/textdiff.js +96 -0
  32. package/dist/worker/assets/assets/js/views/app.js +145 -0
  33. package/dist/worker/assets/assets/js/views/brain.js +260 -0
  34. package/dist/worker/assets/assets/js/views/changed.js +157 -0
  35. package/dist/worker/assets/assets/js/views/checklist.js +115 -0
  36. package/dist/worker/assets/assets/js/views/credential.js +84 -0
  37. package/dist/worker/assets/assets/js/views/docs.js +174 -0
  38. package/dist/worker/assets/assets/js/views/files.js +139 -0
  39. package/dist/worker/assets/assets/js/views/graph.js +436 -0
  40. package/dist/worker/assets/assets/js/views/health.js +304 -0
  41. package/dist/worker/assets/assets/js/views/hire.js +593 -0
  42. package/dist/worker/assets/assets/js/views/home.js +621 -0
  43. package/dist/worker/assets/assets/js/views/inbox.js +1558 -0
  44. package/dist/worker/assets/assets/js/views/memory.js +150 -0
  45. package/dist/worker/assets/assets/js/views/org.js +195 -0
  46. package/dist/worker/assets/assets/js/views/orgedit.js +240 -0
  47. package/dist/worker/assets/assets/js/views/paste.js +216 -0
  48. package/dist/worker/assets/assets/js/views/prompt.js +457 -0
  49. package/dist/worker/assets/assets/js/views/repos.js +97 -0
  50. package/dist/worker/assets/assets/js/views/runonce.js +94 -0
  51. package/dist/worker/assets/assets/js/views/runs.js +182 -0
  52. package/dist/worker/assets/assets/js/views/setup.js +557 -0
  53. package/dist/worker/assets/assets/js/views/staff.js +291 -0
  54. package/dist/worker/assets/assets/js/views/todo.js +62 -0
  55. package/dist/worker/assets/assets/js/yaml.js +134 -0
  56. package/dist/worker/assets/docs-images/brain.jpg +0 -0
  57. package/dist/worker/assets/docs-images/home.jpg +0 -0
  58. package/dist/worker/assets/docs-images/org.jpg +0 -0
  59. package/dist/worker/assets/docs-images/prompt.jpg +0 -0
  60. package/dist/worker/assets/docs-images/setup-org.jpg +0 -0
  61. package/dist/worker/assets/docs-images/setup-plan.jpg +0 -0
  62. package/dist/worker/assets/docs-images/staff.jpg +0 -0
  63. package/dist/worker/assets/index.html +82 -0
  64. package/dist/worker/index.js +5143 -0
  65. package/docs/README.md +2 -2
  66. package/docs/architecture.md +23 -4
  67. package/docs/charters/analyst.md +65 -0
  68. package/docs/charters/community.md +63 -0
  69. package/docs/charters/designer.md +65 -0
  70. package/docs/charters/devops.md +65 -0
  71. package/docs/charters/pm.md +70 -0
  72. package/docs/charters/qa.md +65 -0
  73. package/docs/charters/writer.md +63 -0
  74. package/docs/commands.md +36 -9
  75. package/docs/concepts.md +34 -21
  76. package/docs/cost.md +3 -3
  77. package/docs/developing.md +28 -10
  78. package/docs/doctor-codes.md +3 -1
  79. package/docs/export.md +2 -0
  80. package/docs/getting-started.md +49 -29
  81. package/docs/hosting.md +114 -43
  82. package/docs/images/brain.jpg +0 -0
  83. package/docs/images/home.jpg +0 -0
  84. package/docs/images/org.jpg +0 -0
  85. package/docs/images/prompt.jpg +0 -0
  86. package/docs/images/staff.jpg +0 -0
  87. package/docs/manual-steps.md +3 -2
  88. package/docs/memory.md +2 -1
  89. package/docs/org-yaml.md +3 -0
  90. package/docs/portal.md +144 -45
  91. package/docs/prompts.md +6 -0
  92. package/docs/security.md +70 -11
  93. package/docs/session-workflow.md +24 -6
  94. package/docs/staff-yaml.md +21 -2
  95. package/docs/upgrading.md +3 -3
  96. package/docs/writing-a-charter.md +19 -6
  97. package/package.json +4 -3
  98. package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml +20 -1
  99. package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml +53 -13
  100. package/templates/brain/CHARTER.md +2 -2
  101. package/templates/brain/STATE.md +16 -0
  102. package/templates/brain/memory/INDEX.md +1 -1
  103. package/templates/brain/staff.yaml +4 -1
  104. package/templates/briefs/amend.md +4 -3
  105. package/templates/briefs/priorities.md +46 -0
  106. package/templates/ops/.github/workflows/session.yaml +150 -3
  107. package/templates/ops/compose.mjs +35 -8
  108. package/templates/ops/org/operating.md +29 -10
  109. package/templates/ops/org/voice.md +2 -1
  110. package/templates/ops/prompts/daily.md +51 -14
  111. package/templates/ops/prompts/mention.md +24 -2
  112. package/templates/ops/run-record.mjs +5 -3
  113. package/templates/ops/status-week.mjs +169 -0
  114. package/templates/portal/css/base.css +49 -0
  115. package/templates/portal/css/health.css +14 -1
  116. package/templates/portal/css/home.css +114 -0
  117. package/templates/portal/css/inbox.css +21 -4
  118. package/templates/portal/css/layout.css +35 -3
  119. package/templates/portal/css/markdown.css +19 -0
  120. package/templates/portal/css/search.css +48 -0
  121. package/templates/portal/css/setup.css +79 -4
  122. package/templates/portal/index.html +15 -9
  123. package/templates/portal/js/api.js +60 -4
  124. package/templates/portal/js/app.js +125 -7
  125. package/templates/portal/js/dialog.js +36 -0
  126. package/templates/portal/js/homesort.js +174 -0
  127. package/templates/portal/js/icons.js +41 -0
  128. package/templates/portal/js/inflight.js +18 -0
  129. package/templates/portal/js/md.js +5 -2
  130. package/templates/portal/js/mdedit.js +84 -0
  131. package/templates/portal/js/readiness.js +70 -0
  132. package/templates/portal/js/refresh.js +10 -2
  133. package/templates/portal/js/search.js +366 -0
  134. package/templates/portal/js/state.js +11 -5
  135. package/templates/portal/js/views/app.js +1 -2
  136. package/templates/portal/js/views/brain.js +1 -1
  137. package/templates/portal/js/views/checklist.js +19 -4
  138. package/templates/portal/js/views/credential.js +42 -51
  139. package/templates/portal/js/views/health.js +11 -6
  140. package/templates/portal/js/views/hire.js +593 -0
  141. package/templates/portal/js/views/home.js +621 -0
  142. package/templates/portal/js/views/inbox.js +237 -68
  143. package/templates/portal/js/views/org.js +31 -111
  144. package/templates/portal/js/views/orgedit.js +240 -0
  145. package/templates/portal/js/views/paste.js +111 -66
  146. package/templates/portal/js/views/prompt.js +94 -40
  147. package/templates/portal/js/views/repos.js +10 -10
  148. package/templates/portal/js/views/runs.js +21 -4
  149. package/templates/portal/js/views/setup.js +130 -163
  150. package/templates/portal/js/views/staff.js +181 -301
  151. 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 six things you need to know
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 layer.** One private repo, `<org>/roster-ops`, holds what every staff member
15
- shares: what the business is (`org/business.md`), what matters this month
16
- (`org/priorities.md`), the house voice and the guardrails. Change it once and every staff
17
- member has it on their next run. [More](#the-ops-repo).
18
- 2. **A staff member is a repo.** Each one has a private repo, its *brain*: what it knows, what
19
- it is working on, and what it has decided. There is no database and no server; the portal
20
- reads the repos. [More](#the-brain).
21
- 3. **The charter.** `CHARTER.md` in the brain says who this staff member is and what it
22
- decides alone. You write it, with a brief that interviews you; roster never generates one,
23
- because a generated charter makes a generic agent. [More](#charter-and-manifest).
24
- 4. **Memory.** `memory/INDEX.md` is one line per fact, read at the start of every run. The
25
- agent writes it and deletes from it; you can read and correct it in the portal. That is how
26
- a staff member remembers yesterday. [More](memory.md).
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
- On a Claude subscription, through a Claude Code OAuth token, it is a flat subscription rather
16
- than spend per token, and what grows with a session is how much of its usage you take. That is
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
@@ -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 portal
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 has no build step, on purpose
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, and a bundler would be a
38
- build step in a tool whose selling point is that it does not have one.
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 the portal is offline-first and an icon that
55
- needs the network is an icon that is sometimes a blank square. They take colour from
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
@@ -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` | 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, or the settings cannot be read. See [security](security.md#the-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/` |
@@ -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. roster
26
- does everything through your own `gh` and holds no token of its own.
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 six things in Concepts](concepts.md#the-six-things-you-need-to-know) to follow
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
  ![The Staff screen, with a card per staff member and Hire someone underneath](images/staff.jpg)
73
75
 
74
- **Staff → Hire someone.** Only the handle is required. The plan shows the repo it creates, the
75
- schedule it chose, and the commits it will make **as you** in repos that already exist: each
76
- peer's `staff.yaml`, and `org.yaml`. Nothing is left uncommitted on disk.
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
- For the first hire there is nobody to copy an App name from, so the form asks for two: this
79
- staff member's App, and the shared public App. Names are unique across GitHub, so prefix them
80
- with the org. The public one only matters if a product repo is public; leave it empty when they
81
- are all private.
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
- **GitHub App**, on the new card. GitHub has no API that creates an App, so a tab opens and you
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. Store the agent credential, once
109
+ ## 5. Write the charter
97
110
 
98
- **Agent credential**, on the card or on the setup screen. Paste the token from `claude
99
- setup-token` (or your agent's key; the box says where to get one). It is stored as one
100
- organisation secret, shared with the brain repos, and each later hire is added to it. It is not
101
- asked for again.
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
- On GitHub Free an org secret does not reach private repos, so there it goes on each brain repo
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
- ## 6. Write the charter
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
- **Write the charter**, on the card. The same copy-a-prompt loop as step 2, aimed at
109
- `CHARTER.md`, carrying the org layer, the peers' charters and, where the role matches one, a
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 or on **Health**. It starts the daily workflow, follows it, and
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; write priorities.md too
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**: [the Inbox](portal.md#inbox) is everything open across the org, and
169
- the reply goes out as you. Work they finished sits in [Pending work](portal.md#pending-work).
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: "Local is the default, and the honest options if you want it elsewhere."
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
- `roster portal` is local-first and that is the intended way to run it. It reads the checked-out
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 # http://localhost:4300
14
- roster portal --port 4400
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
- ## Why local is the default
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
- **Setup is local only.** The screen that stands up a tenant also creates GitHub Apps and writes
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
- The portal can write. It replies to issues, closes them, reopens them and opens new ones,
24
- acting as you through your own `gh`. That is the point: it is where a person answers their
25
- agents. It also means it is not a thing to leave listening on a network.
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
- Three things guard it, and they only work locally:
26
+ These stay on your machine, and the hosted page says so where they would be:
28
27
 
29
- - it binds to `127.0.0.1`
30
- - a write needs a `POST` with an `x-roster` header, which forces a CORS preflight that fails
31
- from any other origin
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
- `--host` overrides the bind address and prints a warning. Do not use it to "just have a look
35
- from my phone".
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
- ## Reading it from elsewhere
35
+ ## Who can get in
38
36
 
39
- The honest options, in order of how much you should like them.
37
+ Only the people listed under `humans:` in `org.yaml`, signed in with their own GitHub account.
40
38
 
41
- **A tunnel, briefly.** `ssh -L 4300:localhost:4300 you@yourmachine`, or Tailscale, or
42
- `cloudflared tunnel --url http://localhost:4300`. Your machine stays the only thing running it
43
- and the write path stays behind your own network identity. Turn it off afterwards.
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
- **A read-only static build.** `roster export` produces the whole org as one JSON document, and
46
- the portal's rendering is decoupled from its parsing precisely so this is possible:
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
- roster export --out org.json
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
- Serve that plus the portal HTML from anything static (Cloudflare Pages, S3, a directory). You
53
- get memory, the graph, the brain and what-changed. You do not get the inbox or any write
54
- action, because both need `gh`.
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
- Put access control in front of it. Cloudflare Access with a one-person policy is the least
57
- work. **This is private business content and a map of what your agents know**, so an
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
- **A hosted instance with write access.** Not documented, and not recommended. It would need a
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
- ## Keeping it current
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
- The portal reads your working tree, so a stale checkout shows stale data. `/api/sync` fetches
68
- and fast-forwards every repository on each refresh. It refuses to pull one that is dirty or has
69
- diverged, and says which in a banner rather than guessing.
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
- If you host a static export, the export is a point in time. Regenerate it on a schedule, or
72
- accept that it is yesterday's.
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.
Binary file
Binary file
Binary file
Binary file
Binary file
@@ -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, each
49
- peer's tracker, and the product repos. Check the list and confirm.
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 pinned status issue.
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`