How to Create Custom AI-DLC Extensions with Rules in awslabs/aidlc-workflows

To create custom AI-DLC extensions with rules, you must create a paired set of Markdown files in aidlc-rules/aws-aidlc-rule-details/extensions/: a rules file (<name>.md) containing constraint definitions and an opt-in file (<name>.opt-in.md) that presents a multiple-choice question during the Requirements Analysis phase.

The AI-DLC framework in the awslabs/aidlc-workflows repository provides a lightweight extension system that allows teams to layer organization-specific policies onto the core workflow. By placing properly named Markdown files in the extensions directory, you can inject custom security checks, testing standards, or performance guidelines that integrate seamlessly with the Inception, Construction, and Operations phases defined in core-workflow.md.

Understanding the Extension Architecture

AI-DLC’s architecture revolves around a core workflow that remains untouched while optional extensions provide additional constraints. The extension system uses a deliberate two-file pattern to separate rule definitions from user activation.

Extensions reside under aidlc-rules/aws-aidlc-rule-details/extensions/ and follow a strict naming convention:

• Rules file (<name>.md): Contains the actual constraint definitions, verification steps, and blocking requirements.
• Opt-in file (<name>.opt-in.md): Contains a multiple-choice question presented during the Requirements Analysis phase that determines whether the associated rules should be activated.

Extensions without a corresponding .opt-in.md file are always enforced as mandatory constraints, while those with opt-in files remain dormant until explicitly activated by the user.

How Extensions Are Loaded and Activated

The workflow processes extensions through four distinct phases when starting a new AI-DLC session:

1. Discovery: The system recursively walks the extensions/ directory and gathers all *.opt-in.md files.
2. Prompting: During the Requirements Analysis step, each opt-in file is rendered as a structured multiple-choice question.
3. Activation: When a user selects "Yes," the corresponding rules file (same base name without the .opt-in suffix) is loaded into the active rule set as blocking constraints that every workflow stage must satisfy.
4. Isolation: Because extensions are plain Markdown, they can be version-controlled, added, or removed without modifying the core workflow definition in core-workflow.md.

Step-by-Step: Creating a Custom Extension

Create the Rules File

Create a Markdown file containing your constraint definitions. Each rule should specify clear verification criteria that the AI must check against generated artifacts.

Place this file at aidlc-rules/aws-aidlc-rule-details/extensions/<category>/<name>/<name>.md:

## Rule PERF-01: CPU Utilization Limit

**Rule**  
The application must not exceed 70% average CPU utilization under load.

**Verification**  
The model should verify that the generated deployment manifest includes appropriate resource limits or autoscaling policies.

Create the Opt-in File

Create a companion file with the same base name plus the .opt-in suffix to control activation:

Place this at aidlc-rules/aws-aidlc-rule-details/extensions/<category>/<name>/<name>.opt-in.md:

### Enable Performance Baseline Checks?

- [ ] Yes – apply the performance-baseline rules
- [ ] No – skip the performance-baseline rules

Directory Placement and Naming

Extensions follow a hierarchical directory structure under aidlc-rules/aws-aidlc-rule-details/extensions/. You can organize extensions by category (such as security/, testing/, or performance/) to maintain clarity as your rule set grows.

The complete file structure for a "performance-baseline" extension appears as follows:

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

Complete Implementation Example

The following command sequence creates the performance-baseline extension structure in your repository:

mkdir -p aidlc-rules/aws-aidlc-rule-details/extensions/performance/baseline

cat > aidlc-rules/aws-aidlc-rule-details/extensions/performance/baseline/performance-baseline.md <<'EOF'

## Rule PERF-01: CPU Utilization Limit

**Rule**  
The application must not exceed 70% average CPU utilization under load.

**Verification**  
The model should verify that the generated deployment manifest includes appropriate resource limits or autoscaling policies.
EOF

cat > aidlc-rules/aws-aidlc-rule-details/extensions/performance/baseline/performance-baseline.opt-in.md <<'EOF'

### Enable Performance Baseline Checks?

- [ ] Yes – apply the performance-baseline rules
- [ ] No – skip the performance-baseline rules
EOF

When a user starts a new AI-DLC session and selects "Yes" for the performance prompt, the constraints defined in performance-baseline.md become blocking requirements throughout the Inception, Construction, and Operations phases defined in the core workflow.

Summary

• AI-DLC extensions require two paired Markdown files: a rules file (<name>.md) and optionally an opt-in file (<name>.opt-in.md).
• Place extensions in aidlc-rules/aws-aidlc-rule-details/extensions/ using subdirectories for organization.
• Extensions without opt-in files are automatically enforced; those with opt-in files activate only when users select "Yes" during Requirements Analysis.
• The system treats activated extension rules as blocking constraints that must be satisfied before proceeding to subsequent workflow phases.
• Extensions are plain Markdown, enabling version control and portability without touching core-workflow.md.

Frequently Asked Questions

What is the difference between the .md and .opt-in.md files?

The .md file contains the actual rule definitions and verification criteria that constrain AI-generated outputs, while the .opt-in.md file contains a multiple-choice question presented during the Requirements Analysis phase. According to the awslabs/aidlc-workflows source code, the workflow only scans for *.opt-in.md files during discovery, then loads the corresponding .md rules file if the user selects "Yes."

Where should I place my custom extension files?

All extension files must reside under aidlc-rules/aws-aidlc-rule-details/extensions/. You should create subdirectories for organization (such as security/, testing/, or performance/), but the critical requirement is that paired files share the same base name and directory location.

Are extensions without opt-in files mandatory or optional?

Extensions that lack a corresponding .opt-in.md file are always enforced as mandatory constraints. The AI-DLC workflow loads these rules automatically without prompting the user, making them suitable for organizational baselines that must apply to every project.

Can I version control custom extensions?

Yes. Because extensions are plain Markdown files stored in the repository alongside core-workflow.md, they integrate directly with Git or other version control systems. This design allows teams to branch, review, and merge rule changes just like source code, without modifying the core AI-DLC methodology.

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