diff --git a/README.md b/README.md index b7b68c52..99ab21d8 100644 --- a/README.md +++ b/README.md @@ -670,6 +670,55 @@ You can extend an existing category or create an entirely new one. 3. Add a matching **opt-in file** using the naming convention `.opt-in.md` (e.g., `compliance.opt-in.md`). See `security-baseline.opt-in.md` for the expected format. Omitting this file means the extension is always enforced with no user opt-out. 4. Rules are blocking by default — if verification criteria are not met, the stage cannot proceed until the finding is resolved. +### Organizational Complexity + +When multiple teams share a single AI-DLC installation, extension management benefits from a layered approach that separates org-wide concerns from team-specific ones. + +#### Layer 1 — Org-Wide Extensions + +These are extensions that apply across the entire organization (e.g., security baselines, compliance rules). They live alongside the AWS-shipped extensions under `extensions/`: + +```text +aws-aidlc-rule-details/ +└── extensions/ + ├── security/ # AWS-shipped extension + └── org-compliance/ # Org-wide extension (your addition) + ├── hipaa/ + └── soc2/ +``` + +Org-wide extensions follow the same format as any other extension — markdown files with rule IDs, applicability questions, and verification sections. + +#### Layer 2 — Team-Specific Extensions + +Individual teams can layer their own rules without modifying org-wide or AWS-shipped files. Create separate directories under `extensions/` with a team prefix: + +```text +aws-aidlc-rule-details/ +└── extensions/ + ├── security/ # AWS-shipped + ├── org-compliance/ # Org-wide (Layer 1) + ├── team-api-standards/ # Team-specific (Layer 2) + └── team-data-governance/ # Team-specific (Layer 2) +``` + +Each `team-*` directory is owned by its respective team. This naming convention makes ownership clear and avoids merge conflicts between teams. + +#### Distribution Approach + +Git subtree is the recommended mechanism for distributing AI-DLC rules across repositories. It embeds the rule files directly in each consuming repo (no special tooling required at clone time), avoids the detached-HEAD pitfalls of submodules, and keeps the full file history available locally — making it a pragmatic choice for teams that want simple, self-contained repositories. + +The following table summarizes the lifecycle events and who is responsible: + +| Event | What Happens | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| AWS ships a new release | Central team pulls latest via `git subtree pull`. AWS-shipped dirs (`security/`, etc.) overwritten; org/team dirs unaffected. | +| Org rules change | Central team commits changes to `org-*` directories and pushes to the org's internal AI-DLC fork or overlay repo. | +| New team onboards | Team creates a `team-/` dir under `extensions/`; central team adds repo as a subtree source if distributing centrally. | +| Team adds own rules | Owning team commits to their `team-/` directory. Changes stay scoped to that team. | + +> **Note:** The "install script" referenced in some AI-DLC distribution guides is an optional convenience wrapper around `git subtree add` / `git subtree pull` that your organization can provide. If your org doesn't ship one, the raw git subtree commands work directly. See the [Git subtree documentation](https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_subtree_merge) for details. + --- ## Tenets