@nanocollective/roster 0.1.0-beta.3 → 0.1.0-beta.30
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 +3391 -1239
- 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 +51 -110
- package/dist/worker/assets/assets/css/brain.css +26 -2
- package/dist/worker/assets/assets/css/connectors.css +58 -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 +18 -22
- 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 +3 -0
- package/dist/worker/assets/assets/js/app.js +25 -1
- package/dist/worker/assets/assets/js/astryx-ui.js +34 -0
- package/dist/worker/assets/assets/js/dom.js +1 -1
- package/dist/worker/assets/assets/js/homesort.js +66 -20
- 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 +423 -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 +19 -3
- package/dist/worker/index.js +4478 -1098
- 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 +169 -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 +67 -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 +52 -11
- package/docs/prompts.md +3 -2
- package/docs/routines.md +65 -0
- package/docs/security.md +37 -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 +92 -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 +51 -110
- package/templates/portal/css/brain.css +26 -2
- package/templates/portal/css/connectors.css +58 -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 +18 -22
- 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 +19 -3
- package/templates/portal/js/api.js +3 -0
- package/templates/portal/js/app.js +25 -1
- package/templates/portal/js/astryx-ui.js +34 -0
- package/templates/portal/js/dom.js +1 -1
- package/templates/portal/js/homesort.js +66 -20
- 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 +423 -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/hosting.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Hosting the portal"
|
|
3
3
|
description: "The portal on your own URL, behind Sign in with GitHub, redeploying itself."
|
|
4
|
-
sidebar_order:
|
|
4
|
+
sidebar_order: 12
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Hosting the portal
|
|
@@ -35,10 +35,12 @@ does. That is not something to put behind a public URL.
|
|
|
35
35
|
## Who can get in
|
|
36
36
|
|
|
37
37
|
Only the people listed under `humans:` in `org.yaml`, signed in with their own GitHub account.
|
|
38
|
+
That includes anyone marked `view_only`, who can read everything and wake nobody; see
|
|
39
|
+
[org.yaml](org-yaml.md#human-and-humans).
|
|
38
40
|
|
|
39
41
|
- Sign-in is GitHub's own OAuth flow, through an OAuth App your org creates for the portal.
|
|
40
|
-
The token it hands back is that person's, scoped `repo` and `
|
|
41
|
-
`gh` holds on their machine.
|
|
42
|
+
The token it hands back is that person's, scoped `repo`, `notifications` and `workflow`, the
|
|
43
|
+
same kind `gh` holds on their machine.
|
|
42
44
|
- Everything they do is as themselves. A reply is theirs, a merge is theirs, and what they can
|
|
43
45
|
read is what GitHub lets them read.
|
|
44
46
|
- Somebody who signs in and is not one of the humans, or cannot read the ops repo, is turned
|
|
@@ -48,6 +50,53 @@ Only the people listed under `humans:` in `org.yaml`, signed in with their own G
|
|
|
48
50
|
|
|
49
51
|
See [security](security.md#the-hosted-portal) for what is held where.
|
|
50
52
|
|
|
53
|
+
## Talking to your staff from Claude
|
|
54
|
+
|
|
55
|
+
The hosted portal is also an MCP server, at `/mcp`. Add it to Claude as a custom connector with
|
|
56
|
+
the URL `https://roster.acme.com/mcp`. Claude sends you to sign in with GitHub, the same check
|
|
57
|
+
against `humans:` as the portal, and then to a page that says what it will be able to do, with
|
|
58
|
+
**Allow**.
|
|
59
|
+
|
|
60
|
+
Then you can ask Claude things like "what needs me today?", "what did the CTO do?" or "tell the
|
|
61
|
+
CMO to draft this week's post". The tools:
|
|
62
|
+
|
|
63
|
+
| Tool | Does |
|
|
64
|
+
|---|---|
|
|
65
|
+
| `brief` | Each staff member's report, what needs you (with each decision's default), your requests, what was closed today |
|
|
66
|
+
| `read_thread` | One issue or pull request with every reply |
|
|
67
|
+
| `reply` | A reply as you, optionally closing the issue |
|
|
68
|
+
| `ask_staff` | A new issue on a staff member's tracker with their mention, which starts them |
|
|
69
|
+
| `ask_for_report` | Asks a staff member to bring their report up to date now |
|
|
70
|
+
| `list_issues` | Open issues and pull requests, by staff member, repo, kind or label |
|
|
71
|
+
| `run` | Starts a staff member's session now, or one of their routines |
|
|
72
|
+
| `runs` | Recent runs: how each went, how long, what it cost, and its log |
|
|
73
|
+
| `read_brain` | `STATE.md`, `CHARTER.md`, `memory/INDEX.md`, `log/decisions.md` or `staff.yaml` |
|
|
74
|
+
| `read_pr` | A pull request to review: checks, conflicts, review state, commits and the diff |
|
|
75
|
+
| `approve` | An approving review, as you |
|
|
76
|
+
| `merge` | Merges a pull request, only when you have told it to |
|
|
77
|
+
| `wait` | Waits up to ten minutes for a staff member's reply on a thread, or for their run to finish |
|
|
78
|
+
|
|
79
|
+
The Connectors screen has the line to paste for Claude Code, Codex and Claude, under **Connect
|
|
80
|
+
your own agent**. From Claude Code:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
claude mcp add --transport http roster-acme https://roster.acme.com/mcp
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
then `/mcp` to sign in. With more than one Roster, give each its own name (`roster-acme`,
|
|
87
|
+
`roster-globex`): an agent keeps each server's tools apart by that name.
|
|
88
|
+
|
|
89
|
+
So with half an hour spare you can work through the brief with your agent: answer the asks,
|
|
90
|
+
read and merge the pull requests, ask for the next thing and wait for the answer, without
|
|
91
|
+
waiting for the daily run.
|
|
92
|
+
|
|
93
|
+
It merges only when you tell it to: the tool asks for your words, and Claude Code asks you
|
|
94
|
+
before the call. It cannot hire, retire or change the org: those stay local. Everything it
|
|
95
|
+
posts is posted as you.
|
|
96
|
+
|
|
97
|
+
Nothing to set up beyond the portal itself: the connector signs in through the same OAuth App,
|
|
98
|
+
on the same callback URL (`/auth/callback`).
|
|
99
|
+
|
|
51
100
|
## Deploying it
|
|
52
101
|
|
|
53
102
|
You need a Cloudflare account with the domain on it, and wrangler signed in to it. If your
|
|
@@ -78,6 +127,9 @@ and commits two files to the ops repo:
|
|
|
78
127
|
- `portal/wrangler.jsonc`: the Worker's name, the domain, the org. Nothing secret.
|
|
79
128
|
- `.github/workflows/portal.yaml`: redeploys it.
|
|
80
129
|
|
|
130
|
+
To show your own icon on the sign-in page and in the portal, commit a square image as
|
|
131
|
+
`portal/icon.png` (or `.svg`, `.jpg`, `.webp`). The push redeploys the portal with it.
|
|
132
|
+
|
|
81
133
|
## Keeping it up to date
|
|
82
134
|
|
|
83
135
|
The workflow redeploys the portal when its config changes, every morning, and when you run it
|
|
@@ -105,6 +157,18 @@ On your machine it is `~/.cache/roster`. On Cloudflare it is the edge cache, whi
|
|
|
105
157
|
setup. To keep it everywhere rather than per data centre, bind a KV namespace as `CACHE` in
|
|
106
158
|
`portal/wrangler.jsonc`.
|
|
107
159
|
|
|
160
|
+
## Signed-in connectors
|
|
161
|
+
|
|
162
|
+
A [connector](connectors.md) that signs in with a browser, like Notion, keeps its sign-in on the
|
|
163
|
+
hosted portal, which needs somewhere durable to keep it: a KV namespace bound as `CONNECTORS`.
|
|
164
|
+
`roster portal deploy` finds one by name, or creates it, on any deploy that does not have it
|
|
165
|
+
bound yet, the morning one included; a deploy by hand also writes it into
|
|
166
|
+
`portal/wrangler.jsonc`. Without it, connectors that take a key still work, and the ones that
|
|
167
|
+
sign in are not offered.
|
|
168
|
+
|
|
169
|
+
A run collects a fresh access token from `/connectors/token`, proving with GitHub's OIDC token
|
|
170
|
+
that it is a run of this org's `session.yaml`.
|
|
171
|
+
|
|
108
172
|
## On your machine
|
|
109
173
|
|
|
110
174
|
`roster portal` binds to `127.0.0.1` and acts as whoever `gh` is signed in as. To open an org
|
package/docs/images/brain.jpg
CHANGED
|
Binary file
|
package/docs/images/home.jpg
CHANGED
|
Binary file
|
package/docs/images/org.jpg
CHANGED
|
Binary file
|
package/docs/images/prompt.jpg
CHANGED
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/docs/images/staff.jpg
CHANGED
|
Binary file
|
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
|
|
@@ -19,6 +19,11 @@ It can also be hosted, on your own URL behind Sign in with GitHub: see [hosting]
|
|
|
19
19
|
|
|
20
20
|
## The sidebar
|
|
21
21
|
|
|
22
|
+
**Your own icon.** Put a square image in the ops repo at `portal/icon.png` (or `.svg`, `.jpg`,
|
|
23
|
+
`.webp`) and it replaces roster's mark in the sidebar and the browser tab, and on a hosted
|
|
24
|
+
portal's sign-in page. Locally it shows on the next reload; a hosted portal picks it up when it
|
|
25
|
+
redeploys, which a push to `portal/` does.
|
|
26
|
+
|
|
22
27
|
**Search everything** with ⌘K (Ctrl+K off a Mac), from anywhere, or the Search field at the
|
|
23
28
|
top of the sidebar, which opens the same dialog. It searches as you type, across:
|
|
24
29
|
|
|
@@ -94,17 +99,23 @@ goes away; the repo picker lives on under [Org](#org).
|
|
|
94
99
|
|
|
95
100
|
## Home
|
|
96
101
|
|
|
97
|
-

|
|
98
103
|
|
|
99
|
-
Where the portal opens.
|
|
104
|
+
Where the portal opens. A card for each staff member at the top, then these, in order.
|
|
100
105
|
|
|
101
|
-
- **Ask.**
|
|
102
|
-
tracker with their `@handle` in front, which wakes them in about a minute
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
+
- **Ask a question.** On each staff member's card. Type what you want and **Send**: it opens an
|
|
107
|
+
issue on their tracker with their `@handle` in front, which wakes them in about a minute, and
|
|
108
|
+
their card says so until it starts. Close the box before sending and what you typed is kept.
|
|
109
|
+
- **Progress.** Each staff member's report, a row each: its status, the one line on how it is
|
|
110
|
+
going and what is next, from the status issue every run rewrites. **Full report** opens what
|
|
111
|
+
got done, what is next and what is waiting on a person; **Ask for an update** asks them, with
|
|
112
|
+
their `@handle`, to bring it up to date now, which takes a few minutes. It comes after Unread
|
|
113
|
+
and Your requests.
|
|
106
114
|
- **Needs you.** Every ask a staff member has put on you, and every pull request ready to
|
|
107
|
-
merge, oldest first.
|
|
115
|
+
merge, oldest first. An ask is on you when it is assigned to you, carries your label, or its
|
|
116
|
+
newest comment @mentions you: a staff member who asks for your OK by name puts it here, not
|
|
117
|
+
only in your GitHub notifications. Mentioning the person whose own request it is does not
|
|
118
|
+
count, and whoever wrote the newest comment has passed it on. Each card has one action on its right:
|
|
108
119
|
- a `decision` has **Reply**, and **Go with the default** when it carries one. The default
|
|
109
120
|
and its date are shown, and turn amber once the date has passed.
|
|
110
121
|
- a `review` has **Approve**.
|
|
@@ -188,8 +199,10 @@ down with the list, so opening a thread is a render rather than a request.
|
|
|
188
199
|
to find out it landed.
|
|
189
200
|
- **How much conversation** is on each row, which is most of what tells a live thread from
|
|
190
201
|
something filed and never answered.
|
|
191
|
-
- Issue and PR references in a body become chips
|
|
192
|
-
|
|
202
|
+
- Issue and PR references in a body become chips, and `@handle` mentions become chips too.
|
|
203
|
+
Hovering a chip for one of the org's repos shows a card with its title, state, opening
|
|
204
|
+
lines and labels. Clicking it opens the thread in a side sheet, closed or not, over
|
|
205
|
+
whatever you were reading. ⌘-click or middle-click still opens GitHub. A mention of somebody on this roster goes to their repository
|
|
193
206
|
rather than to a GitHub profile of that name, which for `@cto` is a stranger.
|
|
194
207
|
- **Not every comment is markdown.** Deploy bots post raw HTML. A `<table>` renders as a
|
|
195
208
|
table, and inline `<a>`, `<img>`, `<strong>`, `<em>`, `<code>` and `<br>` are reduced to
|
|
@@ -399,6 +412,34 @@ from `org.yaml` and from every peer, and deletes the dead `from-<handle>` labels
|
|
|
399
412
|
what it keeps as prominently as what it stops, because that is the thing you have to believe
|
|
400
413
|
before clicking it.
|
|
401
414
|
|
|
415
|
+
## Connectors
|
|
416
|
+
|
|
417
|
+
Outside services the staff can use in their runs: Sentry, Linear, Stripe and the rest of the
|
|
418
|
+
[catalogue](connectors.md#the-catalogue).
|
|
419
|
+
|
|
420
|
+
What is connected is a list: each service, who can use it, and whether its key is stored. **Edit**
|
|
421
|
+
changes who can use it, or replaces the key; **Remove** asks once more, then deletes the keys and
|
|
422
|
+
takes it out of `org.yaml`.
|
|
423
|
+
|
|
424
|
+
Below it is every service you can add. Picking one opens a sheet with the steps to get a key, a
|
|
425
|
+
link to the right settings page, the key, and who can use it, ticked for the roles that usually
|
|
426
|
+
want it. **Check key** asks the service whether the key works before anything is stored. **Save**
|
|
427
|
+
checks it again, stores it as a GitHub secret and commits `org.yaml`.
|
|
428
|
+
|
|
429
|
+
Notion signs in instead, on the [hosted portal](hosting.md) only: **Sign in to Notion** goes to
|
|
430
|
+
Notion and comes back here.
|
|
431
|
+
|
|
432
|
+
## Routines
|
|
433
|
+
|
|
434
|
+
When each staff member wakes, and what they do then. Each has a **Daily round** with
|
|
435
|
+
**Change time**, then their routines. Each routine shows its name, when it runs, and the
|
|
436
|
+
start of what it says to do, with **Run now**, **Edit** and **Remove**.
|
|
437
|
+
|
|
438
|
+
**New routine** opens the editor: who, a name, when (days of the week, a day of the month, or a
|
|
439
|
+
cron), and what to do. A preview below says it as a sentence while you type. **Save** writes
|
|
440
|
+
`staff.yaml`, `routines/<id>.md` and the daily caller in one commit, as you. See
|
|
441
|
+
[routines](routines.md).
|
|
442
|
+
|
|
402
443
|
## Brain
|
|
403
444
|
|
|
404
445
|
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,42 @@ 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 can approve and merge, which the
|
|
174
|
+
person's own token could do on GitHub anyway; the merge tool is marked destructive, so a client
|
|
175
|
+
asks before calling it, and takes the person's words telling it to. They cannot hire or change
|
|
176
|
+
the org.
|
|
177
|
+
|
|
178
|
+
**The OAuth scopes.** `repo`, `notifications` and `workflow`. A GitHub App would be narrower,
|
|
179
|
+
but its tokens cannot read notifications, and unread in the portal is GitHub's own unread, kept
|
|
180
|
+
in step with the website and your phone. `workflow` is for [routines](routines.md): a routine's
|
|
181
|
+
time is a line in the daily caller under `.github/workflows/`, and GitHub refuses any change
|
|
182
|
+
there from a token without it. `gh` on your own machine already has it.
|
|
183
|
+
|
|
184
|
+
## Connectors
|
|
185
|
+
|
|
186
|
+
A [connector](connectors.md)'s key is a GitHub secret every brain repo can read, encrypted to
|
|
187
|
+
GitHub's key by the portal or the CLI before it leaves your machine. It reaches a run because the
|
|
188
|
+
callers pass their secrets on with `secrets: inherit`. Inside the run, one step reads them
|
|
189
|
+
(`connectors.mjs`) and writes only this staff member's connectors' keys into the agent's MCP
|
|
190
|
+
config, in the runner's temp directory. No other step, and no agent, sees the rest.
|
|
191
|
+
|
|
192
|
+
The agent can read that config, so treat a key as given to the staff members who have it, and
|
|
193
|
+
give it the least it needs: a read-only key is a limit no prompt can argue with.
|
|
194
|
+
|
|
195
|
+
A signed-in connector's refresh token stays on the hosted portal, sealed under its session key.
|
|
196
|
+
A run gets a short-lived access token, and only after proving with GitHub's OIDC token that it is
|
|
197
|
+
a job of this org's `session.yaml`; a token minted for any other audience, workflow or org is
|
|
198
|
+
refused.
|
|
166
199
|
|
|
167
200
|
## Trust in a prompt
|
|
168
201
|
|
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