aoa-agents is the role and persona layer of the AoA ecosystem. It makes
agents explicit as role-bearing actors with reviewable contracts, rather than
leaving them as prompt folklore or hidden orchestration assumptions.
An agent is not a skill. A skill is a bounded workflow. An agent is the role-bearing actor that may use skills, route to proof, carry memory posture, or hand off to a stronger owner without absorbing those layers.
This README is the public front door. When work becomes operational, source-authored, generated, mechanic-local, or direction-bearing, follow the linked owner surface instead of expanding this page.
Current release:
v0.4.0. See CHANGELOG for release notes.
| Function | Surface |
|---|---|
| Repository authority boundary | CHARTER |
| Role-layer system form | DESIGN |
| Agent-facing guidance form | DESIGN.AGENTS |
| Agent route law and local checks | AGENTS, then the nearest nested AGENTS.md |
| Source-authored agent object home | agents |
| Repeatable agent-layer mechanics | mechanics |
| Documentation and owner-route map | docs |
| Current shipped surface contour | CURRENT_CONTOUR |
| Owner boundaries | BOUNDARIES |
| Current direction | ROADMAP.md |
| Durable obligations | QUESTBOOK and quests |
This repository is strongest when it clarifies who acts, under which contract, with which handoff and authority limits. It is weakest when it tries to become skills, proof, memory, routing, playbooks, runtime, or a giant prompt archive.
Read only the surface that matches the job.
| Need | Route |
|---|---|
| Shortest honest overview | this README -> CHARTER -> DESIGN -> agents |
| Decide whether something belongs here | CHARTER -> BOUNDARIES |
| Edit role source objects | agents, then the nearest agents/**/AGENTS.md |
| Work on a repeatable operation | mechanics, then the owning package AGENTS.md and PARTS.md |
| Inspect current shipped route families | CURRENT_CONTOUR |
| Inspect generated companions | generated and the source surface named by the generated file |
| Update direction | ROADMAP.md |
| Work as an agent | AGENTS, then the nearest nested route card |
Before adding, trusting, or publishing an agent-layer claim, ask the narrowest owner that can answer it.
| Question | Owner route |
|---|---|
May aoa-agents claim this? |
CHARTER, then BOUNDARIES |
| What is the agent model? | AGENT_MODEL |
| Where do role sources live? | agents and agents/source_home.manifest.json |
| Is this a base role, companion form, specialization, tier, cohort, orchestrator, capability pack, or runtime seam binding? | agents, then the owning branch card |
| Is this recurring operation pressure? | mechanics, then the package route |
| Is this a Codex projection or refresh question? | codex-projection |
| Is this proof, memory, routing, skill, technique, playbook, KAG, stats, or runtime truth? | route to the sibling owner named in BOUNDARIES |
aoa-agents currently carries:
- source-authored role houses and operating-model inputs under
agents/; - generated registries, formation readers, quest readers, runtime-seam readers,
and Codex projection companions under
generated/; - mechanics packages for formation, projection, Titan role-bearing, runtime seams, checkpoints, quest posture, stress posture, recurrence, RPG, boundary bridges, and release support;
- local route cards that keep each district's authority visible.
The detailed shipped surface list lives in CURRENT_CONTOUR. The root README should not become that inventory.
| District | Use for |
|---|---|
| agents | source-authored agent objects and operating-model inputs |
| mechanics | repeatable role-layer operations and package-local contracts |
| docs | public explanation, maps, boundaries, and decision records |
| schemas | shared schemas that are not yet part-local |
| examples | public-safe schema-backed examples |
| generated | derived readers and machine companions |
| config | repo-level publication and projection configuration |
| scripts | deterministic builders and validators |
| tests | regression and contract checks |
| .agents | agent-facing companion lanes |
| memo | local memory candidates and writeback port |
Generated files are companions, not authority. Source docs, source JSON, mechanic packages, builders, validators, tests, and decision records keep the meaning.
Executable validation routes live in AGENTS and the
nearest nested AGENTS.md.
For root documentation route changes, use the root route card. Run source
builders only when source-authored inputs or generated companions move, and
take those commands from the nearest owning AGENTS.md.
Grow the role layer by making the next actor boundary clearer.
Add role sources, mechanics, generated companions, examples, tests, decisions, and memory candidates only where they improve reviewability and preserve owner boundaries. When detail belongs to a sibling repository, mechanic, generated reader, roadmap, changelog, quest, decision record, or route card, route it there instead of making this README carry it.
Apache-2.0