aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
Agent: Workflow schema — explicit convergence and terminal_outcomes
- Dominant language
- TypeScript
- Stars
- 143
- Forks
- 46
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 20
Description
> **Roadmap:** Workflow-driven tasks (shipped); complements verification evidence bundles
> **Priority:** P1
## Component
Agent (Python runtime)
## Describe the feature
Extend the workflow JSON Schema so each workflow declares **how the harness decides the task is done** (convergence criteria), rather than relying on implicit behavior (agent stops, orchestrator infers PR opened). Literature on multi-agent coding harnesses shows implicit convergence (fixed iterations, phase count) is a major reliability gap; test-gated and artifact-gated convergence are principled alternatives.
## Use case
- **Workflow authors** need a declarative contract for "done" (`test_gated`, `review_submitted`, `artifact_delivered`, `human_approved`).
- **Conformance tests** need to assert terminal behavior per workflow without hardcoding workflow IDs in test code.
- **Operators** need predictable terminal semantics when forking workflows.
## Proposed solution
1. Add optional `convergence` block to workflow schema in `contracts/workflow-validation/`:
```yaml
convergence:
mode: test_gated | artifact_delivered | human_approved | review_submitted
required_sensors:
- verify_build
- verify_lint
terminal_outcomes:
- pr_opened
- review_published
early_exit:
allow_on_policy_deny: true
```
2. Step runner validates `convergence` at workflow load time (`agent/` workflow runner).
3. Update shipped coding workflows:
- `coding/new-task-v1`, `coding/pr-iteration-v1` → `test_gated` + `pr_opened`
- `coding/pr-review-v1` → `review_submitted`
4. Orchestrator may emit a `convergence_met` TaskEvent when inferred terminal matches declared mode (optional v1).
5. Document in `docs/design/WORKFLOWS.md`.
### Acceptance criteria
- [ ] JSON Schema updated; CI workflow-validation tests pass
- [ ] All three shipped coding workflows declare convergence
- [ ] Invalid convergence config fails at workflow load with clear error
- [ ] Design doc section with examples for repo-less `knowledge/*` workflows (`artifact_delivered`)
- [ ] No change to default terminal behavior for existing deployments (declarative documentation of current behavior)
## Other information
- **Related:** Verification evidence bundles issue (sensors referenced by `required_sensors`)
- **Paper:** arXiv:2605.18747 §4.3.2 convergence patterns
- **ADR:** ADR-014 workflow-driven tasks
## Acknowledgements
- [ ] I may be able to implement this feature
- [ ] This might be a breaking change
Contributor guide
Assessment
This issue has not been assessed yet.