@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/portal.md
CHANGED
|
@@ -10,19 +10,33 @@ sidebar_order: 17
|
|
|
10
10
|
roster # or `roster portal`, or `npx @nanocollective/roster`
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
A
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
A web UI over every staff member's brain, read from GitHub as you. It needs no checkout to show
|
|
14
|
+
the org, and it acts on GitHub with your own token, so a reply here is the same as a reply on the
|
|
15
|
+
site. Setting up, hiring and doctor still use the checkout, so keep the repos checked out beside
|
|
16
|
+
each other, in the same shape the runner uses.
|
|
16
17
|
|
|
17
|
-
|
|
18
|
+
It can also be hosted, on your own URL behind Sign in with GitHub: see [hosting](hosting.md).
|
|
18
19
|
|
|
19
20
|
## The sidebar
|
|
20
21
|
|
|
22
|
+
**Search everything** with ⌘K (Ctrl+K off a Mac), from anywhere, or the Search field at the
|
|
23
|
+
top of the sidebar, which opens the same dialog. It searches as you type, across:
|
|
24
|
+
|
|
25
|
+
- issues and pull requests, open and recently closed, which open in the side sheet
|
|
26
|
+
- staff, every fact in every memory, and every note and file in every brain
|
|
27
|
+
- the org files, the docs (every page, not only titles), and runs from the last 30 days, which
|
|
28
|
+
open their log on GitHub
|
|
29
|
+
- the screens themselves, so it doubles as a way to get anywhere
|
|
30
|
+
|
|
31
|
+
Every word has to match; a title that starts with one ranks first. Arrow keys move, Enter opens,
|
|
32
|
+
Escape closes. Everything except the docs is searched in the page, from what the portal has
|
|
33
|
+
already read.
|
|
34
|
+
|
|
21
35
|
Anything that asks before it acts (a merge, a push, a hire, a retire, a paid run) asks in the
|
|
22
36
|
page's own dialog, never the browser's `confirm()`, which blocks the whole tab.
|
|
23
37
|
|
|
24
|
-
**The counts are right on load.** The badges beside
|
|
25
|
-
boot, and the
|
|
38
|
+
**The counts are right on load.** The badges beside Home and Trackers are fetched once at
|
|
39
|
+
boot, and the screens share that request rather than making a second one. A sidebar that
|
|
26
40
|
says nothing until you look at it is not a sidebar.
|
|
27
41
|
|
|
28
42
|
While the first answer is outstanding the badge is a placeholder rather than blank, because an
|
|
@@ -78,23 +92,72 @@ staff member* first, then the Actions setting, the credential, the repo picker,
|
|
|
78
92
|
what doctor still says. A link to another screen still wins. When the list is empty the entry
|
|
79
93
|
goes away; the repo picker lives on under [Org](#org).
|
|
80
94
|
|
|
81
|
-
##
|
|
95
|
+
## Home
|
|
96
|
+
|
|
97
|
+

|
|
98
|
+
|
|
99
|
+
Where the portal opens. An Ask box at the top, then these, in order.
|
|
100
|
+
|
|
101
|
+
- **Ask.** Pick a staff member, type what you want, **Send**. It opens an issue on their
|
|
102
|
+
tracker with their `@handle` in front, which wakes them in about a minute.
|
|
103
|
+
- **Latest reports.** Each staff member's run report from the last day: the three lines they
|
|
104
|
+
post on their status issue at the end of a daily run, with the issues and pull requests it
|
|
105
|
+
names as links. Click a report to open their status issue. **Ask for a report** comments on
|
|
106
|
+
their status issue with their `@handle`, and they reply there in a few minutes.
|
|
107
|
+
- **Needs you.** Every ask a staff member has put on you, and every pull request ready to
|
|
108
|
+
merge, oldest first. Each card has one action on its right:
|
|
109
|
+
- a `decision` has **Reply**, and **Go with the default** when it carries one. The default
|
|
110
|
+
and its date are shown, and turn amber once the date has passed.
|
|
111
|
+
- a `review` has **Approve**.
|
|
112
|
+
- a `chore` has **Done**, which closes it.
|
|
113
|
+
- a pull request has **Merge**, unless its checks fail, are still running, or it conflicts.
|
|
114
|
+
Where the branch rules require an approving review, it also has **Approve**, and Merge waits
|
|
115
|
+
until you have pressed it. Approving is your review, given on purpose; Merge never gives it
|
|
116
|
+
for you.
|
|
117
|
+
|
|
118
|
+
Answers go out as you, with the staff member's `@handle`, so they act on them straight away.
|
|
119
|
+
Once you have had the last word, the card leaves Needs you for Your requests, since it is
|
|
120
|
+
waiting on them now. If they reply, it comes back. When nothing is waiting, it says so.
|
|
121
|
+
- **Unread.** Anything on a staff member's own tracker, or elsewhere, with activity you have not
|
|
122
|
+
seen: a peer's ask, a status issue, their own work. Unread comes from your GitHub
|
|
123
|
+
notifications, as on Trackers. Cards and rows anywhere on Home carry the same blue mark, and
|
|
124
|
+
opening one marks it read here and on GitHub.
|
|
125
|
+
- **Working now.** Each staff member: what they are running and what started it (the daily run,
|
|
126
|
+
a follow-on, answering an issue, a peer's ask), for how long, with a link to the log. When
|
|
127
|
+
they are idle, how their last run ended. Peer and follow-on runs today are counted against
|
|
128
|
+
`max_runs_per_day`. This asks GitHub every few seconds while a run is going and every half
|
|
129
|
+
minute otherwise, and only while Home is on screen.
|
|
130
|
+
- **Your requests.** What you asked for, and asks of theirs you have answered: waiting, being worked on (a run for it is going), or
|
|
131
|
+
answered (a staff member had the last word).
|
|
132
|
+
- **Closed today.** What the staff closed today, with the line they closed it with, and
|
|
133
|
+
**Reopen** beside each. Staff close finished issues themselves, so this is where you check.
|
|
134
|
+
|
|
135
|
+
**Every item opens in a side sheet.** Click anywhere on a card or a row and its thread opens
|
|
136
|
+
on the right: the conversation, Reply, Close or Reopen, Merge for a pull request, and Open in
|
|
137
|
+
GitHub. Escape or the × closes it, and Home repaints where you were.
|
|
138
|
+
|
|
139
|
+
**Nothing is missed.** Every open issue and pull request has exactly one place: on Home, or on
|
|
140
|
+
the staff member's own tracker (their status issue, a peer's ask, their own work), or elsewhere
|
|
141
|
+
(draft pull requests, contributor issues). The line at the bottom counts the last two, with a
|
|
142
|
+
link to Trackers.
|
|
143
|
+
|
|
144
|
+
## Trackers
|
|
82
145
|
|
|
83
146
|
Everything open across the org, from one GraphQL call per repo. Bodies and full timelines come
|
|
84
147
|
down with the list, so opening a thread is a render rather than a request.
|
|
85
148
|
|
|
86
|
-
- **
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
- **Open
|
|
149
|
+
- **The links under Trackers in the sidebar filter it.** All; Unread; each staff member, which
|
|
150
|
+
lists the issues on their own tracker whoever filed them; and Issues, the product repos.
|
|
151
|
+
- **Unread comes from your GitHub notifications.** A thread with activity you have not read has
|
|
152
|
+
a bar on the left and a bold title, and Unread lists only those, with a count. Opening one
|
|
153
|
+
marks it read on GitHub too, and reading it on GitHub clears it here. GitHub only notifies you
|
|
154
|
+
about repos you watch and threads you are part of.
|
|
155
|
+
- **Open or closed.** Open by default: an inbox is what is waiting on
|
|
93
156
|
somebody, and months of finished work mixed into that answers a different question. Closed
|
|
94
157
|
work reaches back 45 days, up to 30 issues and 30 pull requests per repository, and carries
|
|
95
158
|
a shorter timeline than open work because it is there to be read rather than triaged. A
|
|
96
159
|
closed row is dimmed and marked; the sidebar badge keeps counting only what is open.
|
|
97
|
-
- **Reply, close, reopen, open an issue.** All as you,
|
|
160
|
+
- **Reply, close, reopen, open an issue.** All as you, with your own token, so they are
|
|
98
161
|
indistinguishable from doing it on the site. Closing asks for confirmation. A half-written
|
|
99
162
|
reply survives a repaint, and pressing Comment with an empty box says so rather than
|
|
100
163
|
silently doing nothing.
|
|
@@ -144,7 +207,7 @@ down with the list, so opening a thread is a render rather than a request.
|
|
|
144
207
|
|
|
145
208
|
## Pending work
|
|
146
209
|
|
|
147
|
-
The same screen, scoped to pull requests
|
|
210
|
+
The same screen, scoped to pull requests. It is where a pull request opens from Home. An inbox is what is
|
|
148
211
|
waiting on you; a pull request is work that is finished and waiting on a merge, and the count
|
|
149
212
|
that matters is not how many are open but how many are green and still sitting there.
|
|
150
213
|
|
|
@@ -201,7 +264,7 @@ On the **Files** tab each file's heading has its own Reply, which opens the same
|
|
|
201
264
|
one file. "This bit is wrong" is what you want to say while looking at a diff, and the
|
|
202
265
|
alternative is describing in prose which of thirty files you meant.
|
|
203
266
|
|
|
204
|
-
Both writes
|
|
267
|
+
Both writes are yours, made with your own token. Nothing is dispatched between repositories and no
|
|
205
268
|
credential is put on a public repo. The tracker issue goes first, because it is the half that
|
|
206
269
|
reaches anybody; if the copy on the pull request then fails you are told, rather than being
|
|
207
270
|
shown an error that invites you to ask the same person the same thing twice.
|
|
@@ -213,13 +276,19 @@ it took, turns and cost where known, and a link to the log. Above the tables, th
|
|
|
213
276
|
for the org, and each staff member's own in their heading.
|
|
214
277
|
|
|
215
278
|
Runs are not in any repo, so this is the one screen that is only ever on GitHub. It reads the
|
|
216
|
-
run lists
|
|
217
|
-
than drawing an empty table that reads as "nothing ran".
|
|
279
|
+
run lists as you, the same way the inbox does, and when GitHub cannot be reached it says so
|
|
280
|
+
rather than drawing an empty table that reads as "nothing ran".
|
|
218
281
|
|
|
219
282
|
Cost comes from the record each run leaves behind (see [cost](cost.md#what-each-run-cost)). A
|
|
220
283
|
run from before records existed, or from an agent that does not report cost, shows a dash, and
|
|
221
|
-
a total says how many runs it could price. Each record is downloaded once and kept
|
|
222
|
-
|
|
284
|
+
a total says how many runs it could price. Each record is downloaded once, ever, and kept in
|
|
285
|
+
`~/.cache/roster/runs` (or `ROSTER_CACHE_DIR`), since a finished run's record never changes.
|
|
286
|
+
The table shows at once with the costs already known; any not yet read are fetched in the
|
|
287
|
+
background, and the screen says how many and fills them in as they arrive.
|
|
288
|
+
|
|
289
|
+
The run list asks GitHub for each outcome separately (succeeded, failed, cancelled and so on)
|
|
290
|
+
rather than paging through every run, because most of a mention caller's runs are comments that
|
|
291
|
+
woke nobody and were skipped.
|
|
223
292
|
|
|
224
293
|
A skipped mention is not a run and is not listed. A `setup-failure` is a run that failed before
|
|
225
294
|
the agent started, usually a token or a checkout. Past a [`budget`](org-yaml.md#budget), the
|
|
@@ -236,7 +305,7 @@ heading.
|
|
|
236
305
|
typing `role: product` into `org.yaml` by hand. Adding one commits `org.yaml` and pushes. A new
|
|
237
306
|
hire picks it up; somebody already hired keeps the `works_in` in their own `staff.yaml`.
|
|
238
307
|
|
|
239
|
-
**The list comes
|
|
308
|
+
**The list comes from the ops repo**, not out of the page, so a tenant that adds `org/pricing.md` can
|
|
240
309
|
open it like any other. Only files the
|
|
241
310
|
portal may actually write are listed: an editor that offers a file it cannot save is a trap.
|
|
242
311
|
|
|
@@ -262,21 +331,48 @@ have more than one human, and a card that names one of two reads as the only one
|
|
|
262
331
|
|
|
263
332
|
Everyone on the roster, and the things you would otherwise do from a terminal.
|
|
264
333
|
|
|
265
|
-
**Hiring**
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
334
|
+
**Hiring** starts from a role. With nobody hired the Staff screen opens on the role picker;
|
|
335
|
+
after that it is behind **Hire someone**. The cards are CTO, CMO and Support, each with a line
|
|
336
|
+
on what they do, and **Something else**, which asks for the role's name and a sentence about it.
|
|
337
|
+
A role that is already hired is not offered. Picking one fills in the handle, name and repo
|
|
338
|
+
(`cto`, `cmo`, `support`, or a handle made from the name) and leaves the schedule empty, so the
|
|
339
|
+
server picks a free slot. All four are under **Advanced**, still editable. The first hire has
|
|
340
|
+
nobody to copy App names from, so Advanced also holds the App's name and the shared public
|
|
341
|
+
App's, which are `--app` and `--public-app`, filled in as `<org>-<handle>` and `<org>-robot`.
|
|
342
|
+
The public one only matters when a product repo is public; on private ones the session uses the
|
|
343
|
+
staff member's own App.
|
|
344
|
+
|
|
345
|
+
The role opens a numbered list on the same screen:
|
|
346
|
+
|
|
347
|
+
1. **Hire.** One sentence from the plan: the repo it creates and when it runs. **Show details**
|
|
348
|
+
has the full plan, from the same `buildPlan` and `applyPlan` that `roster hire` runs on the
|
|
349
|
+
server: every file, every label, the schedule and why, the commits it makes as you in repos
|
|
350
|
+
that already exist (each peer's `staff.yaml`, `org.yaml`), and whether the new brain joins
|
|
351
|
+
the credential's org secret. **Hire** asks before it acts.
|
|
352
|
+
2. **Create their GitHub App.** The private App, and the shared public one only when a product
|
|
353
|
+
repo in `org.yaml` is public (or has no visibility written, which hire treats as public).
|
|
354
|
+
3. **Write their charter.** Three tabs: an AI interview (the default), the matching worked
|
|
355
|
+
example with your business's name in place of Acme's, and the file itself. A role that
|
|
356
|
+
matches no example has no template tab.
|
|
357
|
+
4. **Add your agent credential.** Only while none is stored.
|
|
358
|
+
5. **Run once now.**
|
|
359
|
+
|
|
360
|
+
Steps 2 to 5 say *Hire first* until the hire is done. Each step's Done comes from real data:
|
|
361
|
+
the hire from the staff member appearing in `org.yaml`, the charter from `CHARTER.md` no longer
|
|
362
|
+
being the stub (the same test as doctor's `charter.stub`), the App from its `_APP_ID` secret on
|
|
363
|
+
the brain repo, the credential from the org secret, and the run from a successful daily run.
|
|
364
|
+
After **Hire** the screen reloads the org and stays on the same staff member, on step 2.
|
|
365
|
+
|
|
366
|
+
A card whose setup is not finished (a stub charter, no App secrets, or no successful run yet)
|
|
367
|
+
shows **Finish setting up**, which opens the same list for them. The App secrets and the run
|
|
368
|
+
are read from GitHub.
|
|
274
369
|
|
|
275
370
|
**Writing the charter** is the copy-a-prompt loop below, aimed at `CHARTER.md`. `hire`
|
|
276
371
|
deliberately does not write it, because a generated charter produces exactly the generic agent
|
|
277
372
|
this whole arrangement exists to avoid. It is the same brief as `roster brief charter
|
|
278
373
|
<handle>`, with somewhere to put the answer, and a picker for the worked example it carries as a
|
|
279
|
-
model: matched to the role, or another, or none.
|
|
374
|
+
model: matched to the role, or another, or none. For a role added with **Something else**, the
|
|
375
|
+
sentence you typed goes into the brief.
|
|
280
376
|
|
|
281
377
|
**The GitHub App** is `roster app`, on this server rather than a second one. There is no API that
|
|
282
378
|
creates an App: the only route is the manifest flow, where you post a manifest to a settings page,
|
|
@@ -312,7 +408,7 @@ already declared `memory/` as a surface.
|
|
|
312
408
|
The navigator has three boxes, because a parsed memory section and a file on disk are
|
|
313
409
|
different kinds of thing.
|
|
314
410
|
|
|
315
|
-
**
|
|
411
|
+
**What they know** is the fact sections, the notes behind them, and `INDEX.md` itself. A note is the
|
|
316
412
|
argument behind one fact, read only when that fact is in play, which is what keeps the index
|
|
317
413
|
cheap enough to read at every boot. Both live here rather than among the files: `INDEX.md` is
|
|
318
414
|
literally what "All facts" renders.
|
|
@@ -358,11 +454,15 @@ half complaints answered neither well.
|
|
|
358
454
|
|
|
359
455
|
### Getting help changing it
|
|
360
456
|
|
|
361
|
-
**
|
|
362
|
-
|
|
363
|
-
self-contained
|
|
364
|
-
and what may and may not be edited.
|
|
365
|
-
|
|
457
|
+
**Change this with your AI** opens a side sheet in three steps:
|
|
458
|
+
1. What you want changed, in a box big enough to say it in.
|
|
459
|
+
2. **Copy the prompt**: a self-contained brief carrying the composed text, every layer with its
|
|
460
|
+
path and blast radius, and what may and may not be edited. It only copies. The prompt as it
|
|
461
|
+
composes today is under it, to read first.
|
|
462
|
+
3. Paste your AI's reply. It hands back whole files, which are checked against the layers this
|
|
463
|
+
prompt is made of and shown as diffs, each with Save. Nothing is written until you press it.
|
|
464
|
+
|
|
465
|
+
`roster brief amend <handle> --want "…"` prints the same brief from the terminal.
|
|
366
466
|
|
|
367
467
|
It carries the state rather than asking for it, because working out which of eight files to
|
|
368
468
|
open is the difficulty being solved. A brief that says "read your layers first" has handed
|
|
@@ -370,8 +470,9 @@ that straight back.
|
|
|
370
470
|
|
|
371
471
|
### Editing
|
|
372
472
|
|
|
373
|
-
Layers are editable in place. Saving
|
|
374
|
-
|
|
473
|
+
Layers are editable in place. Saving commits **only that file** to GitHub, as you. If
|
|
474
|
+
the file has changed on GitHub since you opened it, the save is refused and says to reload,
|
|
475
|
+
rather than overwriting somebody else's edit. The confirmation names the repository and says who picks it up:
|
|
375
476
|
every staff member for anything under `org/` or `prompts/`, one staff member for a brain file.
|
|
376
477
|
|
|
377
478
|
The writable set is an allowlist, because this commits to repositories the agents run from:
|
|
@@ -481,11 +582,9 @@ worse than no linter. A finding true of more than one prompt is one row, and it
|
|
|
481
582
|
| it names a file that is not there | an instruction to read something absent is a quiet no-op inside a run nobody watches |
|
|
482
583
|
| an included layer is empty | it contributes nothing and costs a line of includes |
|
|
483
584
|
|
|
484
|
-
**Every finding carries the fix.** "
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
not. The box comes pre-filled with what the finding worked out, so you can add to it rather
|
|
488
|
-
than retype it. "Open the file" takes you to that layer on the Prompt screen.
|
|
585
|
+
**Every finding carries the fix.** "Fix this with your AI" opens the same sheet as the Prompt
|
|
586
|
+
screen's, with the finding at the top and the box pre-filled with what it worked out, so you
|
|
587
|
+
can add to it rather than retype it. Copy the prompt, paste the reply back, save the diff. "Open the file" takes you to that layer on the Prompt screen.
|
|
489
588
|
|
|
490
589
|
**Memory problems** are the same checks `roster lint` runs. Each one has a button that opens an
|
|
491
590
|
issue in that staff member's own repo asking them to fix it, which is usually right, because
|
package/docs/prompts.md
CHANGED
|
@@ -99,6 +99,12 @@ than a hang.
|
|
|
99
99
|
| `ops.dir` | ops repo directory in the checkout |
|
|
100
100
|
| `staff` | the whole of this staff member's `staff.yaml` |
|
|
101
101
|
| `staff.dir` | where their brain lands in the checkout |
|
|
102
|
+
| `staff.handle`, `staff.name` | their handle (`cto`) and role name (`Chief Technology Officer`) |
|
|
103
|
+
| `staff.brain` | their brain repo, `owner/name` |
|
|
104
|
+
| `staff.bot` | the login they post as on private repos, e.g. `acme-cto[bot]` |
|
|
105
|
+
| `staff.public_bot` | the login they post as on public repos |
|
|
106
|
+
| `staff.public_token_env` | the environment variable holding the public repo token during a run |
|
|
107
|
+
| `staff.status_issue` | the number of their pinned status issue |
|
|
102
108
|
| `staff.product` | **first entry of `works_in`, or null** |
|
|
103
109
|
| `staff.product.repo` | that repo's `owner/name` |
|
|
104
110
|
| `peers` | list of the other staff members |
|
package/docs/security.md
CHANGED
|
@@ -16,9 +16,14 @@ What can reach what, and what stops it.
|
|
|
16
16
|
| Public App private key | a repo secret | mint a token for the public product repo |
|
|
17
17
|
| Agent credential | a repo secret | spend money with your model provider |
|
|
18
18
|
| Your `gh` token | your machine | whatever you can |
|
|
19
|
+
| A hosted portal's sign-in | a sealed cookie in your browser | whatever you can |
|
|
20
|
+
| The portal's OAuth App secret and session key | Worker secrets | sign people in |
|
|
19
21
|
|
|
20
|
-
**
|
|
21
|
-
|
|
22
|
+
**On your machine, no credential is held by roster.** The CLI uses your own `gh`, and the
|
|
23
|
+
portal asks `gh` for its token once, holds it in memory, and writes it nowhere.
|
|
24
|
+
|
|
25
|
+
**A hosted portal holds each person's sign-in, and nothing else.** See
|
|
26
|
+
[the hosted portal](#the-hosted-portal).
|
|
22
27
|
|
|
23
28
|
## The App private key
|
|
24
29
|
|
|
@@ -55,17 +60,25 @@ The rule: **the default branch of every product repo requires a pull request wit
|
|
|
55
60
|
approving review, and no staff App is on the list of who may bypass it.** A ruleset or classic
|
|
56
61
|
branch protection both count.
|
|
57
62
|
|
|
58
|
-
|
|
63
|
+
**It is off unless you turn it on**, with `review_gate: true` in `org.yaml`. Without it, staff
|
|
64
|
+
are told to leave merging to you, and on Pip they always have, but GitHub does not stop them.
|
|
65
|
+
Most orgs keep product repos private on the Free plan, where GitHub cannot enforce the rule.
|
|
66
|
+
|
|
67
|
+
With it on, `roster doctor` reads it for every `role: product` repo in `org.yaml` and every repo a staff
|
|
59
68
|
member `works_in`, as `review-gate`. It fails when nothing requires a PR or a staff App can
|
|
60
69
|
bypass the rule, and warns when a PR is required with no approval, since then whoever opened
|
|
61
70
|
it can merge it.
|
|
62
71
|
|
|
63
|
-
`roster hire --apply` adds a ruleset named `roster: review before merge` to each product repo
|
|
72
|
+
With it on, `roster hire --apply` adds a ruleset named `roster: review before merge` to each product repo
|
|
64
73
|
that does not already require an approving review, and leaves anything stricter alone. Pass
|
|
65
74
|
`--no-review-gate` to skip it. The ruleset lets repository admins bypass it only by merging a
|
|
66
75
|
pull request, so your own merge is still the approval (GitHub will not let you approve your
|
|
67
76
|
own PR) and an App, which is never an admin, cannot merge at all.
|
|
68
77
|
|
|
78
|
+
**On GitHub Free, private repos can't have this rule.** GitHub only enforces rulesets and
|
|
79
|
+
branch protection on private repos for paid plans. To use the gate there, make the product repo
|
|
80
|
+
public or move the org to GitHub Team.
|
|
81
|
+
|
|
69
82
|
To set it by hand: repo **Settings -> Rules -> Rulesets -> New branch ruleset**, target the
|
|
70
83
|
default branch, tick **Require a pull request before merging** with one required approval, and
|
|
71
84
|
keep the staff Apps off the bypass list.
|
|
@@ -89,8 +102,8 @@ Never verify an installation by reading the API. The only proof is a run that fi
|
|
|
89
102
|
|
|
90
103
|
The setup screen creates repositories, creates GitHub Apps and writes repository secrets. It is
|
|
91
104
|
the most privileged surface roster has, and it is **local only**: bound to `127.0.0.1`, behind the
|
|
92
|
-
same write guard as everything else, and never something to put behind a tunnel.
|
|
93
|
-
|
|
105
|
+
same write guard as everything else, and never something to put behind a tunnel. A hosted
|
|
106
|
+
portal does not have it, nor hiring, retiring or doctor.
|
|
94
107
|
|
|
95
108
|
The App manifest hand-off runs on the portal's own port rather than a second one, which changes
|
|
96
109
|
where the callback lands and nothing else: the one-time code is still exchanged server-side, and
|
|
@@ -102,14 +115,13 @@ callback whose state is unknown is refused.
|
|
|
102
115
|
|
|
103
116
|
It can write to GitHub, so it is worth being precise.
|
|
104
117
|
|
|
105
|
-
|
|
118
|
+
On your machine, it binds to `127.0.0.1`. A write needs a `POST`, an `x-roster` header (which forces a CORS
|
|
106
119
|
preflight that fails from any other origin), and an `Origin` that is either absent or
|
|
107
120
|
localhost. Reads are served to anything that can reach the port.
|
|
108
121
|
|
|
109
|
-
|
|
110
|
-
constrained rather than sanitised:
|
|
122
|
+
These paths take attacker-controlled input, and each is constrained rather than sanitised:
|
|
111
123
|
|
|
112
|
-
- `/api/file` resolves the path and refuses anything outside the
|
|
124
|
+
- `/api/file` resolves the path and refuses anything outside the org's repositories.
|
|
113
125
|
- `/api/diff` requires the directory to be a known staff repo and the sha to look like a sha.
|
|
114
126
|
- `/api/doc` requires the page to be one the listing offered.
|
|
115
127
|
- `/api/docasset` requires the screenshot to be one sitting in `docs/images/`, matched by name
|
|
@@ -118,6 +130,53 @@ constrained rather than sanitised:
|
|
|
118
130
|
`--host` overrides the bind address and prints a warning. It exists for people who know what
|
|
119
131
|
they are doing on a network they control. See [hosting the portal](hosting.md).
|
|
120
132
|
|
|
133
|
+
A save says what text the edit started from, and is refused if the file has moved on GitHub
|
|
134
|
+
since, so the portal never overwrites somebody else's change without saying so.
|
|
135
|
+
|
|
136
|
+
## The hosted portal
|
|
137
|
+
|
|
138
|
+
The same portal on Cloudflare Workers, behind Sign in with GitHub.
|
|
139
|
+
|
|
140
|
+
**Who gets in.** The people in `org.yaml`'s `humans:`, signed in through an OAuth App the org
|
|
141
|
+
creates. Membership is checked with their own token at sign-in, which also proves they can read
|
|
142
|
+
the ops repo, and again every few minutes. Anybody else is turned away and their token revoked.
|
|
143
|
+
|
|
144
|
+
**What it holds.** Each person's GitHub token, their login and an expiry, sealed with AES-GCM
|
|
145
|
+
under the Worker's `SESSION_KEY` and set as an `HttpOnly`, `Secure`, `SameSite=Lax` cookie.
|
|
146
|
+
There is no database. A cookie that was tampered with, or sealed under another key, does not
|
|
147
|
+
open. Rotating `SESSION_KEY` signs everybody out. The OAuth App's client secret is a Worker
|
|
148
|
+
secret and is used only to finish a sign-in and to revoke a token.
|
|
149
|
+
|
|
150
|
+
**What a write needs.** A `POST`, the `x-roster` header, an `Origin` that is the portal's own,
|
|
151
|
+
and a signed-in session. `SameSite=Lax` keeps the cookie off cross-site posts as well.
|
|
152
|
+
|
|
153
|
+
**What it can do if somebody reaches it.** Without a sign-in, nothing but show the sign-in page
|
|
154
|
+
and the page's own scripts. With one, only what that person's GitHub account can already do:
|
|
155
|
+
every read and write goes to GitHub with their token, so GitHub's own permissions are the
|
|
156
|
+
boundary. It cannot set up an org, create an App, write a secret, hire or retire.
|
|
157
|
+
|
|
158
|
+
**What it shares between people.** The copy it holds of the org's repositories is shared by
|
|
159
|
+
everyone signed in, as is the cache. Everyone signed in is one of the org's humans, so this is
|
|
160
|
+
the org shown to its own people; a human whose GitHub account cannot read one of the brains can
|
|
161
|
+
still see that brain in the portal. Their unread marks and anything they do are their own.
|
|
162
|
+
|
|
163
|
+
**Claude, through MCP.** `/mcp` takes a bearer token rather than the cookie. The portal is its
|
|
164
|
+
own OAuth 2.1 server for it, with PKCE and dynamic client registration, in front of GitHub's
|
|
165
|
+
sign-in: the same check against `humans:`, then a page the person has to press **Allow** on.
|
|
166
|
+
Nothing is stored for this either. The client's registration, the code, and the access and
|
|
167
|
+
refresh tokens are each sealed under `SESSION_KEY` with a kind of their own, so a refresh token
|
|
168
|
+
or a code cannot be used as an access token, and none of them opens the portal as a cookie. An
|
|
169
|
+
access token lasts an hour and a refresh token thirty days. Each connection signs in to GitHub
|
|
170
|
+
separately, so signing out of the portal does not disconnect Claude; revoking the OAuth App on
|
|
171
|
+
GitHub disconnects both, and rotating `SESSION_KEY` disconnects every connector. A code is not
|
|
172
|
+
single use, since there is no store to remember it in, but it lasts five minutes and is useless
|
|
173
|
+
without the PKCE verifier only the client holds. The tools cannot merge, approve, hire or change
|
|
174
|
+
the org.
|
|
175
|
+
|
|
176
|
+
**The OAuth scopes.** `repo` and `notifications`. A GitHub App would be narrower, but its
|
|
177
|
+
tokens cannot read notifications, and unread in the portal is GitHub's own unread, kept in step
|
|
178
|
+
with the website and your phone.
|
|
179
|
+
|
|
121
180
|
## Trust in a prompt
|
|
122
181
|
|
|
123
182
|
Everything composed into a prompt is content you or your agents wrote: `org/`, the charter, the
|
|
@@ -133,7 +192,7 @@ So a mention on a public pull request is decoration. It posts, it renders as a c
|
|
|
133
192
|
nothing happens, which is safe and also invisible. The portal is what makes it visible and what
|
|
134
193
|
gets you out of it: replying with an `@handle` where nothing listens says so, and offers to
|
|
135
194
|
open the request on that person's own private tracker as well, carrying the pull request and
|
|
136
|
-
the hunk. It writes
|
|
195
|
+
the hunk. It writes as you, with your own token, so no credential lives on the
|
|
137
196
|
public repo and nothing is dispatched across a boundary.
|
|
138
197
|
|
|
139
198
|
If you add a workflow to a product repo that bridges this automatically, its author gate is
|
package/docs/session-workflow.md
CHANGED
|
@@ -33,6 +33,8 @@ repositories in this organisation**. Without it, callers fail with "workflow not
|
|
|
33
33
|
| `allowed_tools` | string | `Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch` | Tool permissions, for agents that take them. |
|
|
34
34
|
| `issue_number` | string | `""` | Trigger context. |
|
|
35
35
|
| `comment_id` | string | `""` | Trigger context. |
|
|
36
|
+
| `trigger` | string | `""` | What started the run: `daily`, `manual`, `follow-on`, `mention` or `peer`. Passed to the prompt. |
|
|
37
|
+
| `max_runs_per_day` | number | `6` | How many `peer` and `follow-on` runs may start in a UTC day. Mentions are never counted. |
|
|
36
38
|
|
|
37
39
|
## Secrets
|
|
38
40
|
|
|
@@ -51,6 +53,14 @@ authentication error forty lines into a log.
|
|
|
51
53
|
|
|
52
54
|
## What it does, in order
|
|
53
55
|
|
|
56
|
+
Before the session job, a small **budget** job. For a `peer` or `follow-on` run it counts this
|
|
57
|
+
brain's runs today with those names in their `run-name`, this one included and skipped ones
|
|
58
|
+
left out. Over `max_runs_per_day`, the session does not start and the issue that woke it gets a
|
|
59
|
+
comment saying so. If the runs cannot be read, the run does not start either: a run held back
|
|
60
|
+
costs a day, and a loop costs a bill. Every other trigger goes straight through.
|
|
61
|
+
|
|
62
|
+
Then the session:
|
|
63
|
+
|
|
54
64
|
1. **Start the clock**, for the run record.
|
|
55
65
|
2. **Mint the private-tracker token** from the staff member's App.
|
|
56
66
|
3. **Mint the public-repo token**, if a public App was passed.
|
|
@@ -65,15 +75,23 @@ authentication error forty lines into a log.
|
|
|
65
75
|
`inflight.mjs`, for the prompt. Never fatal. See [prompts](prompts.md#human-work-in-flight).
|
|
66
76
|
10. **Set git identity** to the App.
|
|
67
77
|
11. **Set up Node and pnpm**, if the plan found a `package.json`.
|
|
68
|
-
12. **
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
78
|
+
12. **Open this week's status issue**, daily runs only, by running `status-week.mjs`: when the
|
|
79
|
+
status issue in `staff.yaml` is from an earlier week, a new one is opened, pinned and
|
|
80
|
+
committed to `staff.yaml`, and the prompt is told which earlier week still needs its summary.
|
|
81
|
+
Never fatal. See [architecture](architecture.md#the-weeks-status-issue).
|
|
82
|
+
13. **Compose the prompt**, to a step output and to `.roster-prompt.txt`.
|
|
83
|
+
14. **Check the agent has a credential.**
|
|
84
|
+
15. **Work out which agent runs this**, by running `agents.mjs`.
|
|
85
|
+
16. **Run the session**, by one of two steps: the Action-based reference runner, or the generic
|
|
72
86
|
CLI one. See [choosing a coding agent](agents.md).
|
|
73
|
-
|
|
87
|
+
Then, for a mention, **check the request was answered**: a reply in the thread, or the issue
|
|
88
|
+
closed. Neither fails the job, so the notice below tells the human.
|
|
89
|
+
Then, for a daily run that finished and wrote `.roster-run/continue`, **start a follow-on
|
|
90
|
+
run**: one more daily run with `trigger: follow-on`, which waits for this one to end.
|
|
91
|
+
17. **Write down the run**, whatever happened: staff, kind, outcome, duration, and turns, cost
|
|
74
92
|
and tokens where the agent reports them. Into the job summary, and kept as an artifact
|
|
75
93
|
called `roster-run`. Never fatal. See [cost](cost.md#what-each-run-cost).
|
|
76
|
-
|
|
94
|
+
18. **Say so if the run did not finish.** A comment on the status issue, or on the issue that
|
|
77
95
|
woke a mention, linking the run.
|
|
78
96
|
|
|
79
97
|
## When the failure is the token
|
package/docs/staff-yaml.md
CHANGED
|
@@ -25,6 +25,7 @@ schedule: "0 7 * * 1-5"
|
|
|
25
25
|
model: claude-opus-5-5
|
|
26
26
|
timeout_minutes: 90
|
|
27
27
|
mention_timeout_minutes: 90
|
|
28
|
+
max_runs_per_day: 6
|
|
28
29
|
|
|
29
30
|
bot: acme-cto[bot]
|
|
30
31
|
public_bot: acme-robot[bot]
|
|
@@ -49,7 +50,7 @@ surfaces:
|
|
|
49
50
|
|
|
50
51
|
labels:
|
|
51
52
|
owner: [will, cto, cmo]
|
|
52
|
-
kind: [decision,
|
|
53
|
+
kind: [decision, review, chore, keep-open, build, blocked]
|
|
53
54
|
```
|
|
54
55
|
|
|
55
56
|
## Identity
|
|
@@ -59,8 +60,9 @@ labels:
|
|
|
59
60
|
| `handle` | yes | Must match `org.yaml`. The composer looks them up by the `org.yaml` one, so a mismatch composes the wrong brain. |
|
|
60
61
|
| `name` | yes | Role name in prose. |
|
|
61
62
|
| `mention` | yes | What wakes them, as in `@cto`. The caller's condition tests for this string. |
|
|
63
|
+
| `icon` | no | The icon the portal shows for them: `code`, `megaphone`, `life-buoy`, `compass`, `brush`, `bug`, `server`, `book-open`, `bar-chart`, `users` or `person`. Unset, it is picked from the role. |
|
|
62
64
|
| `brain` | yes | `owner/name` of this repo. Without it nothing can check secrets, labels or runs. |
|
|
63
|
-
| `status_issue` | yes in practice | Number of
|
|
65
|
+
| `status_issue` | yes in practice | Number of this week's pinned status issue. The prompts reference it, so a run cannot compose without it. `roster hire --apply` writes the first; the first daily run of each week moves it on. |
|
|
64
66
|
|
|
65
67
|
## Schedule and limits
|
|
66
68
|
|
|
@@ -70,6 +72,7 @@ labels:
|
|
|
70
72
|
| `model` | org default | Model id. |
|
|
71
73
|
| `timeout_minutes` | 90 | Ceiling on the daily session. |
|
|
72
74
|
| `mention_timeout_minutes` | 90 | Ceiling on a mention run. |
|
|
75
|
+
| `max_runs_per_day` | 6 | Runs a UTC day that start without a person asking: a peer's ask, or a follow-on to a daily run. Mentions never count. Rendered into the callers, so change it and run `roster upgrade`. |
|
|
73
76
|
|
|
74
77
|
The three ceilings are separate on purpose. Raising the daily one because sessions have grown
|
|
75
78
|
should not double the budget for a PR amendment. A job killed by a ceiling is reported by
|
|
@@ -154,6 +157,22 @@ Labels this staff member expects to exist on its own tracker, grouped for readab
|
|
|
154
157
|
value across every group is checked by `roster doctor`. An agent applying a label that does not
|
|
155
158
|
exist gets an API error mid-run.
|
|
156
159
|
|
|
160
|
+
Four labels are roster's own and are checked on every tracker whatever this lists:
|
|
161
|
+
|
|
162
|
+
| Label | Means |
|
|
163
|
+
|---|---|
|
|
164
|
+
| `decision` | An ask for the human to rule on. It carries a default and a date; past the date, the staff member acts on the default and closes it. |
|
|
165
|
+
| `review` | An ask for the human to read or approve something. |
|
|
166
|
+
| `chore` | Something only the human can do: a setting, an account, a key. |
|
|
167
|
+
| `keep-open` | A standing thread. A sweep never closes it. On this week's status issue; taken off last week's so it can be closed. |
|
|
168
|
+
|
|
169
|
+
A fifth, `status`, marks a week's status issue. The session creates it, so doctor does not check
|
|
170
|
+
it. An open one other than this week's is waiting for its summary.
|
|
171
|
+
|
|
172
|
+
Every ask on the human carries exactly one of the first three, which is how the portal sorts
|
|
173
|
+
what needs them. Staff close any issue on their tracker once nothing is left to do on it,
|
|
174
|
+
including the human's requests, with one line saying what closed it.
|
|
175
|
+
|
|
157
176
|
## `memory`
|
|
158
177
|
|
|
159
178
|
This staff member's own memory budgets, overriding the org's. Same three fields as
|
package/docs/upgrading.md
CHANGED
|
@@ -10,9 +10,9 @@ The framework writes templates out. A tenant runs its own copies. So the two dri
|
|
|
10
10
|
`roster upgrade` is what reconciles them without eating your edits.
|
|
11
11
|
|
|
12
12
|
```bash
|
|
13
|
-
roster upgrade
|
|
14
|
-
roster upgrade --apply
|
|
15
|
-
roster upgrade --check
|
|
13
|
+
npx @nanocollective/roster@latest upgrade # what would change
|
|
14
|
+
npx @nanocollective/roster@latest upgrade --apply # do it
|
|
15
|
+
npx @nanocollective/roster@latest upgrade --check # exit non-zero if anything is pending (for CI)
|
|
16
16
|
```
|
|
17
17
|
|
|
18
18
|
## How it decides
|
|
@@ -28,10 +28,10 @@ layer. That is the part that matters most, because without them the model writes
|
|
|
28
28
|
of whoever it was shown. The brief then interviews you, drafts from your answers, and tells you
|
|
29
29
|
what it cut and why.
|
|
30
30
|
|
|
31
|
-
**So is a worked example, when one fits.** A staff member whose handle or role reads as
|
|
32
|
-
|
|
31
|
+
**So is a worked example, when one fits.** A staff member whose handle or role reads as one of
|
|
32
|
+
the ten roles below gets the matching [example](#worked-examples) inside the brief, labelled as a
|
|
33
33
|
model for the shape and not content to copy. The copy-a-prompt panel has a picker to choose
|
|
34
|
-
another or none; in a terminal it is `--example
|
|
34
|
+
another or none; in a terminal it is `--example <handle>` or `--example none`. It is still a brief you
|
|
35
35
|
answer: the interview comes first, and nothing in the charter should come from the example
|
|
36
36
|
rather than from you.
|
|
37
37
|
|
|
@@ -72,9 +72,22 @@ status issue, and the surfaces the manifest declares.
|
|
|
72
72
|
|
|
73
73
|
## Worked examples
|
|
74
74
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
75
|
+
Ten, for an invented company called Acme. The handle in brackets is the one `--example` takes.
|
|
76
|
+
|
|
77
|
+
| Example | What they do |
|
|
78
|
+
|---|---|
|
|
79
|
+
| [CTO](charters/cto.md) (`cto`) | Builds the product: fixes, features and tests, as pull requests. |
|
|
80
|
+
| [CMO](charters/cmo.md) (`cmo`) | Posts, SEO, copy and launch plans, as drafts to approve. |
|
|
81
|
+
| [Head of Support](charters/support.md) (`support`) | Answers issues, writes help docs, and turns user reports into bugs. |
|
|
82
|
+
| [Product Manager](charters/pm.md) (`pm`) | Turns ideas and user feedback into clear specs and a ranked backlog. |
|
|
83
|
+
| [Designer](charters/designer.md) (`designer`) | Improves the product's look and usability, with accessibility fixes, as pull requests. |
|
|
84
|
+
| [QA Engineer](charters/qa.md) (`qa`) | Tests the product, finds bugs, and writes clear reproductions and tests. |
|
|
85
|
+
| [DevOps Engineer](charters/devops.md) (`devops`) | Keeps CI, deploys and dependencies healthy, and patches security updates. |
|
|
86
|
+
| [Technical Writer](charters/writer.md) (`writer`) | Writes and keeps up the docs, guides and changelog. |
|
|
87
|
+
| [Data Analyst](charters/analyst.md) (`analyst`) | Reads the numbers and writes a short weekly report on what changed. |
|
|
88
|
+
| [Community Manager](charters/community.md) (`community`) | Answers discussions, welcomes contributors, and drafts release announcements. |
|
|
89
|
+
|
|
90
|
+
They are examples to adapt, not templates to fill in. Read them for what a finished charter covers and how specific it gets, then write your own
|
|
78
91
|
about your business. A charter copied from one of these describes Acme. The brief carries the matching one for
|
|
79
92
|
you; these links are for reading them first.
|
|
80
93
|
|