aes-taxonomy

Purpose: Scaffold AES taxonomy files (VO / entity / error / event / constant / request / response) — the stable language of the domain. Audience: The agent creating or validating a taxonomy file. Scope: Python, Rust, and TypeScript taxonomy_<domain>_<suffix> files in the shared domain.

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:

taxonomy_*_vo|entity|error|event|constant|request|response (bottom layer) → contract → capabilities → agent → surface → 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

Machine-checked rules are enforced by lint-arwaky-cli scan <layer-path> (see each HOW-TO § Verify). Convention-level rules are enforced by reading; the linter covers what it can, and the HOW-TO states explicitly which of the three is the case. Cite the HOW-TO, 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 (AES701)

A taxonomy_* file belongs in the workspace's shared/ folder, beside utility_* and contract_* files:

crates/shared/src/     # Rust
modules/shared/src/     # Python
packages/shared/src/    # TypeScript

The shared folder is locked. Placing taxonomy_* in a feature folder leaves the domain types unreachable from every member, and the barrel that should register them does not exist there. A capabilities_*, agent_*, or surface_* file found inside shared/ is an AES701 violation and must be moved out.

Diagnostic Tree

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

1. Is this a domain value, identity, failure, fact, literal, or an aggregate boundary?
   • Value → _vo; identity → _entity; failure → _error; fact → _event; literal → _constant; inbound aggregate call → _request; outbound aggregate call → _response.
2. Does the file import anything above taxonomy or touch I/O?
   • Yes → strip the import / move I/O to capabilities or utility.
3. Are domain fields raw primitives?
   • Yes → wrap each in a VO (AES401).
4. Is the file registered in the shared barrel?
   • No → register; else the module is dead code.
5. Does lint-arwaky-cli scan <layer-path> exit 0?
   • No → fix findings, re-scan.

Workflow

1. Resolve the shared taxonomy dir beside contracts.
2. Determine type (VO / Entity / Error / Event / Constant / Request / Response). Run lint-arwaky-cli scan <layer-path> — findings are your work list.
3. Draft the file from the language HOW-TO § Template / § Section Contract.
4. Register in __init__.py / mod.rs / index.ts.
5. Verify with lint-arwaky-cli scan <layer-path> (HOW-TO § Verify), then wire through aes-contract / aes-capabilities as needed.

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):

- **Primitives in domain fields**: wrap in a VO (AES401).
- **I/O or upward imports in taxonomy**: forbidden — move to capabilities/utility.
- **Computed "constants"**: pure literals only; computed values go to Utility.
- **Restating HOW-TO rules in SKILL.md**: delegate — this file only routes.

---

## Related Skills

- `aes-contract`
- `aes-utility`
- `aes-capabilities`