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

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

Aperta
#507 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
documentation P0
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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.