aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
Docs: ABCA Spec — Plan–Execute–Verify (PEV) control model
- Lingua principale
- TypeScript
- Stelle
- 143
- Fork
- 46
- Merge medio
- 3g 10h
- PR unite (30g)
- 24
Descrizione
> **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
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia leggendo docs/design/ABCA_V2.md, ARCHITECTURE.md, ORCHESTRATOR.md, WORKFLOWS.md, CEDAR_HITL_GATES.md ed EVALUATION.md per mappare le fasi esistenti a Plan, Execute e Verify. Aggiungi la sezione normativa PEV in docs/design/ con il diagramma e la tabella dei sensori richiesti, aggiorna i cross-link elencati, quindi esegui mise //docs:sync. Il lavoro è completato quando la checklist di accettazione è soddisfatta, il contenuto Starlight generato è committed e non è stato modificato alcun file di runtime o di schema.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Ambito
- documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 3/5
- Tempo stimato
- 1-2 giorni
- Stato di attività
- Tranquilla
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 68/100