---
slug: "adlc-pi"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/voodootikigod/adlc@main/README.md"
repo: "https://github.com/voodootikigod/adlc"
source_file: "README.md"
branch: "main"
---
# ADLC — Agentic Development Lifecycle Toolkit

[![CI](https://github.com/voodootikigod/adlc/actions/workflows/ci.yml/badge.svg)](https://github.com/voodootikigod/adlc/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)

A workspace of **zero-dependency, gate-shaped Node.js CLIs** for running software
development the way frontier models actually behave — not the way humans do.

The SDLC is 60 years of defenses against *human* failure modes (forgetfulness, ego,
fatigue). Models have a different flaw profile: premature satisfaction, sycophancy,
context rot, confident hallucination, reward hacking. The **Agentic Development
Lifecycle (ADLC)** redesigns every phase, gate, and loop around those flaws. Read the
full thesis in [ADLC.md](https://github.com/voodootikigod/adlc/blob/HEAD/ADLC.md).

---

## Why this exists

> Every phase, gate, and loop in this lifecycle must trace to a specific model failure
> mode it defends against, or a specific model property it exploits. If it traces to a
> human failure mode instead, cut it.

Each tool is a small CLI that enforces one machine-checkable gate. They share a runtime
convention (`.adlc/` for tickets, ledgers, and gate evidence) and a common contract
(see [CONVENTIONS.md](https://github.com/voodootikigod/adlc/blob/HEAD/CONVENTIONS.md)) so 22 independently built tools feel like one
product.

## Install

Each package publishes independently under the `@adlc` npm scope. For normal use,
install the dispatcher and run tools through the stable `adlc <tool>` surface:

```sh
npm install -g @adlc/cli
adlc spec-lint <spec.md>

# or run without installing
npx @adlc/cli spec-lint <spec.md>
```

Individual packages can still be installed for package development, but Codex skills,
hooks, CI, and lifecycle docs should use the dispatcher.

## The toolkit

| Phase | Packages |
| --- | --- |
| **Spec & ticket shaping** | [`parallax`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/parallax) · [`spec-lint`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/spec-lint) · [`premortem`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/premortem) · [`coldstart`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/coldstart) · [`ticket-prune`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/ticket-prune) |
| **Execution supervision & rails** | [`preflight`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/preflight) · [`model-router`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/model-router) · [`merge-forecast`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/merge-forecast) · [`rails-guard`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/rails-guard) · [`build-gate`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/build-gate) · [`flail-detector`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/flail-detector) · [`consensus-fix`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/consensus-fix) · [`runner`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/runner) |
| **Review evidence & calibration** | [`behavior-diff`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/behavior-diff) · [`gate-manifest`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/gate-manifest) · [`hollow-test`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/hollow-test) · [`prosecute`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/prosecute) · [`review-calibration`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/review-calibration) · [`model-ratchet`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/model-ratchet) · [`gate-fuzzing`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/gate-fuzzing) |
| **Compounding defenses** | [`lesson-foundry`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/lesson-foundry) · [`rejection-mining`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/rejection-mining) · [`skill-rot`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/skill-rot) |
| **Shared foundation** | [`@adlc/cli`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/cli) · [`@adlc/core`](https://github.com/voodootikigod/adlc/tree/HEAD/packages/core) |

See [docs/package-reference.md](https://github.com/voodootikigod/adlc/blob/HEAD/docs/package-reference.md) for binaries, command forms,
and per-package detail, and [docs/toolkit.md](https://github.com/voodootikigod/adlc/blob/HEAD/docs/toolkit.md) for how the packages fit
the ADLC flow.

## Use it in Claude Code

This repo is also a Claude Code plugin — it makes the whole lifecycle usable from
inside the editor (phase-routing skill, ticket/distill/maintain commands, a
prosecutor subagent, and hooks that fire the gates automatically), with no API
keys (Claude is the model via `--prompt-only`).

**Recommended:** install with [`plugins`](https://www.npmjs.com/package/plugins), the
vendor-neutral installer that auto-detects your agent tools and installs the plugin
into each (Claude Code today; other harnesses as their plugin packages publish — each
has a native install path below; see [ADR-0009](https://github.com/voodootikigod/adlc/blob/HEAD/docs/adr/0009-universal-install-via-plugins.md)
for why this is the preferred path):

```sh
npx plugins add voodootikigod/adlc   # install the plugin into your agent tool(s)
npm install -g @adlc/cli             # the gate toolkit the plugin shells out to
/adlc:adlc-init                      # bootstrap .adlc/ in your repo (once)
```

Already using Claude Code's native plugin marketplace? That path still works:

```sh
npm install -g @adlc/cli
/plugin marketplace add voodootikigod/adlc
/plugin install adlc@adlc
/adlc:adlc-init
```

See **[docs/integrations/claude-code.md](https://github.com/voodootikigod/adlc/blob/HEAD/docs/integrations/claude-code.md)** for the full adoption guide.

## Use it in other editors

Each agent tool has its own native integration. See the guides:

- **[Codex](https://github.com/voodootikigod/adlc/blob/HEAD/docs/integrations/codex.md)** — hooks-based integration.
- **[Cursor](https://github.com/voodootikigod/adlc/blob/HEAD/docs/integrations/cursor.md)** — preToolUse rails dispatcher, hook parity, command suite + prosecutor loop, rules.
- **[Google Antigravity](https://github.com/voodootikigod/adlc/blob/HEAD/docs/integrations/antigravity.md)** — native plugin system.
- **[OpenCode](https://github.com/voodootikigod/adlc/blob/HEAD/docs/integrations/opencode.md)** — full phase-router coverage.
- **[Pi](https://github.com/voodootikigod/adlc/blob/HEAD/docs/integrations/pi.md)** — TypeScript Extension integration.

## Project layout

| Directory | Contents |
|---|---|
| `packages/` | The toolkit: 22 zero-dependency, gate-shaped CLIs |
| `plugins/adlc-claude-code/` | Claude Code integration (skill, commands, hooks, subagent) |
| `plugins/adlc-codex/` | Codex integration (hooks and skills; no TypeScript package) |
| `plugins/adlc-antigravity/` | Google Antigravity integration (native plugin system, skills, hooks) |
| `plugins/adlc-pi/` | Pi harness integration package (TypeScript, skills, tests) |
| `docs/` | Lifecycle thesis, integration guides, ADRs, CI templates |
| `.claude/commands/` | Maintainer commands for this repo (release workflow) |
| `scripts/` | Release, smoke test, and CI helper scripts (not published; run by `npm test` and CI) |
| `.adlc/` | Runtime data directory (tickets, gate evidence — gitignored except example) |
| `.claude-plugin/` | Repo-root marketplace manifest (`marketplace.json`) — the index `npx plugins add voodootikigod/adlc` (and the native `/plugin marketplace add voodootikigod/adlc`) read to resolve the plugin. See [ADR 0003](https://github.com/voodootikigod/adlc/blob/HEAD/docs/adr/0003-adlc-claude-code-plugin.md) for the subdirectory-source assumption and Pre-GA checklist. |

## Design principles

Every tool follows the same contract ([CONVENTIONS.md](https://github.com/voodootikigod/adlc/blob/HEAD/CONVENTIONS.md)):

- **Zero runtime dependencies** — Node 18+ built-ins and `@adlc/core` only.
- **`--prompt-only`** on every LLM-backed tool — print the exact prompt and exit, so the
  tool is usable with zero API keys (paste into any harness).
- **`--json`** on every tool — machine-readable output for orchestrators.
- **Exit codes are the gate**: `0` = gate passes · `1` = operational error · `2` = gate fails.
- **Never mutate the working tree without a flag** — writers default to dry-run.
- **Tests run offline** — no network, no API keys, no trace left behind.

## Quick start (from source)

```sh
git clone https://github.com/voodootikigod/adlc.git
cd adlc
npm install
npm test
```

Requires **Node.js 18 or newer**.

## Documentation

- [ADLC.md](https://github.com/voodootikigod/adlc/blob/HEAD/ADLC.md) — the full lifecycle thesis and flaw inventory.
- [docs/integrations/claude-code.md](https://github.com/voodootikigod/adlc/blob/HEAD/docs/integrations/claude-code.md) — adopt the ADLC inside Claude Code (plugin).
- [docs/integrations/codex.md](https://github.com/voodootikigod/adlc/blob/HEAD/docs/integrations/codex.md) — native Codex integration guide.
- [docs/integrations/pi.md](https://github.com/voodootikigod/adlc/blob/HEAD/docs/integrations/pi.md) — pi coding-agent harness integration guide.
- [docs/](https://github.com/voodootikigod/adlc/blob/HEAD/docs/README.md) — toolkit guide, package reference, ADRs, and narrative essays.
- [CONVENTIONS.md](https://github.com/voodootikigod/adlc/blob/HEAD/CONVENTIONS.md) — the contract every package follows.

## Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](https://github.com/voodootikigod/adlc/blob/HEAD/CONTRIBUTING.md) for the dev
setup, the package contract, the testing requirements, and the PR process. By
participating you agree to our [Code of Conduct](https://github.com/voodootikigod/adlc/blob/HEAD/CODE_OF_CONDUCT.md).

- 🐛 [Report a bug](https://github.com/voodootikigod/adlc/issues/new?template=bug_report.yml)
- 💡 [Request a feature](https://github.com/voodootikigod/adlc/issues/new?template=feature_request.yml)
- 🔒 [Report a vulnerability](https://github.com/voodootikigod/adlc/blob/HEAD/SECURITY.md)

## License

[MIT](https://github.com/voodootikigod/adlc/tree/HEAD/LICENSE) © Chris Williams