aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

Docs: ABCA Spec — harness engineering glossary and extension catalog

Open
#506 0 comments 0 reactions 1 assignee Claimed by @mayakost View on GitHub
documentation P0
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.