aes-agent

Purpose: Scaffold AES agent orchestrators — orchestration only: call the aggregate, return shared VOs, zero I/O and zero computation. Audience: The agent creating or validating an agent orchestrator file. Scope: Python, Rust, and TypeScript agent_<domain>_orchestrator files — one aggregate, 3-block structure.

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:

contract_*_aggregate (created via aes-contract) → agent implements → surface / root call the agent

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.

Placement (AES702, AES703)

An agent_*_orchestrator file belongs in a feature folder — a subdirectory of a member directory (crates/, modules/, packages/) that is neither shared/ nor a surface folder:

crates/<feature_name>/src/agent_<domain>_orchestrator.rs    # Rust
modules/<feature_name>/src/agent_<domain>_orchestrator.py  # Python
packages/<feature_name>/src/agent_<domain>_orchestrator.ts # TypeScript

A feature folder is defined as a folder holding at least one agent_*_orchestrator and one capabilities_* file. If a folder holds only capabilities without an agent of its own it is an AES702 violation; if the agent sits in a surface-dominated folder it is also AES702 and the file should be moved out of the surface folder.

An orchestrator may sit at the member root (e.g. packages/agent_calculator_orchestrator.ts) when it routes across features rather than serving one. That makes it a routing aggregate over the features beneath it — it holds one orchestrator per feature and delegates to them. It does not satisfy AES702 for those folders: each feature still owes an orchestrator of its own, so a capabilities folder under a member-level orchestrator is still a split feature.

agent_*_orchestrator files are forbidden in shared/ — that is an AES701 violation and the file must be moved to a feature folder.

Feature folder documents

The feature folder holding this agent also carries two documents at its root, beside the source:

crates/<feature_name>/FRD.md       # what the feature does — requirements
crates/<feature_name>/BACKLOG.md   # where its work stands

The folder name matches the feature it serves. A folder named after a generic word (utils, common, core) describes no feature and cannot carry a meaningful FRD.

A feature folder carrying an agent but neither document is an AES702 violation — the linter names the missing file and you write it.

Diagnostic Tree

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

1. Is this orchestration only — or does it compute / touch I/O / hold domain data?
   • Computes/I-O/data → move to capabilities / taxonomy / utility.
2. Does an _aggregate contract exist?
   • No → create it first with aes-contract.
3. Block 2 only aggregate methods? ≥1 aggregate? ≤3 types?
   • No → restructure to 1→2→3; extract free functions to utility.
4. Any silently discarded errors or raw primitives in signatures?
   • Yes → propagate/Result; wrap primitives in VOs.
5. Does lint-arwaky-cli scan <layer-path> exit 0?
   • No → fix findings, re-scan.

Workflow

1. Confirm orchestration only — computation → capabilities, domain data → taxonomy, pure helpers → utility.
2. Ensure an _aggregate contract exists — if missing, run aes-contract first.
3. Resolve the feature agent dir. Run lint-arwaky-cli scan <layer-path> — findings are your work list.
4. Implement the 3 blocks from the language HOW-TO § Template / § Section Contract; inject the aggregate via DI.
5. Check imports, I/O, computation, error handling, and primitives against HOW-TO § Rules.
6. Register in the shared barrel, verify with lint-arwaky-cli scan, then compose via aes-root / consume via aes-surface.

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 `__init__.py` / `mod.rs` / `index.ts`.
- [ ] 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):

- **Computation or I/O in the agent**: arithmetic/parsing/FS/network belong below the agent layer.
- **Silently discarded errors**: no `or ""` / `unwrap_or_default()` / `?? ""` on results.
- **Agent implements protocol instead of aggregate (or both)**: exactly one aggregate, 3-block order.
- **Restating HOW-TO rules in SKILL.md**: delegate — this file only routes.

---

## Related Skills

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