aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
Docs: ABCA Spec — harness engineering glossary and extension catalog
- Dominant language
- TypeScript
- Stars
- 143
- Forks
- 46
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 20
Description
> **Roadmap:** Exposed project specifications; ABCA V2 pillar 5.1
> **Priority:** P0
## Doc area
Design / architecture (`docs/design/`)
## Describe the issue
External literature and industry practice treat the **agent harness** as the primary design object — tools, sandboxes, memory, validators, permissions, telemetry — distinct from the base model. ABCA V2 positions the **ABCA Spec** as normative and the CDK app as one conforming implementation, but there is no consolidated glossary or extension-point catalog for platform builders.
Fork authors still reverse-engineer `ComputeStrategy`, workflow steps, Cedar seams, and memory interfaces from code.
## Affected docs
- `docs/design/` — new harness glossary + extension catalog (section in `HARNESS.md` or standalone)
- `docs/design/ABCA_V2.md` — pillar 5.1 deliverables table
- `docs/design/COMPUTE.md`, `WORKFLOWS.md`, `REPO_ONBOARDING.md`, `API_CONTRACT.md`, `ORCHESTRATOR.md`
- `docs/src/content/docs/` — synced mirrors
## Suggested change
Publish two linked artifacts:
### 1. Harness engineering glossary
Define terms aligned with arXiv:2605.18747:
| Term | ABCA meaning |
|------|----------------|
| Harness interface | Code connecting agent to reasoning, action, environment (repo, tests, traces) |
| Harness mechanisms | Planning, memory, tools, PEV control, harness optimization |
| System-provided harness | Orchestrator, Cedar, sandbox, workflows, observability |
| Agent-initiated artifacts | Tests, tools, plans, skills the agent creates during execution |
| Deep telemetry | Trajectory-linked spans, TaskEvents, traces, cost, policy decisions |
| Harness-level evaluation | Metrics isolating runtime quality from model quality |
### 2. Extension Point Catalog
Table for each seam:
| Extension point | Contract location | Reference impl | Conformance fixture |
|-----------------|-------------------|----------------|---------------------|
| `ComputeStrategy` | `COMPUTE.md` | AgentCore | TBD |
| Workflow step registry | `WORKFLOWS.md` | shipped step kinds | `contracts/workflow-validation/` |
| Memory store | `MEMORY.md` | AgentCore Memory | TBD |
| Identity/auth | ADR-016 | Cognito + HMAC webhooks | TBD |
| Cedar policy packs | `CEDAR_HITL_GATES.md` | `hard_deny.cedar` | `contracts/cedar-parity/` |
Mark fixtures as **TBD** with links to follow-up issues where not yet implemented.
### Acceptance criteria
- [ ] Glossary and catalog published under `docs/design/`
- [ ] Every row in V2 pillar 5.1 "Extension Point Catalog" table mapped or marked TBD with issue link placeholder
- [ ] `ABCA_V2.md` links to the new sections
- [ ] `mise //docs:sync` committed
- [ ] Documentation-only (no code changes)
### Out of scope
- Machine-readable OpenAPI/JSON Schema generation (separate roadmap item)
- Implementing missing conformance fixtures
Contributor guide
Assessment
This issue has not been assessed yet.