aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
(docs): reference workflow templates and adoption maturity guide
- Dominant language
- TypeScript
- Stars
- 143
- Forks
- 46
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 20
Description
## Component
Documentation
## Describe the feature
Ship a curated library of ready-to-use reference workflows (and optional trigger examples) plus an operator-facing adoption guide that maps maturity stages— from interactive CLI submission through governed background automation— to concrete ABCA capabilities, recommended first use cases, and success metrics.
The templates should live in-repo (for example, under `agent/workflows/examples/` or documented copy-paste paths), with short README per template: intent, prerequisites, expected PR shape, and verification steps. The maturity guide should help teams choose where to start and what to enable next without ad-hoc prompt engineering.
## Use case
I'm always frustrated when new operators don't know which workflow to run first or how to phrase tasks for reliable outcomes. Champions need copy-paste starting points for high-ROI, low-risk work (dependency bumps, flaky-test fixes, doc sync, lint adoption) and language for security and leadership on a phased rollout. Documentation-only deliverables can dramatically shorten time-to-first-successful-PR without waiting for new platform code.
## Proposed solution
1. **Reference workflows (3–5 minimum)** — Author first-party example YAML aligned with `WORKFLOWS.md`, e.g.:
- dependency / CVE bump with test verification
- flaky-test or CI-failure iteration
- documentation or comment sync from issue
- read-only `pr_review` with scope checklist
- optional repo-less research workflow pointer
2. **Template README** — Each example: `workflow_ref`, sample `bgagent submit` / API body, Blueprint expectations, anti-patterns.
3. **Adoption maturity guide** — New doc in `docs/guides/` (sync to Starlight): phases (interactive → background → event-driven fleet), mapped ABCA features per phase, recommended first use cases ordered by verifiability, metrics to track (merge rate, cost per task, CI pass rate).
4. **Quick start cross-links** — Link from `DEVELOPER_GUIDE.md`, `USER_GUIDE.md`, and Claude plugin `/submit` skill to templates and maturity guide.
5. **Optional CLI helper** — `bgagent submit --template cve-bump --repo ...` that fills description and workflow_ref from template metadata (stretch; docs-only acceptable for v1).
## Acceptance criteria
- [ ] At least three reference workflows are committed with tests or schema validation where applicable.
- [ ] Adoption maturity guide is published under `docs/guides/` with Starlight mirrors regenerated.
- [ ] Quick start / user guide links to templates and guide; no stale references to removed `task_type` enums.
- [ ] Each template documents prerequisites (onboarded repo, tests, Cedar/HITL expectations if any).
- [ ] Review confirms templates align with shipped workflow refs and do not promise unshipped platform features without labeling them as future.
## Other information
- Related roadmap: **Dynamic onboarding artifacts**, **Exposed project specifications**, workflow-driven tasks (shipped).
- Related design: `docs/design/WORKFLOWS.md`, `docs/design/VISION.md`, `docs/guides/PROMPT_GUIDE.md`.
- Prefer maintenance-style templates first (migrations, deps, tests) over open-ended feature templates for initial rollout credibility.
- Alternatives considered: external blog-only content (not versioned with repo); large template gallery before quality bar (hard to maintain).
## Acknowledgements
- [ ] I may be able to implement this feature
- [ ] This might be a breaking change
Contributor guide
Research direction
Start with docs/design/WORKFLOWS.md, docs/design/VISION.md, docs/guides/PROMPT_GUIDE.md, and the existing DEVELOPER_GUIDE.md and USER_GUIDE.md links. Inspect current workflow examples under agent/workflows/examples/ and the Starlight documentation structure before adding templates and the maturity guide. Done means at least three validated examples, a published guide with regenerated mirrors, updated cross-links, and no stale task_type references.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- yaml
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100