aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
Docs: ABCA Spec — Plan–Execute–Verify (PEV) control model
- Dominant language
- TypeScript
- Stars
- 143
- Forks
- 46
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 20
Description
> **Roadmap:** Exposed project specifications
> **Priority:** P0
## Doc area
Design / architecture (`docs/design/`)
## Describe the issue
ABCA's orchestrator → agent → post-hooks pipeline already behaves like a **Plan–Execute–Verify (PEV)** loop, but the concept is not named or specified normatively. The [Code as Agent Harness](https://arxiv.org/abs/2605.18747) survey (§3.4) frames reliable coding agents as governed state transitions: plan as contract, execute in a sandbox, verify with deterministic sensors and human gates.
Without a spec section, operators and fork authors must reverse-engineer PEV from scattered design docs (`ARCHITECTURE.md`, `ORCHESTRATOR.md`, `WORKFLOWS.md`, `CEDAR_HITL_GATES.md`).
## Affected docs
- `docs/design/` — new `HARNESS.md` section or dedicated `PEV_CONTROL_MODEL.md` (TBD in implementation)
- `docs/design/ABCA_V2.md` — link from pillar 5.1 (ABCA Spec)
- `docs/design/ARCHITECTURE.md`, `ORCHESTRATOR.md`, `WORKFLOWS.md`, `CEDAR_HITL_GATES.md`, `EVALUATION.md` — cross-links
- `docs/src/content/docs/` — regenerated via `mise //docs:sync`
## Suggested change
Add a normative **PEV control model** section to the ABCA Spec track:
### Plan (contract formation)
- Admission, context hydration, workflow resolution, pre-flight
- Explicit inputs: issue/PR body, attachments, memory, blueprint/workflow config
- Outputs: assembled prompt, validation commands, Cedar policy posture, risky-operation hints
### Execute (permissioned state transition)
- Isolated compute (MicroVM), tool hooks, repo clone/branch/edit
- Permission tiers via Cedar HITL (`read` / sandbox-edit / full-access escalation)
### Verify (deterministic sensors + gates)
- Build/lint/test post-hooks, Bedrock Guardrails, output screening
- Terminal inference, PR creation, memory write, task terminal state
Include a mermaid diagram mapping ABCA phases to PEV and a table of **deterministic sensors** (linters, tests, Cedar, guardrails) vs **non-oracle signals** (LLM self-report).
### Acceptance criteria
- [ ] PEV section published under `docs/design/` with diagram and phase mapping table
- [ ] Each existing pipeline phase in `ARCHITECTURE.md` linked to Plan, Execute, or Verify
- [ ] Cross-links from `ABCA_V2.md` and related design docs
- [ ] `mise //docs:sync` run; Starlight mirrors committed
- [ ] No runtime/code changes in this issue (documentation only)
### Out of scope
- Implementing new verification tiers or workflow steps
- OpenAPI/schema changes
Contributor guide
Research direction
Start by reading docs/design/ABCA_V2.md, ARCHITECTURE.md, ORCHESTRATOR.md, WORKFLOWS.md, CEDAR_HITL_GATES.md, and EVALUATION.md to map existing phases to Plan, Execute, and Verify. Add the normative PEV section under docs/design/ with the requested diagram and sensor table, update the listed cross-links, then run mise //docs:sync. Done means the acceptance checklist is met, generated Starlight content is committed, and no runtime or schema files change.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100