Subagents — the full cast

The Constellation repo ships eleven subagents under .claude/agents/. Each has a narrow scope, a written tool allowlist, and ends every response with the standardised verdict bar so other subagents and CI scripts can route on its output mechanically.

This page is the orientation map. The frontmatter description: in each subagent file is what Claude Code reads when you describe the work you want done — use those descriptions when picking which one to invoke.

The map

                ┌──────────────────────────┐
                │  pt-coordinator          │  read-only programme view
                │  (planning, delegation)  │  — never edits code
                └────────────┬─────────────┘
                             │ delegates
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────────┐
│ spec-author  │ →  │ spec-reviewer│ →  │ <module>-developer │  implements
└──────────────┘    └──────────────┘    └────────┬─────────┘
                                                 │ before PR
                                                 ▼
                                        ┌─────────────────────┐
                                        │ post-impl-reviewer  │  self-review
                                        └─────────────────────┘  (INF-114 hook
                                                                  blocks gh pr
                                                                  create without
                                                                  this)

                ┌──────────────────────────┐
                │  memory-curator          │  weekly / per-release
                │  (.ai/lessons.md only)   │  PR with promoted lessons
                └──────────────────────────┘

Planning

pt-coordinator

Scope	Programme-wide planning across the 6 PT projects.
Edits code?	No — tool allowlist excludes Edit, Write, NotebookEdit.
When to invoke	"What should I work on next?", "Is this duplicating something in flight?", "Plan this week", "What's blocked?", "Cut a release?".
What it returns	Ranked recommendation + clear decision point. Often delegates to a module developer subagent once you confirm.
File	.claude/agents/pt-coordinator.md

Spec lifecycle triad

The three subagents that bracket implementation — authoring the spec, reviewing it before code is written, and auditing the diff before the PR opens. Each is a thin role (~30 lines) that loads its checklist from a paired skill in .claude/skills/.

spec-author

Scope	Drafts .ai/specs/SPEC-<slug>.md from a problem statement.
Edits code?	Spec files only — no apps/<module>/ writes.
When to invoke	A feat: PR is planned, or any change touching 3+ files. Before implementation begins.
What it returns	Path to the spec file + verdict bar with Next: spec-reviewer to audit, then <module>-developer to implement.
Paired skill	spec-authoring — required frontmatter, mandatory H2 sections, AC anchor format.
File	.claude/agents/spec-author.md

spec-reviewer

Scope	Audits a spec against AGENTS.md hard rules before implementation begins.
Edits code?	No — read-only.
When to invoke	After spec-author produces a spec, before any developer subagent picks up the work.
What it returns	Verdict bar. blocked on any AGENTS.md MUST violation; needs revision on any risk; merge-ready when the checklist is clean.
Paired skill	spec-review — the full checklist (format compliance, AGENTS.md hard rules, completeness, silent-assumption sweep).
File	.claude/agents/spec-reviewer.md

post-impl-reviewer

Scope	Maps each AC in the spec to a file:function in the diff; audits AGENTS.md compliance; runs the pre-push pipeline.
Edits code?	No — read-only.
When to invoke	After a developer subagent finishes its work, before opening a PR. Also called by the INF-114 hook on gh pr create.
What it returns	Verdict bar with each AC marked met / partial / missing / over-scoped, plus blockers/risks/suggestions citing file:line.
Paired skill	post-impl-review — AC traceability, CI gates, AGENTS.md hard rules in the actual diff, surprise sweep.
File	.claude/agents/post-impl-reviewer.md

Self-review hook (INF-114)

.claude/hooks/pre-pr-self-review.sh intercepts every gh pr create Bash call:

• If the PR body has no <details><summary>Self-review</summary>...</details> block → blocked.
• If the verdict inside is blocked → blocked.
• If needs revision → warning to stderr; allowed.
• If merge-ready → silent allow.

Bypass: [skip self-review] in PR title (any substring) or body (own line, with a written reason). All six module-developer subagents have a step 9/10 that invokes post-impl-reviewer and embeds the verdict bar before opening the PR — the hook is the last line of defence.

Module developers (six)

One subagent per code-owning module. Each is bounded to its module's paths by a three-layer mechanism: system prompt, pre-commit self-check (git diff --name-only HEAD), and a Refuse list that delegates out-of-scope work back to pt-coordinator.

Subagent	Scope	PT prefix	File
catalog-developer	apps/catalog/**	CAT-*	link
directory-developer	apps/directory/**	DIR-*	link
project-tracker-developer	apps/project-tracker/**	PT-*	link
wiki-developer	apps/wiki/**	PLT-*	link
platform-developer	packages/platform/**, packages/contracts/**, packages/ui/**	PLT-*	link
infra-developer	.github/**, scripts/**, tools/**, root config	INF-*	link

All six run the full pre-push pipeline (turbo lint typecheck build test + check:routes), add a changeset, run post-impl-reviewer on their own diff, embed the verdict bar in the PR body, and open the PR. The complete step-by-step flow is in Agent workflow.

Memory

memory-curator

Scope	Curates .ai/lessons.md — promotes per-session learnings from PR review threads, deduplicates, marks stale entries.
Edits code?	Only .ai/lessons.md.
When to invoke	Weekly (auto on cadence), per-release (manual before cutting a release branch), or ad-hoc after a painful debug session.
What it returns	A PR titled chore(memory): curator pass <YYYY-MM-DD> [INF-115] with promoted lessons + verdict bar listing suggestions for AGENTS.md / skills / constitution that need a follow-up.
File	.claude/agents/memory-curator.md

The curator is explicitly forbidden from editing AGENTS.md, skills, or the constitution — if a lesson implies a change there, it surfaces as a suggestion in the verdict bar and an infra-developer picks it up next.

Verdict bar

Every reviewing subagent — and every implementing subagent on handoff — ends its response with the standardised verdict bar from .claude/skills/agent-output-format/SKILL.md:

## <Review type> — <subject>

**Scope:** <surfaces touched>
**Verdict:** blocked | needs revision | merge-ready
**Reason:** <one sentence>

### Blockers (must fix)

- ...

### Risks (should fix before merge)

- ...

### Suggestions (non-blocking)

- ...

### Checklist

| Area   | Status                   |
| ------ | ------------------------ |
| <area> | pass / risk / fail / N/A |

Verdict	Meaning
blocked	Hard rule violation. Do not merge.
needs revision	Material gaps. Author iterates.
merge-ready	No blockers; ≤ minor suggestions.

scripts/parse-agent-verdict.ts extracts the verdict mechanically (exit code communicates verdict to bash callers — 0 merge-ready, 1 needs revision, 2 blocked, 10 malformed). The self-review hook uses it.

Paired skills

Each reviewing subagent loads its checklist from a paired skill so the thin agent file stays under ~40 lines and the checklist can be edited independently:

• spec-authoring — spec format (INF-107) + AC anchor format (INF-110)
• spec-review — what spec-reviewer checks against
• post-impl-review — what post-impl-reviewer checks against, plus the CI gate run
• agent-output-format — the verdict bar schema

Other skills (audit-logging, tenant-scope-wrapping, multi-zone-routing, release-and-migrations, mcp-tool-authoring, pt-sla-urgency, directory-rbac, worktree-and-mcp) are domain knowledge loaded on demand — see .claude/skills/.

See also

• Constitution — the architectural invariants every subagent presupposes.
• Workflow — the end-to-end flow from PT task → spec → implement → self-review → PR → merge.
• CI gates — the scripts the pipelines run; what each one enforces and how to bypass.
• Tools — pt CLI, MCP server, hosted MCP endpoint.