@nanocollective/roster 0.1.0-beta.2 → 0.1.0-beta.21

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 (99) hide show
  1. package/README.md +8 -0
  2. package/dist/agents-POITEZRI.js +232 -0
  3. package/dist/chunk-FF2WBNNW.js +370 -0
  4. package/dist/chunk-GDAJPOHK.js +562 -0
  5. package/dist/cli.js +3187 -1105
  6. package/dist/compose-5DBEHSEV.js +17 -0
  7. package/dist/connectors-5E5ZMGZV.js +23 -0
  8. package/dist/worker/assets/assets/css/base.css +21 -2
  9. package/dist/worker/assets/assets/css/brain.css +20 -0
  10. package/dist/worker/assets/assets/css/connectors.css +50 -0
  11. package/dist/worker/assets/assets/css/home.css +141 -54
  12. package/dist/worker/assets/assets/css/inbox.css +11 -0
  13. package/dist/worker/assets/assets/css/layout.css +6 -0
  14. package/dist/worker/assets/assets/css/markdown.css +21 -0
  15. package/dist/worker/assets/assets/css/routines.css +40 -0
  16. package/dist/worker/assets/assets/js/api.js +33 -0
  17. package/dist/worker/assets/assets/js/app.js +47 -3
  18. package/dist/worker/assets/assets/js/homesort.js +28 -21
  19. package/dist/worker/assets/assets/js/icons.js +4 -0
  20. package/dist/worker/assets/assets/js/md.js +7 -2
  21. package/dist/worker/assets/assets/js/refcard.js +216 -0
  22. package/dist/worker/assets/assets/js/refresh.js +4 -2
  23. package/dist/worker/assets/assets/js/report.js +51 -0
  24. package/dist/worker/assets/assets/js/state.js +14 -1
  25. package/dist/worker/assets/assets/js/views/connectors.js +290 -0
  26. package/dist/worker/assets/assets/js/views/home.js +368 -152
  27. package/dist/worker/assets/assets/js/views/inbox.js +68 -16
  28. package/dist/worker/assets/assets/js/views/org.js +2 -0
  29. package/dist/worker/assets/assets/js/views/people.js +103 -0
  30. package/dist/worker/assets/assets/js/views/routines.js +378 -0
  31. package/dist/worker/assets/index.html +8 -0
  32. package/dist/worker/index.js +3972 -963
  33. package/docs/README.md +2 -0
  34. package/docs/architecture.md +23 -4
  35. package/docs/commands.md +111 -9
  36. package/docs/concepts.md +2 -1
  37. package/docs/connectors.md +157 -0
  38. package/docs/cost.md +1 -1
  39. package/docs/developing.md +3 -3
  40. package/docs/doctor-codes.md +8 -2
  41. package/docs/export.md +4 -3
  42. package/docs/extending.md +1 -1
  43. package/docs/getting-started.md +19 -2
  44. package/docs/hosting.md +42 -3
  45. package/docs/memory.md +3 -2
  46. package/docs/org-yaml.md +58 -5
  47. package/docs/portal.md +37 -6
  48. package/docs/prompts.md +3 -2
  49. package/docs/routines.md +65 -0
  50. package/docs/security.md +35 -4
  51. package/docs/session-workflow.md +31 -8
  52. package/docs/staff-yaml.md +7 -3
  53. package/docs/troubleshooting.md +1 -1
  54. package/docs/upgrading.md +1 -1
  55. package/docs/writing-a-charter.md +1 -1
  56. package/package.json +2 -1
  57. package/templates/brain/.gitattributes +3 -0
  58. package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml +24 -15
  59. package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml +12 -10
  60. package/templates/brain/CHARTER.md +2 -2
  61. package/templates/brain/STATE.md +16 -0
  62. package/templates/brain/memory/INDEX.md +1 -1
  63. package/templates/brain/staff.yaml +3 -0
  64. package/templates/ops/.gitattributes +3 -0
  65. package/templates/ops/.github/workflows/session.yaml +74 -13
  66. package/templates/ops/agents.mjs +38 -11
  67. package/templates/ops/compose.mjs +60 -2
  68. package/templates/ops/connectors.mjs +722 -0
  69. package/templates/ops/org/operating.md +10 -0
  70. package/templates/ops/org/voice.md +21 -3
  71. package/templates/ops/prompts/_identity.md +20 -0
  72. package/templates/ops/prompts/daily.md +70 -19
  73. package/templates/ops/prompts/mention.md +7 -2
  74. package/templates/ops/status-week.mjs +169 -0
  75. package/templates/portal/css/base.css +21 -2
  76. package/templates/portal/css/brain.css +20 -0
  77. package/templates/portal/css/connectors.css +50 -0
  78. package/templates/portal/css/home.css +141 -54
  79. package/templates/portal/css/inbox.css +11 -0
  80. package/templates/portal/css/layout.css +6 -0
  81. package/templates/portal/css/markdown.css +21 -0
  82. package/templates/portal/css/routines.css +40 -0
  83. package/templates/portal/index.html +8 -0
  84. package/templates/portal/js/api.js +33 -0
  85. package/templates/portal/js/app.js +47 -3
  86. package/templates/portal/js/homesort.js +28 -21
  87. package/templates/portal/js/icons.js +4 -0
  88. package/templates/portal/js/md.js +7 -2
  89. package/templates/portal/js/refcard.js +216 -0
  90. package/templates/portal/js/refresh.js +4 -2
  91. package/templates/portal/js/report.js +51 -0
  92. package/templates/portal/js/state.js +14 -1
  93. package/templates/portal/js/views/connectors.js +290 -0
  94. package/templates/portal/js/views/home.js +368 -152
  95. package/templates/portal/js/views/inbox.js +68 -16
  96. package/templates/portal/js/views/org.js +2 -0
  97. package/templates/portal/js/views/people.js +103 -0
  98. package/templates/portal/js/views/routines.js +378 -0
  99. package/templates/skill/SKILL.md +115 -0
