agents: add declarative agent definitions #2

Merged

ellen merged 9 commits from agent-definitions into main

2026-07-20 11:11:19 +00:00

cloudcli commented

2026-07-19 22:11:22 +00:00

Member

Adds an agents/ directory: one markdown + frontmatter definition per role the
central dispatcher can summon, plus an index README.

These are the contract (what summons each agent, which identity/token it
runs as, which labels it may set, where it hands off); dispatch.yaml + the
reusable workflows remain the implementation.

Roster:

Agent	Summon	Runs as	Workflow	Status
plan	`agent:plan`	claude-plan	`plan.yaml`	active
dev	`agent:dev` / `plan:approved`	claude-dev	`implement.yaml`	active
test	`agent:test`	claude-plan	`test.yaml`	planned
coordinate	`agent:coordinate`	claude-plan	`coordinate.yaml`	planned
reflect	`agent:reflect` / merge	claude-dev	`reflect.yaml`	planned
triage	`issues.opened` / `agent:triage`	agent-read	`triage.yaml`	planned

Grounded in docs/plans/agent-orchestration.md, its runbook, and
reference/agents/agent-access.md. active = the workflow already exists on
main; planned = defined here, workflow to follow.

Merge is human-only per policy — opening for your review.

Adds an `agents/` directory: one markdown + frontmatter definition per role the central dispatcher can summon, plus an index README. These are the **contract** (what summons each agent, which identity/token it runs as, which labels it may set, where it hands off); `dispatch.yaml` + the reusable workflows remain the implementation. Roster: | Agent | Summon | Runs as | Workflow | Status | | --- | --- | --- | --- | --- | | plan | `agent:plan` | claude-plan | `plan.yaml` | active | | dev | `agent:dev` / `plan:approved` | claude-dev | `implement.yaml` | active | | test | `agent:test` | claude-plan | `test.yaml` | planned | | coordinate | `agent:coordinate` | claude-plan | `coordinate.yaml` | planned | | reflect | `agent:reflect` / merge | claude-dev | `reflect.yaml` | planned | | triage | `issues.opened` / `agent:triage` | agent-read | `triage.yaml` | planned | Grounded in `docs/plans/agent-orchestration.md`, its runbook, and `reference/agents/agent-access.md`. `active` = the workflow already exists on `main`; `planned` = defined here, workflow to follow. Merge is human-only per policy — opening for your review.

cloudcli added 7 commits

2026-07-19 22:11:23 +00:00

cloudcli added 1 commit

2026-07-19 22:12:11 +00:00

labels: canonical taxonomy for org seeding b6d9e7cee5

cloudcli added 1 commit

2026-07-19 22:12:11 +00:00

labels: idempotent org seed script 647d997f4f

cloudcli reviewed

2026-07-20 10:58:11 +00:00

cloudcli left a comment

Review — agent definitions + label taxonomy

Contract-first approach is right, and the frontmatter schema (token = phase, never: prohibitions, sets_labels: ownership) is clean and maps well to plans/agent-orchestration.md §5 and reference/agents/agent-access.md. labels.json correctly carries the exclusive flags (state/tier/loop/blocked = true) — landing this fixes the live gap where valssi/ops's repo labels are all non-exclusive. The idempotent create-or-PATCH in seed-org-labels.sh is a real improvement over the runbook's create-only script.

A few things to resolve before merge:

Blocking

