@nanocollective/roster 0.1.0-alpha.1

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

@@ -0,0 +1,33 @@
+name: %%STAFF_UPPER%% daily run
+
+# Generated by roster. The body lives in %%OPS_REPO%%/.github/workflows/session.yaml.
+# Edit this file only to change the schedule; everything else belongs in the ops repo, where
+# one change reaches every staff member.
+#
+# NOTE: %%TOKENS%% are filled by `roster hire`; GitHub's own ${{ }} are left alone.
+
+on:
+  schedule:
+    - cron: "%%SCHEDULE%%"
+  workflow_dispatch:
+
+# A second run while one is in flight would fight it over the tracker and the branch state.
+concurrency:
+  group: %%STAFF%%-session
+  cancel-in-progress: false
+
+jobs:
+  session:
+    uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
+    with:
+      staff: %%STAFF%%
+      kind: daily
+      ops_repo: %%OPS_REPO%%
+      model: %%MODEL%%
+      timeout_minutes: %%TIMEOUT%%
+    secrets:
+      APP_ID: ${{ secrets.%%SECRET_PREFIX%%_APP_ID }}
+      APP_PRIVATE_KEY: ${{ secrets.%%SECRET_PREFIX%%_APP_PRIVATE_KEY }}
+      PUBLIC_APP_ID: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_ID }}
+      PUBLIC_APP_PRIVATE_KEY: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_PRIVATE_KEY }}
+      AGENT_TOKEN: ${{ secrets.%%AGENT_SECRET%% }}

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

@@ -0,0 +1,65 @@
+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
+# goes in the thread.
+#
+# NOTE: %%TOKENS%% are filled by `roster hire`. GitHub's own ${{ }} expressions are left alone.
+
+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
+  # opening a second issue.
+  issues:
+    types: [opened, edited]
+
+  # `edited` is the re-run handle. A re-run from the Actions tab is pinned to the workflow file as
+  # it was when the run started, so it can never pick up a fix, and deleting and reposting a
+  # comment loses its attachments. Editing fires a fresh event against the default branch's
+  # current file with the comment and its uploads intact.
+  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 the human, only on a real mention. A bot quoting the phrase must never wake the loop.
+    #
+    # The outer gate is on `sender` — the account that performed the action — and not on the author
+    # of the thing it acted on. That distinction is load-bearing on the `issues` route: the pinned
+    # status issue is opened by the human and then edited by this staff member on every run, so an
+    # author check would let the agent's own edit wake another run, which would edit it again.
+    #
+    # 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.
+    if: >-
+      github.event.sender.login == '%%HUMAN%%' &&
+      (
+        (github.event_name == 'issue_comment' &&
+         github.event.comment.user.login == '%%HUMAN%%' &&
+         contains(github.event.comment.body, '%%MENTION%%')) ||
+        (github.event_name == 'issues' &&
+         contains(github.event.issue.body, '%%MENTION%%'))
+      )
+    uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
+    with:
+      staff: %%STAFF%%
+      kind: mention
+      ops_repo: %%OPS_REPO%%
+      model: %%MODEL%%
+      timeout_minutes: %%MENTION_TIMEOUT%%
+      issue_number: ${{ github.event.issue.number }}
+      comment_id: ${{ github.event.comment.id }}
+    secrets:
+      APP_ID: ${{ secrets.%%SECRET_PREFIX%%_APP_ID }}
+      APP_PRIVATE_KEY: ${{ secrets.%%SECRET_PREFIX%%_APP_PRIVATE_KEY }}
+      PUBLIC_APP_ID: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_ID }}
+      PUBLIC_APP_PRIVATE_KEY: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_PRIVATE_KEY }}
+      AGENT_TOKEN: ${{ secrets.%%AGENT_SECRET%% }}

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

