aoa-playbooks

aoa-playbooks is the scenario and composition layer of the AoA ecosystem.

It exists to make recurring operational recipes explicit, reviewable, and reusable. A playbook is not a skill. A skill is a bounded workflow. A playbook coordinates multiple surfaces, handoffs, fallbacks, and evidence expectations across a recurring scenario.

Current release: v0.3.1. See CHANGELOG for release notes.

Start here

Use the shortest route by need:

• docs map: docs/README
• role, boundaries, and conceptual model: CHARTER, docs/PLAYBOOK_MODEL, and docs/BOUNDARIES
• authored bundle and activation seam: docs/PLAYBOOK_BUNDLE_CONTRACT, docs/PLAYBOOK_EXECUTION_SEAM, docs/PLAYBOOK_OPERATIONAL_FAMILY, docs/PLAYBOOK_RECURRENCE_DISCIPLINE, docs/PLAYBOOK_LIFECYCLE, and docs/PLAYBOOK_PORTFOLIO
• evidence, gates, and release posture: docs/PLAYBOOK_REAL_RUN_WORKFLOW, docs/PLAYBOOK_REAL_RUN_HARVEST, docs/PLAYBOOK_COMPOSITION_GATES, docs/PLAYBOOK_GAP_MATRIX, and docs/RELEASING
• sovereign shared-root rollout route plus companion lane: playbooks/trusted-rollout-operations/PLAYBOOK.md, docs/CODEX_PLANE_ROLLOUT_CYCLE, docs/TRUSTED_ROLLOUT_CAMPAIGN_CADENCE, and examples/codex_plane_rollout_lane.example.json
• long-arc continuity and explicit reanchor route: AOA-P-0029 self-agency-continuity-cycle
• owner-law component refresh route without scheduler authority: AOA-P-0030 component-refresh-cycle
• A2A summon return checkpoint route without hidden child automation: AOA-P-0031 a2a-summon-return-checkpoint
• additive stress-lane and re-entry doctrine: docs/PLAYBOOK_STRESS_LANES and docs/PLAYBOOK_STRESS_HARVEST
• adjunct outline seam: docs/QUESTLINE_AND_CAMPAIGN_MODEL
• live authored examples: playbooks/self-agent-checkpoint-rollout/PLAYBOOK.md, playbooks/witness-to-compost-pilot/PLAYBOOK.md, playbooks/session-growth-cycle/PLAYBOOK.md, playbooks/owner-followthrough-campaign/PLAYBOOK.md, AOA-P-0027 reviewed-automation-followthrough, AOA-P-0028 trusted-rollout-operations, AOA-P-0029 self-agency-continuity-cycle, AOA-P-0030 component-refresh-cycle, and AOA-P-0031 a2a-summon-return-checkpoint inside the wider playbooks/*/PLAYBOOK.md family
• current direction: ROADMAP

Route by need

• source-authored playbook truth: playbooks/*/PLAYBOOK.md for scenario routes and generated/playbook_registry.min.json for compact registry metadata
• activation, federation, and review-governed landing surfaces: generated/playbook_activation_surfaces.min.json, generated/playbook_federation_surfaces.min.json, generated/playbook_review_status.min.json, generated/playbook_review_intake.min.json, generated/playbook_review_packet_contracts.min.json, and generated/playbook_landing_governance.min.json
• shared-root rollout operations route and companion lane: playbooks/trusted-rollout-operations/PLAYBOOK.md, docs/CODEX_PLANE_ROLLOUT_CYCLE.md, docs/TRUSTED_ROLLOUT_CAMPAIGN_CADENCE.md, and examples/codex_plane_rollout_lane.example.json
• long-arc continuity and explicit reanchor route: playbooks/self-agency-continuity-cycle/PLAYBOOK.md
• owner-law component refresh route: playbooks/component-refresh-cycle/PLAYBOOK.md
• A2A summon return checkpoint route: playbooks/a2a-summon-return-checkpoint/PLAYBOOK.md
• handoff, failure, automation, and subagent adjuncts: generated/playbook_handoff_contracts.json, generated/playbook_failure_catalog.json, generated/playbook_automation_seeds.json, generated/playbook_subagent_recipes.json, docs/HANDOFF_CONTRACTS, docs/FAILURE_RECOVERY, docs/AUTOMATION_SEEDS, and docs/SUBAGENT_PATTERNS
• additive stress-lane adjuncts: schemas/playbook_stress_lane_v1.json, schemas/playbook_reentry_gate_v1.json, examples/playbook_stress_lane.example.json, examples/playbook_reentry_gate.example.json, docs/PLAYBOOK_STRESS_LANES, and docs/PLAYBOOK_STRESS_HARVEST
• via negativa pruning checklist: docs/VIA_NEGATIVA_CHECKLIST
• real-run and gate-review evidence: docs/real-runs/, docs/gate-reviews/, examples/harvests/, docs/PLAYBOOK_REAL_RUN_WORKFLOW, and docs/PLAYBOOK_COMPOSITION_GATES
• owner-local live receipt publication for closeout/stats integration: scripts/publish_live_receipts.py and .aoa/live_receipts/playbook-receipts.jsonl
• live authored bundles and activation examples: playbooks/*/PLAYBOOK.md and examples/playbook_activation.*.example.json
• full non-mutating verify path: the eight generate_* --check builders, python scripts/validate_playbooks.py, and python -m pytest -q tests

What aoa-playbooks owns

This repository is the source of truth for:

• recurring operational scenarios
• multi-step compositions across skills, roles, memory posture, and proof posture
• scenario-level handoff, fallback, rollback, and return posture
• expected evidence and validation posture for recurring routes
• compact playbook registries and derived playbook-owned composition surfaces

What it does not own

Do not treat this repository as the main home for:

• reusable techniques
• single bounded skill bundles
• proof doctrine or verdict logic
• routing surfaces
• primary memory objects
• infrastructure implementation details
• giant prompt scripts pretending to be operations

When a route is really one bounded workflow, keep it in aoa-skills instead of inflating it into a playbook.

Current public surfaces

The committed public surfaces group into four families:

• source-authored playbook canon: playbooks/*/PLAYBOOK.md for route meaning and generated/playbook_registry.min.json for compact registry metadata
• derived activation, federation, review-status, review-packet, review-intake, and landing-governance surfaces such as generated/playbook_activation_surfaces.min.json, generated/playbook_federation_surfaces.min.json, generated/playbook_review_status.min.json, generated/playbook_review_packet_contracts.min.json, generated/playbook_review_intake.min.json, and generated/playbook_landing_governance.min.json
• playbook-owned composition adjuncts such as generated/playbook_handoff_contracts.json, generated/playbook_failure_catalog.json, generated/playbook_subagent_recipes.json, generated/playbook_automation_seeds.json, and generated/playbook_composition_manifest.json
• bounded evidence and readiness adjuncts under docs/real-runs/, docs/gate-reviews/, generated/phase_alpha_review_packets.min.json, generated/phase_alpha_run_matrix.min.json, and QUESTBOOK.md

