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

(docs): reference workflow templates and adoption maturity guide

Abierto
#393 0 comentarios 0 reacciones 0 asignados Ver en GitHub
documentation enhancement
Lenguaje dominante
TypeScript
Estrellas
143
Forks
46
Merge medio
3 d 10 h
PR fusionados (30 d)
24

Descripción

## 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

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

Empieza por docs/design/WORKFLOWS.md, docs/design/VISION.md, docs/guides/PROMPT_GUIDE.md y los enlaces existentes a DEVELOPER_GUIDE.md y USER_GUIDE.md. Inspecciona los ejemplos de workflows actuales en agent/workflows/examples/ y la estructura de documentación de Starlight antes de añadir plantillas y la guía de madurez. Se considera terminado cuando haya al menos tres ejemplos validados, una guía publicada con sus espejos regenerados, enlaces cruzados actualizados y no queden referencias obsoletas a task_type.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
yaml
Área
documentation
Tipo de issue
Documentación
Dificultad
4/5
Tiempo estimado
3-5 días
Estado de actividad
Tranquilo
Claridad
Bastante claro
Aptitud para principiantes
48/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.