@@ -0,0 +1,50 @@
+name: %%STAFF_UPPER%% on a product PR
+
+# Generated by roster. The body lives in %%OPS_REPO%%/.github/workflows/session.yaml.
+#
+# Amends an open PR on the product repo in response to a review comment, so the human can ask for
+# changes where they are already reading the diff instead of opening a ticket and cross-referencing.
+#
+# Not triggered directly. A forwarder in the PUBLIC product repo catches the mention and dispatches
+# here. The split exists because that repo is public: its Actions logs are world readable, so the
+# run that prints a charter and a chain of reasoning has to happen in a repo only we can see.
+#
+# NOTE: %%TOKENS%% are filled by `roster hire`. GitHub's own ${{ }} expressions are left alone.
+
+on:
+  repository_dispatch:
+    types: [pr-mention]
+
+  # Manual handle, for testing without leaving a comment on a public PR, and for re-running a
+  # request the dispatcher already consumed.
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: "PR number on the product repo"
+        required: true
+      comment_id:
+        description: "id of the comment that triggered this"
+        required: true
+
+# Per PR. Several review comments in a row are the normal case; different PRs never contend.
+concurrency:
+  group: %%STAFF%%-pr-${{ github.event.inputs.pr || github.event.client_payload.pr }}
+  cancel-in-progress: false
+
+jobs:
+  amend:
+    uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
+    with:
+      staff: %%STAFF%%
+      kind: pr-mention
+      ops_repo: %%OPS_REPO%%
+      model: %%MODEL%%
+      timeout_minutes: %%PR_MENTION_TIMEOUT%%
+      pr_number: ${{ github.event.inputs.pr || github.event.client_payload.pr }}
+      comment_id: ${{ github.event.inputs.comment_id || github.event.client_payload.comment_id }}
+    secrets:
+      APP_ID: ${{ secrets.%%SECRET_PREFIX%%_APP_ID }}
+      APP_PRIVATE_KEY: ${{ secrets.%%SECRET_PREFIX%%_APP_PRIVATE_KEY }}
+      PUBLIC_APP_ID: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_ID }}
+      PUBLIC_APP_PRIVATE_KEY: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_PRIVATE_KEY }}
+      AGENT_TOKEN: ${{ secrets.%%AGENT_SECRET%% }}

package/templates/brain/CHARTER.md

@@ -0,0 +1,49 @@
+# Charter — %%ORG_NAME%%'s %%NAME%%
+
+**This file is a stub, and it is the most important file in this repo.**
+
+The charter is the personality. It decides what this staff member does when nobody is
+watching, what it refuses, and what it escalates. Nothing else supplies it: the shared half —
+how anyone here operates, how we write, the guardrails everyone is bound by — already lives in
+`%%OPS_REPO%%/org/` and is composed into every prompt. This file is only the difference
+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:
+
+    cd %%DIR%% && claude
+    /charter
+
+Or write it by hand. The headings below are the shape that has worked; the words are yours.
+
+---
+
+## Who I am
+
+One paragraph. What this role is for, in this business specifically.
+
+## The mission (north star)
+
+The single thing this staff member is optimising. If a decision does not serve it, it is
+somebody else's decision.
+
+## How I work, that others here do not
+
+The habits particular to this role. Not the shared operating contract — that is in
+`org/operating.md` and is inherited.
+
+## Decision rights
+
+What this staff member decides alone, what it proposes and waits on, and what it never
+touches. Be specific: a vague boundary is one that gets crossed at 07:00 on a Tuesday.
+
+## Guardrails on top of the org's
+
+Only the additions. `org/guardrails.md` is already binding on everyone.
+
+## Where the rest of it lives
+
+Point at `memory/INDEX.md`, `log/decisions.md`, the pinned status issue, and whatever
+surfaces this role declares in `staff.yaml`.

package/templates/brain/README.md

@@ -0,0 +1,18 @@
+# %%NAME%%
+
+%%MENTION%%'s brain. This repo *is* the memory: everything this staff member knows, is working
+on, and has decided.
+
+| Where | What |
+|---|---|
+| `CHARTER.md` | The personality. Hand-written. Decides everything else. |
+| `staff.yaml` | The machine-readable half of the charter. |
+| `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. |
+| `.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
+sent at 07:00:
+
+    roster prompt %%STAFF%% --kind daily

package/templates/brain/drafts/README.md

@@ -0,0 +1,7 @@
+# Drafts
+
+Work in progress, and specs for things not built yet. A draft is allowed to be long, unsure,
+and wrong — that is what separates it from memory.
+
+When a draft settles into something true, cut the one-line version into `memory/INDEX.md` and
+leave the reasoning here.

package/templates/brain/log/decisions.md

@@ -0,0 +1,6 @@
+# Decisions
+
+Why things were decided, newest first. Not boot context: this is read when a decision is
+being revisited, not every morning.
+
+One entry per decision. What was decided, why, and what would change it back.

package/templates/brain/memory/INDEX.md

