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

Agent: Workflow schema — explicit convergence and terminal_outcomes

Open
#517 1 comment 0 reactions 1 assignee Claimed by @ayushtr-aws View on GitHub
agent-runtime approved enhancement P1
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.