$ 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, on any agent platform.

🌐 Homepage · 📚 Docs · 🎓 Tutorials · 📝 Blog · 📦 npm

npx @rasensio/aidlc init

One command. Any agent.

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, Kiro, Cursor, Windsurf, Codex, GitHub Copilot — and any platform that reads skills. State lives as plain YAML in your repo: no server, no lock-in.

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 — 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

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

aidlc start full-feature --name dark-mode
aidlc status

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 for an interactive menu of the common commands.

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 — npm does not render Mermaid.

The same binary runs in CI. aidlc gate <instance> <phase> 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.

| | | |---|---| | 🚦 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 — 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 <instance> 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 — 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 — npm does not render Mermaid.

| Platform | Config Location | Strategy | |----------|----------------|----------| | Claude Code | .claude/skills/aidlc-*/SKILL.md | Thin activation shims | | Kiro | .kiro/skills/aidlc-*/SKILL.md + steering | Shims + steering file | | Cursor | .cursor/rules/aidlc-*.mdc | Description-based rules | | Windsurf | .windsurf/rules/aidlc-*.md | Size-constrained pointer shims | | Codex | AGENTS.md | Managed delimiter block | | GitHub Copilot | .github/skills/aidlc-*/SKILL.md + .github/copilot-instructions.md | Full bodies + instructions 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:

aidlc metrics

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 — five steps: install, pick a template, run one instance end to end, enforce the gate in CI.

📖 The deep dive — eight short chapters covering everything past that first session:

1. Why the work lives in files
2. How much process is enough
3. The check that says no
4. Notes about your code, kept once
5. What it cost, and what it really cost
6. Ideas that don't evaporate
7. Two people, one checkout
8. Making it yours

Reference material is generated from the shipped packages, so it cannot drift from what you install: CLI reference · phases · skills · templates · guidance layers · glossary.

And 📝 the 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) | Interactive menu of common commands; each entry shows the command it runs | | aidlc menu | The same menu, addressable by name | | aidlc init [--platform <id>] | Set up AIDLC: interactive wizard, or non-interactive with --platform | | aidlc update | Update CLI and refresh project skills | | aidlc gate <instance> [phase] | CI gate check (exit 0 = pass, 1 = fail) | | aidlc start [template] | Begin a new lifecycle instance (--name, --scope, --worktree) | | aidlc continue [instance] | Resume the active instance | | aidlc status [--json] | Show progress across active instances (--all, --prune) | | aidlc transition <instance> | Evaluate gates and advance phase | | aidlc amend <instance> | Record a requirements amendment and reopen the phases it invalidated (--impact is read-only) | | aidlc review <instance> <artifact> | 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 |

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

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. Install one with aidlc compliance add <pack>, 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 — 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.

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.

This repository is a pnpm workspace:

aidlc/
├── docs/                 # How AIDLC works — nine prose pages on why each subsystem exists
├── packages/
│   ├── content/          # @rasensio/aidlc-content — skills, templates, guidance, capabilities
│   ├── 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 |

How this repo works

Reference docs tell you what a command does. docs/ 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.

| Page | What it covers | |---|---| | lifecycle.md | Instances, templates, scope, phases, gates, amendments | | state-and-concurrency.md | State files, claims, the registry, worktrees | | roadmap.md | Capture, triage, promote, and the GitHub Issues projection | | reviews-and-guidance.md | Adversarial review, guidance layers, context docs, the constitution | | cost-tracking.md | What a feature cost, and how the number is attributed | | metrics.md | Change failure rate, lead times, true cost | | knowledge-graph.md | Persistent codebase memory for agents | | skills-and-platforms.md | One canonical skill body, six platform packagings | | 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.

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

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.

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.

• 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.

Contributing

Contributions welcome. Please open an issue first for significant changes.

pnpm install
pnpm build
pnpm test

License

MIT

aidlc.rodrigoasensio.com — docs, tutorials, and the build log