@@ -0,0 +1,28 @@
+# Memory index
+
+**This is %%NAME%%'s memory. Read it at every boot, in full. It is the only file that is.**
+
+One line per fact. The line is the fact; `So:` is what it changes. A few carry a note in
+`notes/` where the argument is load-bearing and worth not re-deriving. Read a note only when
+the fact is in play today.
+
+**The five rules that keep this file usable:**
+
+1. **One line per fact.** If it needs more, the extra goes in `notes/<slug>.md` and the line stays one line.
+2. **Correct in place. Never append "updated:".** An update chain is how one fact became six paragraphs.
+3. **Every fact says what it changes.** If you cannot write the `So:`, it is not memory. Do not add it.
+4. **Measurements carry `n` and a date. Constraints do not expire; measurements do.** Anything with a `review:` date is re-read or deleted on that date.
+5. **Deleting is the maintenance.** Cut every line that no longer changes a decision, and log the cut in `log/decisions.md`. A memory that only grows is a memory nobody reads.
+
+The grammar, which `roster lint` enforces:
+
+    - **`<slug>`** · [<%%HUMAN_MARKER%%|measured|derived>] <the fact, one line>. **So:** <what it changes>. · [note](notes/<slug>.md)
+
+`log/decisions.md` = why things were decided. The pinned status issue = what is outstanding.
+**Nothing is copied between them.**
+
+---
+
+## Ungrouped
+
+*No facts yet. The first session adds them. An empty memory is honest; an invented one is not.*

package/templates/brain/staff.yaml

@@ -0,0 +1,44 @@
+# %%NAME%%'s manifest. The machine-readable half of CHARTER.md.
+# `roster lint` fails if this and the charter disagree.
+#
+# NOTE: %%TOKENS%% are filled by `roster hire`.
+
+handle: %%STAFF%%
+name: %%NAME%%
+mention: "%%MENTION%%"
+brain: %%BRAIN%%
+status_issue: %%STATUS_ISSUE%%
+
+schedule: "%%SCHEDULE%%"
+model: %%MODEL%%
+timeout_minutes: %%TIMEOUT%%
+mention_timeout_minutes: %%MENTION_TIMEOUT%%
+pr_mention_timeout_minutes: %%PR_MENTION_TIMEOUT%%
+
+bot: %%APP%%[bot]
+public_bot: %%PUBLIC_APP%%[bot]
+public_token_env: %%PUBLIC_TOKEN_ENV%%
+# The repo secret holding this staff member's coding-agent credential.
+agent_secret: %%AGENT_SECRET%%
+
+identities:
+  - { app: %%APP%%, secret_prefix: %%SECRET_PREFIX%%, scope: private }
+  - { app: %%PUBLIC_APP%%, secret_prefix: %%PUBLIC_SECRET_PREFIX%%, scope: public }
+
+# Repos this staff member contributes to but does not own.
+works_in:%%WORKS_IN%%
+
+# Written by `roster hire`, both ways: every existing staff member gains an entry for this
+# one, and this one gains an entry for each of them.
+peers: []
+
+# What the portal renders, and what this staff member is expected to keep.
+surfaces:
+  - { path: memory/, render: memory }
+  - { path: strategy/, render: doc }
+  - { path: drafts/, render: doc }
+  - { path: log/, render: doc }
+
+labels:
+  owner: [%%HUMAN_MARKER%%, %%STAFF%%]
+  kind: [decision, setup, build, blocked]

package/templates/brain/strategy/README.md

@@ -0,0 +1,7 @@
+# Strategy
+
+The detail behind a fact. When `memory/INDEX.md` says *what* is true in one line, the working
+that got there lives here.
+
+Not boot context: a strategy document is read when its subject is in play, not every morning.
+If something in here changes a decision, the one-line version belongs in memory with a `So:`.

package/templates/briefs/amend.md

