@nanocollective/roster 0.1.0-alpha.5 → 0.1.0-alpha.51

package/docs/staff-yaml.md

@@ -22,13 +22,14 @@ brain: acme/technology
 status_issue: 15
 
 schedule: "0 7 * * 1-5"
-model: claude-opus-5
+model: claude-opus-5-5
 timeout_minutes: 90
 mention_timeout_minutes: 90
+max_runs_per_day: 6
 
 bot: acme-cto[bot]
 public_bot: acme-robot[bot]
-public_token_env: PIPWEB_TOKEN
+public_token_env: PUBLIC_TOKEN
 agent_secret: CLAUDE_CODE_OAUTH_TOKEN
 
 identities:
@@ -49,7 +50,7 @@ surfaces:
 
 labels:
   owner: [will, cto, cmo]
-  kind: [decision, setup, build, blocked]
+  kind: [decision, review, chore, keep-open, build, blocked]
 ```
 
 ## Identity
@@ -59,6 +60,7 @@ labels:
 | `handle` | yes | Must match `org.yaml`. The composer looks them up by the `org.yaml` one, so a mismatch composes the wrong brain. |
 | `name` | yes | Role name in prose. |
 | `mention` | yes | What wakes them, as in `@cto`. The caller's condition tests for this string. |
+| `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. |
 | `brain` | yes | `owner/name` of this repo. Without it nothing can check secrets, labels or runs. |
 | `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. |
 
@@ -70,6 +72,7 @@ labels:
 | `model` | org default | Model id. |
 | `timeout_minutes` | 90 | Ceiling on the daily session. |
 | `mention_timeout_minutes` | 90 | Ceiling on a mention run. |
+| `max_runs_per_day` | 6 | Runs a UTC day that start without a person asking: a peer's ask, or a follow-on to a daily run. Mentions never count. Rendered into the callers, so change it and run `roster upgrade`. |
 
 The three ceilings are separate on purpose. Raising the daily one because sessions have grown
 should not double the budget for a PR amendment. A job killed by a ceiling is reported by
@@ -154,6 +157,30 @@ Labels this staff member expects to exist on its own tracker, grouped for readab
 value across every group is checked by `roster doctor`. An agent applying a label that does not
 exist gets an API error mid-run.
 
+Four labels are roster's own and are checked on every tracker whatever this lists:
+
+| Label | Means |
+|---|---|
+| `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. |
+| `review` | An ask for the human to read or approve something. |
+| `chore` | Something only the human can do: a setting, an account, a key. |
+| `keep-open` | A standing thread. A sweep never closes it. `roster hire` puts it on the status issue. |
+
+Every ask on the human carries exactly one of the first three, which is how the portal sorts
+what needs them. Staff close any issue on their tracker once nothing is left to do on it,
+including the human's requests, with one line saying what closed it.
+
+## `memory`
+
+This staff member's own memory budgets, overriding the org's. Same three fields as
+[`memory` in org.yaml](org-yaml.md#memory); any left out fall back to the org, then to the
+defaults.
+
+```yaml
+memory:
+  max_index_kb: 32
+```
+
 ## What `roster upgrade` does to this file
 
 Nothing. It is `scaffold` class: written once by `roster hire`, and yours from that moment.

package/docs/troubleshooting.md

@@ -22,8 +22,10 @@ a coding agent, split into what an agent can fix and what only a person can. `ro
 
 **Is:** the ops repo's Actions access is not set to organisation-wide.
 
-Settings -> Actions -> General on `roster-ops`. The setup screen deep-links that exact page,
-which is the fastest way to fix it; Health and `roster doctor` both check it explicitly.
+`roster init --apply` sets it, and so does *Set it for me* on the setup screen. If GitHub
+refused (it needs admin on the ops repo), set it by hand: Settings -> Actions -> General ->
+Access on `roster-ops`, "accessible from repositories in the organisation". Health and `roster
+doctor` both check it explicitly.
 
 ---
 
@@ -90,11 +92,9 @@ constrains it is not a thing anybody wants.
 **Is:** you edited a framework-owned file. `compose.mjs`, `agents.mjs`, `runner-plan.mjs` and
 `session.yaml` are generated. The next `roster upgrade` reconciles them against the template.
 
-This happened here: a fix went into `roster-ops/.github/workflows/session.yaml` instead of
-`templates/ops/...`, and nothing noticed because the framework had not touched that file *yet*.
-
-`roster upgrade` now reports an edit to a framework-owned file whether or not anything has
-collided, and `roster upgrade --check` fails on it. Move the change upstream.
+Nothing notices until the framework next touches that file. `roster upgrade` reports an edit
+to a framework-owned file whether or not anything has collided, and `roster upgrade --check`
+fails on it. Move the change upstream.
 
 ---
 
@@ -181,7 +181,7 @@ landed on GitHub thirty seconds ago and the checkout is behind, that is what you
 
 ## `roster upgrade` says a file has no base
 
-A tenant created before the merge base was recorded has nothing to merge against. Reconstruct
+A tenant with no recorded merge base has nothing to merge against. Reconstruct
 one from the framework's history:
 
 ```bash

package/docs/upgrading.md

@@ -10,9 +10,9 @@ The framework writes templates out. A tenant runs its own copies. So the two dri
 `roster upgrade` is what reconciles them without eating your edits.
 
 ```bash
-roster upgrade                 # what would change
-roster upgrade --apply         # do it
-roster upgrade --check         # exit non-zero if anything is pending (for CI)
+npx @nanocollective/roster@latest upgrade           # what would change
+npx @nanocollective/roster@latest upgrade --apply   # do it
+npx @nanocollective/roster@latest upgrade --check   # exit non-zero if anything is pending (for CI)
 ```
 
 ## How it decides
@@ -53,6 +53,12 @@ The diff is printed either way, so nothing goes quietly.
 If you want a caller to differ, change the thing it is generated from. Timeouts, schedule,
 model and identities all live in `staff.yaml`.
 
+**A caller the framework no longer generates is removed.** It would still dispatch into
+`session.yaml` with a kind that no longer composes, and fail at run time. The plan lists it.
+The one that has gone so far is `<handle>-pr-mention.yaml`; if your tenant is old enough to
+have one, a forwarding workflow in the product repo went with it, and that one is yours to
+delete, because `roster upgrade` never writes into product repos.
+
 ## Conflicts
 
 A conflict is never written into a live file. Agents read `org/voice.md` at every boot, and

package/docs/writing-a-charter.md

@@ -28,6 +28,13 @@ layer. That is the part that matters most, because without them the model writes
 of whoever it was shown. The brief then interviews you, drafts from your answers, and tells you
 what it cut and why.
 
+**So is a worked example, when one fits.** A staff member whose handle or role reads as one of
+the ten roles below gets the matching [example](#worked-examples) inside the brief, labelled as a
+model for the shape and not content to copy. The copy-a-prompt panel has a picker to choose
+another or none; in a terminal it is `--example <handle>` or `--example none`. It is still a brief you
+answer: the interview comes first, and nothing in the charter should come from the example
+rather than from you.
+
 From a terminal, the same brief:
 
 ```bash
@@ -63,6 +70,27 @@ touches. Be specific. A vague boundary is one that gets crossed at 07:00 with no
 **Where the rest of it lives.** Point at `memory/INDEX.md`, `log/decisions.md`, the pinned
 status issue, and the surfaces the manifest declares.
 
+## Worked examples
+
+Ten, for an invented company called Acme. The handle in brackets is the one `--example` takes.
+
+| Example | What they do |
+|---|---|
+| [CTO](charters/cto.md) (`cto`) | Builds the product: fixes, features and tests, as pull requests. |
+| [CMO](charters/cmo.md) (`cmo`) | Posts, SEO, copy and launch plans, as drafts to approve. |
+| [Head of Support](charters/support.md) (`support`) | Answers issues, writes help docs, and turns user reports into bugs. |
+| [Product Manager](charters/pm.md) (`pm`) | Turns ideas and user feedback into clear specs and a ranked backlog. |
+| [Designer](charters/designer.md) (`designer`) | Improves the product's look and usability, with accessibility fixes, as pull requests. |
+| [QA Engineer](charters/qa.md) (`qa`) | Tests the product, finds bugs, and writes clear reproductions and tests. |
+| [DevOps Engineer](charters/devops.md) (`devops`) | Keeps CI, deploys and dependencies healthy, and patches security updates. |
+| [Technical Writer](charters/writer.md) (`writer`) | Writes and keeps up the docs, guides and changelog. |
+| [Data Analyst](charters/analyst.md) (`analyst`) | Reads the numbers and writes a short weekly report on what changed. |
+| [Community Manager](charters/community.md) (`community`) | Answers discussions, welcomes contributors, and drafts release announcements. |
+
+They are examples to adapt, not templates to fill in. Read them for what a finished charter covers and how specific it gets, then write your own
+about your business. A charter copied from one of these describes Acme. The brief carries the matching one for
+you; these links are for reading them first.
+
 ## Things worth being concrete about
 
 - **Escalation.** Name the label and the mechanism, not the sentiment. "Open an issue labelled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanocollective/roster",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.51",
   "description": "An agent-run org, powered by GitHub. Scaffold AI staff members whose brain is a repo.",
   "type": "module",
   "bin": {
@@ -16,23 +16,6 @@
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "build": "tsup src/cli.ts --format esm --target node20 --clean",
-    "dev": "tsx src/cli.ts",
-    "test": "tsx --test test/*.test.ts",
-    "test:all": "pnpm test:format && pnpm test:lint && pnpm test:types && pnpm test:knip && pnpm test",
-    "test:ava:coverage": "c8 --reporter=text --reporter=json-summary tsx --test test/*.test.ts",
-    "test:format": "biome check --no-errors-on-unmatched .",
-    "test:lint": "biome lint .",
-    "test:lint:fix": "biome check --write .",
-    "test:types": "tsc --noEmit",
-    "test:knip": "knip",
-    "test:audit": "pnpm audit --audit-level=high",
-    "test:security": "semgrep scan --config auto --error",
-    "typecheck": "tsc --noEmit",
-    "format": "biome check --write .",
-    "prepublishOnly": "pnpm test:all && pnpm build"
-  },
   "devDependencies": {
     "@biomejs/biome": "^2.5.12",
     "@types/node": "^22.10.2",
@@ -52,9 +35,24 @@
     "url": "https://github.com/Nano-Collective/roster/issues"
   },
   "author": "Nano Collective",
-  "packageManager": "pnpm@11.0.9",
   "publishConfig": {
     "access": "public",
     "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --target node20 --clean",
+    "dev": "tsx src/cli.ts",
+    "test": "tsx --test test/*.test.ts",
+    "test:all": "pnpm test:format && pnpm test:lint && pnpm test:types && pnpm test:knip && pnpm test",
+    "test:ava:coverage": "c8 --reporter=text --reporter=json-summary tsx --test test/*.test.ts",
+    "test:format": "biome check --no-errors-on-unmatched .",
+    "test:lint": "biome lint .",
+    "test:lint:fix": "biome check --write .",
+    "test:types": "tsc --noEmit",
+    "test:knip": "knip",
+    "test:audit": "pnpm audit --audit-level=high",
+    "test:security": "semgrep scan --config auto --error",
+    "typecheck": "tsc --noEmit",
+    "format": "biome check --write ."
   }
-}
+}

package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml

@@ -6,22 +6,47 @@ name: %%STAFF_UPPER%% daily run
 #
 # NOTE: %%TOKENS%% are filled by `roster hire`; GitHub's own ${{ }} are left alone.
 
+# The trigger and the date, as the Actions list shows it. The daily limit counts follow-on runs
+# by this name.
+run-name: "%%STAFF%% ${{ github.event_name == 'schedule' && 'daily' || inputs.trigger || 'manual' }}"
+
 on:
   schedule:
     - cron: "%%SCHEDULE%%"
+  # By hand, from Run once now, or as a follow-on: a daily run that ended with the next step
+  # ready starts one more, up to max_runs_per_day.
   workflow_dispatch:
+    inputs:
+      trigger:
+        description: "manual | follow-on"
+        required: false
+        default: manual
+        type: string
 
-# A second run while one is in flight would fight it over the tracker and the branch state.
+# A second run while one is in flight would fight it over the tracker and the branch state. A
+# follow-on is started from inside the run before it, so it waits here until that one ends.
 concurrency:
   group: %%STAFF%%-session
   cancel-in-progress: false
 
 jobs:
   session:
+    # The ceiling on what session.yaml's job token may do: reading the checkout, and the one
+    # comment that says a run failed when the App that would normally say so is what broke.
+    # A called workflow cannot raise these, so they have to be granted here.
+    #
+    # `actions` is for the daily limit, which reads this repo's runs, and for starting a
+    # follow-on run, which the job token may do: a workflow_dispatch it sends still starts a run.
+    permissions:
+      contents: read
+      issues: write
+      actions: write
     uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
     with:
       staff: %%STAFF%%
       kind: daily
+      trigger: ${{ github.event_name == 'schedule' && 'daily' || inputs.trigger || 'manual' }}
+      max_runs_per_day: %%MAX_RUNS%%
       ops_repo: %%OPS_REPO%%
       model: %%MODEL%%
       timeout_minutes: %%TIMEOUT%%

package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml

@@ -3,11 +3,28 @@ name: %%STAFF_UPPER%% on a mention
 # Generated by roster. The body lives in %%OPS_REPO%%/.github/workflows/session.yaml.
 #
 # "%%MENTION%% ..." in a comment on this tracker, or in the body of a new issue, wakes a focused
-# run in about 30 seconds. It is a task, not a session: no boot ritual, no handoff, and the reply
+# run in about 30 seconds. So does another staff member filing an issue here with their
+# `from-<handle>` label. It is a task, not a session: no boot ritual, no handoff, and the reply
 # goes in the thread.
 #
 # NOTE: %%TOKENS%% are filled by `roster hire`. GitHub's own ${{ }} expressions are left alone.
 
+# What the run is and what started it, as the Actions list shows it. The portal reads this back
+# to link a live run to the request behind it, and the daily limit counts peer runs by it.
+# Most events here are nobody asking (a comment without the mention, this staff member's own
+# reply), and those are named `ignored`, so nothing reads one as work while it waits to be
+# skipped.
+run-name: >-
+  %%STAFF%% ${{
+    (contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.sender.login) &&
+      (contains(github.event.comment.body, '%%MENTION%%') ||
+       (github.event_name == 'issues' && contains(github.event.issue.body, '%%MENTION%%'))))
+    && 'mention'
+    || ((github.event_name == 'issues' && github.event.action == 'opened' &&
+         endsWith(github.event.sender.login, '[bot]') &&
+         github.event.sender.login != '%%APP%%[bot]') && 'peer' || 'ignored')
+  }} #${{ github.event.issue.number }}
+
 on:
   # A mention in the body of a brand new issue, which is often the faster route: one box, rather
   # than a "create, then comment" round trip. `edited` doubles as the way to re-ask without
@@ -22,12 +39,6 @@ on:
   issue_comment:
     types: [created, edited]
 
-# Per issue, not global. Several comments in a row are the normal case and a shared group would
-# silently drop all but one of them.
-concurrency:
-  group: %%STAFF%%-mention-${{ github.event.issue.number }}
-  cancel-in-progress: false
-
 jobs:
   answer:
     # Only a human this org answers to, only on a real mention. A bot quoting the phrase must
@@ -44,19 +55,54 @@ jobs:
     #
     # One spelling of the mention is enough: GitHub's `contains` is documented as not case
     # sensitive, so this already matches an uppercase mention at the start of a sentence.
+    #
+    # The second route is a peer's ask: a new issue opened by an App, never this staff member's
+    # own, carrying a `from-<handle>` label. Only `opened`, so the peer editing its own issue
+    # later wakes nobody. It names no peer, so a later hire needs no regenerated caller: the only
+    # accounts that can open an issue on a private tracker are the people and Apps it is
+    # installed for. A peer run may not file on another peer, and session.yaml holds peer runs
+    # to the day's limit, so two staff cannot wake each other forever.
+    # Per issue, not global: several comments in a row are the normal case, and a shared group
+    # would silently drop all but one of them. On the job rather than the workflow, so the
+    # condition below is decided first. At workflow level every event queued here, including
+    # this staff member's own replies, and GitHub keeps one waiting run per group, so a reply
+    # waiting to be skipped could knock out a real mention waiting behind a run.
+    concurrency:
+      group: %%STAFF%%-mention-${{ github.event.issue.number }}
+      cancel-in-progress: false
     if: >-
-      contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.sender.login) &&
       (
-        (github.event_name == 'issue_comment' &&
-         contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.comment.user.login) &&
-         contains(github.event.comment.body, '%%MENTION%%')) ||
-        (github.event_name == 'issues' &&
-         contains(github.event.issue.body, '%%MENTION%%'))
+        contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.sender.login) &&
+        (
+          (github.event_name == 'issue_comment' &&
+           contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.comment.user.login) &&
+           contains(github.event.comment.body, '%%MENTION%%')) ||
+          (github.event_name == 'issues' &&
+           contains(github.event.issue.body, '%%MENTION%%'))
+        )
+      ) || (
+        github.event_name == 'issues' && github.event.action == 'opened' &&
+        endsWith(github.event.sender.login, '[bot]') &&
+        github.event.sender.login != '%%APP%%[bot]' &&
+        contains(join(github.event.issue.labels.*.name, ','), 'from-')
       )
+    # The ceiling on what session.yaml's job token may do: reading the checkout, and the one
+    # comment that says a run failed when the App that would normally say so is what broke.
+    # A called workflow cannot raise these, so they have to be granted here.
+    #
+    # `actions` is for the daily limit, which counts this repo's runs today. It is `write`
+    # because session.yaml's job asks for that (a daily run starts its follow-on with it), and a
+    # called job asking for more than its caller granted fails before it starts.
+    permissions:
+      contents: read
+      issues: write
+      actions: write
     uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
     with:
       staff: %%STAFF%%
       kind: mention
+      trigger: ${{ contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.sender.login) && 'mention' || 'peer' }}
+      max_runs_per_day: %%MAX_RUNS%%
       ops_repo: %%OPS_REPO%%
       model: %%MODEL%%
       timeout_minutes: %%MENTION_TIMEOUT%%

package/templates/brain/CHARTER.md

@@ -11,10 +11,10 @@ between %%MENTION%% and everyone else.
 Write it before the first unattended run. A generated charter would produce a generic agent,
 which is the failure this whole arrangement exists to avoid.
 
-Write it with your own AI:
+Write it with your own AI. This prints a brief to paste into whichever agent you use (in
+Claude Code it is also /charter, from inside this repo):
 
-    cd %%DIR%% && claude
-    /charter
+    roster brief charter %%STAFF%%
 
 Or write it by hand. The headings below are the shape that has worked; the words are yours.
 

package/templates/brain/README.md

@@ -10,6 +10,7 @@ on, and has decided.
 | `memory/INDEX.md` | One line per fact, read at every boot. |
 | `memory/notes/` | The argument behind a fact, read on demand. |
 | `log/decisions.md` | Why things were decided. Not boot context. |
+| `strategy/` | Longer role documents, and `ideas.md`: ideas parked here rather than filed as issues. |
 | `.github/workflows/` | Three callers. The body lives in `%%OPS_REPO%%`. |
 
 Scheduled runs and mentions are wired up by roster. To see what this staff member is actually

package/templates/brain/log/decisions.md

@@ -4,3 +4,6 @@ Why things were decided, newest first. Not boot context: this is read when a dec
 being revisited, not every morning.
 
 One entry per decision. What was decided, why, and what would change it back.
+
+This file holds the current month. Move anything older into `log/decisions/<YYYY-MM>.md`:
+`roster lint` warns past 24KB.

package/templates/brain/staff.yaml

@@ -13,6 +13,9 @@ schedule: "%%SCHEDULE%%"
 model: %%MODEL%%
 timeout_minutes: %%TIMEOUT%%
 mention_timeout_minutes: %%MENTION_TIMEOUT%%
+# Runs a day that start without a person asking: a peer's ask, or a follow-on to a daily run.
+# Mentions never count against it.
+max_runs_per_day: %%MAX_RUNS%%
 
 bot: %%APP%%[bot]
 public_bot: %%PUBLIC_APP%%[bot]
@@ -40,4 +43,4 @@ surfaces:
 
 labels:
   owner: [%%HUMAN_MARKER%%, %%STAFF%%]
-  kind: [decision, setup, build, blocked]
+  kind: [decision, review, chore, keep-open, build, blocked]

package/templates/brain/strategy/ideas.md

@@ -0,0 +1,7 @@
+# Ideas
+
+Speculative ideas, one line each, parked here rather than filed as issues. An issue is for
+something that needs a ruling; an idea that does not yet is noise on the tracker.
+
+Promote one to an issue when it serves a priority in `org/priorities.md` and needs a ruling.
+Delete one when it stops being interesting.

package/templates/briefs/amend.md

@@ -44,7 +44,8 @@ If what is wanted needs one of these, say so and stop. Do not work around it.
 
 1. **Say which file, and why that one.** Prefer the narrowest file that achieves it. If the
    change is about %%NAME%% specifically, it does not belong in `org/`.
-2. **Show a diff, not a rewritten file.** %%HUMAN%% has to be able to see exactly what moved.
+2. **Hand back the whole file you changed**, in the block described at the end. The tool
+   %%HUMAN%% pastes your answer into shows them the diff, so they see exactly what moved.
 3. **Do not restate.** Every layer is already in the composed text below. A rule added to
    `org/voice.md` that `org/operating.md` already states makes the prompt longer and no
    clearer.
@@ -56,5 +57,5 @@ If what is wanted needs one of these, say so and stop. Do not work around it.
 
 ## Then
 
-Give %%HUMAN%% the diff, the one-line reason for the file you chose, and what you cut. They
-apply it: in the portal's Prompt screen, or by editing the file and committing it.
+Outside the block: the one-line reason for the file you chose, and what you cut. Inside it:
+the whole changed file. Nothing is saved until %%HUMAN%% has seen the diff and pressed Save.

package/templates/briefs/priorities.md

@@ -0,0 +1,46 @@
+Write `org/priorities.md` for %%ORG_NAME%%.
+
+You are helping %%HUMAN%% decide what their AI staff should work on this month. Every staff
+member reads this file at the start of every run and picks work that serves it, so a vague
+priority produces scattered work.
+
+## Where you are
+
+- `%%OPS_REPO_DIR%%/org/business.md`: what the business is. **Read it first**, and don't ask
+  anything it already answers.
+- `%%OPS_REPO_DIR%%/org/priorities.md`: the current file, which you are replacing.
+
+If you cannot read files where you are running, ask %%HUMAN%% to paste `org/business.md`.
+
+## Interview
+
+Ask one question at a time. You are after:
+
+- **The one outcome that matters most this month**, and how they will know it happened.
+- **At most two more**, in order. Push back on a fourth: past three it is a wish list.
+- **What is out of scope this month**: work that is tempting but not now. Naming it is what
+  stops the staff doing it.
+
+Prefer outcomes ("a stranger pays for it") to activities ("improve the landing page"). If an
+answer is an activity, ask what it is for.
+
+## Write it
+
+Use exactly this shape:
+
+```
+## What matters this month
+
+### Priorities, in order
+
+1. The first outcome, and how you will know it happened.
+2. The second.
+3. The third.
+
+### Out of scope this month
+
+- One thing per line.
+```
+
+Keep each priority to a sentence or two. Don't add anything %%HUMAN%% didn't say without
+listing it after the file so they can check it.