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

> Learn to build custom AI-DLC extensions with rules using awslabs/aidlc-workflows. Create paired Markdown files to define constraints and opt-in questions for enhanced control.

- Repository: [Amazon Web Services - Labs/aidlc-workflows](https://github.com/awslabs/aidlc-workflows)
- Tags: how-to-guide
- Published: 2026-05-09

---

**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`](https://github.com/awslabs/aidlc-workflows/blob/main/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`](https://github.com/awslabs/aidlc-workflows/blob/main/.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`](https://github.com/awslabs/aidlc-workflows/blob/main/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`:

```markdown

## 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`:

```markdown

### 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:

```text
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:

```bash
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`](https://github.com/awslabs/aidlc-workflows/blob/main/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`](https://github.com/awslabs/aidlc-workflows/blob/main/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`](https://github.com/awslabs/aidlc-workflows/blob/main/.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`](https://github.com/awslabs/aidlc-workflows/blob/main/.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`](https://github.com/awslabs/aidlc-workflows/blob/main/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.