Real-run harvest templates under examples/harvests/ and review notes under docs/real-runs/ and docs/gate-reviews/ stay bounded evidence surfaces. They do not turn this repository into a runtime log substrate.

Go here when...

• you need a single bounded execution unit: aoa-skills
• you need role and handoff contracts: aoa-agents
• you need proof surfaces or evidence framing: aoa-evals
• you need explicit memory objects or recall posture: aoa-memo
• you need the smallest next object or dispatch hint: aoa-routing
• you need the ecosystem center and boundary doctrine: Agents-of-Abyss

Build and validate

To validate the current playbook-layer surface locally, run:

python -m pip install -r requirements-dev.txt
python scripts/generate_playbook_activation_surfaces.py --check
python scripts/generate_playbook_federation_surfaces.py --check
python scripts/generate_playbook_review_status.py --check
python scripts/generate_playbook_review_packet_contracts.py --check
python scripts/generate_playbook_review_intake.py --check
python scripts/generate_playbook_landing_governance.py --check
python scripts/generate_playbook_composition_surfaces.py --check
python scripts/generate_phase_alpha_surfaces.py --check
python scripts/validate_playbooks.py
python -m pytest -q tests

The validator auto-discovers authored bundles under playbooks/*/PLAYBOOK.md, checks registry alignment, resolves federation-facing references into neighboring repositories, and validates the review-governed experimental landing layer, Phase Alpha, questbook, and local guidance surfaces including playbooks/AGENTS.md and generated/AGENTS.md.

Current contour

aoa-playbooks is currently at v0.3.1 and has moved beyond its initial public baseline. The current honest move is evidence-led maturation rather than bootstrap growth for its own sake.

The runtime-facing extension stays intentionally bounded: selected playbooks may publish explicit memo-read defaults and activation-readable surfaces, but memo truth, routing ownership, and source skill meaning remain in their owning repositories.

Questline and campaign reflection also remains adjunct-only. It is a reviewed outline seam, not a runtime ledger or quest authority surface.

License

Apache-2.0