package/docs/org-yaml.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "org.yaml reference"
3
3
  description: "Every field in the org manifest, and what reads it."
4
- sidebar_order: 13
4
+ sidebar_order: 14
5
5
  ---
6
6
 
7
7
  # `org.yaml` reference
@@ -64,6 +64,30 @@ repos:
64
64
  | `budget` | no | USD over any trailing 30 days, for the whole org. See [below](#budget). |
65
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). |
66
66
 
67
+ ### `connectors`
68
+
69
+ Outside services staff can use in their runs, by name, with who has each. Keys are never here:
70
+ they are GitHub secrets. See [connectors](connectors.md).
71
+
72
+ ```yaml
73
+ connectors:
74
+ sentry:
75
+ staff: [cto]
76
+ supabase:
77
+ staff: [cto]
78
+ project_ref: abc123
79
+ read_only: true
80
+ ```
81
+
82
+ | Field | Required | Means |
83
+ |---|---|---|
84
+ | `staff` | yes | Handles of the staff who can use it. |
85
+ | `read_only` | no | `true` to hold it to reading for everybody who has it. |
86
+ | `portal` | for a sign-in | The hosted portal that keeps its sign-in. Written by the portal. |
87
+ | `url`, `command`, `secrets`, `headers`, `env` | for a service not in the catalogue | See [connectors](connectors.md#a-service-that-is-not-in-the-catalogue). |
88
+
89
+ Anything else is a setting the service needs, such as Supabase's `project_ref`.
90
+
67
91
  ### `human` and `humans`
68
92
 
69
93
  Who the staff answer to. One person is a `human` map; more than one is a `humans` list:
@@ -80,6 +104,8 @@ humans:
80
104
  | `name` | no | What to call them in prose. Defaults to the login. |
81
105
  | `marker` | no | Provenance tag on a fact they ruled on, as in `[will]`. Also used as a label. Defaults to the first part of the name, lowercased. |
82
106
  | `role` | no | Prose only. |
107
+ | `handles` | no | What they look after, as `[marketing, content]`. Staff send each ask to the person whose area it is. See below. |
108
+ | `view_only` | no | `true` for somebody who should see how the org runs and nothing more. See below. |
83
109
 
84
110
  Both keys are read, and the singular is not deprecated: an org with one human should keep
85
111
  writing `human`. When both are present, anyone in `human` who is not already in the list is
@@ -89,11 +115,38 @@ appended rather than dropped.
89
115
  here"), and a list of two cannot go in that sentence, so the first one goes there, their
90
116
  `marker` is what `%%HUMAN_MARKER%%` renders, and the rest are named by
91
117
  `{{humans_extra}}` in the identity fragment. Everything that *gates* on identity reads all of
92
- them: the mention caller's `if:` is `contains(fromJSON('["will-lamerton","sam-x"]'), …)`.
118
+ them: the mention caller's `if:` is
119
+ `contains(fromJSON(vars.ROSTER_HUMANS || '["will-lamerton","sam-x"]'), …)`, the list baked in when
120
+ the caller was generated unless the tracker has a `ROSTER_HUMANS` variable.
121
+
122
+ **Who handles what.** With more than one person, give each a `handles` list:
123
+
124
+ ```yaml
125
+ humans:
126
+ - { name: Will, github: will-lamerton, marker: will, handles: [technical work, the product, deploys] }
127
+ - { name: Ben, github: ben-x, marker: ben, handles: [marketing, content, social] }
128
+ ```
93
129
 
94
- Adding a human changes every generated caller workflow, so it takes a `roster upgrade` to reach
95
- the brain repos. Until that lands, the new person can open issues and read everything, and
96
- mentioning a staff member does nothing.
130
+ The staff are told who looks after what, and send each ask (an issue with a person's label, or
131
+ a pull request) to that one person: their label, assigned to them. On Home, **Needs you** then
132
+ shows the signed-in person what is on them, with a **Yours / Everyone's** switch beside the
133
+ heading. Something that fits nobody's area goes to the first person, and so does anything on
134
+ Home that nobody was assigned, such as a pull request opened before `handles` was set.
135
+
136
+ **View-only.** `{ name: Ben, github: ben-x, view_only: true }` signs in to the portal and the
137
+ Claude connector like anyone in the list, and reads everything there. They are not in the mention
138
+ gate, so an `@cto` from them wakes nobody, and the portal refuses to post one rather than leave
139
+ them waiting. The staff prompts name them only to say that nothing they write is a ruling, and
140
+ that nothing needing a human goes to them. A view-only person is never the primary, wherever they
141
+ are in the list. What they can do on GitHub itself is still whatever their access there allows.
142
+
143
+ **The easy way to add, change or remove someone is People on the portal's Org screen.** It
144
+ writes this list, creates each person's label on every tracker, and sets the `ROSTER_HUMANS`
145
+ Actions variable on every tracker, which the mention callers read in place of the list baked into
146
+ them, so a new person can wake staff at once. Editing `org.yaml` by hand works too, but then it
147
+ takes a `roster upgrade --apply` (and a push of the brain repos) to reach the callers, and if the
148
+ portal has ever set `ROSTER_HUMANS` it has to be updated as well: `roster doctor` says so
149
+ (`humans-variable`) and prints the command.
97
150
 
98
151
  ### `agent`
99
152
 
package/docs/portal.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "The portal"
3
3
  description: "Every view and every action."
4
- sidebar_order: 17
4
+ sidebar_order: 18
5
5
  ---
6
6
 
7
7
  # The portal
@@ -100,9 +100,10 @@ Where the portal opens. An Ask box at the top, then these, in order.
100
100
 
101
101
  - **Ask.** Pick a staff member, type what you want, **Send**. It opens an issue on their
102
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. Nothing shows until there is one.
103
+ - **Latest reports.** Each staff member's report: the body of their status issue, which every
104
+ run rewrites, with the issues and pull requests it names as links. Click it to open the issue.
105
+ **Ask for a report** asks them, with their `@handle`, to bring it up to date now, which takes a
106
+ few minutes.
106
107
  - **Needs you.** Every ask a staff member has put on you, and every pull request ready to
107
108
  merge, oldest first. Each card has one action on its right:
108
109
  - a `decision` has **Reply**, and **Go with the default** when it carries one. The default
@@ -188,8 +189,10 @@ down with the list, so opening a thread is a render rather than a request.
188
189
  to find out it landed.
189
190
  - **How much conversation** is on each row, which is most of what tells a live thread from
190
191
  something filed and never answered.
191
- - Issue and PR references in a body become chips you can click through, and `@handle`
192
- mentions become chips too. A mention of somebody on this roster goes to their repository
192
+ - Issue and PR references in a body become chips, and `@handle` mentions become chips too.
193
+ Hovering a chip for one of the org's repos shows a card with its title, state, opening
194
+ lines and labels. Clicking it opens the thread in a side sheet, closed or not, over
195
+ whatever you were reading. ⌘-click or middle-click still opens GitHub. A mention of somebody on this roster goes to their repository
193
196
  rather than to a GitHub profile of that name, which for `@cto` is a stranger.
194
197
  - **Not every comment is markdown.** Deploy bots post raw HTML. A `<table>` renders as a
195
198
  table, and inline `<a>`, `<img>`, `<strong>`, `<em>`, `<code>` and `<br>` are reduced to
@@ -399,6 +402,34 @@ from `org.yaml` and from every peer, and deletes the dead `from-<handle>` labels
399
402
  what it keeps as prominently as what it stops, because that is the thing you have to believe
400
403
  before clicking it.
401
404
 
405
+ ## Connectors
406
+
407
+ Outside services the staff can use in their runs: Sentry, Linear, Stripe and the rest of the
408
+ [catalogue](connectors.md#the-catalogue).
409
+
410
+ What is connected is a list: each service, who can use it, and whether its key is stored. **Edit**
411
+ changes who can use it, or replaces the key; **Remove** asks once more, then deletes the keys and
412
+ takes it out of `org.yaml`.
413
+
414
+ Below it is every service you can add. Picking one opens a sheet with the steps to get a key, a
415
+ link to the right settings page, the key, and who can use it, ticked for the roles that usually
416
+ want it. **Check key** asks the service whether the key works before anything is stored. **Save**
417
+ checks it again, stores it as a GitHub secret and commits `org.yaml`.
418
+
419
+ Notion signs in instead, on the [hosted portal](hosting.md) only: **Sign in to Notion** goes to
420
+ Notion and comes back here.
421
+
422
+ ## Routines
423
+
424
+ When each staff member wakes, and what they do then. Each has a **Daily round** with
425
+ **Change time**, then their routines. Each routine shows its name, when it runs, and the
426
+ start of what it says to do, with **Run now**, **Edit** and **Remove**.
427
+
428
+ **New routine** opens the editor: who, a name, when (days of the week, a day of the month, or a
429
+ cron), and what to do. A preview below says it as a sentence while you type. **Save** writes
430
+ `staff.yaml`, `routines/<id>.md` and the daily caller in one commit, as you. See
431
+ [routines](routines.md).
432
+
402
433
  ## Brain
403
434
 
404
435
  Memory and the file tree, merged, because they were always the same thing: both manifests
package/docs/prompts.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Prompt reference"
3
3
  description: "The template syntax, the context, and what has to be guarded."
4
- sidebar_order: 15
4
+ sidebar_order: 16
5
5
  ---
6
6
 
7
7
  # Prompt reference
@@ -91,11 +91,12 @@ than a hang.
91
91
  |---|---|
92
92
  | `org` | the whole of `org.yaml` |
93
93
  | `org.name`, `org.org` | the business name, the GitHub org |
94
- | `human` | the primary human: the first of `humans`, or the singular `human` block |
94
+ | `human` | the primary human: the first of `humans` who is not view-only, or the singular `human` block |
95
95
  | `human.name`, `human.github`, `human.marker` | |
96
96
  | `humans` | everyone the staff answer to, in order. See [org.yaml](org-yaml.md#human-and-humans) |
97
97
  | `human_list` | all of them as a sentence: "Will (@will-lamerton) and Sam (@sam-x)" |
98
98
  | `humans_extra` | the same, minus the primary. **Empty when there is only one**, which is what makes `{{#if humans_extra}}` the way to mention the others |
99
+ | `humans_viewing` | the `view_only` humans, as a sentence. Empty when there are none |
99
100
  | `ops.dir` | ops repo directory in the checkout |
100
101
  | `staff` | the whole of this staff member's `staff.yaml` |
101
102
  | `staff.dir` | where their brain lands in the checkout |
@@ -0,0 +1,65 @@
1
+ ---
2
+ title: "Routines"
3
+ description: "When staff wake beyond the daily round, and what they do then."
4
+ sidebar_order: 24
5
+ ---
6
+
7
+ # Routines
8
+
9
+ Every staff member has a **daily round**: the scheduled session where they boot, work and hand
10
+ off. A **routine** is one more time they wake, with a job of its own. For example:
11
+
12
+ - every Monday at 09:00, plan the week
13
+ - on the 1st of the month, write last month's numbers into a report
14
+ - every Friday at 16:00, tidy the tracker and close what is done
15
+
16
+ Make them on the portal's **Routines** screen: who, a name, when, and what to do in your own
17
+ words. A preview shows the routine as a sentence while you type. **Run now** starts one
18
+ straight away, which is the way to try one out.
19
+
20
+ From a terminal:
21
+
22
+ ```bash
23
+ roster routine cto add --name "Monday plan" --at "0 9 * * 1" \
24
+ --do "Plan the week: read last week's status issue and this month's priorities, then open one issue per thing to ship, ranked." --apply
25
+ roster routine cto # list them
26
+ roster routine cto run monday-plan
27
+ roster routine cto daily "0 7 * * 1-5" --apply # move the daily round
28
+ ```
29
+
30
+ ## What a routine run does
31
+
32
+ A routine run is a daily session whose prompt opens with the routine's name and your words. The
33
+ staff member boots as usual, so they know where things stand, then does what the routine asks
34
+ instead of the rest of the daily round. They record it as a daily run would: `STATE.md`, their
35
+ memory and the status issue. In **Runs** and on **Home** it shows as "cto routine monday-plan".
36
+
37
+ A routine is not held to `max_runs_per_day`. That limit is for runs nobody asked for, and a
38
+ routine is one you asked for at a set time.
39
+
40
+ ## Where it lives
41
+
42
+ Each routine is in two places in the staff member's brain repo:
43
+
44
+ - `staff.yaml`, under `routines:`, has its id and its time:
45
+ `- { id: monday-plan, schedule: "0 9 * * 1" }`
46
+ - `routines/monday-plan.md` has its name as the heading, then what to do.
47
+
48
+ Both are compiled into the daily caller's `on.schedule`, one cron line per routine. When the
49
+ schedule fires, the cron that fired (`github.event.schedule`) says which routine it was. Nothing
50
+ polls between runs, so a routine costs nothing until it runs.
51
+
52
+ The portal and `roster routine` write the three files in one commit, as you. That includes the
53
+ caller under `.github/workflows/`, so on the hosted portal you sign in with GitHub's `workflow`
54
+ permission. If you signed in before routines existed, sign out and sign in again.
55
+
56
+ ## Rules
57
+
58
+ - **Times are UTC.** The editor shows your local time beside it.
59
+ - **Two schedules cannot share a minute.** GitHub fires once for a cron listed twice, so the
60
+ second would never run. Move one by a minute.
61
+ - **GitHub runs scheduled workflows late when it is busy**, sometimes by tens of minutes. A
62
+ routine is for "around then", not to the second.
63
+ - **Upgrade first.** Routines need the session workflow from roster 0.1.0-beta.20 or later in
64
+ the ops repo. Saving one before `roster upgrade --apply` is refused with that message, rather
65
+ than writing a caller that would fail.
package/docs/security.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Security model"
3
3
  description: "What can reach what, what stops it, and what is not defended against."
4
- sidebar_order: 21
4
+ sidebar_order: 22
5
5
  ---
6
6
 
7
7
  # Security model
@@ -160,9 +160,40 @@ everyone signed in, as is the cache. Everyone signed in is one of the org's huma
160
160
  the org shown to its own people; a human whose GitHub account cannot read one of the brains can
161
161
  still see that brain in the portal. Their unread marks and anything they do are their own.
162
162
 
163
- **The OAuth scopes.** `repo` and `notifications`. A GitHub App would be narrower, but its
164
- tokens cannot read notifications, and unread in the portal is GitHub's own unread, kept in step
165
- with the website and your phone.
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`, `notifications` and `workflow`. A GitHub App would be narrower,
177
+ but its tokens cannot read notifications, and unread in the portal is GitHub's own unread, kept
178
+ in step with the website and your phone. `workflow` is for [routines](routines.md): a routine's
179
+ time is a line in the daily caller under `.github/workflows/`, and GitHub refuses any change
180
+ there from a token without it. `gh` on your own machine already has it.
181
+
182
+ ## Connectors
183
+
184
+ A [connector](connectors.md)'s key is a GitHub secret every brain repo can read, encrypted to
185
+ GitHub's key by the portal or the CLI before it leaves your machine. It reaches a run because the
186
+ callers pass their secrets on with `secrets: inherit`. Inside the run, one step reads them
187
+ (`connectors.mjs`) and writes only this staff member's connectors' keys into the agent's MCP
188
+ config, in the runner's temp directory. No other step, and no agent, sees the rest.
189
+
190
+ The agent can read that config, so treat a key as given to the staff members who have it, and
191
+ give it the least it needs: a read-only key is a limit no prompt can argue with.
192
+
193
+ A signed-in connector's refresh token stays on the hosted portal, sealed under its session key.
194
+ A run gets a short-lived access token, and only after proving with GitHub's OIDC token that it is
195
+ a job of this org's `session.yaml`; a token minted for any other audience, workflow or org is
196
+ refused.
166
197
 
167
198
  ## Trust in a prompt
168
199
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "The session workflow"
3
3
  description: "Inputs, secrets, and what runs in what order."
4
- sidebar_order: 16
4
+ sidebar_order: 17
5
5
  ---
6
6
 
7
7
  # The session workflow
@@ -33,11 +33,23 @@ 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. |
36
+ | `trigger` | string | `""` | What started the run: `daily`, `routine`, `manual`, `follow-on`, `mention` or `peer`. Passed to the prompt. |
37
+ | `routine` | string | `""` | The routine this run is, by id. The prompt reads `routines/<id>.md` from the brain. See [routines](routines.md). |
37
38
  | `max_runs_per_day` | number | `6` | How many `peer` and `follow-on` runs may start in a UTC day. Mentions are never counted. |
39
+ | `secret_prefix` | string | `""` | The prefix of this staff member's App secrets, so `CTO` reads `CTO_APP_ID`. |
40
+ | `public_secret_prefix` | string | `""` | The same for the public App. |
41
+ | `agent_secret` | string | `""` | The name of the secret holding the agent's credential. |
38
42
 
39
43
  ## Secrets
40
44
 
45
+ A caller passes `secrets: inherit`, so every secret the brain repo can read reaches the session
46
+ under its own name. That is what lets a [connector](connectors.md)'s key reach a run without
47
+ the caller naming it. Inheriting cannot rename, so the three inputs above say which names are
48
+ this staff member's: `secret_prefix: CTO` means `CTO_APP_ID` and `CTO_APP_PRIVATE_KEY`.
49
+
50
+ A caller generated before connectors maps its secrets by hand instead, under the names below,
51
+ and those are read first. Both kinds work against the same `session.yaml`.
52
+
41
53
  | Secret | Required | Means |
42
54
  |---|---|---|
43
55
  | `APP_ID` | yes | This staff member's own App. |
@@ -75,19 +87,28 @@ Then the session:
75
87
  `inflight.mjs`, for the prompt. Never fatal. See [prompts](prompts.md#human-work-in-flight).
76
88
  10. **Set git identity** to the App.
77
89
  11. **Set up Node and pnpm**, if the plan found a `package.json`.
78
- 12. **Compose the prompt**, to a step output and to `.roster-prompt.txt`.
79
- 13. **Check the agent has a credential.**
80
- 14. **Work out which agent runs this**, by running `agents.mjs`.
81
- 15. **Run the session**, by one of two steps: the Action-based reference runner, or the generic
90
+ 12. **Open this week's status issue**, daily runs only, by running `status-week.mjs`: when the
91
+ status issue in `staff.yaml` is from an earlier week, a new one is opened, pinned and
92
+ committed to `staff.yaml`, and the prompt is told which earlier week still needs its summary.
93
+ Never fatal. See [architecture](architecture.md#the-weeks-status-issue).
94
+ 13. **Compose the prompt**, to a step output and to `.roster-prompt.txt`.
95
+ 14. **Check the agent has a credential.**
96
+ 15. **Connect services**, by running `connectors.mjs`: each [connector](connectors.md) this
97
+ staff member has, written as the agent's own MCP config in the runner's temp directory,
98
+ with its key read from the inherited secrets. Never fatal: one without its key is left out
99
+ and named in the job summary.
100
+ 16. **Work out which agent runs this**, by running `agents.mjs`, which adds the connectors'
101
+ tools to the agent's allowlist.
102
+ 17. **Run the session**, by one of two steps: the Action-based reference runner, or the generic
82
103
  CLI one. See [choosing a coding agent](agents.md).
83
104
  Then, for a mention, **check the request was answered**: a reply in the thread, or the issue
84
105
  closed. Neither fails the job, so the notice below tells the human.
85
106
  Then, for a daily run that finished and wrote `.roster-run/continue`, **start a follow-on
86
107
  run**: one more daily run with `trigger: follow-on`, which waits for this one to end.
87
- 16. **Write down the run**, whatever happened: staff, kind, outcome, duration, and turns, cost
108
+ 18. **Write down the run**, whatever happened: staff, kind, outcome, duration, and turns, cost
88
109
  and tokens where the agent reports them. Into the job summary, and kept as an artifact
89
110
  called `roster-run`. Never fatal. See [cost](cost.md#what-each-run-cost).
90
- 17. **Say so if the run did not finish.** A comment on the status issue, or on the issue that
111
+ 19. **Say so if the run did not finish.** A comment on the status issue, or on the issue that
91
112
  woke a mention, linking the run.
92
113
 
93
114
  ## When the failure is the token
@@ -107,6 +128,8 @@ jobs:
107
128
  permissions:
108
129
  contents: read
109
130
  issues: write
131
+ actions: write
132
+ id-token: write
110
133
  uses: acme/roster-ops/.github/workflows/session.yaml@main
111
134
  ```
112
135
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "staff.yaml reference"
3
3
  description: "Every field in a staff member's manifest."
4
- sidebar_order: 14
4
+ sidebar_order: 15
5
5
  ---
6
6
 
7
7
  # `staff.yaml` reference
@@ -62,13 +62,14 @@ labels:
62
62
  | `mention` | yes | What wakes them, as in `@cto`. The caller's condition tests for this string. |
63
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. |
64
64
  | `brain` | yes | `owner/name` of this repo. Without it nothing can check secrets, labels or runs. |
65
- | `status_issue` | yes in practice | Number of the pinned status issue. The prompts reference it, so a run cannot compose without it. `roster hire --apply` writes it. |
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. |
66
66
 
67
67
  ## Schedule and limits
68
68
 
69
69
  | Field | Default | Means |
70
70
  |---|---|---|
71
71
  | `schedule` | none | Cron for the daily run. Rendered into the caller. |
72
+ | `routines` | `[]` | More times to wake, each `{ id, schedule }`, with what to do in `routines/<id>.md`. Rendered into the caller's schedule. See [routines](routines.md). |
72
73
  | `model` | org default | Model id. |
73
74
  | `timeout_minutes` | 90 | Ceiling on the daily session. |
74
75
  | `mention_timeout_minutes` | 90 | Ceiling on a mention run. |
@@ -164,7 +165,10 @@ Four labels are roster's own and are checked on every tracker whatever this list
164
165
  | `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
166
  | `review` | An ask for the human to read or approve something. |
166
167
  | `chore` | Something only the human can do: a setting, an account, a key. |
167
- | `keep-open` | A standing thread. A sweep never closes it. `roster hire` puts it on the status issue. |
168
+ | `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. |
169
+
170
+ A fifth, `status`, marks a week's status issue. The session creates it, so doctor does not check
171
+ it. An open one other than this week's is waiting for its summary.
168
172
 
169
173
  Every ask on the human carries exactly one of the first three, which is how the portal sorts
170
174
  what needs them. Staff close any issue on their tracker once nothing is left to do on it,
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Troubleshooting"
3
3
  description: "Every trap we have actually hit, and what it looks like from the outside."
4
- sidebar_order: 10
4
+ sidebar_order: 11
5
5
  ---
6
6
 
7
7
  # Troubleshooting
package/docs/upgrading.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Upgrading"
3
3
  description: "How framework changes reach a tenant without eating your edits."
4
- sidebar_order: 9
4
+ sidebar_order: 10
5
5
  ---
6
6
 
7
7
  # Upgrading
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Writing a charter"
3
3
  description: "The one file nothing can generate for you, and the shape that has worked."
4
- sidebar_order: 5
4
+ sidebar_order: 6
5
5
  ---
6
6
 
7
7
  # Writing a charter
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nanocollective/roster",
3
- "version": "0.1.0-beta.2",
3
+ "version": "0.1.0-beta.21",
4
4
  "description": "An agent-run org, powered by GitHub. Scaffold AI staff members whose brain is a repo.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -39,6 +39,7 @@
39
39
  "@types/node": "^22.10.2",
40
40
  "c8": "^12.0.0",
41
41
  "knip": "^6.34.0",
42
+ "libsodium-wrappers": "^0.8.4",
42
43
  "tsup": "^8.3.5",
43
44
  "tsx": "^4.19.2",
44
45
  "typescript": "^5.7.2"
@@ -0,0 +1,3 @@
1
+ # LF on every platform. Git for Windows checks out CRLF by default, and roster compares these
2
+ # files with the ones it generates line by line.
3
+ * text=auto eol=lf
@@ -1,20 +1,21 @@
1
1
  name: %%STAFF_UPPER%% daily run
2
2
 
3
- # Generated by roster. The body lives in %%OPS_REPO%%/.github/workflows/session.yaml.
4
- # Edit this file only to change the schedule; everything else belongs in the ops repo, where
5
- # one change reaches every staff member.
3
+ # Generated by roster from staff.yaml. The body lives in %%OPS_REPO%%/.github/workflows/session.yaml.
4
+ # The schedule is staff.yaml's `schedule:` (the daily round) and `routines:`; change those, in
5
+ # the portal or with `roster routine`, rather than this file.
6
6
  #
7
7
  # NOTE: %%TOKENS%% are filled by `roster hire`; GitHub's own ${{ }} are left alone.
8
8
 
9
- # The trigger and the date, as the Actions list shows it. The daily limit counts follow-on runs
10
- # by this name.
11
- run-name: "%%STAFF%% ${{ github.event_name == 'schedule' && 'daily' || inputs.trigger || 'manual' }}"
9
+ # The trigger, as the Actions list shows it: "cto daily", "cto routine monday-plan". The daily
10
+ # limit counts follow-on runs by this name.
11
+ run-name: "%%STAFF%% ${{ github.event_name == 'schedule' && (%%ROUTINE%% != '' && format('routine {0}', %%ROUTINE%%) || 'daily') || inputs.routine != '' && format('routine {0}', inputs.routine) || inputs.trigger || 'manual' }}"
12
12
 
13
13
  on:
14
+ # The daily round first, then one line per routine. The cron that fired says which it was.
14
15
  schedule:
15
- - cron: "%%SCHEDULE%%"
16
+ %%SCHEDULES%%
16
17
  # By hand, from Run once now, or as a follow-on: a daily run that ended with the next step
17
- # ready starts one more, up to max_runs_per_day.
18
+ # ready starts one more, up to max_runs_per_day. `routine` runs one routine now.
18
19
  workflow_dispatch:
19
20
  inputs:
20
21
  trigger:
@@ -22,6 +23,11 @@ on:
22
23
  required: false
23
24
  default: manual
24
25
  type: string
26
+ routine:
27
+ description: "a routine's id, to run that routine now"
28
+ required: false
29
+ default: ""
30
+ type: string
25
31
 
26
32
  # A second run while one is in flight would fight it over the tracker and the branch state. A
27
33
  # follow-on is started from inside the run before it, so it waits here until that one ends.
@@ -41,19 +47,22 @@ jobs:
41
47
  contents: read
42
48
  issues: write
43
49
  actions: write
50
+ id-token: write
44
51
  uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
45
52
  with:
46
53
  staff: %%STAFF%%
47
54
  kind: daily
48
- trigger: ${{ github.event_name == 'schedule' && 'daily' || inputs.trigger || 'manual' }}
55
+ trigger: ${{ github.event_name == 'schedule' && (%%ROUTINE%% != '' && 'routine' || 'daily') || inputs.routine != '' && 'routine' || inputs.trigger || 'manual' }}
56
+ routine: ${{ github.event_name == 'schedule' && %%ROUTINE%% || inputs.routine || '' }}
49
57
  max_runs_per_day: %%MAX_RUNS%%
50
58
  ops_repo: %%OPS_REPO%%
51
59
  model: %%MODEL%%
52
60
  timeout_minutes: %%TIMEOUT%%
53
61
  allowed_tools: "%%ALLOWED_TOOLS%%"
54
- secrets:
55
- APP_ID: ${{ secrets.%%SECRET_PREFIX%%_APP_ID }}
56
- APP_PRIVATE_KEY: ${{ secrets.%%SECRET_PREFIX%%_APP_PRIVATE_KEY }}
57
- PUBLIC_APP_ID: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_ID }}
58
- PUBLIC_APP_PRIVATE_KEY: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_PRIVATE_KEY }}
59
- AGENT_TOKEN: ${{ secrets.%%AGENT_SECRET%% }}
62
+ secret_prefix: %%SECRET_PREFIX%%
63
+ public_secret_prefix: %%PUBLIC_SECRET_PREFIX%%
64
+ agent_secret: %%AGENT_SECRET%%
65
+ # Inherited rather than listed, so a connector's key added later reaches the run without
66
+ # this file changing. session.yaml reads the App's pair and the agent credential by the
67
+ # names above, and each connector's key by the name its connector gives it.
68
+ secrets: inherit
@@ -16,7 +16,7 @@ name: %%STAFF_UPPER%% on a mention
16
16
  # skipped.
