Metadata-Version: 2.4
Name: aidlc-kit
Version: 0.3.3
Summary: Scaffold AI-DLC projects with enterprise guardrails, prompts, and compliance templates.
Author-email: Ricardo González Vargas <rgonv@hotmail.com>
License: BUSL-1.1
License-File: LICENSE
Keywords: ai-dlc,enterprise,governance,guardrails,scaffold
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Description-Content-Type: text/markdown

# aidlc-kit

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

**aidlc-kit** is the companion CLI tool for the [AI-DLC methodology](https://prod.d13rzhkk8cj2z0.amplifyapp.com/), 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](https://leanpub.com/reimaginedontretrofit) 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

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

## Quick Start

```bash
# 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 |
| `export-egs` | Export the project's EGS definition to a file |
| `import-egs` | Import an external EGS definition into the project |
| `consistency` | Run structural consistency checks across artifacts |

## 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/                      ← Drop-in cross-cutting rules
│   ├── README.md
│   └── security-extensions.md       ← 14 security rules (OWASP-aligned, blocking)
├── 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

The `extensions/` directory contains cross-cutting rules enforced by the AI at every phase and stage. The included security extension has 14 rules organized by AI-DLC phase (design, build, ops) with checklist verification and blocking enforcement. During pre-flight, the AI asks whether to enable each extension; the answer is recorded in the state file.

Add your own extensions by dropping a `.md` file in the directory. Remove an extension by deleting its file.

## 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](https://agents.md/) |
| aider | [aider.chat](https://aider.chat/) |
| amp | [ampcode.com](https://ampcode.com/) |
| auggie | [augmentcode.com](https://www.augmentcode.com/) |
| claude-code | [docs.anthropic.com/claude-code](https://docs.anthropic.com/en/docs/claude-code/overview) |
| cline | [cline.bot](https://cline.bot/) |
| codebuddy | [codebuddy.ai](https://codebuddy.ai/) |
| codex | [openai.com/codex](https://openai.com/index/openai-codex/) |
| copilot | [github.com/features/copilot](https://github.com/features/copilot) |
| copilot-cli | [docs.github.com/copilot-cli](https://docs.github.com/en/copilot/how-tos/copilot-cli) |
| costrict | [docs.costrict.ai](https://docs.costrict.ai/) |
| crush | [github.com/charmbracelet/crush](https://github.com/charmbracelet/crush) |
| cursor | [cursor.com](https://www.cursor.com/) |
| factory-droid | [factory.ai](https://www.factory.ai/) |
| gemini | [gemini.google.com](https://gemini.google.com/) |
| gemini-cli | [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) |
| iflow | [iflow.cn](https://platform.iflow.cn/en/cli/quickstart) |
| kilo-code | [kilocode.ai](https://kilocode.ai/) |
| kiro | [kiro.dev](https://kiro.dev/) |
| opencode | [opencode.ai](https://opencode.ai/) |
| q-developer | [aws.amazon.com/q/developer](https://aws.amazon.com/q/developer/) |
| qoder | [qodo.ai](https://www.qodo.ai/) |
| roo-code | [roocode.com](https://roocode.com/) |
| windsurf | [windsurf.com](https://windsurf.com/) |

## Workflow

1. Open your project in your IDE and ask: "Start Mob Elaboration"
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, also customize `egs_definition.md` before step 1.

## Upgrading to Enterprise

Start with standard and upgrade later without re-scaffolding:

```bash
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](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.