@@ -0,0 +1,60 @@
+Change what %%NAME%% is told to do.
+
+You are helping %%HUMAN%% amend the prompt that %%NAME%% (%%MENTION%%) at %%ORG_NAME%% runs on.
+Everything you need is in this message: the prompt as it is composed today, and every file it
+is assembled from. You do not need to ask for any of it.
+
+## What is wanted
+
+%%WANT%%
+
+## How this prompt is assembled
+
+The text an agent receives is composed at run time from several files across two repositories.
+No single file is the prompt. A `{{> path}}` line pulls another file in where it stands, so
+the composed text is the whole tree flattened, in order.
+
+The consequence that matters: **the same change can be made in more than one place, and the
+places have different blast radius.** A rule in `%%OPS_REPO_DIR%%/org/voice.md` reaches every
+staff member on their next run. The same rule in `%%DIR%%/prompts/work.md` reaches only
+%%NAME%%. Choosing wrong is how one person's preference becomes everyone's problem.
+
+## What you may change
+
+| File | Reaches |
+|---|---|
+| `%%OPS_REPO_DIR%%/org/*.md` | every staff member, next run |
+| `%%OPS_REPO_DIR%%/prompts/*.md` | every staff member, next run |
+| `%%DIR%%/CHARTER.md` | %%NAME%% only |
+| `%%DIR%%/prompts/*.md` | %%NAME%% only |
+
+## What you may not change
+
+- `staff.yaml` and `org.yaml` — the machine-readable half. Wrong values here stop the prompt
+  composing at all, and `roster lint` and `roster doctor` are what change them safely.
+- `.github/workflows/` anywhere — the agents cannot push these and neither should you.
+- `memory/INDEX.md` — the agent's own working memory. It rewrites that file itself every run,
+  so a hand edit is writing over something about to be replaced.
+- `compose.mjs`, `agents.mjs`, `session.yaml` — framework files, vendored into the tenant.
+  Fixing one here is lost on the next `roster upgrade`.
+
+If what is wanted needs one of these, say so and stop. Do not work around it.
+
+## How to make the change
+
+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.
+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.
+4. **Cut before you add.** This text is read in full on every run forever. If you are adding a
+   paragraph, find one to remove.
+5. **Check the composed result.** Say what the composed prompt will read like after the change,
+   and name anything it now contradicts.
+6. `org/voice.md` binds these files too. Write in that voice.
+
+## 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.

package/templates/briefs/charter.md

@@ -0,0 +1,47 @@
+Write or revise `CHARTER.md` for %%NAME%%.
+
+You are helping %%HUMAN%% author the charter for %%NAME%% (%%MENTION%%) at %%ORG_NAME%%. This
+is the file that decides everything else about how this staff member behaves.
+
+## Where you are
+
+The workspace holds the ops repo and every brain repo side by side. You are writing
+`%%DIR%%/CHARTER.md`.
+
+If you cannot read files where you are running, ask %%HUMAN%% to paste the files below.
+
+## Read first, in this order
+
+1. `../%%OPS_REPO_DIR%%/org/business.md` — what this business actually is.
+2. `../%%OPS_REPO_DIR%%/org/operating.md`, `org/voice.md`, `org/guardrails.md` — the shared
+   half every staff member already inherits. **Do not restate any of it.** The charter is only
+   the difference between this role and the others.
+3. Every peer's `CHARTER.md`, for consistency of register and to find the seams between roles.
+4. This repo's `staff.yaml` — the machine-readable half. The charter must not contradict it.
+
+## Then interview
+
+Ask about the role's purpose, the decisions it owns outright, the ones it must escalate, and
+what it should refuse. Ask one question at a time and follow the answers; do not present a
+form.
+
+The questions that actually matter:
+
+- **What is this role for?** One sentence. If it needs three, the role is two roles.
+- **What does it decide alone?** Be concrete: it will be acting at 07:00 with nobody awake.
+- **What must it escalate?** And what should it do while it waits, since a run that stops to
+  ask has wasted its slot.
+- **What should it refuse**, even when asked directly?
+- **Where does it end and a peer begin?** Seams are where two agents do the same work twice.
+
+## Then write it
+
+Draft `CHARTER.md` from what they tell you. Then check it yourself:
+
+- Does anything here duplicate `org/`? Cut it.
+- Are the decision rights specific enough to act on at 07:00 with nobody awake?
+- Does it contradict `staff.yaml`? `roster lint` will fail if so.
+- Does it read in the house voice? `org/voice.md` binds this file too.
+
+Show %%HUMAN%% the draft and the list of what you cut and why. The charter is theirs, not
+yours — do not commit it without them reading it.

package/templates/briefs/discover.md