17
17
  run-name: >-
18
18
  %%STAFF%% ${{
19
- (contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.sender.login) &&
19
+ (contains(fromJSON(vars.ROSTER_HUMANS || '%%HUMAN_LOGINS%%'), github.event.sender.login) &&
20
20
  (contains(github.event.comment.body, '%%MENTION%%') ||
21
21
  (github.event_name == 'issues' && contains(github.event.issue.body, '%%MENTION%%'))))
22
22
  && 'mention'
@@ -72,10 +72,10 @@ jobs:
72
72
  cancel-in-progress: false
73
73
  if: >-
74
74
  (
75
- contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.sender.login) &&
75
+ contains(fromJSON(vars.ROSTER_HUMANS || '%%HUMAN_LOGINS%%'), github.event.sender.login) &&
76
76
  (
77
77
  (github.event_name == 'issue_comment' &&
78
- contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.comment.user.login) &&
78
+ contains(fromJSON(vars.ROSTER_HUMANS || '%%HUMAN_LOGINS%%'), github.event.comment.user.login) &&
79
79
  contains(github.event.comment.body, '%%MENTION%%')) ||
80
80
  (github.event_name == 'issues' &&
81
81
  contains(github.event.issue.body, '%%MENTION%%'))
@@ -97,11 +97,12 @@ jobs:
97
97
  contents: read
98
98
  issues: write
99
99
  actions: write
100
+ id-token: write
100
101
  uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
101
102
  with:
102
103
  staff: %%STAFF%%
103
104
  kind: mention
104
- trigger: ${{ contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.sender.login) && 'mention' || 'peer' }}
105
+ trigger: ${{ contains(fromJSON(vars.ROSTER_HUMANS || '%%HUMAN_LOGINS%%'), github.event.sender.login) && 'mention' || 'peer' }}
105
106
  max_runs_per_day: %%MAX_RUNS%%
106
107
  ops_repo: %%OPS_REPO%%
107
108
  model: %%MODEL%%
@@ -109,9 +110,10 @@ jobs:
109
110
  allowed_tools: "%%ALLOWED_TOOLS%%"
110
111
  issue_number: ${{ github.event.issue.number }}
111
112
  comment_id: ${{ github.event.comment.id }}
112
- secrets:
113
- APP_ID: ${{ secrets.%%SECRET_PREFIX%%_APP_ID }}
114
- APP_PRIVATE_KEY: ${{ secrets.%%SECRET_PREFIX%%_APP_PRIVATE_KEY }}
115
- PUBLIC_APP_ID: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_ID }}
116
- PUBLIC_APP_PRIVATE_KEY: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_PRIVATE_KEY }}
117
- AGENT_TOKEN: ${{ secrets.%%AGENT_SECRET%% }}
113
+ secret_prefix: %%SECRET_PREFIX%%
114
+ public_secret_prefix: %%PUBLIC_SECRET_PREFIX%%
115
+ agent_secret: %%AGENT_SECRET%%
116
+ # Inherited rather than listed, so a connector's key added later reaches the run without
117
+ # this file changing. session.yaml reads the App's pair and the agent credential by the
118
+ # names above, and each connector's key by the name its connector gives it.
119
+ secrets: inherit
@@ -45,5 +45,5 @@ Only the additions. `org/guardrails.md` is already binding on everyone.
45
45
 
