diff --git a/README.md b/README.md index b7b68c52..e7e990fd 100644 --- a/README.md +++ b/README.md @@ -625,16 +625,16 @@ Deployment and monitoring (future) ## Extensions -AI-DLC supports an extension system that lets you layer additional rules on top of the core workflow. Extensions are markdown files organized under `aws-aidlc-rule-details/extensions/` and grouped by category (e.g., `security/`, `testing/`). +AI-DLC supports an extension system that lets you layer additional rules on top of the core workflow. Extensions are markdown files organized under `aws-aidlc-rule-details/extensions/` and grouped by category (e.g., `security/`, `compliance/`, `testing/`). ### How Extensions Work Each extension consists of two files placed in the same directory: - A **rules file** (e.g., `security-baseline.md`) containing the extension's rules. -- An **opt-in file** (e.g., `security-baseline.opt-in.md`) containing a structured multiple-choice question presented to the user during Requirements Analysis. +- An **opt-in file** (e.g., `security-baseline.opt-in.md`) containing metadata for the extension selection menu. -At workflow start, AI-DLC scans the `extensions/` directory and loads only `*.opt-in.md` files. During Requirements Analysis, it presents each opt-in prompt to the user. When the user opts in, the corresponding rules file is loaded (derived by naming convention: strip `.opt-in.md`, append `.md`). When the user opts out, the rules file is never loaded. Extensions without a matching `*.opt-in.md` file are always enforced. +At workflow start, AI-DLC scans the `extensions/` directory and loads only `*.opt-in.md` files. During Requirements Analysis, it presents a **consolidated selection menu** listing all available extensions — the user selects which ones to enable in a single answer. When the user opts in, the corresponding rules file is loaded (derived by naming convention: strip `.opt-in.md`, append `.md`). When the user opts out, the rules file is never loaded. Extensions without a matching `*.opt-in.md` file are always enforced. Once enabled, extension rules are blocking constraints — at each stage, the model verifies compliance before allowing the stage to proceed. @@ -645,31 +645,35 @@ The `extensions/` directory ships with the following (new extensions may be adde ```text aws-aidlc-rule-details/ └── extensions/ - ├── security/ # Extension category + ├── security/ # Security rules │ └── baseline/ - │ ├── security-baseline.md # Baseline security rules - │ └── security-baseline.opt-in.md # Opt-in prompt - └── testing/ # Extension category + │ ├── security-baseline.md + │ └── security-baseline.opt-in.md + └── testing/ # Testing rules └── property-based/ - ├── property-based-testing.md # Property-based testing rules - └── property-based-testing.opt-in.md # Opt-in prompt + ├── property-based-testing.md + └── property-based-testing.opt-in.md ``` > [!IMPORTANT] -> The security extension rules are provided as a directional reference for building effective security rules within AI-DLC workflows. Each organization should build, customize, and thoroughly test their own security rules before deploying in production workflows. +> The security extension rules are provided as a directional reference for building effective rules within AI-DLC workflows. Each organization should build, customize, and thoroughly test their own rules before deploying in production workflows. ### Adding Your Own Extensions You can extend an existing category or create an entirely new one. -1. Create a directory under `extensions/` (e.g., `security/compliance/` or `performance/baseline/`). -2. Add a **rules file** (e.g., `compliance.md`). Follow the same structure as `security-baseline.md`: +1. Create a directory under `extensions/` (e.g., `compliance/pci-dss/` or `performance/baseline/`). +2. Add a **rules file** (e.g., `pci-dss-controls.md`). Follow the same structure as `security-baseline.md`: - Define each rule as a heading in the format `## Rule : ` where the prefix is a short category identifier and NN is a sequential number (e.g., `COMPLIANCE-01`, `COMPLIANCE-02`). These IDs are referenced in audit logs and compliance summaries, so they must be unique across all loaded extensions. - Include a **Rule** section describing the requirement. - Include a **Verification** section with concrete checks the model should evaluate. -3. Add a matching **opt-in file** using the naming convention `<name>.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. +3. Add a matching **opt-in file** using the naming convention `<name>.opt-in.md` (e.g., `pci-dss.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. +### Community Extensions + +Community extensions are authored in external repositories and registered in the `community-extensions-index.yaml` at the repository root. To install one, copy its files into the matching `extensions/` subdirectory. See the index file for available community extensions and install instructions. + --- ## Tenets diff --git a/aidlc-rules/aws-aidlc-rule-details/extensions/README.md b/aidlc-rules/aws-aidlc-rule-details/extensions/README.md new file mode 100644 index 00000000..49b97464 --- /dev/null +++ b/aidlc-rules/aws-aidlc-rule-details/extensions/README.md @@ -0,0 +1,39 @@ +# Extensions + +This folder is read by the AI-DLC rules loader at workflow start. Place installed extension files here — the AI will automatically detect and load them. + +**This README file is not processed by the extensions loader.** The loader scans subdirectories only. + +--- + +## Available Extensions + +| Extension | Category | Description | +|---|---|---| +| `security/baseline/` | security | OWASP-mapped security rules | +| `testing/property-based/` | testing | Property-based testing rules | + +--- + +## How the Loader Works + +At workflow start, the AI scans subdirectories under `extensions/`: + +1. A subfolder containing a `*.opt-in.md` file is an **opt-in extension** — during Requirements Analysis, a consolidated selection menu is presented listing all available extensions for the user to choose from +2. A subfolder with rule `.md` files but no `*.opt-in.md` is **always enforced** — its rules are loaded immediately at workflow start +3. The `project-type/` subfolder is **excluded from this scan** — project-type extensions are loaded by Workspace Detection + +--- + +## Installing Community Extensions + +Community extensions are hosted in external repositories and listed in `community-extensions-index.yaml` at the repo root. To install one, copy its rule files into the matching category subdirectory here: + +```bash +mkdir -p extensions/<category>/<extension-name> +cp <source>/*.opt-in.md <source>/*-rules.md extensions/<category>/<extension-name>/ +``` + +Then start a new AI-DLC session to load the extension. + +--- diff --git a/aidlc-rules/aws-aidlc-rule-details/inception/requirements-analysis.md b/aidlc-rules/aws-aidlc-rule-details/inception/requirements-analysis.md index bf0ea729..8880cbd3 100644 --- a/aidlc-rules/aws-aidlc-rule-details/inception/requirements-analysis.md +++ b/aidlc-rules/aws-aidlc-rule-details/inception/requirements-analysis.md @@ -90,11 +90,34 @@ Analyze whatever the user has provided: **When in doubt, ask questions** - incomplete requirements lead to poor implementations. -### Step 5.1: Extension Opt-In Prompts +### Step 5.1: Extension Selection -**MANDATORY**: Scan all loaded `*.opt-in.md` files (loaded at workflow start from `extensions/` subdirectories) for an `## Opt-In Prompt` section. For each extension that declares one, include that question in the clarifying questions file created in Step 6. Present each opt-in question in the same language as the user's conversation. +**MANDATORY**: Scan all loaded `*.opt-in.md` files (loaded at workflow start from `extensions/` subdirectories). Present the user with a single consolidated extension selection menu listing ALL available extensions. Present the menu in the same language as the user's conversation. -After receiving answers: +**Selection Menu Format** (include as a question in the clarifying questions file from Step 6): + +```markdown +## Question: Extensions + +The following extensions are available for this project. Select which ones to enable: + +| # | Extension | Category | Description | +|---|---|---|---| +| 1 | [Extension Name] | [category] | [one-line description from opt-in file] | +| 2 | [Extension Name] | [category] | [one-line description from opt-in file] | +| ... | ... | ... | ... | + +Enter the numbers of extensions to enable (comma-separated), "all" to enable all, or "none" to skip. + +[Answer]: +``` + +**Rules**: +- List ALL extensions with `*.opt-in.md` files in a single table — do NOT present them as individual questions +- Populate the description from each extension's `*.opt-in.md` content +- If only one extension is available, still use this format for consistency + +After receiving the answer: 1. Record each extension's enablement status in `aidlc-docs/aidlc-state.md` under `## Extension Configuration`: ```markdown diff --git a/community-extensions-index.yaml b/community-extensions-index.yaml new file mode 100644 index 00000000..ff0e1289 --- /dev/null +++ b/community-extensions-index.yaml @@ -0,0 +1,32 @@ +# Community Extensions Index +# This file provides discovery and integrity verification for community-authored extensions. +# Community extensions are hosted in external repositories (Proposal C model). +# Official extensions ship in aidlc-rules/aws-aidlc-rule-details/extensions/ (Proposal B model). +# +# To add a community extension: submit a PR adding your entry below. +# See CONTRIBUTING.md for the full submission process. + +schema_version: "1.0" + +extensions: [] + +# Example entry (uncomment and fill in to register a community extension): +# +# extensions: +# - name: "my-extension" +# display_name: "My Extension" +# description: "What this extension does" +# category: "compliance" +# version: "1.0.0" +# maturity: "new" # new | incubating | reviewed | adopted +# author: "Your Name" +# repo: "https://github.com/your-org/your-repo" +# path: "path/to/extension" +# ref: "main" +# files: +# - name: "my-extension.opt-in.md" +# sha256: "" # Required for reviewed+ maturity +# - name: "my-extension-rules.md" +# sha256: "" +# tags: ["compliance", "example"] +# install_path: "extensions/compliance/my-extension" diff --git a/docs/WORKING-WITH-AIDLC.md b/docs/WORKING-WITH-AIDLC.md index 136fe9ab..252427e8 100644 --- a/docs/WORKING-WITH-AIDLC.md +++ b/docs/WORKING-WITH-AIDLC.md @@ -257,7 +257,7 @@ See the answering tips in [Section 1](#the-question--doc--approval-flow) for the - **State deliberate "no" decisions clearly.** `D — no caching required at this time` signals intent. An empty answer invites the AI to make a speculative choice. - **Describe phased approaches inline.** `X — simple role-based workflow now; replace with external workflow engine when available` lets AIDLC design the current solution with the right extension points. -> **Advanced tip — Security Extensions**: During Requirements Analysis, AIDLC will ask whether you want to enforce security extension rules. For production-grade applications, choose Yes. For prototypes, No is fine. This decision is recorded and enforced throughout Construction, so choose deliberately. +> **Advanced tip — Extensions**: During Requirements Analysis, AIDLC presents a consolidated extension selection menu listing all available extensions (security, compliance, testing, etc.). Select the ones relevant to your project in a single answer. This decision is recorded and enforced throughout Construction, so choose deliberately. ---