Skip to content

ADLC5 Overview

Jump to bottom
dango85 edited this page Oct 13, 2026 · 4 revisions

ADLC5 — A repeatable workflow for AI-assisted coding

Turn a feature request into a reviewed, test-backed change with a process you can repeat.

ADLC5 is an open-source coding harness that brings structure to AI-assisted software work. It combines agent skills for reasoning with a deterministic command-line kernel for workflow state, transitions, and checks. You keep your existing repository, tools, and agent host; ADLC5 provides a clearer path from a request to a pull request that is ready for review.

Public preview: ADLC5 has tested workflow contracts. Comparative coding-quality results and qualification with outside contributors are still pending. ADLC5 makes work and evidence more repeatable; it does not guarantee correct or defect-free software.

From request to review

ADLC5 guides work through four stages:

  1. Specify — define behavior, constraints, acceptance criteria, and risk.
  2. Plan — inspect the existing code and choose a focused approach.
  3. Tasks — break work into bounded units with checkable specs when useful.
  4. Implement — make the change, run the declared checks, and capture current evidence for review.

The depth scales with the work. A small change can stay in one short feature note. Higher-risk work can include detailed design, independent critique, QA, and human approval.

What makes the workflow different

  • A deterministic kernel handles repeatable decisions. Scripts validate state and gates; the model does not decide whether a required check passed.
  • Evidence is tied to the change. Checks use commands declared by the consumer project. Relevant edits make earlier evidence stale, so pr-ready reflects current inputs.
  • Acceptance stays with your project. ADLC5 helps structure the work; your team defines what success means and which tests matter.
  • Use the tools you already have. Install the skills for a supported agent host, then call the same kernel through its CLI or optional MCP interface.
  • Keep project work in your repository. ADLC5 feature state and artifacts live in your consumer project, not in a remote ADLC5 service.

Get started

Install ADLC5, initialize it in an application repository, and start a feature:

git clone https://github.com/dango-tech/adlc5.git
cd adlc5
cp config.example.yaml config.yaml
./scripts/install.sh --platform codex  # replace codex with your agent host
./scripts/verify-install.sh --platform codex

# From your application repository:
/path/to/adlc5/scripts/init-workspace.sh --project .
/path/to/adlc5/scripts/init-feature.sh --feature my-feature --interaction hitl

Then ask your agent to run @adlc5 for my-feature. See the installation guide for other hosts and update steps.

Native plugins: Codex, Claude Code, and Cursor

The repository builds self-contained packages for Codex, Claude Code, and Cursor from shared skills and runtime sources. Build and registration instructions for all three hosts, including public marketplace submission steps, are in the agent plugin guide.

python3 scripts/package-plugin.py --check
python3 scripts/package-plugin.py --out /tmp/adlc5-dist

The output includes one package per host plus local marketplace roots for Codex and Claude Code. Install a plugin for your host, then invoke adlc5-setup in your application repository. Feature state stays in the consumer repository's .adlc5/, never in the plugin. Package builds are separate from public marketplace listings, which require host-specific submission and review.

Existing repositories: brownfield initialization and JSON indexing

ADLC5 starts from your existing codebase. Run init-workspace.sh --project . once before the first feature. It preserves existing constitution files, creates missing drafts under .agents/ and an ADR area under docs/adr/, and builds generated repository intelligence in the gitignored .agent-cache/ directory. Review the architecture, boundaries, and commands in .agents/, then run:

/path/to/adlc5/scripts/adlc5 repo-spec validate --workspace .
/path/to/adlc5/scripts/adlc5 repo-index check --workspace .

The codebase is indexed into JSON, not copied wholesale into JSON. Six files capture local structural context:

Artifact in .agent-cache/ Contents
manifest.json Snapshot fingerprint and generated artifact list
repo-index.json Repository summary, languages, and modules
module-map.json Source and test files grouped by module
symbols.json Supported declarations with file paths and line numbers
dependency-graph.json Extracted import edges
test-map.json Test locations and heuristic source/test matches

The scan covers eligible source files and workspace manifests across the repository. Generated/dependency folders, symlinks, and recognized secret files are excluded. Symbol/import extraction varies by language; the index does not store source bodies or provide a complete semantic model. Agents load relevant records, then inspect source where needed.

Feature initialization refreshes the index. After other changes, run adlc5 repo-index refresh --workspace . if the check reports stale intelligence. Commit reviewed constitution files and ADRs; keep .agent-cache/ ignored.

For team-shared knowledge, initialize with --with-project-wiki, then run /path/to/adlc5/scripts/wiki/ingest-repo.sh --workspace .. Ingest produces draft entity stubs and a source manifest; humans review evidence before promotion to wiki/entities/. Feature initialization also bootstraps this optional wiki when the brownfield repository profile warrants it. See repository context and the project wiki guide.

What pr-ready means

pr-ready means the selected profile's required checks and review evidence passed for the current inputs. It is a readiness signal for human review—not a claim that code has been deployed, is publicly available, or is free of defects. Local state is procedural evidence and is not a security boundary against someone who can arbitrarily modify the worktree.

Current validation and limits

The repository tests workflow contracts on Ubuntu and macOS and includes disposable installation and distribution checks. Host validation is not uniform: the README describes which adapters have packaged tests. The evaluation fixtures are designed to report missing observations honestly; they are not comparative coding-quality results. The Claude Code plugin package has archive, MCP stdio, bootstrap, and hook tests plus a recorded live local session (setup, gate check, engagement warning, resume); a full human-approved lifecycle on it and live Codex qualification are still pending. Live delivery and resume behavior still need qualification for each host before broader claims.

Join the project

ADLC5 is public preview software, and focused, evidence-backed contributions are welcome. Start with a reproducible issue, explain the failure your change prevents, and run the checks in Contributing. Browse the source repository, open an issue, or review the README and technical references.

Clone this wiki locally