A pipeline framework for fast and correct software development with coordinated agent teams.

Three principles:

• Platform constraint: Claude Code and Codex support only bounded, single-level subagent delegation at runtime — a skill or lead can spawn specialist sub-agents (Claude via the Task tool; Codex via .codex/agents/*.toml, explicit and depth-limited, agents.max_depth default 1), but those sub-agents cannot spawn further, and neither runtime offers unbounded recursive spawning. Roster is designed around this depth limit: orchestration is one level deep per skill, and deeper multi-stage work is relayed through artifacts and human gates between sessions. This is not a feature — it is an architectural reality we work within.
• The team is the unit, not the agent. Adding an agent means wiring it into the pipeline: patching the lead, updating adjacent agents, validating the integration.
• Every plan needs a human who understood it. A structured quiz runs before any execution batch begins. Passive approval is not validation.

Install

Pick a channel — all install the recruiter, then /recruit assembles the team and offers to install the pipeline skills:

# Claude Code plugin marketplace (Claude Code)
/plugin marketplace add mathiasbourgoin/roster
/plugin install roster@roster

# npx, no clone/publish (any project with Node)
npx github:mathiasbourgoin/roster --runtime claude,opencode,codex

# curl | bash — universal, auto-detects your runtime
curl -fsSL https://raw.githubusercontent.com/mathiasbourgoin/roster/main/scripts/install.sh | bash

Prerequisites:

Tool	Needed by	Notes
bash ≥ 4	installer	macOS ships 3.2 — brew install bash. The installer fails early with guidance if it's older.
curl or wget	installer	to download component files
jq + git	/recruit	required by sync-harness.sh (run during team assembly), not by the installer itself
gh	/roster-ship	optional — only for opening PRs

Detects and installs for all present runtimes simultaneously:

Runtime	Detected by	Recruiter target	Notes
Claude Code	.claude/	.claude/agents/recruiter.md + .claude/commands/recruit.md
OpenCode	.opencode/	.opencode/skills/recruit/SKILL.md	native Agent-Skills discovery
Codex (project)	.agents/	.agents/skills/recruit/SKILL.md
Codex (global)	~/.codex/skills/	~/.codex/skills/recruit/SKILL.md

Options:

# Install for all runtimes (creates dirs)
curl -fsSL .../install.sh | bash -s -- --all

# Explicit runtimes
curl -fsSL .../install.sh | bash -s -- --runtime claude,opencode

# Team mode: appends one-liner to AGENTS.md so teammates get it automatically
curl -fsSL .../install.sh | bash -s -- --team

# Release channel: stable (default, tracks main) or next (the edge branch)
curl -fsSL .../install.sh | bash -s -- --channel next
# Arbitrary git ref (overrides --channel)
curl -fsSL .../install.sh | bash -s -- --branch <ref>

The installer records the channel in a per-runtime .roster-channel marker; /roster-doctor reports the active channel. stable is the default — omitting --channel reproduces prior behavior.

After install: run /recruit (Claude) or invoke the discovered recruit skill (OpenCode / Codex, via native Agent-Skills discovery) to assemble your team. The installed SKILL.md follows the open Agent-Skills standard, so it is also readable by other skill-aware tools (e.g. GitHub Copilot) that scan a compatible skills path — roster does not yet install to a Copilot-specific location.

The Pipeline

Roster ships as a set of slash-command skills. /roster-run is the entry point — it detects context and routes to the right phase automatically.

Three modes

/roster-run classifies every task into one of three depths before routing. Review is always mandatory — what changes is the upfront discovery and downstream documentation.

Mode	When	Pipeline
Express	No spec/KB impact — typo, rename, formatting, config tweak, dependency bump, doc fix, pure refactor	implement → review → ship
Fast	Quick change with possible spec/KB impact — bug fix, small behaviour change, missing case, perf fix	implement → review → qa → ship
Full	New capability, API change, design trade-offs, or "spec it first"	question → research → intake → spec → plan → implement → review → qa → ship

The classifier infers the mode from the task, but you can force one with a flag — /roster-run --full <task> (or --fast / --express). An explicit --full always wins; an explicit --express/--fast is honoured unless the task would skip a mandatory phase (e.g. a new public API), in which case /roster-run asks before downgrading.

Skill	Phase	What it does
/roster-run	Entry point	Detects context, routes to right phase
/roster-init	Bootstrap	Adversarial project interview — 6 questions, 3 adversarial
/roster-question	Question	Decomposes task into neutral research questions
/roster-research	Research	Blind documentarian research — file:line grounded, optional online scan
/roster-intake	Intake	Turns a task into a contractual brief with human gate
/roster-spec	Spec	Adversarial spec phase: user stories + challenges + runnable AC checks
/roster-plan	Plan	Dual-voice decomposition (two adversarial sub-agents), consensus
/roster-implement	Implement	TDD + improvement loop + specialist sub-agents
/roster-review	Review	Fix-first review, GO/NO-GO JSON verdict
/roster-qa	QA	Deterministic quality gates, gated on review GO
/roster-ship	Ship	Rebase-merge, conventional commits, PR
/roster-investigate	Operational	Root-cause analysis, read-only, freeze scope
/roster-audit	Operational	Code quality + spec compliance combined report
/roster-skill-health	Meta	Friction log analysis → proposes new skills, tools, adaptations
/roster-skill-evolve	Meta	Implements approved skill-health proposals

The spec phase

/roster-spec is auto-triggered for feature and api-change tasks. It runs a multi-sub-agent adversarial mini-pipeline before any implementation begins:

1. Research sub-agent — blind codebase survey (existing patterns, adjacent tests, entity conflicts)
2. Story generation — ≥2 independent user stories, each with priority, "why", and an independent test description; bounces if not achievable
3. Challenge sub-agent — adversarial agent finds ≥1 challenge per story (gaps, contradictions, missing constraints)
4. Resolution loop — challenges resolved from code/KB or escalated to the user (max 5 questions)
5. Cross-spec consistency — entity names grepped across specs/*.md to catch definition conflicts
6. Artifact write — specs/<slug>.md (permanent, indexed) + briefs/<task>-spec.md (pipeline marker)

Produced specs/<slug>.md files are indexed as component_type: "spec" and consumed by the architect, reviewer, and QA agents throughout the rest of the pipeline. A spec-level failure in review routes back to /roster-spec, not /roster-implement.

Metabolism

The two things that make roster compound over time — rather than stay static like a prompt library.

Skill metabolism

Every pipeline skill logs structured friction events to skills-meta/friction.jsonl (gitignored, local to each project):

{"date":"...","skill":"roster-plan","frictions":["decomp took 3 rounds"],"suggestion_type":"SKILL","suggestion":"roster-decomp-validator"}

Run /roster-skill-health manually after every 5–10 pipeline cycles (or when the friction count reminder fires at the end of /roster-ship). It clusters patterns and proposes concrete improvements:

• [SKILL] — a recurring workflow deserves its own reusable skill
• [TOOL] — a deterministic check should replace an LLM step (e.g. a custom linter)
• [ADAPT] — a tunable should change for this project's specific patterns
• [AGENT] — a new specialist agent is warranted

/roster-skill-evolve implements approved proposals. After ≥2 proposals are approved, run /improvement-loop-planner to convert them into bounded improvement loops with measurable success signals and iteration budgets.

Agent metabolism

The recruiter is not a one-time setup tool. It:

• Searches roster + 6 external agent registries (VoltAgent/awesome-claude-code-subagents, wshobson/agents, and others) scored against your project's actual needs
• Proposes the minimal team that covers the task surface — no bloat
• Runs /recruit update to compare installed agent versions against the registry and propose upgrades
• Creates new agents from scratch (Mode 4) when no existing agent fits — invoke with /recruit create <description>, e.g. /recruit create "an agent that reviews OpenAPI specs for REST conventions"

The combination — a pipeline that logs its own friction + a recruiter that continuously rebalances the team — is what separates roster from a static prompt collection.

Quick Start

/recruit

The recruiter assembles a minimal team and configures the harness. Default team (covers 80% of tasks):

Agent	Role
tech-lead	Orchestration, Ralph Loop, human gates
implementer	Code execution in isolated worktrees
reviewer	Structured review: correctness, security, regression
qa	Independent test verification

Then run /roster-run <task description> to start the pipeline on any task.

Harness Model

The canonical project harness lives under .harness/ and is projected into runtime-specific surfaces:

project/
├── .harness/          ← canonical source of truth
│   ├── agents/
│   ├── skills/
│   ├── rules/
│   ├── hooks/
│   │   ├── safety/          ← tool-level hooks (PreToolUse/PostToolUse)
│   │   ├── quality/
│   │   ├── skills/          ← skill-level hooks (pre/post per skill)
│   │   └── shared/          ← shared hook fragments (build-time inlined)
│   └── harness.json
├── .claude/           ← generated Claude projection
│   ├── agents/
│   ├── commands/
│   └── rules/
├── .agents/skills/    ← generated Codex projection
└── AGENTS.md

Bootstrap: ./scripts/init-harness.sh /path/to/project [profile]
Re-project after edits: ./scripts/sync-harness.sh /path/to/project

Profiles: core · developer · security · full

Roster's own harness (.harness/harness.json) uses the developer profile — a live reference for what a minimal, working harness looks like.

In Production

Roster was built while developing octez-manager, a production OCaml project. The pipeline has been used for:

• Spec-driven feature development with the adversarial spec phase catching requirement gaps before implementation
• Multi-runtime agent harness management across Claude Code and OpenCode
• Iterative self-improvement via the friction log → skill-health → skill-evolve loop

This project is the distillation of what worked.

Development

To add or update components:

1. Create the file in agents/, skills/, rules/, or hooks/ following the relevant schema/
2. npm run build:index
3. Update AGENTS.md
4. Open a PR (rebase-merge only, conventional commits)

specs/ contains sample pipeline spec outputs (produced by /roster-spec) — useful as reference examples of what a complete spec looks like.

Version numbers: package.json tracks the npm build tooling (1.x). The recruiter skill has its own independent version (2.x) declared in recruiter/recruiter.md frontmatter and mirrored in the VERSION file at repo root. These are separate semver tracks.

index.json is gitignored and not published to the repo. Build locally with npm run build:index before running searches. It is not required for install.

Language Patterns

patterns/ contains curated good/antipattern guides per language (TypeScript, Go, Python, Rust, OCaml, prompt engineering). These are reference material consumed by language-specific agents (implementer, ocaml-implementer) and injected as context during implementation phases — not standalone skills.

→ Full agent and skill catalog
→ Skill Overlap Guide — when to use each audit/spec/research skill
→ Skill hooks DSL and tutorial
→ Roster extensions — local extension packs, install registry, converge checks
→ Claims reconciliation — stable spec identities, deterministic KB projections, and offline behavior → Changelog