aes-root

Purpose: Scaffold AES composition roots — containers wire capabilities to contracts; entries bootstrap and start the process. Audience: The agent creating or validating a container or entry file. Scope: Python, Rust, and TypeScript root_<concept>_<container|entry> files (plus documented barrel/entry exceptions).

The layer decides which suffix, which imports, and which structure apply. Rules, templates, section contracts, and Verify blocks live in the language HOW-TUs under references/.

The layer chain:

root (constructs everything below) → agent / surface / capabilities / contract / utility / taxonomy — nothing below imports root

Each file answers one layer's job. A method or import in the wrong layer is the defect this skill exists to prevent.

Invariants

Every rule is machine-checked by lint-arwaky-cli scan <layer-path> (see each HOW-TO § Verify). A rule cannot drift from the gate. Cite the linter, not this file, when pointing at a rule.

Split details, templates, and Section Contract tables: read the language HOW-TO — do not restate them here.

Diagnostic Tree

Ask these questions in order. The first "No" dictates your next action.

1. Container or Entry?
   • Wire one feature → _container; bootstrap all → _entry.
2. Does the file contain business / orchestration / parsing / UI logic?
   • Yes → move down to capabilities / agent / utility / surface.
3. Are bindings exposed as contracts (not concretions)?
   • Concretions leak → bind to protocol/aggregate types (Arc<dyn Trait> in Rust).
4. Does anything below root import from root?
   • Yes → invert: root depends downward only.
5. Does lint-arwaky-cli scan <layer-path> exit 0?
   • No → fix findings, re-scan.

Workflow

1. Determine role — Container (wire one feature) or Entry (bootstrap all).
2. Resolve the package top. Run lint-arwaky-cli scan <layer-path> — findings are your work list.
3. Create root_<concept>_<suffix> from the language HOW-TO § Template / § Section Contract.
4. Wire dependencies: instantiate capabilities, bind them to contract protocol/aggregate types.
5. Compose: the entry builds every container and starts the surface or CLI loop.
6. Register the module, verify with lint-arwaky-cli scan.

Verification

Machine Checks

lint-arwaky-cli scan <layer-path>   # AES101/102, AES201–205, AES401–406 → must be 0
# Fallback only: language compile (python -c import / cargo check / npx tsc --noEmit)

```text

A pass means naming, imports, primitives, and roles are clean. Structural judgement
(tier choice, block order, helper-vs-utility, "orchestration only") is **manual** — see HOW-TO § Rules.

### Human Checks

A machine pass does not mean the file is right. Layer purpose, structural order, and
"only what this layer may do" still need a reader (HOW-TO § Rules).

---

## Pre-flight Checklist

- [ ] `lint-arwaky-cli scan <layer-path>` exits 0.
- [ ] Every touched HOW-TO's `Verify` block was executed.
- [ ] File registered in the right barrel for its language: `__init__.py` (Python), `mod.rs` (Rust),
      or `index.ts` (TypeScript).
- [ ] Language fallback compile clean if the HOW-TO lists it.
- [ ] Related skills considered for the next layer up/down.

---

## Common Mistakes (Anti-Patterns)

The linter covers naming, imports, and primitives. These need a reader (HOW-TO § Rules):

- **Business / orchestration / parsing / UI logic in root**: forbidden — route down a layer.
- **Concretions visible above root**: bind to contracts so agents/surfaces see interfaces, not classes.
- **Wrong suffix / undocumented name**: `_container` or `_entry` only (exceptions listed in HOW-TO).
- **Restating HOW-TO rules in SKILL.md**: delegate — this file only routes.

---

## Related Skills

- `aes-capabilities`
- `aes-agent`
- `aes-surface`
- `aes-contract`