# `$ aidlc_`
## AI codes fast. AIDLC makes it ship right.
A real software lifecycle for AI coding agents: **phases, gates, state, and traceability** โ from idea to maintenance, in Claude Code and Codex.
[](https://www.npmjs.com/package/@rasensio/aidlc)
[](https://www.npmjs.com/package/@rasensio/aidlc)
[](https://nodejs.org)
[](https://github.com/rasensio/aidlc/blob/main/LICENSE)
[](https://aidlc.rodrigoasensio.com)
**[๐ Homepage](https://aidlc.rodrigoasensio.com)** ยท [๐ Docs](https://aidlc.rodrigoasensio.com/docs/) ยท [๐ Tutorials](https://aidlc.rodrigoasensio.com/tutorials/) ยท [๐ Blog](https://aidlc.rodrigoasensio.com/blog/) ยท [๐ฆ npm](https://www.npmjs.com/package/@rasensio/aidlc) ยท [๐ฌ Feedback](#feedback)
```bash
npx @rasensio/aidlc init
```
**One command. Claude Code or Codex.**
---
## The problem isn't speed
Agents outpace the capacity to review what they produce. What's missing isn't throughput โ it's the lifecycle around it:
- requirements anyone actually agreed to
- designs anyone actually challenged
- tests mapped to the criteria they're supposed to prove
- a record of why decisions were made
AIDLC adds that missing lifecycle **without slowing the agent down**. It works with **Claude Code** and **Codex**. State lives as plain YAML in your repo: no server, no lock-in.
## Why v2: Claude Code and Codex only
AIDLC 2 supports two platforms: Claude Code and Codex. Cursor, Windsurf, Kiro and GitHub Copilot are no longer supported.
We are focusing on the top contenders. Two platforms built and tested well beat six built thinly. Every skill, hook and install change used to be shaped six ways, and the four we dropped always got a lesser version. Claude Code and Codex are where the native features exist: plugins, hooks, skill metadata, typed agent results and token cost.
If your project is set up for a dropped platform:
- Your existing files are left alone. Nothing is deleted.
- `aidlc update` says so once, and tells you how to silence it.
- To keep updating those files, stay on 1.x: `npm i -g @rasensio/aidlc@1`.
- Need your platform back? Say so at [github.com/rasensio/aidlc-feedback/issues](https://github.com/rasensio/aidlc-feedback/issues).
## The loop
An idea arrives mid-task, gets captured in five seconds, and comes back out the far end with a number attached to it.
> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#the-loop)** โ npm does not render Mermaid.
Nothing in that picture lives in a database. Every box is a file in your repository, readable by the next agent, the next session, and you.
## Quick Start
```bash
# 1 โ Set up once (interactive wizard, or pass --platform to skip prompts)
npx @rasensio/aidlc init --platform claude-code
```
Then work from your AI coding tool. In Claude Code, invoke the entry point:
```
/aidlc
```
It reads your lifecycle state and offers the next actions โ continue an in-progress instance, start something new, check status, or review an artifact. You can also just describe what you want ("help me fix a bug") and the matching skill activates on its own.
Prefer the terminal? The same state protocol is addressable directly:
```bash
aidlc start full-feature --name dark-mode
aidlc status
```
```text
Name Template Phase Completion Owner Stalled Cost Coverage Tasks
------------------ ------------ -------------- ---------- ---------- ------- ----- -------- -------
20260821-dark-mode full-feature implementation 57% session-a1 no $4.18 12/14 9/12 โธ1
20260824-login-500 bugfix testing 80% - no $0.92 3/3 4/4
```
Or run `aidlc` with no arguments to open the console: a full-screen dashboard with autopilot,
the roadmap, unfinished instances and spend in view, in colour. One key acts on the selected row โ
`a` approves an item waiting for review, `r` runs autopilot, `n` starts the next roadmap item โ and
Ctrl-K finds any command or action by typing. `c` opens your own Claude Code or Codex in a drawer
under the autopilot panel, where `/doctor` and `!git status` still work. `?` lists every key; `q`
leaves and never stops a run. On a terminal narrower than 60 columns you get the one-column console
instead.
## The gate is the whole idea
A phase doesn't end because an agent says it did. It ends when the gate lets it.
> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#the-gate-is-the-whole-idea)** โ npm does not render Mermaid.
The same binary runs in CI. `aidlc gate ` exits 0 when the phase is complete and 1 when it isn't, so a pull request can be blocked by the identical check the agent just faced โ see [`ci/aidlc-gate.yml`](https://github.com/rasensio/aidlc/blob/main/ci/aidlc-gate.yml).
| | |
|---|---|
| **๐ฆ Phases with gates** | Each phase exits through a gate that requires artifacts, adversarial review, and a test per criterion. Agents cannot skip ahead. |
| **๐พ State on disk** | Lifecycle state is YAML under `.aidlc/` โ readable across agents, sessions, and git worktrees. Claims stop concurrent sessions from colliding. |
| **๐ Traceability built in** | Every acceptance criterion gets an ID. Tasks reference criteria; tests reference both. The gate fails on any criterion without a test. |
## How much process? Pick a template
Ceremony that fits a new subsystem will make people route around a typo fix. So the amount of lifecycle is a choice you make per piece of work, and it is the choice worth getting right.
> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#how-much-process-pick-a-template)** โ npm does not render Mermaid.
| Template | Scope | Description |
|----------|-------|-------------|
| `full-feature` | full | Full lifecycle from ideation through maintenance with adversarial review gates |
| `quick-feature` | standard | Standard feature workflow from requirements through deployment |
| `bugfix` | standard | Bug fix workflow with reproduction steps, no design phase |
| `spike` | standard | Spike or research workflow for exploration and findings documentation |
| `micro-task` | micro | Minimal workflow for small tasks requiring only implementation and testing |
**Scope** is the second dial, and the one people get wrong: it is not how big or ambitious the work is, it is which phases run. **Full** (all phases), **Standard** (Requirements โ Deployment), **Micro** (Implementation + Testing only). A large change with a settled design is standard; a small change nobody has thought about is full.
## Lifecycle Phases
| Phase | Purpose |
|-------|---------|
| Ideation | Explore and validate ideas, identify alternatives |
| Requirements | Define acceptance criteria, scope, and constraints |
| Design | Produce architecture and technical design documents |
| Implementation | Write code following established conventions |
| Testing | Validate correctness and coverage |
| Deployment | Release to target environment |
| Maintenance | Monitor, patch, and evolve |
When requirements move after their phase closed, `aidlc amend ` retires the old criterion, issues a replacement, and reopens exactly the phases that assumption invalidated โ so drift shows up in history instead of hiding behind gates that all still pass.
## Two people, one repo
Claims are a lease on an instance, not a lock on the filesystem. They are what keeps two sessions from silently overwriting each other's phase.
> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#two-people-one-repo)** โ npm does not render Mermaid.
For genuinely concurrent work, use a worktree: `aidlc start --worktree` puts the second instance in its own checkout, because two sessions in one checkout collide on git long before they collide on state.
## Supported Platforms
One canonical skill body is written once and packaged into whatever each tool reads natively.
> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#supported-platforms)** โ npm does not render Mermaid.
| Platform | Config Location | Strategy |
|----------|----------------|----------|
| Claude Code | `.claude/skills/aidlc-*/SKILL.md` | Thin activation shims |
| Codex | `.agents/skills/aidlc-*/SKILL.md` + `AGENTS.md` | Skills + managed delimiter block |
Switching assistants, or having two people on different ones, doesn't fork your process: the rules are in your repository, the packaging is per-tool.
## It Closes the Loop
Most tooling stops at "the feature shipped." AIDLC keeps measuring after that, from state you already have:
```bash
aidlc metrics
```
```text
Feedback-loop metrics (attribution: full-count-per-cause)
Coverage: 14 instances, 5 with defect linkage, 12 with cost data
By template:
full-feature: 6 completed, change failure rate 33%, avg lead time 2.4d
phases: ideation 3.1h, requirements 5.8h, design 7.2h, implementation 1.4d
bugfix: 5 completed, change failure rate 0%, avg lead time 4.6h
By instance:
20260821-dark-mode (full-feature): complete, lead 2.1d, cost $4.18, caused 1 bugfix(es), true cost $5.10
```
- **`aidlc metrics`** โ DORA-style roll-ups: change failure rate per template, lead time per phase, and true feature cost including the bugfixes it caused
- **`aidlc cost`** โ per-instance cost tracking with metered capture across every session that touched the instance
- **`caused_by`** โ links a bugfix back to the feature that produced it, so quality leaks become measurable instead of anecdotal
## Learn it
The tutorials are on the website, where the terminal transcripts are interactive.
**[๐ Getting Started](https://aidlc.rodrigoasensio.com/tutorials/getting-started/)** โ five steps: install, pick a template, run one instance end to end, enforce the gate in CI.
**[๐ The deep dive](https://aidlc.rodrigoasensio.com/tutorials/deep-dive/)** โ eight short chapters covering everything past that first session:
1. [Why the work lives in files](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-why-files/)
2. [How much process is enough](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-how-much-process/)
3. [The check that says no](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-gates-that-say-no/)
4. [Notes about your code, kept once](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-memory/)
5. [What it cost, and what it really cost](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-what-it-cost/)
6. [Ideas that don't evaporate](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-ideas-you-keep/)
7. [Two people, one checkout](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-two-people/)
8. [Making it yours](https://aidlc.rodrigoasensio.com/tutorials/deep-dive-making-it-yours/)
Reference material is generated from the shipped packages, so it cannot drift from what you install: **[CLI reference](https://aidlc.rodrigoasensio.com/docs/cli/)** ยท **[phases](https://aidlc.rodrigoasensio.com/docs/phases/ideation/)** ยท **[skills](https://aidlc.rodrigoasensio.com/docs/skills/overview/)** ยท **[templates](https://aidlc.rodrigoasensio.com/docs/templates/bugfix/)** ยท **[guidance layers](https://aidlc.rodrigoasensio.com/docs/guidance/secure-defaults/)** ยท **[glossary](https://aidlc.rodrigoasensio.com/docs/glossary/)**.
And [๐ the blog](https://aidlc.rodrigoasensio.com/blog/) has a post per release, written the moment the work landed โ including the ones where it went wrong.
## CLI Commands
The CLI has two core jobs: **bootstrap** (installing and refreshing skills โ the step that can't be a skill) and **CI enforcement** (`aidlc gate`, which runs where no agent does). Lifecycle work itself happens inside your AI tool via skills; the runtime commands below remain available as terminal shortcuts for the same state protocol.
| Command | Purpose |
|---------|---------|
| `aidlc` (no arguments) | The console: a full-screen dashboard of autopilot, roadmap, instances and spend; one key per action, Ctrl-K for everything, your agent in a drawer |
| `aidlc menu` | The same console, addressable by name |
| `aidlc init [--platform ]` | Set up AIDLC: interactive wizard, or non-interactive with `--platform` |
| `aidlc update` | Update CLI and refresh project skills |
| `aidlc gate [phase]` | CI gate check (exit 0 = pass, 1 = fail) |
| `aidlc start [template]` | Begin a new lifecycle instance (`--name`, `--scope`, `--worktree`, `--no-open`) |
| `aidlc continue [instance]` | Resume the active instance |
| `aidlc status [--json]` | Show progress across active instances (`--all`, `--prune`) |
| `aidlc transition ` | Evaluate gates and advance phase |
| `aidlc amend ` | Record a requirements amendment and reopen the phases it invalidated (`--impact` is read-only) |
| `aidlc review ` | Adversarial review of a lifecycle artifact |
| `aidlc metrics [--json]` | DORA-style metrics: change failure rate, lead times, true cost |
| `aidlc cost` | Per-instance cost tracking: reports, capture, rates, hooks |
| `aidlc claim` / `release` | Claim or release an instance for this session |
| `aidlc knowledge` | Local knowledge graph โ persistent codebase memory for agents |
| `aidlc discover` | Scan codebase, generate context docs |
| `aidlc docs` | Generate onboarding documentation |
| `aidlc doctor` | Check and repair repo hygiene |
| `aidlc constitution` | Import a product vision document and track the repo scope derived from it |
| `aidlc compliance` | Install compliance packs and report evidence per control (`list`, `add`, `remove`, `check`, `report`) |
| `aidlc roadmap` | Project the roadmap onto GitHub Issues (`sync`), or seed an item from one (`import`) |
| `aidlc add` | Add framework components: an `action` on a lifecycle event, or an app-owned `skill` |
Non-interactive setup (CI or agent-driven)
```bash
# Apply defaults (or keep the existing config) without prompts
npx @rasensio/aidlc init --non-interactive
# Add a platform and install its skills without prompts
npx @rasensio/aidlc init --platform claude-code
```
## Configuration
Project configuration lives in `.aidlc/config.yaml`:
```yaml
version: 1
defaults: { scope: micro, template: micro-task }
stalled_threshold_days: 7
claim_timeout_minutes: 60
```
Without this file, AIDLC defaults to Micro scope (Implementation + Testing only).
## Compliance packs
A compliance pack applies a regime's controls while code is written and reports the
evidence the lifecycle already produces. Packs are opt-in: with none installed,
nothing changes. Two ship: `soc2` (the SOC 2 Common Criteria) and `iso27001` (ISO/IEC
27001:2022 Annex A). Install one with `aidlc compliance add `, and it applies from
the next phase โ advisory by default, so findings are recorded and reported without
blocking. Set `compliance.enforce: true` in `.aidlc/config.yaml` to make a critical
control finding block a phase transition.
Packs describe themselves as guidance toward a regime. Nothing a pack emits states or
implies that a project is compliant, certified, or audit-ready.
`aidlc compliance check` assesses a change against the installed controls, for use in
continuous integration. Its exit codes:
| Exit | Meaning |
|------|---------|
| 0 | No failing control, or failures present in advisory mode |
| 1 | A failing critical control, with `--enforce` |
| 2 | Usage or pack-load error, or a control left unassessed with `--enforce` |
`--enforce` raises the exit code for that one invocation and reads no config, so a
failing pull-request check does not require blocking every local phase transition. An
unassessed control exits non-zero under `--enforce` rather than passing silently: a
control nothing looked at is never a pass.
## Architecture
Three packages, one direction of dependency.
> **[View this diagram on GitHub](https://github.com/rasensio/aidlc/blob/main/README.md#architecture)** โ npm does not render Mermaid.
- **`@rasensio/aidlc-content`** โ Knowledge layer. Skills, templates, guidance documents, capability maps, and phase definitions. The single source of truth for what AIDLC knows about lifecycle phases.
- **`@rasensio/aidlc`** (CLI) โ Engine. Orchestrates lifecycle state, compiles skills into platform-native formats, evaluates transition gates, and manages instance sessions.
- **`@rasensio/aidlc-website`** โ Documentation and marketing site at [aidlc.rodrigoasensio.com](https://aidlc.rodrigoasensio.com).
Content is the shared dependency. The CLI reads it at compile time to produce installable artifacts. The website reads it at build time to generate documentation pages โ which is why the reference docs cannot describe a command the binary doesn't have.
Monorepo structure
This repository is a pnpm workspace:
```
aidlc/
โโโ packages/
โ โโโ content/ # @rasensio/aidlc-content โ skills, templates, guidance, capabilities,
โ โ # and docs/: nine prose pages on why each subsystem exists
โ โโโ cli/ # @rasensio/aidlc โ CLI tool (npm package)
โ โโโ website/ # @rasensio/aidlc-website โ documentation website (Next.js)
โโโ ci/ # CI pipeline configuration
โโโ pnpm-workspace.yaml
โโโ tsconfig.json # Shared compiler options + project references
โโโ package.json # Workspace-level scripts
```
| Package | Description | Published |
|---------|-------------|-----------|
| `@rasensio/aidlc-content` | Shared content (skills, templates, guidance layers, capability maps) | npm |
| `@rasensio/aidlc` | CLI tool โ lifecycle engine, platform adapters, state management | npm |
| `@rasensio/aidlc-website` | Marketing site + documentation (Next.js, Tailwind, static export) | AWS Amplify โ [aidlc.rodrigoasensio.com](https://aidlc.rodrigoasensio.com) |
## How this repo works
Reference docs tell you *what* a command does. [**`packages/content/docs/`**](https://github.com/rasensio/aidlc/blob/main/packages/content/docs/README.md) tells you *why the subsystem exists and what breaks without it* โ nine pages, written for a person trying to understand the system and for an agent about to change it. Read the relevant page before modifying a subsystem: several of these designs look arbitrary until you know which bug bought them.
The pages ship inside `@rasensio/aidlc-content`, so a project that installed AIDLC can read them without this repository: `aidlc explain` lists them and `aidlc explain ` prints one. Nothing is copied into your project.
| Page | What it covers |
|---|---|
| [lifecycle.md](https://github.com/rasensio/aidlc/blob/main/packages/content/docs/lifecycle.md) | Instances, templates, scope, phases, gates, amendments |
| [state-and-concurrency.md](https://github.com/rasensio/aidlc/blob/main/packages/content/docs/state-and-concurrency.md) | State files, claims, the registry, worktrees |
| [roadmap.md](https://github.com/rasensio/aidlc/blob/main/packages/content/docs/roadmap.md) | Capture, triage, promote, and the GitHub Issues projection |
| [reviews-and-guidance.md](https://github.com/rasensio/aidlc/blob/main/packages/content/docs/reviews-and-guidance.md) | Adversarial review, guidance layers, context docs, the constitution |
| [cost-tracking.md](https://github.com/rasensio/aidlc/blob/main/packages/content/docs/cost-tracking.md) | What a feature cost, and how the number is attributed |
| [metrics.md](https://github.com/rasensio/aidlc/blob/main/packages/content/docs/metrics.md) | Change failure rate, lead times, true cost |
| [knowledge-graph.md](https://github.com/rasensio/aidlc/blob/main/packages/content/docs/knowledge-graph.md) | Persistent codebase memory for agents |
| [skills-and-platforms.md](https://github.com/rasensio/aidlc/blob/main/packages/content/docs/skills-and-platforms.md) | One canonical skill body, two platform packagings |
| [hygiene-and-compliance.md](https://github.com/rasensio/aidlc/blob/main/packages/content/docs/hygiene-and-compliance.md) | `aidlc doctor`, compliance packs |
## Development
**Prerequisites:** Node.js >= 22.13 (the CLI's knowledge graph uses the built-in `node:sqlite` module, unflagged since 22.13) and pnpm >= 9.5 (the first with catalogs, where `pnpm-workspace.yaml` declares the shared dev-tool versions).
```bash
pnpm install
pnpm build # content first, then CLI + website in parallel
pnpm test # all tests, one package at a time (see note below)
pnpm lint # type-check all packages
pnpm --filter @rasensio/aidlc-website dev # work on the site locally
```
Tests use **vitest** (unit + integration) and **fast-check** (property-based testing):
```bash
pnpm --filter @rasensio/aidlc test
pnpm --filter @rasensio/aidlc-content test
pnpm --filter @rasensio/aidlc-website test
```
`pnpm test` is `pnpm -r --workspace-concurrency=1 test` โ the packages run one at a
time, deliberately. vitest already parallelises test files across workers, so a
second axis of parallelism oversubscribes the CPU and pushes subprocess-spawning
tests past their timeout. Measured on an idle machine: 263s for `packages/cli` with
two 30-second timeouts when the packages run concurrently, against 71s and 75s for
the whole workspace when they do not. Serialising is both faster and greener โ
please don't change it back.
Every push to `main` and every pull request runs the same gate as a release โ
`pnpm build`, `pnpm lint`, `pnpm test` โ via [`.github/workflows/ci.yml`](https://github.com/rasensio/aidlc/blob/main/.github/workflows/ci.yml).
**One caution, learned the hard way:** during development invoke the workspace build,
`node packages/cli/dist/cli.js`, never `npx aidlc`. `npx` prefers a globally installed
binary, and it once reported "0 files updated, 35 unchanged" while the edited files sat
changed on disk.
Project conventions & migration notes
- TypeScript, ES modules, Node >= 22.13
- Pure-function core (no I/O) with I/O pushed to edges
- Pinned dependencies
- Property-based tests for core logic
- Content package uses `import.meta.url` for path resolution
> **Migration note (v1.0):** the CLI previously ran on Node >= 18. The local
> knowledge graph feature raised the floor to Node 22.13+ to use `node:sqlite`
> with zero native dependencies. Users on Node 18/20 must upgrade their Node
> runtime (e.g. `nvm install 22`); no other migration steps are required.
## Feedback
Found a bug, or missing something? Post it at [github.com/rasensio/aidlc-feedback/issues](https://github.com/rasensio/aidlc-feedback/issues). Anyone with a GitHub account can post there; you do not need access to the source repo, which is private. Requests for a platform AIDLC does not support are welcome too: they are counted, and the count is read when deciding what to support.
## Contributing
Contributions welcome. Please [open an issue](https://github.com/rasensio/aidlc-feedback/issues) first for significant changes.
```bash
pnpm install
pnpm build
pnpm test
```
## License
[MIT](https://github.com/rasensio/aidlc/blob/main/LICENSE)
---
**[aidlc.rodrigoasensio.com](https://aidlc.rodrigoasensio.com)** โ docs, tutorials, and the build log