agents/triage.md — identity is incoherent. actor: agent-read + capability: reader + token: CLAUDE_PLAN_PAT. Two problems: (a) the token belongs to claude-plan, not agent-read; (b) agent-read's PAT is read-only (read:repository, read:organization — no write:issue per agent-access.md), yet triage's whole job is to comment + set tier/*, which needs issue-write. As written it either can't do its job or misrepresents which identity runs it. Recommend running triage as claude-plan (planner has write:issue) on the local/haiku model — the reader account can't label.
labels.json omits plan:ready and pr:open, but plan.md/dev.md set them. plan.md sets_labels: [state/planning, plan:ready, needs/approval] and dev.md sets_labels: [..., pr:open, ...] reference labels the seed file won't create, and neither is in the plan §5 taxonomy. Decide one way: drop the two legacy labels from the agent defs, or add them to labels.json explicitly marked legacy. Right now the contract and the seed disagree.

Should fix

reflect.md ticks the valssi/ops epic as claude-dev. Per agent-access.md the membership matrix has claude-dev = Read in valssi, so it can't edit the epic issue body there. This only works today because the org contributors team is includes_all_repositories: true (grants code+issue write across all valssi repos incl. stack-composes/docs) — which is itself the unresolved runbook §0.5 concern. Cleaner: have the epic task-list tick run under claude-plan (planner = write:issue in valssi), keeping the reflect docs-PR under claude-dev.
coordinate.md lists agent:dev in sets_labels. The dev-bounce guard requires plan:approved present (or actor == APPROVER). A freshly-created child issue has neither, so agent:dev from the coordinator would no-op. Suggest coordinator summons agent:plan on ready children and lets the normal approve→dev gate run; clarify what "ready" means.

Minor

seed-org-labels.sh: ?limit=50 + set -e — fine for the current 28 labels, but a >50-label org or a stray 409 in the && echo chain could abort mid-run. A || true on the write and pagination would harden it.
Consider a scripts/ dir for labels.json + seed-org-labels.sh rather than repo root (cosmetic).
dev is marked status: active, but only the plan:approved path is wired in dispatch.yaml; the agent:dev bounce route (Phase 3) isn't there yet. Fine as a contract, just noting the roster slightly over-claims.

Not approving/merging — merge stays human-only per policy. These are contract fixes; the shape is sound.

## Review — agent definitions + label taxonomy Contract-first approach is right, and the frontmatter schema (token = phase, `never:` prohibitions, `sets_labels:` ownership) is clean and maps well to `plans/agent-orchestration.md` §5 and `reference/agents/agent-access.md`. `labels.json` correctly carries the `exclusive` flags (state/tier/loop/blocked = true) — landing this fixes the live gap where `valssi/ops`'s repo labels are all non-exclusive. The idempotent create-or-PATCH in `seed-org-labels.sh` is a real improvement over the runbook's create-only script. A few things to resolve before merge: ### Blocking 1. **`agents/triage.md` — identity is incoherent.** `actor: agent-read` + `capability: reader` + `token: CLAUDE_PLAN_PAT`. Two problems: (a) the token belongs to `claude-plan`, not `agent-read`; (b) `agent-read`'s PAT is read-only (`read:repository`, `read:organization` — no `write:issue` per agent-access.md), yet triage's whole job is to **comment + set `tier/*`**, which needs issue-write. As written it either can't do its job or misrepresents which identity runs it. Recommend running triage as `claude-plan` (planner has `write:issue`) on the `local`/`haiku` model — the reader account can't label. 2. **`labels.json` omits `plan:ready` and `pr:open`, but `plan.md`/`dev.md` set them.** `plan.md` `sets_labels: [state/planning, plan:ready, needs/approval]` and `dev.md` `sets_labels: [..., pr:open, ...]` reference labels the seed file won't create, and neither is in the plan §5 taxonomy. Decide one way: drop the two legacy labels from the agent defs, or add them to `labels.json` explicitly marked legacy. Right now the contract and the seed disagree. ### Should fix 3. **`reflect.md` ticks the `valssi/ops` epic as `claude-dev`.** Per agent-access.md the membership matrix has `claude-dev` = **Read** in `valssi`, so it can't edit the epic issue body there. This only works today because the org `contributors` team is `includes_all_repositories: true` (grants code+issue write across *all* `valssi` repos incl. `stack-composes`/`docs`) — which is itself the unresolved runbook §0.5 concern. Cleaner: have the epic task-list tick run under `claude-plan` (planner = `write:issue` in `valssi`), keeping the reflect docs-PR under `claude-dev`. 4. **`coordinate.md` lists `agent:dev` in `sets_labels`.** The dev-bounce guard requires `plan:approved` present (or actor == APPROVER). A freshly-created child issue has neither, so `agent:dev` from the coordinator would no-op. Suggest coordinator summons `agent:plan` on ready children and lets the normal approve→dev gate run; clarify what "ready" means. ### Minor 5. `seed-org-labels.sh`: `?limit=50` + `set -e` — fine for the current 28 labels, but a >50-label org or a stray 409 in the `&& echo` chain could abort mid-run. A `|| true` on the write and pagination would harden it. 6. Consider a `scripts/` dir for `labels.json` + `seed-org-labels.sh` rather than repo root (cosmetic). 7. `dev` is marked `status: active`, but only the `plan:approved` path is wired in `dispatch.yaml`; the `agent:dev` bounce route (Phase 3) isn't there yet. Fine as a contract, just noting the roster slightly over-claims. Not approving/merging — merge stays human-only per policy. These are contract fixes; the shape is sound.