@@ -0,0 +1,61 @@
+Write `org/business.md` for %%ORG_NAME%%.
+
+You are helping %%HUMAN%% describe their business to the AI staff who will work on it. What you
+write is composed into the top of every prompt every one of them ever runs. It is the single
+file standing between agents that know this company and agents that produce generic slop.
+
+## Where you are
+
+The workspace holds the ops repo and every brain repo side by side:
+
+- `%%OPS_REPO_DIR%%/` — the org layer. You are writing `%%OPS_REPO_DIR%%/org/business.md`.
+- `%%OPS_REPO_DIR%%/org/operating.md`, `org/voice.md`, `org/guardrails.md` — the shared half
+  every staff member already inherits. **Read them.** Do not restate any of it.
+
+If you cannot read files where you are running, ask %%HUMAN%% to paste the current
+`org/business.md` stub and anything else you need.
+
+## Read before you ask anything
+
+Whatever exists already: the product's README, the site, the docs, recent commits, open
+issues. Come to the interview knowing what you could have found out for yourself. A question
+whose answer is in the README wastes the one thing this file is spending, which is %%HUMAN%%'s
+attention.
+
+## Then interview
+
+Ask one question at a time and follow the answers. Do not present a form. You are after:
+
+- **What the business does**, in one line, in %%HUMAN%%'s own words rather than marketing copy.
+- **Who the customers are**, and which of them matter most right now.
+- **The one fact everything follows from.** Every business has one. It is usually the thing
+  they would say if you asked what is really going on. Push for it.
+- **What is true today** that an agent would otherwise assume wrongly: what is built, what is
+  not, what shipped and disappointed, what is deliberately parked.
+- **The numbers that matter**, and how to read them. An agent that cannot tell a good week
+  from a bad one will report both the same way.
+- **What is off the table**, and why. Constraints are as load-bearing as goals.
+
+## Then write it
+
+Write `org/business.md`. It is prose, not a form. Aim for something a new colleague could read
+in three minutes and then be useful.
+
+- **The first paragraph is the one fact everything follows from.** If they read only that, they
+  should know what to optimise for.
+- **Be specific and dated.** "About 10 arrivals a day (31 Jul to 30 Aug)" beats "low traffic".
+  A number without a date rots silently.
+- **Say what is not true.** The things an agent would otherwise assume are the expensive
+  mistakes.
+- **No aspiration.** This file is what is, not what is hoped for. Strategy belongs in a brain.
+- `org/voice.md` binds this file too. Read it and write in that voice.
+
+## Then check it
+
+- Would an agent reading only this write something a customer of %%ORG_NAME%% would recognise?
+- Does anything here duplicate `org/operating.md`, `org/voice.md` or `org/guardrails.md`? Cut it.
+- Is every number dated?
+- Is there anything you asserted that %%HUMAN%% did not actually say?
+
+Show them the draft and what you cut. **This file is theirs, not yours.** Do not commit it
+without them reading it.

package/templates/briefs/voice.md

@@ -0,0 +1,53 @@
+Revise `org/voice.md` for %%ORG_NAME%%.
+
+You are helping %%HUMAN%% set the house voice every AI staff member writes in. It binds every
+surface they produce: issues, comments, PR bodies, run reports, briefs to each other, and how
+they talk in a session. Changing this file once changes all of them on their next run.
+
+## Where you are
+
+You are editing `%%OPS_REPO_DIR%%/org/voice.md`. It already exists and is already opinionated:
+roster ships a version that argues for concision over word counts. **Start from what is there.**
+This is a revision, not a blank page.
+
+If you cannot read files where you are running, ask %%HUMAN%% to paste the current
+`org/voice.md`.
+
+## Read first
+
+1. `%%OPS_REPO_DIR%%/org/voice.md` — what is in force today.
+2. `%%OPS_REPO_DIR%%/org/business.md` — who is being written for.
+3. A dozen real issues and comments the staff have actually written. **This is the important
+   one.** A voice rule that does not name a habit you can point at in the output is decoration.
+
+## Then interview
+
+Ask one question at a time. What you are after is friction, not preferences:
+
+- **What did you last read from them and wish were shorter?** Find the specific thing.
+- **What do they do that you have to correct every time?**
+- **What register is wrong?** Too formal, too chatty, too hedged, too certain.
+- **What must never appear?** Sign-offs, apologies, recaps, options menus, emoji.
+- **How do you want to be addressed?** They are writing to %%HUMAN%% far more than to anyone
+  else.
+
+## Then write it
+
+- **Every rule names a behaviour, not a virtue.** "The first sentence is the point" is
+  actionable. "Be clear" is not.
+- **Cut on sight lists work.** A list of things to delete is easier to obey than a list of
+  things to aspire to.
+- **No word counts.** They are the obvious rule and the wrong one: they produce padded short
+  writing rather than concise writing. Say what to cut instead.
+- **Keep it short.** This file is read in full on every run by every staff member. Every line
+  you add is paid for on every run forever.
+
+## Then check it
+
+- Could you point at a real issue and say which rule it breaks?
+- Does it contradict `org/operating.md` or a `CHARTER.md`?
+- Is anything here already covered by `org/guardrails.md`? Guardrails are non-negotiables;
+  voice is style. Do not blur them.
+- Has it got longer? If so, what came out?
+
+Show %%HUMAN%% the diff and what you cut. Do not commit it without them reading it.