Roster

Imported from zhiming-dev/Roster (AGENTS.md). Install upstream with npx skills add zhiming-dev/Roster. Copyright stays with the author.

AGENTS.md

Entry point for any LLM coding agent (Copilot, Claude Code, Cursor, Aider, etc.) reading this repository. Read this file first.

Session start reading order

Before doing repository work in a new chat session, read these in order:

1. .github/copilot-instructions.md — build/style conventions
2. .agent/instructions/collaboration-rules.instructions.md
3. .agent/instructions/memory-bank.instructions.md
4. .memory-bank/activeContext.md and .memory-bank/learnings.md

Per-agent VS Code chat modes live in .github/chatmodes/ — one per Roster role (Planner, Coder, QA, Reviewer, Researcher, E2E) plus a repo-expert Q&A mode.

What this repo is

Roster — a human-in-the-loop, hierarchical multi-agent framework for software-engineering and workflow automation. Architecture and rationale are in conclave-spec.md. A summary is in README.md.

The repo is markdown-first: agents and skills are plain markdown files with YAML frontmatter plus reference docs. They can be loaded directly by any agent IDE (Copilot, Claude Code, Cursor, Aider), and runs are materialized on disk under runs/<run-id>/.

There is also an optional standalone runtime in runtime/ — a small Python service that loads each .agent.md as a live agent backed by a local Ollama (or other provider), exposes a principal-only chat with the Planner, and serves a live dashboard at http://localhost:8765/ showing every inter-agent message. Use the runtime when you want a self-contained demo, an out-of-IDE control surface, or a reproducible target for the research harness.

Agents in this repo

Shared contracts every agent depends on

• Schemas — shared/schemas/ — the source of truth for Plan, Task, ActionProposal, AgentMessage, ProvenanceEvent, CapabilityGrant.
• Approval gate — shared/approval-gate/SKILL.md — risk-tier classification (T0–T4) and approval UX rules.
• Provenance — shared/provenance/SKILL.md — the append-only event log format every agent writes to.
• Council — shared/council/SKILL.md — optional cross-model deliberation protocol with anti-conformity safeguards.
• Skill registry — shared/skills.registry.yaml

If the user asks you to start a new run

1. Generate a run_id (e.g. run_YYYY-MM-DD_<short-hash>).
2. Create runs/<run_id>/goal.md with the user's goal verbatim.
3. Invoke the planner (planner-agent/planner.agent.md) with that goal path.
4. The planner will produce plan.draft.json and pause for human approval — do not skip this gate, even if you believe you could plan and execute the work directly. The HITL gate is the point of the framework.

If the user asks you to start the standalone runtime

1. cd runtime
2. python -m venv .venv && .\.venv\Scripts\Activate.ps1 && pip install -r requirements.txt
3. Make sure ollama serve is running and the configured model is pulled (default llama3.1:8b).
4. python -m roster then open http://localhost:8765/.
5. The user chats with the Planner only. Do not surface sub-agents as conversational partners — they appear in the dashboard's event feed, not in the chat pane.

If the user asks you to work on the dashboard frontend

The dashboard is a Vite + React + TypeScript SPA in frontend/ (spec 002-react-motion-ui-rewrite), animated with Motion. The Python backend and its /api/* + /ws contract are unchanged.

• cd frontend && npm install
• npm run dev — Vite dev server on :5173, proxying /api + /ws → the runtime on :8765.
• npm run build — type-check + bundle into runtime/static/app/, which FastAPI serves at / (the Docker image builds this in a dedicated stage; without a build, / shows a build hint).
• npm run test (Vitest) · npm run lint (ESLint).

State lives in a Zustand store (frontend/src/store/); one backend event maps to store mutations in handleEvent.ts. Keep the event types in frontend/src/types/events.ts in sync with runtime/roster/events.py.

If the user asks you to extend the framework

• New expert role → create <role>-agent/<role>.agent.md + <role>-agent/<role>-runner/SKILL.md following the QA agent's structure.
• New shared skill → add under shared/<skill>/SKILL.md and register in shared/skills.registry.yaml.
• Any schema change → update shared/schemas/*.schema.json, bump the schema $id version, and call out the breaking change in the PR description.

Read-only zones (do not edit unless explicitly asked)

• e2e-agent/e2e-test/test-definitions/** and e2e-agent/e2e-test/suites/** — these are user test fixtures. Same rule as in e2e-agent/e2e-runner/SKILL.md: let tests fail, do not silently edit them to match the page.
• examples/**/provenance.sample.jsonl — sample traces; treat as immutable reference data.
• runs/<id>/provenance.jsonl of an in-progress run — append only; never rewrite history.

Conventions

• Every agent file: <role>.agent.md with frontmatter description, tools.
• Every skill file: SKILL.md with frontmatter name, description, argument-hint.
• All JSON artifacts validate against a schema in shared/schemas/.
• All times are ISO-8601 UTC.
• All ids are stable, URL-safe, and prefixed by kind: plan_…, task_…, msg_…, evt_…, prop_…, run_….