@nanocollective/roster 0.1.0-beta.2 → 0.1.0-beta.22
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 +8 -0
- package/dist/agents-POITEZRI.js +232 -0
- package/dist/chunk-FF2WBNNW.js +370 -0
- package/dist/chunk-GDAJPOHK.js +562 -0
- package/dist/cli.js +3187 -1105
- package/dist/compose-5DBEHSEV.js +17 -0
- package/dist/connectors-5E5ZMGZV.js +23 -0
- package/dist/worker/assets/assets/css/astryx.css +948 -0
- package/dist/worker/assets/assets/css/base.css +64 -110
- package/dist/worker/assets/assets/css/brain.css +26 -2
- package/dist/worker/assets/assets/css/connectors.css +50 -0
- package/dist/worker/assets/assets/css/graph.css +9 -12
- package/dist/worker/assets/assets/css/health.css +4 -7
- package/dist/worker/assets/assets/css/home.css +145 -60
- package/dist/worker/assets/assets/css/inbox.css +11 -0
- package/dist/worker/assets/assets/css/layout.css +16 -20
- package/dist/worker/assets/assets/css/markdown.css +22 -1
- package/dist/worker/assets/assets/css/routines.css +40 -0
- package/dist/worker/assets/assets/css/runs.css +5 -3
- package/dist/worker/assets/assets/css/search.css +3 -6
- package/dist/worker/assets/assets/css/setup.css +3 -15
- package/dist/worker/assets/assets/js/api.js +33 -0
- package/dist/worker/assets/assets/js/app.js +49 -3
- package/dist/worker/assets/assets/js/astryx-ui.js +34 -0
- package/dist/worker/assets/assets/js/homesort.js +28 -21
- package/dist/worker/assets/assets/js/icons.js +6 -0
- package/dist/worker/assets/assets/js/md.js +7 -2
- package/dist/worker/assets/assets/js/refcard.js +216 -0
- package/dist/worker/assets/assets/js/refresh.js +4 -2
- package/dist/worker/assets/assets/js/report.js +51 -0
- package/dist/worker/assets/assets/js/select.js +362 -0
- package/dist/worker/assets/assets/js/state.js +14 -1
- package/dist/worker/assets/assets/js/views/connectors.js +290 -0
- package/dist/worker/assets/assets/js/views/graph.js +67 -28
- package/dist/worker/assets/assets/js/views/home.js +378 -176
- package/dist/worker/assets/assets/js/views/inbox.js +68 -16
- package/dist/worker/assets/assets/js/views/org.js +2 -0
- package/dist/worker/assets/assets/js/views/people.js +109 -0
- package/dist/worker/assets/assets/js/views/routines.js +378 -0
- package/dist/worker/assets/assets/js/views/runs.js +3 -1
- 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 +16 -1
- package/dist/worker/index.js +3972 -963
- package/docs/README.md +2 -0
- package/docs/architecture.md +23 -4
- package/docs/commands.md +111 -9
- package/docs/concepts.md +2 -1
- package/docs/connectors.md +157 -0
- package/docs/cost.md +1 -1
- package/docs/developing.md +3 -3
- package/docs/doctor-codes.md +8 -2
- package/docs/export.md +4 -3
- package/docs/extending.md +1 -1
- package/docs/getting-started.md +20 -3
- package/docs/hosting.md +42 -3
- 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/setup-org.jpg +0 -0
- package/docs/images/setup-plan.jpg +0 -0
- package/docs/images/staff.jpg +0 -0
- package/docs/memory.md +3 -2
- package/docs/org-yaml.md +58 -5
- package/docs/portal.md +43 -10
- package/docs/prompts.md +3 -2
- package/docs/routines.md +65 -0
- package/docs/security.md +35 -4
- package/docs/session-workflow.md +31 -8
- package/docs/staff-yaml.md +7 -3
- package/docs/troubleshooting.md +1 -1
- package/docs/upgrading.md +1 -1
- package/docs/writing-a-charter.md +1 -1
- package/package.json +8 -1
- package/templates/brain/.gitattributes +3 -0
- package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml +24 -15
- package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml +12 -10
- 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 +3 -0
- package/templates/ops/.gitattributes +3 -0
- package/templates/ops/.github/workflows/session.yaml +74 -13
- package/templates/ops/agents.mjs +38 -11
- package/templates/ops/compose.mjs +60 -2
- package/templates/ops/connectors.mjs +722 -0
- package/templates/ops/org/operating.md +10 -0
- package/templates/ops/org/voice.md +21 -3
- package/templates/ops/prompts/_identity.md +20 -0
- package/templates/ops/prompts/daily.md +70 -19
- package/templates/ops/prompts/mention.md +7 -2
- package/templates/ops/status-week.mjs +169 -0
- package/templates/portal/css/astryx.css +948 -0
- package/templates/portal/css/base.css +64 -110
- package/templates/portal/css/brain.css +26 -2
- package/templates/portal/css/connectors.css +50 -0
- package/templates/portal/css/graph.css +9 -12
- package/templates/portal/css/health.css +4 -7
- package/templates/portal/css/home.css +145 -60
- package/templates/portal/css/inbox.css +11 -0
- package/templates/portal/css/layout.css +16 -20
- package/templates/portal/css/markdown.css +22 -1
- package/templates/portal/css/routines.css +40 -0
- package/templates/portal/css/runs.css +5 -3
- package/templates/portal/css/search.css +3 -6
- package/templates/portal/css/setup.css +3 -15
- package/templates/portal/index.html +16 -1
- package/templates/portal/js/api.js +33 -0
- package/templates/portal/js/app.js +49 -3
- package/templates/portal/js/astryx-ui.js +34 -0
- package/templates/portal/js/homesort.js +28 -21
- package/templates/portal/js/icons.js +6 -0
- package/templates/portal/js/md.js +7 -2
- package/templates/portal/js/refcard.js +216 -0
- package/templates/portal/js/refresh.js +4 -2
- package/templates/portal/js/report.js +51 -0
- package/templates/portal/js/select.js +362 -0
- package/templates/portal/js/state.js +14 -1
- package/templates/portal/js/views/connectors.js +290 -0
- package/templates/portal/js/views/graph.js +67 -28
- package/templates/portal/js/views/home.js +378 -176
- package/templates/portal/js/views/inbox.js +68 -16
- package/templates/portal/js/views/org.js +2 -0
- package/templates/portal/js/views/people.js +109 -0
- package/templates/portal/js/views/routines.js +378 -0
- package/templates/portal/js/views/runs.js +3 -1
- package/templates/skill/SKILL.md +115 -0
package/docs/memory.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Memory"
|
|
3
3
|
description: "The grammar, the five rules, and why deleting is the maintenance."
|
|
4
|
-
sidebar_order:
|
|
4
|
+
sidebar_order: 8
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Memory
|
|
@@ -69,7 +69,8 @@ hand-off and make pruning that run's job when it is over.
|
|
|
69
69
|
- **How a thing works.** That is a draft or a strategy document.
|
|
70
70
|
- **An idea not yet acted on.** That is one line in `strategy/ideas.md`, and it becomes an issue
|
|
71
71
|
only when it needs a ruling.
|
|
72
|
-
- **What is outstanding.** That is the
|
|
72
|
+
- **What is outstanding.** That is `STATE.md`, the handover each daily run rewrites. The pinned
|
|
73
|
+
status issue is the same picture written for you.
|
|
73
74
|
|
|
74
75
|
Nothing is copied between them. Four places, four jobs, and a fact that appears in two of them
|
|
75
76
|
will disagree with itself within a month.
|
package/docs/org-yaml.md
CHANGED
|
@@ -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:
|
|
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
|
|
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
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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:
|
|
4
|
+
sidebar_order: 18
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# The portal
|
|
@@ -94,15 +94,18 @@ goes away; the repo picker lives on under [Org](#org).
|
|
|
94
94
|
|
|
95
95
|
## Home
|
|
96
96
|
|
|
97
|
-

|
|
98
98
|
|
|
99
|
-
Where the portal opens.
|
|
99
|
+
Where the portal opens. A card for each staff member at the top, then these, in order.
|
|
100
100
|
|
|
101
|
-
- **Ask.**
|
|
102
|
-
tracker with their `@handle` in front, which wakes them in about a minute
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
101
|
+
- **Ask a question.** On each staff member's card. Type what you want and **Send**: it opens an
|
|
102
|
+
issue on their tracker with their `@handle` in front, which wakes them in about a minute, and
|
|
103
|
+
their card says so until it starts. Close the box before sending and what you typed is kept.
|
|
104
|
+
- **Progress.** Each staff member's report, a row each: its status, the one line on how it is
|
|
105
|
+
going and what is next, from the status issue every run rewrites. **Full report** opens what
|
|
106
|
+
got done, what is next and what is waiting on a person; **Ask for an update** asks them, with
|
|
107
|
+
their `@handle`, to bring it up to date now, which takes a few minutes. It comes after Unread
|
|
108
|
+
and Your requests.
|
|
106
109
|
- **Needs you.** Every ask a staff member has put on you, and every pull request ready to
|
|
107
110
|
merge, oldest first. Each card has one action on its right:
|
|
108
111
|
- a `decision` has **Reply**, and **Go with the default** when it carries one. The default
|
|
@@ -188,8 +191,10 @@ down with the list, so opening a thread is a render rather than a request.
|
|
|
188
191
|
to find out it landed.
|
|
189
192
|
- **How much conversation** is on each row, which is most of what tells a live thread from
|
|
190
193
|
something filed and never answered.
|
|
191
|
-
- Issue and PR references in a body become chips
|
|
192
|
-
|
|
194
|
+
- Issue and PR references in a body become chips, and `@handle` mentions become chips too.
|
|
195
|
+
Hovering a chip for one of the org's repos shows a card with its title, state, opening
|
|
196
|
+
lines and labels. Clicking it opens the thread in a side sheet, closed or not, over
|
|
197
|
+
whatever you were reading. ⌘-click or middle-click still opens GitHub. A mention of somebody on this roster goes to their repository
|
|
193
198
|
rather than to a GitHub profile of that name, which for `@cto` is a stranger.
|
|
194
199
|
- **Not every comment is markdown.** Deploy bots post raw HTML. A `<table>` renders as a
|
|
195
200
|
table, and inline `<a>`, `<img>`, `<strong>`, `<em>`, `<code>` and `<br>` are reduced to
|
|
@@ -399,6 +404,34 @@ from `org.yaml` and from every peer, and deletes the dead `from-<handle>` labels
|
|
|
399
404
|
what it keeps as prominently as what it stops, because that is the thing you have to believe
|
|
400
405
|
before clicking it.
|
|
401
406
|
|
|
407
|
+
## Connectors
|
|
408
|
+
|
|
409
|
+
Outside services the staff can use in their runs: Sentry, Linear, Stripe and the rest of the
|
|
410
|
+
[catalogue](connectors.md#the-catalogue).
|
|
411
|
+
|
|
412
|
+
What is connected is a list: each service, who can use it, and whether its key is stored. **Edit**
|
|
413
|
+
changes who can use it, or replaces the key; **Remove** asks once more, then deletes the keys and
|
|
414
|
+
takes it out of `org.yaml`.
|
|
415
|
+
|
|
416
|
+
Below it is every service you can add. Picking one opens a sheet with the steps to get a key, a
|
|
417
|
+
link to the right settings page, the key, and who can use it, ticked for the roles that usually
|
|
418
|
+
want it. **Check key** asks the service whether the key works before anything is stored. **Save**
|
|
419
|
+
checks it again, stores it as a GitHub secret and commits `org.yaml`.
|
|
420
|
+
|
|
421
|
+
Notion signs in instead, on the [hosted portal](hosting.md) only: **Sign in to Notion** goes to
|
|
422
|
+
Notion and comes back here.
|
|
423
|
+
|
|
424
|
+
## Routines
|
|
425
|
+
|
|
426
|
+
When each staff member wakes, and what they do then. Each has a **Daily round** with
|
|
427
|
+
**Change time**, then their routines. Each routine shows its name, when it runs, and the
|
|
428
|
+
start of what it says to do, with **Run now**, **Edit** and **Remove**.
|
|
429
|
+
|
|
430
|
+
**New routine** opens the editor: who, a name, when (days of the week, a day of the month, or a
|
|
431
|
+
cron), and what to do. A preview below says it as a sentence while you type. **Save** writes
|
|
432
|
+
`staff.yaml`, `routines/<id>.md` and the daily caller in one commit, as you. See
|
|
433
|
+
[routines](routines.md).
|
|
434
|
+
|
|
402
435
|
## Brain
|
|
403
436
|
|
|
404
437
|
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:
|
|
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
|
|
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 |
|
package/docs/routines.md
ADDED
|
@@ -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:
|
|
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
|
-
**
|
|
164
|
-
|
|
165
|
-
|
|
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
|
|
package/docs/session-workflow.md
CHANGED
|
@@ -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:
|
|
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. **
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
package/docs/staff-yaml.md
CHANGED
|
@@ -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:
|
|
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
|
|
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.
|
|
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,
|
package/docs/troubleshooting.md
CHANGED
package/docs/upgrading.md
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nanocollective/roster",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.22",
|
|
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": {
|
|
@@ -35,10 +35,17 @@
|
|
|
35
35
|
"build:worker": "node scripts/build-worker.mjs"
|
|
36
36
|
},
|
|
37
37
|
"devDependencies": {
|
|
38
|
+
"@astryxdesign/core": "0.7.11",
|
|
39
|
+
"@astryxdesign/theme-neutral": "0.7.11",
|
|
38
40
|
"@biomejs/biome": "^2.5.12",
|
|
41
|
+
"@stylexjs/stylex": "^0.19.1",
|
|
39
42
|
"@types/node": "^22.10.2",
|
|
40
43
|
"c8": "^12.0.0",
|
|
44
|
+
"jsdom": "^31.0.0",
|
|
41
45
|
"knip": "^6.34.0",
|
|
46
|
+
"libsodium-wrappers": "^0.8.4",
|
|
47
|
+
"react": "^19.3.1",
|
|
48
|
+
"react-dom": "^19.3.1",
|
|
42
49
|
"tsup": "^8.3.5",
|
|
43
50
|
"tsx": "^4.19.2",
|
|
44
51
|
"typescript": "^5.7.2"
|
|
@@ -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
|
-
#
|
|
5
|
-
#
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|