From 0ca2ba8b2cefe29ac822d8c1b2c941e1571574b3 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Mon, 30 Mar 2026 14:45:18 +0000 Subject: [PATCH 1/7] chore: add .worktrees to .gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 6c33b574..9dd7b6b5 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ .amazonq/** .claude/** .codebuild/** +.worktrees/** .vscode/** .env buildspec.yml From fb7c0a0f3a39b82d137018614feb6b2f6494dcc3 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Mon, 30 Mar 2026 16:00:03 +0000 Subject: [PATCH 2/7] feat: gate CodeBuild workflow on 'codebuild' label and aidlc-rules paths PR builds now require the 'codebuild' label and changes under aidlc-rules/ to trigger. Push to main, tags, and workflow_dispatch remain unconditional. --- .github/workflows/codebuild.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.github/workflows/codebuild.yml b/.github/workflows/codebuild.yml index 5bde1432..287d3699 100644 --- a/.github/workflows/codebuild.yml +++ b/.github/workflows/codebuild.yml @@ -5,6 +5,13 @@ on: pull_request: branches: - main + types: + - opened + - synchronize + - reopened + - labeled + paths: + - 'aidlc-rules/**' push: branches: - main @@ -37,6 +44,9 @@ permissions: jobs: build: + if: >- + github.event_name != 'pull_request' + || contains(github.event.pull_request.labels.*.name, 'codebuild') environment: codebuild permissions: From a128fde141ff1d26552b4c5a33a8fb4969f23f77 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Mon, 30 Mar 2026 16:12:44 +0000 Subject: [PATCH 3/7] chore: add project-level attribution setting for PR contributor statement Uses the `attribution.pr` setting so Claude Code automatically appends the required contributor statement to all PR descriptions. Adds a gitignore negation for .claude/settings.json so shared project settings are committed while other .claude/ files remain ignored. --- .claude/settings.json | 6 ++++++ .gitignore | 1 + 2 files changed, 7 insertions(+) create mode 100644 .claude/settings.json diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..3e568582 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,6 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "attribution": { + "pr": "By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the [project license](https://github.com/awslabs/aidlc-workflows/blob/main/LICENSE)." + } +} diff --git a/.gitignore b/.gitignore index 9dd7b6b5..286d2384 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ .DS_Store .amazonq/** .claude/** +!.claude/settings.json .codebuild/** .worktrees/** .vscode/** From d07719b92d586c2dc418fd3c4b5366c6d9e9a49c Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Mon, 30 Mar 2026 16:22:35 +0000 Subject: [PATCH 4/7] docs: update administrative guide for CodeBuild label gate - Add .claude/settings.json to repo tree diagram - Update Pipeline 2 mermaid diagram with PR label-gate flow - Update CodeBuild workflow triggers table and add label gate detail - Add label-gated CI row to Security Posture table --- docs/ADMINISTRATIVE_GUIDE.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/ADMINISTRATIVE_GUIDE.md b/docs/ADMINISTRATIVE_GUIDE.md index d77cfee5..6c5ce0c3 100644 --- a/docs/ADMINISTRATIVE_GUIDE.md +++ b/docs/ADMINISTRATIVE_GUIDE.md @@ -51,6 +51,8 @@ awslabs/aidlc-workflows/ │ ├── release.yml # GitHub Release on tag push │ ├── release-pr.yml # Changelog PR before release │ └── tag-on-merge.yml # Auto-tag on release PR merge +├── .claude/ +│ └── settings.json # Shared Claude Code project settings ├── aidlc-rules/ # The distributable product │ ├── aws-aidlc-rules/ # Core workflow rules │ └── aws-aidlc-rule-details/ # Detailed rules by phase @@ -114,8 +116,11 @@ The release flow is **changelog-first**: the CHANGELOG is updated *before* the t flowchart LR A["git push main"] --> B{{"Manual approval\n(codebuild environment)"}} C["workflow_dispatch\n(no tag input)"] --> B - B --> D["Run AWS CodeBuild"] - D --> E["Upload workflow artifacts"] + D["pull_request\n(aidlc-rules/** changed)"] --> E{"codebuild\nlabel?"} + E -->|yes| B + E -->|no| F["Job skipped"] + B --> G["Run AWS CodeBuild"] + G --> H["Upload workflow artifacts"] ``` ### Pipeline 3: Pull Request Validation @@ -203,13 +208,15 @@ flowchart TD | Property | Value | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **File** | `.github/workflows/codebuild.yml` | -| **Triggers** | `push` to `main`, `push` tags `v*`, `workflow_dispatch` (dispatched by `tag-on-merge.yml` or manual — select a tag in the UI to trigger a release build) | +| **Triggers** | `push` to `main`, `push` tags `v*`, `pull_request` to `main` (label-gated, path-filtered), `workflow_dispatch` (dispatched by `tag-on-merge.yml` or manual — select a tag in the UI to trigger a release build) | | **Environment** | `codebuild` (protected, manual approval) | | **Runner** | `ubuntu-latest` | | **Concurrency** | Groups by `{workflow}-{ref}`, cancels in-progress | **Purpose:** Runs an AWS CodeBuild project, downloads primary and secondary artifacts from S3, caches them in GitHub Actions cache, uploads them as workflow artifacts, and (when triggered from a `v*` tag) attaches them to the GitHub Release. +**PR label gate:** For `pull_request` events, the workflow only fires when files under `aidlc-rules/**` are changed (via `paths` filter) and the `build` job only runs when the `codebuild` label is present on the PR (via `contains(github.event.pull_request.labels.*.name, 'codebuild')`). The trigger includes `types: [opened, synchronize, reopened, labeled]` so that subsequent pushes to a labeled PR re-trigger the build automatically. `push`, `workflow_dispatch`, and tag events bypass the label check entirely. + **Job: `build`** | Step | Name | Condition | Action | @@ -414,6 +421,7 @@ Both `codebuild.yml` and `pull-request-lint.yml` follow a **deny-all-then-grant* | **AWS authentication** | OIDC-based role assumption via `id-token: write` — no static credentials stored | | **Least-privilege tokens** | `codebuild.yml` and `pull-request-lint.yml` explicitly deny all 16 permission scopes at workflow level, grant only required scopes at job level | | **Environment protection** | `codebuild` environment gates AWS credential access with potential reviewer/branch rules | +| **Label-gated CI** | `codebuild.yml` requires the `codebuild` label on PRs and only triggers for `aidlc-rules/**` changes, preventing unnecessary builds and environment approval prompts | | **Concurrency control** | `codebuild.yml` and `pull-request-lint.yml` cancel in-progress runs for the same branch | | **Safe PR trigger** | `pull-request-lint.yml` uses `pull_request_target` but never checks out PR code — only inspects metadata (title, labels, body) | | **Injection-safe inputs** | All user-controlled and event-driven inputs (`inputs.version`, `pull_request.head.ref`) passed via `env:` variables, never directly interpolated in `run:` blocks | From 7903ad3c8c9b15cf7946e2938cf1008a9c98831f Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Mon, 30 Mar 2026 16:27:59 +0000 Subject: [PATCH 5/7] style: alphabetize pull_request activity types in codebuild workflow --- .github/workflows/codebuild.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/codebuild.yml b/.github/workflows/codebuild.yml index 287d3699..b9d98bc2 100644 --- a/.github/workflows/codebuild.yml +++ b/.github/workflows/codebuild.yml @@ -6,10 +6,10 @@ on: branches: - main types: + - labeled - opened - - synchronize - reopened - - labeled + - synchronize paths: - 'aidlc-rules/**' push: From f40ed832082a16efce2c3a9ad0eb31846abab969 Mon Sep 17 00:00:00 2001 From: Kalindi Vijesh Parekh Date: Mon, 30 Mar 2026 15:52:50 -0400 Subject: [PATCH 6/7] fix: complete overconfidence prevention fix in remaining rule files Three stage files (nfr-design, infrastructure-design, units-generation) still contained the "Skip entire categories if not applicable" directive that overconfidence-prevention.md identified as the root cause of insufficient question-asking. The fix was applied to functional-design and nfr-requirements but missed these three files, creating contradictory instructions within the same workflow. Aligns all three files with the corrected approach: default to asking questions when there is any ambiguity, evaluate all question categories, and strengthen answer analysis to catch vague responses. Co-Authored-By: Claude Opus 4.6 --- .../construction/infrastructure-design.md | 34 +++++++++++-------- .../construction/nfr-design.md | 28 +++++++++------ .../inception/units-generation.md | 25 ++++++++------ 3 files changed, 51 insertions(+), 36 deletions(-) diff --git a/aidlc-rules/aws-aidlc-rule-details/construction/infrastructure-design.md b/aidlc-rules/aws-aidlc-rule-details/construction/infrastructure-design.md index 8ff9b274..0a7025f1 100644 --- a/aidlc-rules/aws-aidlc-rule-details/construction/infrastructure-design.md +++ b/aidlc-rules/aws-aidlc-rule-details/construction/infrastructure-design.md @@ -21,20 +21,23 @@ Map logical software components to actual infrastructure choices for deployment - Each step should have a checkbox [] ### Step 3: Generate Context-Appropriate Questions -**DIRECTIVE**: Analyze the functional and NFR design to generate ONLY questions relevant to THIS specific unit's infrastructure needs. Use the categories below as inspiration, NOT as a mandatory checklist. Skip entire categories if not applicable. +**DIRECTIVE**: Thoroughly analyze the functional and NFR design to identify ALL areas where clarification would improve infrastructure decisions. Be proactive in asking questions to ensure comprehensive infrastructure coverage. + +**CRITICAL**: Default to asking questions when there is ANY ambiguity or missing detail that could affect infrastructure design quality. It's better to ask too many questions than to make incorrect assumptions. - EMBED questions using [Answer]: tag format -- Focus on ambiguities and missing information specific to this unit -- Generate questions only where user input is needed for infrastructure decisions - -**Example question categories** (adapt as needed): -- **Deployment Environment** - Only if cloud provider or environment setup is unclear -- **Compute Infrastructure** - Only if compute service choice needs clarification -- **Storage Infrastructure** - Only if database or storage selection is ambiguous -- **Messaging Infrastructure** - Only if messaging/queuing services need specification -- **Networking Infrastructure** - Only if load balancing or API gateway approach is unclear -- **Monitoring Infrastructure** - Only if observability tooling needs clarification -- **Shared Infrastructure** - Only if infrastructure sharing strategy is ambiguous +- Focus on ANY ambiguities, missing information, or areas needing clarification +- Generate questions wherever user input would improve infrastructure decisions +- **When in doubt, ask the question** - overconfidence leads to poor designs + +**Question categories to consider** (evaluate ALL categories): +- **Deployment Environment** - Ask about cloud provider, region selection, environment setup, and deployment targets +- **Compute Infrastructure** - Ask about compute service choices, instance types, and scaling configurations +- **Storage Infrastructure** - Ask about database selection, storage types, backup strategies, and data lifecycle +- **Messaging Infrastructure** - Ask about messaging and queuing services, event-driven patterns, and throughput needs +- **Networking Infrastructure** - Ask about load balancing, API gateway approach, DNS, and network segmentation +- **Monitoring Infrastructure** - Ask about observability tooling, logging, metrics, alerting, and dashboards +- **Shared Infrastructure** - Ask about infrastructure sharing strategy, resource pooling, and multi-tenancy approach ### Step 4: Store Plan - Save as `aidlc-docs/construction/plans/{unit-name}-infrastructure-design-plan.md` @@ -42,8 +45,11 @@ Map logical software components to actual infrastructure choices for deployment ### Step 5: Collect and Analyze Answers - Wait for user to complete all [Answer]: tags -- Review for vague or ambiguous responses -- Add follow-up questions if needed +- **MANDATORY**: Carefully review ALL responses for vague or ambiguous answers +- **CRITICAL**: Add follow-up questions for ANY unclear responses - do not proceed with ambiguity +- Look for responses like "depends", "maybe", "not sure", "mix of", "somewhere between" +- Create clarification questions file if ANY ambiguities are detected +- **Do not proceed until ALL ambiguities are resolved** ### Step 6: Generate Infrastructure Design Artifacts - Create `aidlc-docs/construction/{unit-name}/infrastructure-design/infrastructure-design.md` diff --git a/aidlc-rules/aws-aidlc-rule-details/construction/nfr-design.md b/aidlc-rules/aws-aidlc-rule-details/construction/nfr-design.md index 92b950b1..59f114d1 100644 --- a/aidlc-rules/aws-aidlc-rule-details/construction/nfr-design.md +++ b/aidlc-rules/aws-aidlc-rule-details/construction/nfr-design.md @@ -20,18 +20,21 @@ Incorporate NFR requirements into unit design using patterns and logical compone - Each step should have a checkbox [] ### Step 3: Generate Context-Appropriate Questions -**DIRECTIVE**: Analyze the NFR requirements to generate ONLY questions relevant to THIS specific unit's NFR design. Use the categories below as inspiration, NOT as a mandatory checklist. Skip entire categories if not applicable. +**DIRECTIVE**: Thoroughly analyze the NFR requirements to identify ALL areas where clarification would improve the NFR design. Be proactive in asking questions to ensure comprehensive coverage of design patterns and logical components. + +**CRITICAL**: Default to asking questions when there is ANY ambiguity or missing detail that could affect NFR design quality. It's better to ask too many questions than to make incorrect assumptions. - EMBED questions using [Answer]: tag format -- Focus on ambiguities and missing information specific to this unit -- Generate questions only where user input is needed for pattern and component decisions +- Focus on ANY ambiguities, missing information, or areas needing clarification +- Generate questions wherever user input would improve pattern and component decisions +- **When in doubt, ask the question** - overconfidence leads to poor designs -**Example question categories** (adapt as needed): -- **Resilience Patterns** - Only if fault tolerance approach needs clarification -- **Scalability Patterns** - Only if scaling mechanisms are unclear -- **Performance Patterns** - Only if performance optimization strategy is ambiguous -- **Security Patterns** - Only if security implementation approach needs input -- **Logical Components** - Only if infrastructure components (queues, caches, etc.) need clarification +**Question categories to consider** (evaluate ALL categories): +- **Resilience Patterns** - Ask about fault tolerance approach, retry strategies, and circuit breaker patterns +- **Scalability Patterns** - Ask about scaling mechanisms, load distribution, and elasticity requirements +- **Performance Patterns** - Ask about optimization strategies, caching approaches, and latency targets +- **Security Patterns** - Ask about security implementation approach, encryption, and access control patterns +- **Logical Components** - Ask about infrastructure components (queues, caches, etc.) and their configuration needs ### Step 4: Store Plan - Save as `aidlc-docs/construction/plans/{unit-name}-nfr-design-plan.md` @@ -39,8 +42,11 @@ Incorporate NFR requirements into unit design using patterns and logical compone ### Step 5: Collect and Analyze Answers - Wait for user to complete all [Answer]: tags -- Review for vague or ambiguous responses -- Add follow-up questions if needed +- **MANDATORY**: Carefully review ALL responses for vague or ambiguous answers +- **CRITICAL**: Add follow-up questions for ANY unclear responses - do not proceed with ambiguity +- Look for responses like "depends", "maybe", "not sure", "mix of", "somewhere between" +- Create clarification questions file if ANY ambiguities are detected +- **Do not proceed until ALL ambiguities are resolved** ### Step 6: Generate NFR Design Artifacts - Create `aidlc-docs/construction/{unit-name}/nfr-design/nfr-design-patterns.md` diff --git a/aidlc-rules/aws-aidlc-rule-details/inception/units-generation.md b/aidlc-rules/aws-aidlc-rule-details/inception/units-generation.md index db228c8b..fd65d6b4 100644 --- a/aidlc-rules/aws-aidlc-rule-details/inception/units-generation.md +++ b/aidlc-rules/aws-aidlc-rule-details/inception/units-generation.md @@ -35,19 +35,22 @@ This stage decomposes the system into manageable units of work through two integ - [ ] Ensure all stories are assigned to units ## Step 3: Generate Context-Appropriate Questions -**DIRECTIVE**: Analyze the requirements, stories, and application design to generate ONLY questions relevant to THIS specific decomposition problem. Use the categories below as inspiration, NOT as a mandatory checklist. Skip entire categories if not applicable. +**DIRECTIVE**: Thoroughly analyze the requirements, stories, and application design to identify ALL areas where clarification would improve the system decomposition. Be proactive in asking questions to ensure comprehensive understanding of unit boundaries and responsibilities. + +**CRITICAL**: Default to asking questions when there is ANY ambiguity or missing detail that could affect decomposition quality. It's better to ask too many questions than to make incorrect assumptions. - EMBED questions using [Answer]: tag format -- Focus on ambiguities and missing information specific to this context -- Generate questions only where user input is needed for decision-making - -**Example question categories** (adapt as needed): -- **Story Grouping** - Only if multiple stories exist and grouping strategy is unclear -- **Dependencies** - Only if multiple units likely and integration approach is ambiguous -- **Team Alignment** - Only if team structure or ownership is unclear -- **Technical Considerations** - Only if scalability/deployment requirements differ across units -- **Business Domain** - Only if domain boundaries or bounded contexts are unclear -- **Code Organization (Greenfield multi-unit only)** - Ask deployment model and directory structure preferences +- Focus on ANY ambiguities, missing information, or areas needing clarification +- Generate questions wherever user input would improve decomposition decisions +- **When in doubt, ask the question** - overconfidence leads to poor decomposition + +**Question categories to consider** (evaluate ALL categories): +- **Story Grouping** - Ask about grouping strategy, cohesion criteria, and story dependencies +- **Dependencies** - Ask about integration approach, communication patterns, and dependency direction between units +- **Team Alignment** - Ask about team structure, ownership boundaries, and development workflow preferences +- **Technical Considerations** - Ask about scalability and deployment requirements that may differ across units +- **Business Domain** - Ask about domain boundaries, bounded contexts, and shared domain concepts +- **Code Organization (Greenfield multi-unit only)** - Ask about deployment model and directory structure preferences ## Step 4: Store UOW Plan - Save as `aidlc-docs/inception/plans/unit-of-work-plan.md` From e4f4af739fc5b5d43328503b71d324b909bde83a Mon Sep 17 00:00:00 2001 From: Kalindi Vijesh Parekh Date: Thu, 2 Apr 2026 15:20:11 -0400 Subject: [PATCH 7/7] chore: retrigger CI