Directory Structure Requirements for AI-DLC Rules: A Complete Guide to awslabs/aidlc-workflows

AI-DLC rules require two immutable top-level directories—aidlc-rules/aws-aidlc-rules/ for the workflow definition and aidlc-rules/aws-aidlc-rule-details/ for rule files—alongside a strict separation between application code (workspace root) and AI-generated documentation (aidlc-docs/).

The awslabs/aidlc-workflows repository enforces a rigid directory structure to ensure the workflow engine can reliably discover rule files, validate extensions, and maintain clean separation between source code and generated artifacts. Understanding these directory structure requirements for AI-DLC rules is essential for IDE integrations, CI pipelines, and the core workflow engine to resolve paths correctly. Every file path and naming convention described below derives directly from the core workflow specification as implemented in the repository.

Immutable Root Directories

The hierarchy anchors in two unchangeable directories that must never be renamed, moved, or altered. According to aidlc-rules/aws-aidlc-rules/core-workflow.md, these directories serve as the entry point and rule repository for the entire AI-DLC lifecycle.

aws-aidlc-rules Directory

This directory contains the master workflow definition file core-workflow.md. The workflow engine uses this path to locate the directory-structure contract and initialize the lifecycle phases. If this directory is renamed or relocated, IDE integrations and CI pipelines will fail to resolve the workflow entry point.

aws-aidlc-rule-details Directory

This directory houses the actual rule files organized by phase subdirectories (common/, inception/, construction/). When the engine loads rules, it references files relative to this location. The analysis of aidlc-rules/aws-aidlc-rule-details/common/process-overview.md confirms that all rule inheritance and extension chains resolve from this root.

Rule-Detail Resolution Order

When a workflow step executes, the engine resolves rule files by searching directories in a specific priority sequence. As documented in the Mandatory: Rule Details Loading section of the core workflow, the engine checks the following paths in order:

1. .aidlc/aidlc-rules/aws-aidlc-rule-details/
2. .aidlc-rule-details/
3. .kiro/aws-aidlc-rule-details/
4. .amazonq/aws-aidlc-rule-details/

The first directory found in this list becomes the active rule-detail root for that session. All subsequent rule loads are relative to that selected path.

Documentation vs. Application Code Separation

AI-DLC enforces a strict boundary: all production source files live outside aidlc-docs/, while all AI-generated artifacts (requirements, designs, audit logs) reside inside aidlc-docs/. The workflow will never write application code under the documentation tree.

aidlc-docs Structure

The documentation directory organizes artifacts by lifecycle phase:

• inception/ — Contains plans/, reverse-engineering/ (brownfield only), requirements/, user-stories/, and application-design/
• construction/ — Contains plans/, {unit-name}/ subdirectories with functional-design/, nfr-requirements/, nfr-design/, infrastructure-design/, and code/ (markdown summaries only), plus build-and-test/
• operations/ — Placeholder for operational phase documentation
• aidlc-state.md — Tracks overall workflow progress via check-boxes
• audit.md — Immutable log of every user prompt and AI response with timestamps

File Naming and Extension Conventions

The workflow engine distinguishes between mandatory rules and optional extensions through specific file naming patterns.

Opt-In Extension Loading

Only files matching *.opt-in.md are loaded at startup. This keeps the initial context lightweight. When a user explicitly opts in, the engine derives the full rule file name (replacing .opt-in.md with .md) and loads the complete extension at that moment.

Content Validation

Every file created must first pass checks defined in aidlc-rules/aws-aidlc-rule-details/common/content-validation.md. This includes validation rules for generated code, documentation format compliance, and metadata requirements.

State Tracking and Audit Requirements

The directory structure supports immutable audit trails and mutable state tracking through specific marker files.

Plan Tracking

Check-boxes inside aidlc-docs/**/plans/ must be updated immediately after each workflow step completes. The paths follow the pattern aidlc-docs/{phase}/plans/ where phase is inception or construction.

aidlc-state.md

This file located at aidlc-docs/aidlc-state.md records the overall workflow progress. Unlike the phase-specific plans, this file provides a dashboard view of the entire AI-DLC lifecycle status.

audit.md

Located at aidlc-docs/audit.md, this append-only file records every user prompt and AI response with timestamps. The workflow never overwrites this file; it strictly appends new entries to maintain a complete history.

Practical Implementation Examples

Adding a New Common Rule

Create a file under the mandatory common/ subdirectory to apply rules across all phases:

# aidlc-rules/aws-aidlc-rule-details/common/new-rule.md

## New Rule

- Description: Enforce that all Lambda functions have a timeout ≤ 30 seconds.
- Impact: Applied during the NFR Requirements stage of the Construction phase.

Place this file under aidlc-rules/aws-aidlc-rule-details/common/. The workflow automatically loads it because it resides in the mandatory common/ directory referenced by aidlc-rules/aws-aidlc-rules/core-workflow.md.

Creating an Opt-In Extension

Create a lightweight entry point to defer heavy rule loading:

# aidlc-rules/aws-aidlc-rule-details/extensions/security-baseline.opt-in.md

## Security Baseline (Opt-In)

Do you want to enforce the security baseline extension?
- A) Yes – load `security-baseline.md` and apply all its rules.
- B) No – skip loading the full rule file.

When the user selects A, the engine loads aidlc-rules/aws-aidlc-rule-details/extensions/security-baseline.md at that specific moment rather than at startup.

Summary

• Immutable directories: aidlc-rules/aws-aidlc-rules/ and aidlc-rules/aws-aidlc-rule-details/ must never be renamed or relocated
• Resolution priority: The engine searches .aidlc/, .aidlc-rule-details/, .kiro/, and .amazonq/ prefixes in order to locate rule details
• Code separation: Application source lives outside aidlc-docs/; all AI-generated documentation lives inside
• File conventions: Use *.opt-in.md for deferred extensions and validate all content against common/content-validation.md
• Audit integrity: aidlc-docs/audit.md is append-only, while aidlc-state.md and phase-specific plans track mutable progress

Frequently Asked Questions

What happens if I rename the aws-aidlc-rules directory?

Renaming or moving aidlc-rules/aws-aidlc-rules/ will break IDE integrations, CI pipelines, and the core workflow engine because these components resolve paths relative to this immutable entry point. The system requires this exact path to locate core-workflow.md and initialize the lifecycle.

Where should I place my production source code?

Production source files must reside in the workspace root or project-specific directories outside aidlc-docs/. As specified in aidlc-rules/aws-aidlc-rule-details/construction/code-generation.md, the workflow will never write actual code under the aidlc-docs/ tree; that directory is reserved exclusively for markdown documentation, design specs, and audit logs.

How does the workflow handle optional rule extensions?

Optional extensions use a two-stage loading process. Files ending in *.opt-in.md load at startup to present the option, while the full rule files (*.md) remain unloaded until the user explicitly opts in. This prevents bloating the context with unused rules while maintaining discoverability.

What is the purpose of the aidlc-state.md file?

aidlc-docs/aidlc-state.md serves as the central progress tracker for the entire AI-DLC workflow. Unlike phase-specific plan files (which track individual steps within inception/ or construction/), this file provides a high-level dashboard view of which lifecycle phases are complete, in-progress, or pending, enabling quick status checks across long-running projects.

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