aidlc-kit 0.4.0

Scaffold AI-DLC projects with enterprise guardrails, prompts, and compliance templates.

aidlc-kit

Scaffold AI-DLC projects with prompts, templates, and consistency checks.

aidlc-kit is the companion CLI tool for the AI-DLC methodology, originally introduced by Raja SP in the AWS DevOps Blog. The methodology is extended with additional rituals, enterprise guardrails, brownfield workflows, and tooling in Reimagine, Don't Retrofit by Ricardo González Vargas. The book provides the methodology, principles, and rituals; this tool provides the project scaffolding to put them into practice.

Install

pip install aidlc-kit
# or with uv
uv tool install aidlc-kit
# or run without installing
uvx aidlc-kit

Quick Start

# Scaffold a new project (interactive wizard)
aidlc-kit init my-project

# Non-interactive
aidlc-kit init my-project --mode greenfield --platform aws --ide kiro

# Brownfield (existing codebase)
cd existing-repo
aidlc-kit init . --mode brownfield --platform azure --ide copilot

# Enterprise tier (adds EGS guardrails, compliance matrix, gap analysis)
aidlc-kit init my-project --mode greenfield --platform aws --tier enterprise

Commands

Command	Purpose
init	Scaffold a new AI-DLC project
check	Validate project health and consistency
status	Show current project progress dashboard
update	Update kit-owned templates to latest version
archive	Archive completed intent and reset workspace
intent	Manage parallel intents via git branches (create, list, switch, archive)
bolt	Manage parallel bolts via git branches (branch, list, merge)
egs-init	Create an org-level EGS definition (guided setup)
export-egs	Export the project's EGS definition to a file
import-egs	Import an external EGS definition into the project
extensions	Manage project extensions (list, install, remove)
consistency	Run structural consistency checks across artifacts
validate-plan	Validate elaboration plan before starting construction

What It Creates

Standard tier (default)

aidlc-docs/
├── README.md                        ← Project card (name, mode, platform, tier)
├── aidlc-state.md                   ← Session state tracking
├── intents/
│   └── intent-primary.md            ← Blank intent template
├── prompts/                         ← AI-DLC prompt templates
│   ├── mob-elaboration.md
│   ├── mob-construction.md
│   └── code-elevation.md            ← (brownfield only)
├── plan-templates/                  ← Plan templates for AI to populate
│   ├── mob_elaboration_plan.md
│   ├── mob_construction_plan.md
│   └── code_elevation_plan.md       ← (brownfield only)
├── code-elevation/                  ← (brownfield only)
│   ├── static_model.md
│   ├── dynamic_model.md
│   └── technical_debt.md
├── mob-elaboration/
├── mob-construction/
│   ├── bolt-1/ (or bolt-b1/)
│   ├── bolt-2/ (or bolt-b2/)
│   └── bolt-3/ (or bolt-b3/)
├── standards/                       ← Content validation, error handling, question format
├── completion/                      ← Bolt criteria, consistency check, intent consolidation
├── decisions/
│   └── decision-log.md
├── retrospectives/
│   └── session-retrospective.md
├── audit/
│   └── audit-log.md
├── extensions/                      ← Install-on-demand cross-cutting rules
│   ├── README.md
│   └── available.md                 ← Shows installable extensions
├── intent-summaries/
└── archive/

Enterprise tier (--tier enterprise)

Adds on top of standard:

• egs_definition.md — Enterprise Guardrails Specification (10 categories, customize per project)
• mob-elaboration/guardrails_compliance_matrix.md — Story-to-guardrail mapping
• code-elevation/guardrails_gap_analysis.md — Codebase violation-to-guardrail mapping (brownfield only)
• overrides/guardrails_overrides.md — Guardrail exception tracking
• Prompt templates include EGS validation gates at every phase/stage

Extensions

