How to Create Custom AI-DLC Extensions with Opt-In Prompt Files

AI-DLC extensions let you layer optional constraints on top of core workflows by pairing a rule definition file with an opt-in prompt file that users select during the Requirements Analysis phase.

The awslabs/aidlc-workflows repository provides a modular extension system that allows teams to customize AI-DLC (AI-Driven Lifecycle) pipelines without modifying the core codebase. When you create custom AI-DLC extensions with opt-in prompt files, you define conditional rules that only activate when users explicitly opt in, while extensions without prompt files are enforced automatically as mandatory policies.

How the AI-DLC Extension System Works

The extension mechanism operates on a two-file pairing system located under aws-aidlc-rule-details/extensions/. Each extension consists of:

• A rule file (*.md) containing the actual constraints, verification steps, and policy definitions.
• An opt-in file (*.opt-in.md) containing a multiple-choice prompt presented during the Requirements Analysis step.

During workflow initialization, the engine scans for *.opt-in.md files and presents their prompts to the user. If the user selects the "yes" option, the corresponding rule file (matching the base name without the .opt-in suffix) is loaded and enforced throughout the Inception, Construction, and Operations stages. Extensions without an opt-in file bypass the prompt and are always enforced as mandatory constraints.

File Structure and Naming Conventions

Extensions are organized by category within the extensions/ directory. The loader enforces strict naming conventions to map opt-in prompts to their corresponding rules.

The Rule File

Rule files define constraints using a standardized markdown format. Each rule must include:

• A heading following the pattern ## Rule <PREFIX-NN>: <Title>

• A Rule section describing the constraint

• A Verification checklist outlining how compliance is validated

The Opt-In File

Opt-in files must share the same base name as their corresponding rule file (e.g., security-baseline.md and security-baseline.opt-in.md). The file contains:

• A multiple-choice question with a single "yes" option
• Descriptive text explaining the extension's impact
• A [Select one] indicator

Step-by-Step Guide to Creating a Custom Extension

Follow these steps to add a custom extension to your AI-DLC workflow:

1. Create a category directory under aws-aidlc-rule-details/extensions/ (e.g., extensions/performance/ or extensions/compliance/).

2. Create the rule file (your-extension.md) with properly formatted rule definitions using the ## Rule <PREFIX-NN>: heading structure.

3. Create the opt-in file (your-extension.opt-in.md) with the same base name, containing a multiple-choice prompt that asks users whether to enable the extension.

4. Commit both files to your repository. The workflow will automatically detect the opt-in file during the next Requirements Analysis phase.

Real-World Code Examples

Property-Based Testing Extension

This example adds optional property-based testing requirements to Python projects.

Directory layout:

aidlc-rules/
└── aws-aidlc-rule-details/
    └── extensions/
        └── testing/
            └── property-based/
                ├── property-based-testing.md
                └── property-based-testing.opt-in.md

Opt-in prompt file (property-based-testing.opt-in.md):

# Property-Based Testing (opt-in)

We can add property-based testing to the project.  
Select the option that best describes your intent:

- ✅ **Yes, enable property-based testing** – We want the model to generate property-based tests and enforce the associated verification steps.
- ❌ No – Keep the current testing approach.

[Select one]

Rule file (property-based-testing.md):

## Rule PT-01: Generate Property-Based Tests

**Rule**  
All newly added functions must be covered by at least one property-based test generated by the AI-DLC model.

**Verification**  
- The model must produce a test file that uses a property-testing framework (e.g., `hypothesis` for Python).  
- The test must fail when a property violation is injected.  
- The test file must be added to version control and pass the project's CI pipeline.

Security Baseline Extension

This example enforces security policies as an optional add-on.

Directory layout:

aws-aidlc-rule-details/extensions/security/baseline/
├── security-baseline.md
└── security-baseline.opt-in.md

Opt-in prompt file (security-baseline.opt-in.md):

# Security Baseline (opt-in)

Would you like to enforce the baseline security rules defined for this project?

- ✅ Yes – Apply the security-baseline rules.
- ❌ No – Do not apply these rules.

[Select one]

How Extensions Are Loaded and Enforced

According to the source code in the awslabs/aidlc-workflows repository, the workflow engine follows this execution path:

• Scanning: The loader recursively searches aws-aidlc-rule-details/extensions/ for files ending in *.opt-in.md.
• Prompting: During the Requirements Analysis step, each discovered opt-in file is rendered as an interactive multiple-choice question.
• Conditional Loading: If the user selects the affirmative option, the engine loads the associated rule file (matched by base name) into the active rule set.
• Blocking Enforcement: All enabled extensions become blocking constraints. The workflow cannot proceed to the next lifecycle stage until the model verifies that the extension's verification criteria are satisfied.

Extensions without corresponding opt-in files are loaded automatically and treated as mandatory organizational policies.

Summary

• Extensions reside under aws-aidlc-rule-details/extensions/ and require paired files: a *.md rule file and an optional *.opt-in.md prompt file.

• The workflow loads only *.opt-in.md files during the Requirements Analysis phase to determine which rules to activate.

• Rule files must follow the ## Rule <PREFIX-NN>: <Title> format and include Rule and Verification sections.

• Enabled extensions function as blocking constraints that must pass verification before the workflow advances.

• Extensions without opt-in files are always enforced, ensuring baseline policies remain mandatory.

Frequently Asked Questions

What happens if I create a rule file without an opt-in file?

The extension is treated as mandatory and is always enforced during all workflow stages. The absence of an *.opt-in.md file signals to the engine that the rules are baseline requirements that do not require user consent.

Can I nest extensions in subdirectories?

Yes, you should organize extensions into category subdirectories such as extensions/security/ or extensions/testing/property-based/. The loader recursively scans all subdirectories under extensions/, so deeply nested organizational structures are fully supported.

What format must the opt-in prompt file follow?

The opt-in file must use the same base name as the rule file with the .opt-in.md suffix added. It must contain a multiple-choice question with a single "yes" option (indicated by a ✅ emoji) and a [Select one] marker. The file is only processed if it resides within the aws-aidlc-rule-details/extensions/ directory tree.

Are custom extensions blocking or advisory?

All enabled extensions are blocking constraints. According to the extension system implementation, a stage cannot proceed until the model confirms that the extension's verification checklist has been satisfied. This ensures that opted-in rules are treated as hard gates rather than suggestions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}