46
46
  ## Where the rest of it lives
47
47
 
48
- Point at `memory/INDEX.md`, `log/decisions.md`, the pinned status issue, and whatever
49
- surfaces this role declares in `staff.yaml`.
48
+ Point at `memory/INDEX.md`, `log/decisions.md`, `STATE.md`, the pinned status issue, and
49
+ whatever surfaces this role declares in `staff.yaml`.
@@ -0,0 +1,16 @@
1
+ # Where I am
2
+
3
+ %%NAME%%'s handover between runs. Every daily run reads it first and rewrites it last. What
4
+ people read is the pinned status issue.
5
+
6
+ ## Situation
7
+
8
+ Just hired. Nothing done yet.
9
+
10
+ ## Next, in order
11
+
12
+ 1. Read the charter and the org's priorities, and pick the first piece of work.
13
+
14
+ ## Parked
15
+
16
+ Nothing.
@@ -18,7 +18,7 @@ The grammar, which `roster lint` enforces:
18
18
 
19
19
  - **`<slug>`** · [<%%HUMAN_MARKER%%|measured|derived>] <the fact, one line>. **So:** <what it changes>. · [note](notes/<slug>.md)
20
20
 
21
- `log/decisions.md` = why things were decided. The pinned status issue = what is outstanding.
21
+ `log/decisions.md` = why things were decided. `STATE.md` = what is outstanding.
22
22
  **Nothing is copied between them.**
23
23
 
24
24
  ---