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

docs(bootstrap): update DEPLOYMENT_ROLES.md, AGENTS.md, deployment guide

Open
#128 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement infra-cdk
Dominant language
TypeScript
Stars
143
Forks
46
Avg merge
3d 9h
Merged PRs (30d)
20

Description

## Parent

Sub-issue 8 of #120 (RFC: Least-privilege CDK bootstrap policies as code)

## Branch strategy

`feat/bootstrap-docs` → targets `feat/bootstrap-cicd` → final merge to `main`

## Estimated review time: ~15 min

## Summary

Update all documentation to reference the new code-as-source-of-truth and new operator workflows. This is the final PR in the stack — merging it to `main` completes the full feature.

## Deliverables

- [ ] Update `docs/design/DEPLOYMENT_ROLES.md`:
- Remove inline JSON policy blobs (replaced by generated artifacts)
- Add "Source of truth: `cdk/src/bootstrap/policies/`" reference
- Update "Using these policies" section to reference `mise //cdk:bootstrap`
- Keep the "How CDK deployment roles work" explanation (still valuable context)
- Add "Versioning" section explaining the triple-layer scheme
- [ ] Update `docs/guides/DEPLOYMENT_GUIDE.md`:
- Add "Bootstrap with least-privilege" section
- Document the upgrade path: default bootstrap → custom bootstrap
- Document preflight validation and what to do on failure
- [ ] Update `AGENTS.md`:
- Routing table: add `cdk/src/bootstrap/` → "Bootstrap policies, preflight, Aspect"
- Routing table: add `cdk/bootstrap/` → "Generated bootstrap artifacts (do not edit directly)"
- "Common mistakes": add "Editing `cdk/bootstrap/` directly instead of regenerating from `cdk/src/bootstrap/`"
- "Commands you can use": add `mise //cdk:bootstrap`, `mise //cdk:bootstrap:generate`, `mise //cdk:preflight`
- [ ] Sync Starlight mirrors (`mise //docs:sync`)
- [ ] Verify: `mise //docs:build` passes
- [ ] Final PR targets `main` — squash-merge the full stack

## Acceptance criteria

- `DEPLOYMENT_ROLES.md` no longer contains raw JSON (points to generated artifacts)
- `AGENTS.md` correctly routes agents to bootstrap code and generated artifacts
- Deployment guide has clear operator instructions for fresh bootstrap and upgrades
- Starlight mirrors are in sync
- `mise run build` passes (full monorepo build including docs)

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.