aoa-techniques

aoa-techniques is the public AoA practice canon: reusable, sanitized, bounded engineering techniques for coding agents and humans.

A technique here is one atomic executable move. It is not a snippet dump, skill bundle, playbook, proof verdict, role contract, routing policy, memory object, or runtime behavior.

This README is only the public front door. When the question becomes authority, authoring, classification, review, release, mechanics, or agent routing, follow the linked owner surface instead of expanding root prose.

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

What This Repository Does

This repository keeps portable practice small enough to select, adapt, verify, and hand to a small agent after orchestration supplies context.

• Repository boundary: CHARTER
• System form: DESIGN
• Agent-surface form: DESIGN.AGENTS
• AoA layer position: ECOSYSTEM_CONTEXT
• First repo-owned route: START_HERE
• Live corpus map: TECHNIQUE_INDEX
• Atomic technique contract: TECHNIQUE_ATOM_CONTRACT
• Classification and path law: TECHNIQUE_TOPOLOGY_CONTRACT and TECHNIQUE_TREE_CONTRACT
• Direction and durable follow-through: ROADMAP and QUESTBOOK

Keep broad workflows, private residue, raw logs, sibling-repo authority, and multi-step scenario choreography out of this canon unless they have been distilled into one reusable move.

Start Here

Read only the surface that matches the job.

• Short bounded overview: this README -> CHARTER -> START_HERE -> TECHNIQUE_INDEX
• One concrete example bundle: plan-diff-apply-verify-report
• Decide whether a candidate belongs: CHARTER -> TECHNIQUE_ATOM_CONTRACT
• Classify or place a bundle: TECHNIQUE_TOPOLOGY_CONTRACT -> TECHNIQUE_KIND_GUIDE -> TECHNIQUE_KIND_HANDOFF_PACK -> TECHNIQUE_TREE_CONTRACT
• Pick compact runtime cards: TECHNIQUE_CAPSULES or technique_capsules.min.json
• Query, explain, or pack one source-linked move: TECHNIQUE_INTELLIGENCE, TECHNIQUE_INTELLIGENCE_GUIDE, or technique_intelligence_registry.min.json
• Inspect docs and route surfaces: Documentation Map, Repo Doc Surfaces, and repo_doc_surface_manifest.min.json
• Work as an agent: AGENTS, then the nearest nested AGENTS.md

Deep mechanic runbooks, review packets, scout reports, generated readers, and semantic or shadow review artifacts stay in the docs map, generated readers, or owning mechanics package.

Route Modes

• first-reading: README
• technique-authoring: TECHNIQUE_ATOM_CONTRACT
• classification: TECHNIQUE_TOPOLOGY_CONTRACT
• tree-structure: TECHNIQUE_TREE_CONTRACT
• review-posture: Canonical Review Guide
• mechanic-change: mechanics
• root-editing: ROOT_SURFACE_LAW
• agent-surface-design: DESIGN.AGENTS
• generated-parity: authored source -> builder -> generated output -> validator

Technique Check

Before adding, promoting, or trusting a technique, ask the narrowest owner:

• Atomic move: TECHNIQUE_ATOM_CONTRACT
• Portability: CHARTER and TECHNIQUE_ATOM_CONTRACT
• Classification: TECHNIQUE_TOPOLOGY_CONTRACT, TECHNIQUE_KIND_GUIDE, and TECHNIQUE_INDEX
• Corpus path: TECHNIQUE_TREE_CONTRACT
• Neighboring-object boundary: CHARTER and AGENTS
• Direction, history, obligation, or mechanic-local planning: ROADMAP, CHANGELOG, QUESTBOOK, or the owning mechanic roadmap
• Generated freshness: source and mirror in Repo Doc Surfaces

Current Contour

The corpus is a tree of bundles under techniques/<trunk>/<shelf>/<slug>/. Each bundle's authored meaning lives in TECHNIQUE.md.

Use TECHNIQUE_INDEX and technique_catalog.min.json for the live map. Use ROADMAP for current direction and corpus-scale pressure. Do not treat this README as a status ledger.

Practice Mechanics

Mechanics preserve practice movement around the canon: donor intake, audit, evidence, recurrence, checkpoint, release support, provenance, and package-local routes.

Use mechanics/<slug>/ when a candidate is still moving toward canon. Use the technique bundle when the reusable practice itself is already authored.

Technical Districts

District	Use for
techniques	authored technique bundles
docs	contracts, route maps, review guides, release docs, and generated-reader interpretation
mechanics	practice movement, evidence, provenance, and mechanic-local routes
generated	reproducible catalogs, capsules, source-lift, review, and mesh companions
examples	public-safe repo-wide worked examples
templates	technique authoring and promotion scaffolds
legacy	public-safe repo-wide raw, archive, and migration receipts
.agents	agent-facing companion lanes and local route support
scripts	repo-wide builders and validators
tests	repo-wide validation surfaces

District gates narrow local handling. They do not replace source docs, bundle meaning, mechanic packages, or sibling-owner repositories.

Machine Companions

Machine-facing companions summarize the route:

• technique_catalog.min.json: compact corpus catalog
• technique_capsules.min.json: small runtime technique cards
• technique_intelligence_registry.min.json: source-linked query, explanation, and packing packets for atomic moves
• technique_intelligence_dag.min.json: navigation DAG over domains, kinds, family hints, and load refs
• repo_doc_surface_manifest.min.json: compact map of bounded public route/canon/status docs
• agents_mesh.min.json: compact AGENTS mesh coverage companion
• kag_export.min.json: source-owned KAG export companion

Generated files route and compress. Authored bundles, contracts, route docs, and owner-local mechanics keep authority.

Working Rule

Grow the canon by extracting one reusable move cleanly.

If a detail belongs to a sibling repository, mechanic, generated mirror, roadmap, changelog, quest, decision record, or legacy receipt, route it there instead of making this README carry it.