Handbook
Welcome to the Role OS handbook. This is the complete guide to adopting and running Role OS professionally.
What’s inside
Section titled “What’s inside”- Beginners — New to Role OS? Start here for a plain-language walkthrough
- Getting Started — Install and run your first task in 5 minutes
- Missions — 9 proven recurring workflows with tracked steps and honest-partial reporting
- Role Spine — 61 specialist roles across 10 packs and their contracts
- Team Packs — 10 pre-assembled role chains for common work types
- Reference — CLI commands, schemas, policies, and the operating system layers
- Crew Dossier — per-role character sheets (aptitudes, disposition, portrait) that configure roles at dispatch time
What is Role OS?
Section titled “What is Role OS?”Role OS is a repo-native operating layer for coding-agent work. It staffs work through 61 specialized role contracts, assembles task-specific chains, validates teams before execution, auto-routes recovery when work is blocked, and requires structured evidence in every verdict. Claude Code adapter ships; the contracts are markdown any harness can consume.
The system provides three entry levels and ten operating layers:
Entry levels — roleos start picks the right one:
| Level | When | What happens |
|---|---|---|
| Mission | Task matches a proven recurring workflow | Known role chain, artifact flow, escalation branches, honest-partial definition |
| Pack | Task is a known family but not a full mission | Pre-assembled team with mismatch detection |
| Free routing | Task is novel, mixed, or uncertain | All 61 roles scored, dynamic chain assembled |
Operating layers:
| Layer | What it does |
|---|---|
| Unified entry | Decides mission vs pack vs free routing with confidence scores and alternatives |
| Persistent runs | roleos run creates disk-backed runs with resume, interventions, step guidance, and friction measurement |
| Mission runner | Tracked steps, artifact chain, escalation loops, completion reports |
| Routing | Scores all 61 roles against packet content with weighted keywords, triggers, and confidence levels |
| Chain builder | Assembles phase-ordered chains from scored roles — not frozen templates |
| Conflict detection | 4-pass validation catches hard conflicts, sequence errors, redundancy, and coverage gaps |
| Escalation | Auto-routes blocked/rejected/split work to the right resolver with reason and required artifact |
| Evidence | Role-aware structured evidence in verdicts with sufficiency checks |
| Dispatch | Generates execution manifests for the coding-agent harness with per-role tool profiles and budgets |
| Artifacts | 44 per-role contracts, 10 pack handoff contracts, structural validation |
Core properties
Section titled “Core properties”These are non-negotiable. If a change weakens any of them, reject it.
- Role boundaries hold — each role stays in its lane and escalates when out of scope
- Review has teeth — verdicts require structured evidence, not prose
- Escalation stays honest — blocked work routes to a named resolver, not dead air
- Packets stay testable — every done definition is concrete and verifiable
- Routing explains itself — every recommendation includes matched keywords and confidence
- Conflict detection runs before execution — broken teams are caught before work starts
Proven in execution
Section titled “Proven in execution”- 35 role trials (30 gold + 5 negative) — full roster proven
- 7 pack trials — all executed end-to-end, 3 shipped real code
- 7 pack comparison trials — mission vs pack vs free routing measured
- 6 mission trials — the original 6 missions run through the runner, 5 real-friction findings fixed (the catalog now ships 9 missions)
- Entry path trials — unified entry tested against 20+ real task descriptions
- 6 friction trials — persistent runs measured for operator touches across all entry levels
- 1595 tests (1592 pass, 3 skipped) as of v2.11.0