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

Docs: ABCA Spec — Plan–Execute–Verify (PEV) control model

Open
#507 0 comments 0 reactions 0 assignees 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
> **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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.