Extensions are cross-cutting rules enforced by the AI at every phase and stage. They are opt-in: browse available extensions with aidlc-kit extensions list, install with aidlc-kit extensions install <name>, and remove with aidlc-kit extensions remove <name>. During pre-flight, the AI also suggests relevant extensions based on your intent.

The security extension has 14 OWASP-aligned rules organized by AI-DLC phase (design, build, ops) with checklist verification and blocking enforcement.

You can also create your own extensions by dropping a .md file in the extensions/ directory.

Options

Modes

• greenfield — New project. Mob Elaboration and Mob Construction prompts.
• brownfield — Existing codebase. Adds Code Elevation prompt and templates for static model, dynamic model, and technical debt analysis.

Platforms

aws, azure, gcp, onprem, agnostic — Tailors the EGS definition template to the target platform.

Tiers

• standard (default) — Core AI-DLC workflow without guardrails enforcement.
• enterprise — Adds EGS guardrails, compliance matrix, gap analysis, and validation gates. Use when you have regulatory, security, or governance requirements.

IDE Support

Generate router configs for your IDE with --ide. Use --ide all for every supported IDE.

Tool	Link
agents-md	agents.md
aider	aider.chat
amp	ampcode.com
auggie	augmentcode.com
claude-code	docs.anthropic.com/claude-code
cline	cline.bot
codebuddy	codebuddy.ai
codex	openai.com/codex
copilot	github.com/features/copilot
copilot-cli	docs.github.com/copilot-cli
costrict	docs.costrict.ai
crush	github.com/charmbracelet/crush
cursor	cursor.com
factory-droid	factory.ai
gemini	gemini.google.com
gemini-cli	github.com/google-gemini/gemini-cli
iflow	iflow.cn
kilo-code	kilocode.ai
kiro	kiro.dev
opencode	opencode.ai
q-developer	aws.amazon.com/q/developer
qoder	qodo.ai
roo-code	roocode.com
windsurf	windsurf.com

Workflow

1. Open your project in your IDE and ask: "Start Mob Elaboration" (or "Start Code Elevation" for brownfield)
2. The AI will ask you to describe your intent (or read it from intents/intent-primary.md if you wrote one ahead of time)
3. AI generates the elaboration plan (stories, units, bolts)
4. Run Mob Construction bolt by bolt
5. Use aidlc-kit check between bolts to validate consistency
6. Use aidlc-kit archive when the intent is complete, then start the next one

For enterprise tier: import your org's EGS with aidlc-kit import-egs <path> before step 1, or let the AI help you set one up during your first session. To create an org-level EGS from scratch, run aidlc-kit egs-init.

Parallel Work (Git Branching)

Work on multiple intents or bolts simultaneously using git branches. Requires a git repository.

# Parallel intents
aidlc-kit intent create "User API"       # branch + start working
aidlc-kit intent create "Notifications"  # from main, creates second branch
aidlc-kit intent list                    # show active intent branches
aidlc-kit intent switch "user-api"       # switch between intents
aidlc-kit intent archive                 # archive, merge to parent, clean up

# Parallel bolts (after elaboration, on an intent branch)
aidlc-kit bolt branch 2                  # branch for Bolt 2 (validates dependencies)
aidlc-kit bolt branch 3                  # branch for Bolt 3 (if independent of Bolt 2)
aidlc-kit bolt list                      # show bolt branches
aidlc-kit bolt merge 2                   # merge completed bolt back to intent

The AI detects branching from the state file and guides you through branch, merge, and archive at the right moments.

Upgrading to Enterprise

Start with standard and upgrade later without re-scaffolding:

aidlc-kit update --tier enterprise

This adds the enterprise-only files and updates templates with EGS validation gates.

License

Business Source License 1.1 — see LICENSE for details.

Free to use for scaffolding and managing your AI-DLC projects. You may not offer this tool, or a derivative, as a competing product or hosted service. Converts to Apache 2.0 on 2030-02-27.