aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
(docs): reference workflow templates and adoption maturity guide
- Lingua principale
- TypeScript
- Stelle
- 143
- Fork
- 46
- Merge medio
- 3g 9h
- PR unite (30g)
- 20
Descrizione
## 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
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia da docs/design/WORKFLOWS.md, docs/design/VISION.md, docs/guides/PROMPT_GUIDE.md e dai link esistenti a DEVELOPER_GUIDE.md e USER_GUIDE.md. Esamina gli esempi di workflow attuali in agent/workflows/examples/ e la struttura della documentazione di Starlight prima di aggiungere i template e la guida alla maturità. Il lavoro è completo quando sono presenti almeno tre esempi validati, una guida pubblicata con mirror rigenerati, link incrociati aggiornati e non rimangono riferimenti obsoleti a task_type.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- yaml
- Ambito
- documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Tranquilla
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 48/100