Set up an AI-DLC workspace, and know what every file is for.

AWS AI-DLC never runs inside your code repo. It runs from a workspace: a folder around the repo that holds your team's rules, the tool's harness for Claude Code, and the record of every run. This page builds one from scratch with four commands and explains every command and every file they create. All output is real, from AI-DLC Workflows 2.11.0 on Claude Code; nothing on this page needs an AI session until step 7.

4commands: config, workspace-sync, doctor, commit

324files written by aidlc config

314of them in .claude/, for Claude Code

10files in the first commit (423 lines)

1code repo, cloned from repos.json

0problems from aidlc doctor

Once per machinestep 1 · a few minutes

your machine

Install the aidlc command and Claude Code

aidlc is one self-contained program: it installs AI-DLC's workflow files into projects and checks them. Claude Code is the assistant that runs the workflow. Neither touches your code until you ask.

Once per machine

You type PowerShellTerminal (macOS)

irm https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.ps1 | iex
aidlc --version
claude --version

curl -fsSL https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.sh | sh
aidlc --version
claude --version

You see real output · your Claude Code version will differ

aidlc 2.11.0 (runtime 2.11.0)
2.1.299 (Claude Code)

Command	What it does, in its own words (`aidlc --help`)
`aidlc version` / `--version`	Print binary and runtime versions. The binary is the program; the runtime is the set of workflow files it copies into projects.
`aidlc update`	Install and switch to a newer release. `--check` only looks; `--dry-run` shows the plan; `--channel preview` for pre-releases.
`aidlc use <version>`	Switch to an exact installed release, e.g. to match a teammate.
`aidlc uninstall`	Remove aidlc from this machine; see `aidlc uninstall --help` for `--purge`.
`aidlc config`, `aidlc doctor`	Set up and check a project: steps 3 and 5.

Claude Code must be signed in (claude opens, /help answers). AI-DLC does not choose a model or provider: Claude Code keeps your subscription, API key, Bedrock or gateway setup.

The workspacesteps 2–6 · four commands and a commit

yours, not the tool

Write the team's files: start from an empty folder

A workspace starts as an empty git repo and a few files people write: the house rules, the list of code repos, the test command. Nothing comes from a template or from AI-DLC: the commands below create every file (the same text is in the tabs, to read or to write in an editor instead). AI-DLC reads these files; it never writes them.

The workspace

You type PowerShellTerminal (macOS)

mkdir C:\work\java-workspace\scripts -Force | Out-Null
cd C:\work\java-workspace
git init -b main
[IO.File]::WriteAllText("$PWD\CLAUDE.md", (@'
# java-workspace

Run AI-DLC from this folder. One code repo, `priorauth-api/`, a Spring Boot 4.1 REST API on Java 21, built with Maven.

| Repo          | Owns                                   | Verify with      | Branch pattern       |
|---------------|----------------------------------------|------------------|----------------------|
| priorauth-api | the API the reviewer screen reads      | `mvn -q test`    | request-age/<slug>   |

Rules: the record in `aidlc/` is the source of truth for requirements and decisions; commit it after every gate.
One unit = one branch = one PR. Tests through `./scripts/verify.sh` (`scripts\verify.cmd` on Windows), never ad hoc.
Never add a dependency to pom.xml inside a unit without saying so in the plan.
'@ -replace "`r", "") + "`n")
[IO.File]::WriteAllText("$PWD\repos.json", (@'
{
  "org": "acme-health",
  "repos": [
    { "name": "priorauth-api", "branch": "main", "url": "https://github.com/varasrinivas/aidlc-priorauth-api.git" }
  ]
}
'@ -replace "`r", "") + "`n")
[IO.File]::WriteAllText("$PWD\scripts\verify.sh", (@'
#!/usr/bin/env bash
# The one verification command for this workspace (approved at Code Generation, run after every unit).
set -uo pipefail
cd "$(dirname "$0")/../priorauth-api"
mvn -q test
'@ -replace "`r", "") + "`n")
[IO.File]::WriteAllText("$PWD\scripts\verify.cmd", (@'
@echo off
rem The one verification command for this workspace (Windows twin of verify.sh).
cd /d "%~dp0..\priorauth-api" && mvn -q test
'@ -replace "`r", "") + "`n")
[IO.File]::WriteAllText("$PWD\.gitattributes", (@'
* text=auto eol=lf
*.cmd text eol=crlf
'@ -replace "`r", "") + "`n")
git add .
git update-index --chmod=+x scripts/verify.sh
git commit -m "Team files: rules, repo list, verify scripts"

mkdir -p ~/work/java-workspace/scripts && cd ~/work/java-workspace
git init -b main
cat > CLAUDE.md <<'EOF'
# java-workspace

Run AI-DLC from this folder. One code repo, `priorauth-api/`, a Spring Boot 4.1 REST API on Java 21, built with Maven.

| Repo          | Owns                                   | Verify with      | Branch pattern       |
|---------------|----------------------------------------|------------------|----------------------|
| priorauth-api | the API the reviewer screen reads      | `mvn -q test`    | request-age/<slug>   |

Rules: the record in `aidlc/` is the source of truth for requirements and decisions; commit it after every gate.
One unit = one branch = one PR. Tests through `./scripts/verify.sh` (`scripts\verify.cmd` on Windows), never ad hoc.
Never add a dependency to pom.xml inside a unit without saying so in the plan.
EOF
cat > repos.json <<'EOF'
{
  "org": "acme-health",
  "repos": [
    { "name": "priorauth-api", "branch": "main", "url": "https://github.com/varasrinivas/aidlc-priorauth-api.git" }
  ]
}
EOF
cat > scripts/verify.sh <<'EOF'
#!/usr/bin/env bash
# The one verification command for this workspace (approved at Code Generation, run after every unit).
set -uo pipefail
cd "$(dirname "$0")/../priorauth-api"
mvn -q test
EOF
cat > scripts/verify.cmd <<'EOF'
@echo off
rem The one verification command for this workspace (Windows twin of verify.sh).
cd /d "%~dp0..\priorauth-api" && mvn -q test
EOF
cat > .gitattributes <<'EOF'
* text=auto eol=lf
*.cmd text eol=crlf
EOF
chmod +x scripts/verify.sh
git add .
git commit -m "Team files: rules, repo list, verify scripts"

You see real output · your commit id will differ; the warning is harmless

Initialized empty Git repository in C:/work/java-workspace/.git/
warning: in the working copy of 'scripts/verify.cmd', LF will be replaced by CRLF the next time Git touches it
[main (root-commit) b2ed222] Team files: rules, repo list, verify scripts
 5 files changed, 27 insertions(+)
 create mode 100644 .gitattributes
 create mode 100644 CLAUDE.md
 create mode 100644 repos.json
 create mode 100644 scripts/verify.cmd
 create mode 100755 scripts/verify.sh

On disk now

java-workspace/             a new git repo, branch main: only what people wrote, one commit
  CLAUDE.md             the team's house rules; Claude Code reads it at every start
  repos.json            which code repos belong here, and where to clone them from
  scripts/verify.sh     the one test command the team agrees on (macOS, Linux)
  scripts/verify.cmd    the same, for Windows
  .gitattributes        line endings: LF everywhere, CRLF for .cmd

java-workspace/CLAUDE.mdthe team's rules

java-workspace/repos.jsonthe repo list

java-workspace/scripts/verify.shthe test command

java-workspace/scripts/verify.cmdthe same, for Windows

java-workspace/.gitattributesline endings

Your own code repo? Change three things: the table in CLAUDE.md, the entry in repos.json (name is the folder, url where to clone it from), and the test command in both verify scripts. Everything after this step stays the same.

repos.json field	Meaning
`org`	Default GitHub owner: a repo without `url` clones from `git@github.com:<org>/<name>.git`.
`repos[].name`	The folder the repo is cloned into, directly under the workspace. One plain name, no slashes.
`repos[].url`	Optional: clone from here instead (this workspace uses the public starter repo).
`repos[].branch`	Optional: the branch a new clone checks out. For a repo already on disk it is only compared, never switched.

In plain words. The workspace is the restaurant, the code repo is the kitchen. This step puts up the house rules and the list of kitchens; nobody has cooked yet.

aidlc command

aidlc config: install the harness for Claude Code

One command writes everything Claude Code needs to run AI-DLC: the /aidlc command and its skills, 14 agents, the hooks that enforce the workflow, the rules, and the starting memory. Run bare (aidlc config) it asks its questions one by one; --harness claude answers the only one that matters here.

The workspace

You type inside java-workspace

aidlc config --harness claude

You see real output

configured C:\work\java-workspace for Claude Code 2.11.0; next: open Claude Code in this project (if it is already open in this folder, exit it and start it again) and run `/aidlc --doctor`

On disk now

java-workspace/
  .claude/                       314 files: the harness for Claude Code (reference below)
  .gitignore                     created with AI-DLC's managed block: per-machine files stay out of git
  aidlc/active-space             one word, "default": which space this machine works in (ignored)
  aidlc/spaces/default/memory/   the method's rules, layered:
    org.md                       AI-DLC's defaults: trunk-based, squash-merge, test posture per scope
    team.md                      your team's affirmed practices; empty sections until practices-discovery
    project.md                   this project's rules and corrections; empty sections
    phases/*.md                  guardrails per phase: ideation, inception, construction, operation
    templates/.gitkeep           where a team may put artifact-format overrides

java-workspace/.gitignoreafter step 4 · real file

# BEGIN AI-DLC:gitignore
# AI-DLC: local working files
aidlc/active-space
aidlc/spaces/*/intents/active-intent
aidlc/.aidlc-clone-id
aidlc.settings.local.json
aidlc/.aidlc-unit-scope.json
aidlc/.aidlc-unit-parked
aidlc/.aidlc-claim-generations.json
aidlc/.aidlc-unit-participant
aidlc/.aidlc-claim-registry.json
aidlc/.aidlc-unit-releases/
aidlc/.aidlc-unit-merges/
aidlc/.aidlc-active-space-*.tmp
aidlc/.aidlc-sessions/
aidlc/spaces/*/intents/.aidlc-*
**/aidlc/spaces/*/intents/**/.aidlc-engine/
**/aidlc/spaces/*/intents/**/.aidlc-sensors/
aidlc/spaces/*/knowledge/documentkb/.journal/
aidlc/spaces/*/knowledge/.sources.local.json
aidlc/spaces/*/intents/*/runtime-graph.json
aidlc/spaces/*/intents/*/.aidlc-*
aidlc/diagnostics/
.claude/settings.local.json
# END AI-DLC:gitignore

# Child code repos are cloned in as siblings, each with its own git + origin.
# The workspace tracks only the AI-DLC records under aidlc/, not the child source.
# >>> aidlc workspace-sync managed (do not edit inside; regenerated from repos.json) >>>
/.aidlc-workspace-sync-recovery-*/
/priorauth-api/
# <<< aidlc workspace-sync managed <<<

aidlc/spaces/default/memory/team.mdreal file

# Team-Level Rules

> This team's affirmed practices and corrections. Loaded after `org.md` as
> strict-additive guidance; contradictions with broader policy are rejected.
> Populated by the practices-discovery affirmation gate. Edit at the gate,
> not directly.

## Way of Working

## Walking Skeleton

## Testing Posture

## Guard Policy

## Deployment

## Code Style

## Forbidden

## Mandated

## Corrections

`aidlc config <section>`	What it sets
`models`	Which model and effort each agent uses (presets thorough, balanced, minimal). Default: every agent inherits your session's model; the two reviewers use sonnet / medium.
`runtime`	Whether hooks can find `aidlc` and the harness CLI on the PATH.
`providers`	Provider, AWS region and profile, if you want AI-DLC to record them. By default it leaves Claude Code's own setup alone.
`trust`	Acknowledging the host and the command allowlist in `settings.json`.
`flags`	Default scope, swarm, hook debug, sensor timeout.
`project`	Plugins, AI-DLC's MCP servers (`--mcp defaults\|none`, opt-in), shell completions.

You see real output, abridged · aidlc config --show

models
  All 14 agents inherit your session model and effort, except:
    Reviewing (2 agents): sonnet / medium
runtime
  bun: not-required · aidlc: found · Harness CLI: found (claude)
providers
  Provider: harness provider in use (not recorded) · Region/Profile: not managed by AI-DLC
trust
  Allowlist reviewed: not recorded
flags
  Default scope: inherit · Swarm: inherit · Hook debug: inherit · Sensor timeout: inherit
project
  Plugins: all installed · MCP consent: inherit · Completions: not offered

Re-run it any time. aidlc config is safe to repeat: it rewrites only its own files and its own block in .gitignore. After aidlc update, re-run it so .claude/ matches the new release. Never edit .claude/ by hand; your changes would be overwritten.

aidlc command

aidlc system workspace-sync: bring in the code repos

repos.json is a promise; this command keeps it. It clones every listed repo that is missing, writes the lines that keep those repos out of the workspace's git, and writes a VS Code file that opens everything together.

The workspace

You type inside java-workspace

aidlc system workspace-sync

You see real output

aidlc workspace-sync: reconciling C:\work\java-workspace against repos.json (1 repo(s))
  staging clone priorauth-api from https://github.com/varasrinivas/aidlc-priorauth-api.git (branch main) ...
  ✓ cloned priorauth-api on 'main'
  ✓ prior generated files retained at C:\work\java-workspace\.aidlc-workspace-sync-recovery-BIGClI\generated-file-backups
  ✓ .gitignore managed block → 1 child dir(s)
  ✓ aidlc.code-workspace → 1 child root(s)
✓ workspace in sync

On disk now

java-workspace/
  priorauth-api/                          the code repo, cloned from repos.json; its own git, ignored here
  aidlc.code-workspace                    a VS Code multi-root file: the workspace + each repo
  .gitignore                              gains a second managed block: /priorauth-api/ and the recovery folder
  .aidlc-workspace-sync-recovery-…/       backup of the .gitignore it replaced; ignored; delete when you like

java-workspace/aidlc.code-workspacereal file

Disk winsA repo already on disk is never re-cloned or switched; a different branch there is only reported. A repo listed but never cloned is simply not part of a run.

OrphansA repo on disk that repos.json doesn't list blocks the sync. --force moves it aside, but only after proving it has nothing unpushed.

Exit codes0 in sync · 1 blocked or error, nothing changed · 2 synced with warnings (e.g. a branch mismatch).

aidlc command

aidlc doctor: check the machine and the project

Doctor runs 70 checks in three groups and prints a fix for anything wrong. Problems stop a workflow; warnings don't. Run it whenever something looks odd, and once now.

The workspace

You type inside java-workspace

aidlc doctor

You see real output, abridged

AI-DLC doctor

Machine
  warn  Update: update cache is absent
        fix: run `aidlc update --check`
  ok    11 checks passed

Project (.claude, Claude Code)
  warn  AIDLC hooks have not run in this project yet
        fix: This is expected before your first Claude Code chat in this folder. …
  warn  Workspace records: 8 uncommitted change(s) under aidlc/ (advisory - the shared records travel by git; …)
  ok    47 checks passed

Framework integrity
  ok    all 12 checks passed

0 problems, 3 warnings.
Warnings are advisory - if everything works, ignore them.

Warning	Why now	Goes away when
Update cache is absent	The machine has never asked for release notes.	You run `aidlc update --check` (needs network).
Hooks have not run yet	Hooks run inside Claude Code; you haven't started it here.	Step 7: the first `claude` session in this folder.
8 uncommitted changes under aidlc/	The memory files config just wrote.	Step 6: you commit them.

aidlc doctor --verbose lists every check. Inside Claude Code the same check is /aidlc --doctor.

yours, not the tool

Commit the workspace, after one team decision

The record and the team's files travel by git: that is how a teammate gets the same memory, knowledge and run history. The code repo never goes in (it has its own git). The one choice to make is what to do with .claude/.

The workspace

You type inside java-workspace

git add .gitignore aidlc.code-workspace aidlc
git commit -m "AI-DLC set up: config + workspace-sync"

You see real output · then git status

 10 files changed, 423 insertions(+)
?? .claude/

	Commit `.claude/` (AI-DLC's default)	Regenerate it per machine (this course)
How	`git add .claude` too. AI-DLC's own `.gitignore` leaves it tracked (only `settings.local.json` is ignored).	Add `.claude/` to `.gitignore` below the managed blocks; every machine runs `aidlc config`. Tested: both commands keep the line.
Teammate on a fresh clone	Has the harness at once, at exactly the committed release.	Runs `aidlc config` first, with their own installed release.
Size	314 files, about 232,000 lines in the first commit.	10 files, 423 lines.
After `aidlc update`	A large diff to review and commit.	Nothing to commit; each machine re-runs `aidlc config`.
Pick it when	The team wants one pinned framework version everywhere, or runs AI-DLC in CI.	People keep their own `aidlc` up to date and you want small, readable history.

First commit on a new machine? If git answers "Author identity unknown", tell it who you are once: git config --global user.name "Your Name" and git config --global user.email you@example.com, then run the commit again.

Either way, never committed: aidlc/active-space, the active-intent cursor, session and engine scratch, and .claude/settings.local.json. AI-DLC's managed .gitignore block already keeps them out.

First sessionsteps 7–8 · Claude Code takes over; where its work becomes a PR

Claude Code

Start Claude Code in the workspace

From here the workflow runs inside Claude Code. Start it in the workspace folder, never inside the code repo. The first start in a new project asks you to approve the project's hooks; AI-DLC depends on them.

First session

You type inside java-workspace, then in Claude Code

claude
/aidlc --doctor

Claude returns expected; not captured for the course

(Claude Code asks to approve this project's hooks: approve them, then fully restart Claude Code)
AI-DLC doctor … 0 problems
(the statusline at the bottom now shows AI-DLC's state)

What Claude Code loads at start	Why
`CLAUDE.md` (workspace root)	Your team's rules (step 2).
`.claude/CLAUDE.md`	AI-DLC's project instructions: what `/aidlc` does and its flags. Its first line imports the next file.
`.claude/rules/aidlc.md`	Not a copy of the method: it imports `aidlc/spaces/default/memory/*.md`, so the method's rules are in every chat, and you edit them in one place.
`.claude/settings.json`	The hooks, the permission allowlist and the statusline (reference below).

Next: the hello-world run takes this workspace through its first feature with /aidlc express …. Its record lands in aidlc/spaces/default/intents/.

yours, not the tool

Where pull requests come from: files you already wrote

AI-DLC has no pull-request stage in any scope. A run ends with code committed on a branch and a record on disk; pushing, the PR and the merge are the team's. What decides how a run gets there is already in this workspace, written at steps 2 and 3. The one thing left to set up is a way to open PRs.

First session

What it decides	Where	Written at	What happens in a run
Branches and PRs	`CLAUDE.md`	step 2, by you	One unit = one branch = one PR, branch pattern `request-age/<slug>`, commit the record after every gate. Claude makes the branch the plan names and commits the code there and the record in the workspace, because the file says so. Change the pattern when a new request starts, or Claude follows it as written.
The test command	`scripts/`	step 2, by you	Claude runs `verify` before committing. In a scope with units, the engine asks once to record it as the verification command, then runs it itself at every unit checkpoint.
The base branch	`repos.json`	step 2, by you	`"branch": "main"`: `workspace-sync` checks it out; work branches start from it and PRs target it.
How branches merge	`memory/org.md`	step 3, by `aidlc config`	AI-DLC's defaults: trunk-based, short-lived branches, squash-merge. Read at every stage; changed through the method's gates, not by hand.

You type PowerShellTerminal (macOS)

winget install --id GitHub.cli
gh auth login
gh auth status

brew install gh
gh auth login
gh auth status

You see expected; not captured for the course

(gh auth login asks for the host, the protocol and a browser sign-in)
github.com
  ✓ Logged in to github.com account <you>

	Express (no units)	Feature, MVP, enterprise (units)
Branches and PRs	One branch, one PR	One per unit
Before the PR	The Code Generation and Build and Test gates	A unit checkpoint each: the engine runs the verify script, then asks “Approve this completed <unit>?”
Walked through on	the hello-world run, step 14	the feature-scope page, step 11

No GitHub CLI? Push the branch and open the PR in the browser; the run pages use gh pr create --body-file …/code-summary.md only because the code summary Claude writes makes a ready PR description. Following the course with the public starter repo, you can't push at all: its origin isn't yours.

Referenceevery file, every folder, every command

Every file in a set-up workspace, one by one

Including the ones that appear later, during runs. "Written by" says who creates or changes it; "Committed" says whether it travels by git.

Path	Written by	Committed	What it is for
`CLAUDE.md`	people	yes	House rules for every Claude Code session in this workspace.
`repos.json`	people	yes	The code repos that belong here; read by `workspace-sync` and by doctor.
`scripts/`	people	yes	The team's own commands, e.g. the verification command a run approves.
`docs-in/`	people	yes	Inputs you hand to a run: a request, an export, a brief. The course's convention, not the tool's.
`.gitignore`	both	yes	AI-DLC's two managed blocks (between its markers; regenerated) and anything you add outside them.
`aidlc.code-workspace`	workspace-sync	yes	VS Code multi-root file: open it to see the workspace and every repo together.
`.mcp.json`	people / aidlc config	yes	Optional: MCP servers for the session. AI-DLC adds its five only if you opt in; your own entries are kept.
`.claude/`	aidlc config	your choice (step 6)	The harness: 314 files. Folder by folder below.
`.claude/settings.local.json`	you	no (ignored)	Personal overrides (model, environment); copy it from `settings.local.json.example`.
`.aidlc-workspace-sync-recovery-*/`	workspace-sync	no (ignored)	Backups of generated files it replaced. Safe to delete.
`aidlc/active-space`	aidlc	no (ignored)	Which space this machine is working in ("default").
`aidlc/.aidlc-clone-id`, `aidlc/.aidlc-sessions/`, `aidlc/diagnostics/`	aidlc	no (ignored)	Per-machine identity, session scratch and diagnostics.
`aidlc/spaces/default/`	aidlc	yes	A space groups runs that share memory, knowledge and code knowledge. One is enough for a team.
`…/memory/`	aidlc config; then gates	yes	The method's rules: org, team, project, per phase. Read at every stage. Changed through AI-DLC's gates, not by hand.
`…/knowledge/documents/`	people	yes	Documents the team owns (specs, PRDs), copied in for onboarding.
`…/knowledge/documentkb/`	aidlc engine knowledge	yes	The catalog: extracted text, fingerprint, "untrusted" marking. Its `.journal/` is ignored.
`…/knowledge/aidlc-shared/*.md`	people	yes	Context every agent loads at every stage, e.g. a domain glossary.
`…/codekb/<repo>/`	Reverse Engineering	yes	Nine files about each repo, plus a fingerprint of what was scanned; reused by later runs while still valid.
`…/intents/intents.json`	aidlc	yes	The registry of runs in the space: one row each, with status (in-flight, complete, archived).
`…/intents/active-intent`	aidlc	no (ignored)	Which run this machine is on.
`…/intents/<yymmdd-label>/aidlc-state.md`	aidlc	yes	Where a run is: scope, stages, one checkbox per stage, current status. The file a resume reads.
`…/intents/<id>/project-description.json`	aidlc	yes	The request, verbatim, as one JSON string.
`…/intents/<id>/audit/`	aidlc	yes	The audit log: one file per machine, every gate answer and event, with time and actor.
`…/intents/<id>/inception/`, `construction/`, `operation/`, `verification/`	agents	yes	Each stage's artifacts: requirements, plans, test results, deployment logs, phase checks.
`…/intents/<id>/.aidlc-engine/`, `runtime-graph.json`	aidlc	no (ignored)	Engine scratch for a run in progress.

`.claude/`, folder by folder

314 files in ten places. Claude Code looks for agents, skills, hooks, rules and settings in .claude/; AI-DLC fills it. The descriptions next to file names are the files' own headers.

(root) 3 files

CLAUDE.md: AI-DLC's project instructions (what /aidlc does, its flags, prerequisites). settings.json: hooks, allowlist, statusline. settings.local.json.example: copy to settings.local.json for personal overrides.

agents/ 14 files

The roles that do the work, each a Claude Code subagent with its own instructions and tools. Each stage has a lead agent; two are reviewers.

architect-agent: Solutions architect responsible for domain design, contract design, NFR patterns, and component decomposition.
architecture-reviewer-agent: Senior solutions architect who reviews technical design artifacts for soundness, implementability, and coherence.
aws-platform-agent: AWS solutions architect responsible for infrastructure design, environment provisioning, and cloud-native architecture.
compliance-agent: GRC analyst and regulatory specialist responsible for compliance mapping, data classification, and risk assessment.
composer-agent: Adaptive workflow composer.
delivery-agent: Engineering manager responsible for team formation, Bolt sequencing, and phase handoffs.
design-agent: UX/UI designer responsible for wireframing, interaction design, accessibility, and design system compliance.
developer-agent: Senior developer responsible for code generation, reverse engineering, and data modelling.
devsecops-agent: Security engineer and DevSecOps specialist responsible for threat modelling, security requirements, secure design review, and security pipeline integration.
operations-agent: SRE and reliability engineer responsible for observability, incident response, and operational optimization.
pipeline-deploy-agent: CI/CD engineer and release manager responsible for pipeline configuration, deployment strategy, and release execution.
product-agent: Product manager and business analyst responsible for requirements, user stories, market research, and scope.
product-lead-agent: Senior product leader who reviews requirements, user stories, and UX artifacts for completeness, business alignment, and testability.
quality-agent: QA lead responsible for test strategy, test case design, quality gates, and performance validation.

skills/ 44 files

Each becomes a slash command. /aidlc is the main one; one per scope (/aidlc-express, /aidlc-feature, …) bakes the scope in; one per stage runs that stage alone "without advancing the main workflow"; and helpers like /aidlc-knowledge, /aidlc-compose, /aidlc-replay, /aidlc-session-cost.

scopes/ 11 files

The profiles: which of the 33 stages run, at what depth, with which gates.

bugfix: Fix a specific bug
classic: V1-style ceremony through Inception and Construction - the implicit default
enterprise: Regulated enterprise feature, full audit trail
express: Lightest run: requirements to deploy, no design pass, no reviewers
feature: Full lifecycle for new features, practical depth
infra: Infrastructure changes
mvp: Skip operations, ship the core
poc: Prove feasibility fast
refactor: Clean up existing code
security-patch: CVE response
workshop: Facilitated group session with mandatory gates

aidlc-common/ 43 files

The method itself, read by agents: 33 stage definitions under stages/<phase>/ (what each stage consumes, produces and asks), 9 protocol files (how a stage runs, reviews, verifies a phase, records learnings) and conductor.md, the orchestrator's craft notes.

knowledge/ 60 files

Reference material per agent (an architect's ADR template, a developer's code-analysis guide, a QA's test-strategy patterns…) and 9 shared files for all agents (AI-DLC principles, audit format, state template, brownfield guidance). Not your team's knowledge: that lives in aidlc/spaces/default/knowledge/.

hooks/ 19 files

Scripts Claude Code runs at fixed moments: they enforce the workflow (no skipping a gate, no writing before a plan is approved), write the audit log, run sensors and keep the state file in sync. Wired in settings.json; see when each runs, below.

sensors/ 6 files

Automatic checks fired at gates or on code outputs. Express turns them off.

claim-sources: Checks Intent Capture claims carry source tags that resolve to the stage's confirmed source register and answers
linter: Wraps the project's configured linter (eslint by default for v0.5.0); fires on TS/JS code outputs
required-sections: Checks at the gate that stage output contains the required H2 headings
traceability: Verifies element-level upstream coverage, downstream targets, and derived orphans in traceability.json
type-check: Wraps the project's configured type-checker (tsc by default for v0.5.0); fires on TS/TSX code outputs
upstream-coverage: Checks the stage's deliverables reference the upstream artifacts the stage frontmatter declares it consumes

tools/ 113 files

The engine's TypeScript, run by aidlc engine …: state, gates, audit, knowledge, codekb, workspace-sync, doctor. 25 files under tools/data/ hold the compiled stage graph, the scope grid, the memory seed (what config copies to memory/), the .gitignore and .mcp.json templates, and harness.json (your config answers).

rules/ 1 file

aidlc.md: a stub that imports aidlc/spaces/default/memory/ into every chat. The method is authored once, in memory/; never edit this file.

When each hook runs

From the generated .claude/settings.json. Every hook is the same program, aidlc engine hook <name>; the name says what it guards or records. PreToolUse runs before Claude uses a tool and can refuse it; PostToolUse runs after.

Claude Code event	For these tools	Hook
`PreToolUse`	every time	`fold-usage`
`PreToolUse`	Task\|Agent	`deliver-stage-rules`
`PreToolUse`	Read\|NotebookRead\|Edit\|MultiEdit\|Write\|NotebookEdit\|LS\|Glob\|Grep\|Bash	`state-transition-guard`
`PreToolUse`	Read\|NotebookRead\|Edit\|MultiEdit\|Write\|NotebookEdit\|LS\|Glob\|Grep\|Bash	`reviewer-scope`
`PreToolUse`	Read\|NotebookRead\|Edit\|MultiEdit\|Write\|NotebookEdit\|LS\|Glob\|Grep\|Bash	`review-freeze`
`PreToolUse`	Edit\|MultiEdit\|Write\|NotebookEdit\|Bash\|Task\|Agent	`plan-approval-guard`
`UserPromptSubmit`	every time	`record-human-turn`
`SessionStart`	every time	`session-start`
`SessionEnd`	every time	`session-end`
`PostToolUse`	Write\|Edit	`write-audit-log`
`PostToolUse`	Write\|Edit	`run-sensors`
`PostToolUse`	TaskUpdate	`sync-workflow-state`
`PostToolUse`	AskUserQuestion	`record-human-turn`
`PostToolUse`	Bash	`rebuild-stage-graph`
`PostToolUse`	Task\|Agent	`deliver-stage-rules`
`PostToolUse`	every time	`fold-usage`
`PreCompact`	every time	`validate-state`
`SubagentStop`	every time	`log-subagent`
`Stop`	every time	`continue-workflow`

`.claude/settings.json`, explained

Key	What AI-DLC puts there
`permissions.allow`	45 pre-approved actions so a workflow doesn't ask at every step: e.g. `Edit(/*)` (edit files in the project), `Task` (subagents), `Bash(aidlc engine )`, the read-only `aidlc` commands. Your build and test commands still ask once.
`hooks`	19 hook entries on 8 events (table above).
`statusLine`	`aidlc engine statusline`: the bottom line in Claude Code shows the run's phase, stage and status.
`env`	`{"AWS_AIDLC_DEFAULT_SCOPE": "classic"}`: the scope `/aidlc` starts with when you don't name one. Override it in `settings.local.json`.
`companyAnnouncements`	A line Claude Code shows at start-up.

Change your own copy in .claude/settings.local.json (ignored by git). Edits to settings.json are overwritten the next time aidlc config runs.

All 314 generated files

Every file aidlc config writes into .claude/ (2.11.0). The description is the file's own: its description: header, else its first heading or comment; "—" where it has none.

.claude/…	Description
CLAUDE.md	Project Name <!-- Replace with your project name -->
agents/aidlc-architect-agent.md	Solutions architect responsible for domain design, contract design, NFR patterns, and component decomposition. Leads Feasibility, Domain Design, Units Generation, Contract Design, Functional Design, NFR Requirements, and NFR Design stages, and serves as the dispatched final link of the Reverse Engin
agents/aidlc-architecture-reviewer-agent.md	Senior solutions architect who reviews technical design artifacts for soundness, implementability, and coherence. Finds broken cross-references, hidden dependencies, unachievable quality targets, and designs that won't survive contact with reality.
agents/aidlc-aws-platform-agent.md	AWS solutions architect responsible for infrastructure design, environment provisioning, and cloud-native architecture. Leads Infrastructure Design and Environment Provisioning stages. Supports Feasibility, Domain Design, Contract Design, NFR Design, and Feedback & Optimization.
agents/aidlc-compliance-agent.md	GRC analyst and regulatory specialist responsible for compliance mapping, data classification, and risk assessment. Support-only agent for Feasibility & Constraint Analysis and cross-cutting compliance validation.
agents/aidlc-composer-agent.md	Adaptive workflow composer. Estimates implementation entropy (intent ambiguity, codebase structural uncertainty, verification entropy, risk, unresolved assumptions) then composes the minimum viable workflow — the least sufficient sequence of stages that can safely transform the intent into a verifie
agents/aidlc-delivery-agent.md	Engineering manager responsible for team formation, Bolt sequencing, and phase handoffs. Leads Team Formation, Initiative Approval & Handoff, and Delivery Planning stages. Supports Scope Definition and Units Generation.
agents/aidlc-design-agent.md	UX/UI designer responsible for wireframing, interaction design, accessibility, and design system compliance. Leads Rough Mockups and Refined Mockups stages. Supports Domain Design, and serves as a dispatched collaborator in the User Stories mob ensemble.
agents/aidlc-developer-agent.md	Senior developer responsible for code generation, reverse engineering, and data modelling. Leads the Reverse Engineering code scan and Code Generation, and serves as a dispatched collaborator in the Practices Discovery hub-and-spoke and User Stories mob ensembles.
agents/aidlc-devsecops-agent.md	Security engineer and DevSecOps specialist responsible for threat modelling, security requirements, secure design review, and security pipeline integration. Supports NFR Requirements, Infrastructure Design, Build and Test, and Environment Provisioning, and serves as a dispatched collaborator in the
agents/aidlc-operations-agent.md	SRE and reliability engineer responsible for observability, incident response, and operational optimization. Leads Observability Setup, Incident Response, and Feedback & Optimization stages. Supports Performance Validation.
agents/aidlc-pipeline-deploy-agent.md	CI/CD engineer and release manager responsible for pipeline configuration, deployment strategy, and release execution. Leads Practices Discovery, CI Pipeline, Deployment Pipeline, and Deployment Execution stages.
agents/aidlc-product-agent.md	Product manager and business analyst responsible for requirements, user stories, market research, and scope. Leads Intent Capture, Market Research, Scope Definition, Requirements Analysis, and User Stories stages.
agents/aidlc-product-lead-agent.md	Senior product leader who reviews requirements, user stories, and UX artifacts for completeness, business alignment, and testability. Does not produce — only reviews and challenges. Represents the customer's voice at the quality gate.
agents/aidlc-quality-agent.md	QA lead responsible for test strategy, test case design, quality gates, and performance validation. Leads Build and Test and Performance Validation stages. Supports NFR Requirements and Functional Design, and serves as a dispatched collaborator in the Practices Discovery hub-and-spoke and User Stori
aidlc-common/conductor.md	The Conductor's Craft — Execution Quality
aidlc-common/protocols/stage-definition.md	Stage Definition Format
aidlc-common/protocols/stage-protocol-construction.md	Construction Protocol Module
aidlc-common/protocols/stage-protocol-ensemble.md	Ensemble Protocol Module
aidlc-common/protocols/stage-protocol-governance.md	Stage Protocol: Phase Boundary Verification
aidlc-common/protocols/stage-protocol-learnings.md	Learnings Protocol Module
aidlc-common/protocols/stage-protocol-recovery.md	Stage Protocol: Error Recovery & Change Handling
aidlc-common/protocols/stage-protocol-reviewer.md	Reviewer Protocol Module
aidlc-common/protocols/stage-protocol-swarm.md	Swarm Protocol Module
aidlc-common/protocols/stage-protocol.md	Stage Protocol
aidlc-common/stages/construction/build-and-test.md	Build and Test
aidlc-common/stages/construction/ci-pipeline.md	CI Pipeline
aidlc-common/stages/construction/code-generation.md	Code Generation
aidlc-common/stages/construction/functional-design.md	Functional Design
aidlc-common/stages/construction/infrastructure-design.md	Infrastructure Design
aidlc-common/stages/construction/nfr-design.md	NFR Design
aidlc-common/stages/construction/nfr-requirements.md	NFR Requirements
aidlc-common/stages/ideation/approval-handoff.md	Initiative Approval & Handoff
aidlc-common/stages/ideation/feasibility.md	Feasibility & Constraint Analysis
aidlc-common/stages/ideation/intent-capture.md	Intent Capture & Framing
aidlc-common/stages/ideation/market-research.md	Market Research & Competitive Analysis
aidlc-common/stages/ideation/rough-mockups.md	Rough Mockups & Concept Visualization
aidlc-common/stages/ideation/scope-definition.md	Scope Definition & Prioritization
aidlc-common/stages/ideation/team-formation.md	Team Formation & Mob Planning
aidlc-common/stages/inception/contract-design.md	Contract Design
aidlc-common/stages/inception/delivery-planning.md	Delivery Planning
aidlc-common/stages/inception/domain-design.md	Domain Design
aidlc-common/stages/inception/practices-discovery.md	Practices Discovery
aidlc-common/stages/inception/refined-mockups.md	Refined Mockups & UX Design
aidlc-common/stages/inception/requirements-analysis.md	Requirements Analysis
aidlc-common/stages/inception/reverse-engineering.md	Reverse Engineering
aidlc-common/stages/inception/units-generation.md	Units Generation
aidlc-common/stages/inception/user-stories.md	User Stories
aidlc-common/stages/initialization/state-init.md	State Initialization
aidlc-common/stages/initialization/workspace-detection.md	Workspace Detection
aidlc-common/stages/initialization/workspace-scaffold.md	Workspace Scaffold
aidlc-common/stages/operation/deployment-execution.md	Deployment Execution
aidlc-common/stages/operation/deployment-pipeline.md	Deployment Pipeline Configuration
aidlc-common/stages/operation/environment-provisioning.md	Environment Provisioning
aidlc-common/stages/operation/feedback-optimization.md	Continuous Feedback & Optimization
aidlc-common/stages/operation/incident-response.md	Incident Response & Runbook Generation
aidlc-common/stages/operation/observability-setup.md	Observability Setup
aidlc-common/stages/operation/performance-validation.md	Performance Validation & Load Testing
hooks/aidlc-continue-workflow.ts	—
hooks/aidlc-deliver-stage-rules.ts	—
hooks/aidlc-fold-usage.ts	—
hooks/aidlc-log-subagent.ts	—
hooks/aidlc-plan-approval-guard.ts	—
hooks/aidlc-rebuild-stage-graph.ts	—
hooks/aidlc-record-human-turn.ts	—
hooks/aidlc-review-freeze.ts	The offending path (block=true).
hooks/aidlc-reviewer-scope.ts	The conductor-written dispatch record (stage-protocol-reviewer.md §12a step 1).
hooks/aidlc-run-sensors.ts	—
hooks/aidlc-session-end.ts	—
hooks/aidlc-session-start.ts	—
hooks/aidlc-state-transition-guard.ts	—
hooks/aidlc-statusline.ts	—
hooks/aidlc-sync-workflow-state.ts	—
hooks/aidlc-validate-state.ts	—
hooks/aidlc-write-audit-log.ts	—
hooks/review-freeze-command.ts	—
hooks/runtime-integrity.ts	—
knowledge/aidlc-architect-agent/adr-template.md	Architecture Decision Records (ADRs)
knowledge/aidlc-architect-agent/architecture-guide.md	Architecture Guide
knowledge/aidlc-architect-agent/architecture-patterns.md	Architecture Patterns
knowledge/aidlc-architect-agent/ddd-patterns.md	Domain-Driven Design Patterns
knowledge/aidlc-architect-agent/nfr-design-guide.md	NFR Design Guide
knowledge/aidlc-architect-agent/nfr-design-patterns.md	Non-Functional Requirement Design Patterns
knowledge/aidlc-architecture-reviewer-agent/reviewing.md	Reviewing Artifacts (Architecture Lens)
knowledge/aidlc-aws-platform-agent/cdk-best-practices.md	AWS CDK Best Practices
knowledge/aidlc-aws-platform-agent/cost-optimization-patterns.md	AWS Cost Optimization Patterns
knowledge/aidlc-aws-platform-agent/infrastructure-guide.md	Infrastructure Guide
knowledge/aidlc-aws-platform-agent/well-architected-framework.md	AWS Well-Architected Framework
knowledge/aidlc-compliance-agent/regulatory-frameworks.md	Regulatory Frameworks
knowledge/aidlc-composer-agent/composing.md	Composing a Workflow Plan
knowledge/aidlc-delivery-agent/mob-programming-guide.md	Mob Programming Guide
knowledge/aidlc-delivery-agent/team-topologies.md	Team Topologies
knowledge/aidlc-delivery-agent/workflow-planning-guide.md	Workflow Planning Guide
knowledge/aidlc-design-agent/accessibility-wcag.md	Accessibility: WCAG 2.1 AA Guide
knowledge/aidlc-design-agent/component-spec-template.md	Component Specification Template
knowledge/aidlc-design-agent/interaction-design-patterns.md	Interaction Design Patterns
knowledge/aidlc-design-agent/ux-guide.md	UX Guide
knowledge/aidlc-design-agent/wireframing-guide.md	Wireframing Guide
knowledge/aidlc-developer-agent/api-design-guide.md	REST API Design Guide
knowledge/aidlc-developer-agent/code-analysis-guide.md	Code Analysis Guide
knowledge/aidlc-developer-agent/code-generation-guide.md	Code Generation Guide
knowledge/aidlc-developer-agent/code-generation-patterns.md	Code Generation Patterns
knowledge/aidlc-developer-agent/data-modelling-patterns.md	Data Modelling Patterns
knowledge/aidlc-developer-agent/re-artifacts.md	Reverse Engineering Artifact Templates
knowledge/aidlc-devsecops-agent/devsecops-pipeline-patterns.md	DevSecOps Pipeline Patterns
knowledge/aidlc-devsecops-agent/nfr-requirements-guide.md	NFR Requirements Guide
knowledge/aidlc-devsecops-agent/security-guide.md	Security Guide
knowledge/aidlc-devsecops-agent/threat-modelling-stride.md	Threat Modelling with STRIDE
knowledge/aidlc-operations-agent/incident-response-guide.md	Incident Response Guide
knowledge/aidlc-operations-agent/nfr-performance-guide.md	NFR Performance and Scalability Guide
knowledge/aidlc-operations-agent/observability-patterns.md	Observability Patterns
knowledge/aidlc-operations-agent/slo-sli-patterns.md	SLO, SLI, and Error Budget Patterns
knowledge/aidlc-pipeline-deploy-agent/branching-strategies.md	Branching Strategies
knowledge/aidlc-pipeline-deploy-agent/cicd-patterns.md	CI/CD Pipeline Patterns
knowledge/aidlc-pipeline-deploy-agent/deployment-strategies.md	Deployment Strategies
knowledge/aidlc-product-agent/corner-checklist.md	Corner Checklist
knowledge/aidlc-product-agent/functional-design-guide.md	Functional Design Guide
knowledge/aidlc-product-agent/market-research-methods.md	Market Research Methods
knowledge/aidlc-product-agent/prioritization-frameworks.md	Prioritization Frameworks
knowledge/aidlc-product-agent/product-guide.md	Product Guide
knowledge/aidlc-product-agent/requirements-elicitation.md	Requirements Elicitation Techniques
knowledge/aidlc-product-agent/requirements-guide.md	Requirements Guide
knowledge/aidlc-product-agent/user-story-patterns.md	User Story Patterns
knowledge/aidlc-product-lead-agent/reviewing.md	Reviewing Artifacts (Product Lens)
knowledge/aidlc-quality-agent/nfr-reliability-guide.md	NFR Reliability and Observability Guide
knowledge/aidlc-quality-agent/nfr-validation-methods.md	Non-Functional Requirement (NFR) Validation Methods
knowledge/aidlc-quality-agent/test-strategy-patterns.md	Test Strategy Patterns
knowledge/aidlc-quality-agent/testing-guide.md	Testing Guide
knowledge/aidlc-shared/ai-dlc-principles.md	AI-DLC Methodology Principles
knowledge/aidlc-shared/audit-format.md	Audit Event Taxonomy
knowledge/aidlc-shared/brownfield.md	Brownfield Safeguards
knowledge/aidlc-shared/knowledge-readme-template.md	Team Knowledge
knowledge/aidlc-shared/memory-template.md	—
knowledge/aidlc-shared/rules-reading.md	Reading Active-Space Rule Files
knowledge/aidlc-shared/state-template.md	AI-DLC State Tracking
knowledge/aidlc-shared/verification.md	Automatic Verification — Element-Level Traceability
knowledge/aidlc-shared/worktree-info-schema.md	`aidlc-worktree info` and `list` — Output Schema
rules/aidlc.md	—
scopes/aidlc-bugfix.md	Fix a specific bug
scopes/aidlc-classic.md	V1-style ceremony through Inception and Construction - the implicit default
scopes/aidlc-enterprise.md	Regulated enterprise feature, full audit trail
scopes/aidlc-express.md	Lightest run: requirements to deploy, no design pass, no reviewers
scopes/aidlc-feature.md	Full lifecycle for new features, practical depth
scopes/aidlc-infra.md	Infrastructure changes
scopes/aidlc-mvp.md	Skip operations, ship the core
scopes/aidlc-poc.md	Prove feasibility fast
scopes/aidlc-refactor.md	Clean up existing code
scopes/aidlc-security-patch.md	CVE response
scopes/aidlc-workshop.md	Facilitated group session with mandatory gates
sensors/aidlc-claim-sources.md	Checks Intent Capture claims carry source tags that resolve to the stage's confirmed source register and answers
sensors/aidlc-linter.md	Wraps the project's configured linter (eslint by default for v0.5.0); fires on TS/JS code outputs
sensors/aidlc-required-sections.md	Checks at the gate that stage output contains the required H2 headings
sensors/aidlc-traceability.md	Verifies element-level upstream coverage, downstream targets, and derived orphans in traceability.json
sensors/aidlc-type-check.md	Wraps the project's configured type-checker (tsc by default for v0.5.0); fires on TS/TSX code outputs
sensors/aidlc-upstream-coverage.md	Checks the stage's deliverables reference the upstream artifacts the stage frontmatter declares it consumes
settings.json	—
settings.local.json.example	—
skills/aidlc-approval-handoff/SKILL.md	Run the AI-DLC `approval-handoff` stage (ideation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage approval-handoff --single`: the engine emits one run-stage directive for approval-handoff and its gate, the conductor runs it, then the single-stage run commits a synt
skills/aidlc-bugfix/SKILL.md	Run the AI-DLC workflow with the bugfix scope baked in — no scope detection. Fix a specific bug. Packaging over `/aidlc --scope bugfix`, which works without this skill.
skills/aidlc-build-and-test/SKILL.md	Run the AI-DLC `build-and-test` stage (construction phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage build-and-test --single`: the engine emits one run-stage directive for build-and-test and its gate, the conductor runs it, then the single-stage run commits a synthe
skills/aidlc-ci-pipeline/SKILL.md	Run the AI-DLC `ci-pipeline` stage (construction phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage ci-pipeline --single`: the engine emits one run-stage directive for ci-pipeline and its gate, the conductor runs it, then the single-stage run commits a synthetic-id pa
skills/aidlc-code-generation/SKILL.md	Run the AI-DLC `code-generation` stage (construction phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage code-generation --single`: the engine emits one run-stage directive for code-generation and its gate, the conductor runs it, then the single-stage run commits a syn
skills/aidlc-compose/SKILL.md	Compose a tailored AI-DLC workflow plan - the adaptive composer reads your task (or a scan report), proposes the EXECUTE/SKIP stage grid that fits, and after your approval authors it as a scope and runs it. A typeable shortcut for `/aidlc compose`; the same one door, forced to the full composer even
skills/aidlc-contract-design/SKILL.md	Run the AI-DLC `contract-design` stage (inception phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage contract-design --single`: the engine emits one run-stage directive for contract-design and its gate, the conductor runs it, then the single-stage run commits a synthe
skills/aidlc-delivery-planning/SKILL.md	Run the AI-DLC `delivery-planning` stage (inception phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage delivery-planning --single`: the engine emits one run-stage directive for delivery-planning and its gate, the conductor runs it, then the single-stage run commits a
skills/aidlc-deployment-execution/SKILL.md	Run the AI-DLC `deployment-execution` stage (operation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage deployment-execution --single`: the engine emits one run-stage directive for deployment-execution and its gate, the conductor runs it, then the single-stage run c
skills/aidlc-deployment-pipeline/SKILL.md	Run the AI-DLC `deployment-pipeline` stage (operation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage deployment-pipeline --single`: the engine emits one run-stage directive for deployment-pipeline and its gate, the conductor runs it, then the single-stage run comm
skills/aidlc-domain-design/SKILL.md	Run the AI-DLC `domain-design` stage (inception phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage domain-design --single`: the engine emits one run-stage directive for domain-design and its gate, the conductor runs it, then the single-stage run commits a synthetic-id
skills/aidlc-environment-provisioning/SKILL.md	Run the AI-DLC `environment-provisioning` stage (operation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage environment-provisioning --single`: the engine emits one run-stage directive for environment-provisioning and its gate, the conductor runs it, then the single
skills/aidlc-express/SKILL.md	Run the AI-DLC workflow with the express scope baked in — no scope detection. Lightest run: requirements to deploy, no design pass, no reviewers. Packaging over `/aidlc --scope express`, which works without this skill.
skills/aidlc-feasibility/SKILL.md	Run the AI-DLC `feasibility` stage (ideation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage feasibility --single`: the engine emits one run-stage directive for feasibility and its gate, the conductor runs it, then the single-stage run commits a synthetic-id pair a
skills/aidlc-feature/SKILL.md	Run the AI-DLC workflow with the feature scope baked in — no scope detection. Full lifecycle for new features, practical depth. Packaging over `/aidlc --scope feature`, which works without this skill.
skills/aidlc-feedback-optimization/SKILL.md	Run the AI-DLC `feedback-optimization` stage (operation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage feedback-optimization --single`: the engine emits one run-stage directive for feedback-optimization and its gate, the conductor runs it, then the single-stage ru
skills/aidlc-functional-design/SKILL.md	Run the AI-DLC `functional-design` stage (construction phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage functional-design --single`: the engine emits one run-stage directive for functional-design and its gate, the conductor runs it, then the single-stage run commits
skills/aidlc-incident-response/SKILL.md	Run the AI-DLC `incident-response` stage (operation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage incident-response --single`: the engine emits one run-stage directive for incident-response and its gate, the conductor runs it, then the single-stage run commits a
skills/aidlc-infrastructure-design/SKILL.md	Run the AI-DLC `infrastructure-design` stage (construction phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage infrastructure-design --single`: the engine emits one run-stage directive for infrastructure-design and its gate, the conductor runs it, then the single-stage
skills/aidlc-init/SKILL.md	Start an AI-DLC workflow — run the whole Initialization phase (mint the intent, detect the workspace, build state) in one step, without typing a stage. The engine normally auto-creates the first intent; this is opt-in packaging over that move. Pass `--scope <name>` to seed the initial scope. A freef
skills/aidlc-intent-capture/SKILL.md	Run the AI-DLC `intent-capture` stage (ideation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage intent-capture --single`: the engine emits one run-stage directive for intent-capture and its gate, the conductor runs it, then the single-stage run commits a synthetic-
skills/aidlc-knowledge/SKILL.md	Index the team's own documents — PDFs, Word files, Markdown, plain text — into a per-space catalog the AI-DLC agents can cite. Wraps `aidlc-knowledge.ts`: onboard, sync, list, show, associate, dissociate, rebind, summarize. Every catalog row is written by the tool under a workspace lock; this skill
skills/aidlc-market-research/SKILL.md	Run the AI-DLC `market-research` stage (ideation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage market-research --single`: the engine emits one run-stage directive for market-research and its gate, the conductor runs it, then the single-stage run commits a synthet
skills/aidlc-mvp/SKILL.md	Run the AI-DLC workflow with the mvp scope baked in — no scope detection. Skip operations, ship the core. Packaging over `/aidlc --scope mvp`, which works without this skill.
skills/aidlc-nfr-design/SKILL.md	Run the AI-DLC `nfr-design` stage (construction phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage nfr-design --single`: the engine emits one run-stage directive for nfr-design and its gate, the conductor runs it, then the single-stage run commits a synthetic-id pair
skills/aidlc-nfr-requirements/SKILL.md	Run the AI-DLC `nfr-requirements` stage (construction phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage nfr-requirements --single`: the engine emits one run-stage directive for nfr-requirements and its gate, the conductor runs it, then the single-stage run commits a
skills/aidlc-observability-setup/SKILL.md	Run the AI-DLC `observability-setup` stage (operation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage observability-setup --single`: the engine emits one run-stage directive for observability-setup and its gate, the conductor runs it, then the single-stage run comm
skills/aidlc-outcomes-pack/SKILL.md	Generate a comprehensive handover document at workflow close so the team can own, operate, and continue the system without re-running the workflow. Stage/phase/learning counts come from `aidlc engine runtime summary`; prose comes from the artefacts. Writes OUTCOMES.md but never mutates workflow stat
skills/aidlc-performance-validation/SKILL.md	Run the AI-DLC `performance-validation` stage (operation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage performance-validation --single`: the engine emits one run-stage directive for performance-validation and its gate, the conductor runs it, then the single-stage
skills/aidlc-practices-discovery/SKILL.md	Run the AI-DLC `practices-discovery` stage (inception phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage practices-discovery --single`: the engine emits one run-stage directive for practices-discovery and its gate, the conductor runs it, then the single-stage run comm
skills/aidlc-refined-mockups/SKILL.md	Run the AI-DLC `refined-mockups` stage (inception phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage refined-mockups --single`: the engine emits one run-stage directive for refined-mockups and its gate, the conductor runs it, then the single-stage run commits a synthe
skills/aidlc-replay/SKILL.md	Print a structured session narrative for stakeholders who weren't in the room. Numbers (stage counts, phase rollup, duration) come from `aidlc engine runtime summary`; prose comes from the audit trail and artefacts. Renders to the terminal only — writes no file, never mutates workflow state, never e
skills/aidlc-requirements-analysis/SKILL.md	Run the AI-DLC `requirements-analysis` stage (inception phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage requirements-analysis --single`: the engine emits one run-stage directive for requirements-analysis and its gate, the conductor runs it, then the single-stage ru
skills/aidlc-reverse-engineering/SKILL.md	Run the AI-DLC `reverse-engineering` stage (inception phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage reverse-engineering --single`: the engine emits one run-stage directive for reverse-engineering and its gate, the conductor runs it, then the single-stage run comm
skills/aidlc-rough-mockups/SKILL.md	Run the AI-DLC `rough-mockups` stage (ideation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage rough-mockups --single`: the engine emits one run-stage directive for rough-mockups and its gate, the conductor runs it, then the single-stage run commits a synthetic-id
skills/aidlc-scope-definition/SKILL.md	Run the AI-DLC `scope-definition` stage (ideation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage scope-definition --single`: the engine emits one run-stage directive for scope-definition and its gate, the conductor runs it, then the single-stage run commits a synt
skills/aidlc-security-patch/SKILL.md	Run the AI-DLC workflow with the security-patch scope baked in — no scope detection. CVE response. Packaging over `/aidlc --scope security-patch`, which works without this skill.
skills/aidlc-session-cost/SKILL.md	Read-only session cost view. Prints deterministic aggregates for the current workflow — duration, stage outcomes, memory entries, sensor firings, learnings captured — sourced entirely from `aidlc engine runtime summary`. Never mutates workflow state, never emits audit events, never writes files.
skills/aidlc-team-formation/SKILL.md	Run the AI-DLC `team-formation` stage (ideation phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage team-formation --single`: the engine emits one run-stage directive for team-formation and its gate, the conductor runs it, then the single-stage run commits a synthetic-
skills/aidlc-units-generation/SKILL.md	Run the AI-DLC `units-generation` stage (inception phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage units-generation --single`: the engine emits one run-stage directive for units-generation and its gate, the conductor runs it, then the single-stage run commits a syn
skills/aidlc-user-stories/SKILL.md	Run the AI-DLC `user-stories` stage (inception phase) in isolation, without advancing the main workflow. Packages `/aidlc --stage user-stories --single`: the engine emits one run-stage directive for user-stories and its gate, the conductor runs it, then the single-stage run commits a synthetic-id pa
skills/aidlc/SKILL.md	AI-DLC workflow orchestrator. Start, resume, or manage an AI-driven development lifecycle. Scopes are defined one file per scope under `.claude/scopes/`; run `aidlc engine orchestrate help` for the authoritative list and descriptions. Utilities, each an argument to `aidlc engine orchestrate next` an
skills/aidlc/composer.md	Composing a workflow plan (the adaptive composer)
skills/aidlc/question-rendering.md	Question Rendering — Claude Code harness annex
tools/aidlc-archive.ts	—
tools/aidlc-artifact-resolution.ts	Explicit intent record for targeted read-only queries such as --status.
tools/aidlc-artifact-vocabulary.ts	Dependency-free artifact vocabulary shared by library and runtime resolvers.
tools/aidlc-attest.ts	—
tools/aidlc-audit.ts	—
tools/aidlc-bolt.ts	—
tools/aidlc-channel.ts	—
tools/aidlc-color.ts	—
tools/aidlc-command.ts	—
tools/aidlc-completions.ts	—
tools/aidlc-config-diagnostics.ts	—
tools/aidlc-construction-checkpoints.ts	Integrated Construction checkpoints. This module owns evidence and decisions;
tools/aidlc-directive.ts	—
tools/aidlc-distribution.ts	jsonc-settings adds each shipped top-level key that is absent and never changes a key someone else set.
tools/aidlc-doctor-bundle.ts	—
tools/aidlc-doctor.ts	—
tools/aidlc-documentkb-schema.ts	—
tools/aidlc-gitignore.ts	"],
tools/aidlc-graph.ts	—
tools/aidlc-guard-fences.ts	Config keys of the per-run switches: `guard.plan-approval` and so on.
tools/aidlc-guard-operation.ts	—
tools/aidlc-guard-switch.ts	Rename an active intent's valid retired policy field without changing its
tools/aidlc-hook-front-gate.ts	The record's hooks-health folder, as hooksHealthDir in aidlc-lib names it.
tools/aidlc-hook-trace.ts	Append one phase line for this process. Never throws.
tools/aidlc-includes.ts	.json.
tools/aidlc-init.ts	—
tools/aidlc-inline-context.ts	—
tools/aidlc-install-paths.ts	—
tools/aidlc-jump.ts	—
tools/aidlc-kiro-session.ts	—
tools/aidlc-knowledge.ts	`knowledge/documents/` — the user's originals.
tools/aidlc-learnings.ts	—
tools/aidlc-lib.ts	—
tools/aidlc-lifecycle.ts	—
tools/aidlc-log.ts	—
tools/aidlc-machine-config.ts	—
tools/aidlc-metrics.ts	pre-init
tools/aidlc-model-policy.ts	—
tools/aidlc-orchestrate.ts	—
tools/aidlc-plan-approval-ask.ts	The fingerprint of the plan, instructions, and contract when asked.
tools/aidlc-plugin-build.ts	—
tools/aidlc-plugin-create.ts	—
tools/aidlc-plugin-emit.ts	—
tools/aidlc-plugin-test.ts	—
tools/aidlc-plugin-validate.ts	—
tools/aidlc-plugin.ts	—
tools/aidlc-question-store.ts	An item a routing question named, by folder and immutable uuid.
tools/aidlc-recorded-switches.ts	The switches that take a check from the person and are off because a
tools/aidlc-release.ts	—
tools/aidlc-reply-reader.ts	—
tools/aidlc-review-brief.ts	Parse a legacy embedded review: the `## Review` section a reviewer wrote into
tools/aidlc-rule-schema.ts	—
tools/aidlc-rules-held.ts	The sentence a pointer step carries beside `rules_held`.
tools/aidlc-runner-gen.ts	.md` files. A stage added to the graph (or a
tools/aidlc-runtime-budget.ts	Operational backstops for tools, hooks, and build-time consumers.
tools/aidlc-runtime-paths.ts	—
tools/aidlc-runtime.ts	—
tools/aidlc-sensor-claim-sources.ts	—
tools/aidlc-sensor-linter.ts	—
tools/aidlc-sensor-required-sections.ts	—
tools/aidlc-sensor-schema.ts	—
tools/aidlc-sensor-traceability.ts	—
tools/aidlc-sensor-type-check.ts	—
tools/aidlc-sensor-upstream-coverage.ts	—
tools/aidlc-sensor.ts	—
tools/aidlc-settings.ts	` (what it does)` to follow a setting's name in a line the person reads, or
tools/aidlc-stage-schema.ts	—
tools/aidlc-state.ts	—
tools/aidlc-steering.ts	—
tools/aidlc-swarm-checkpoints.ts	Human review of a completed native swarm batch, independent of its driver.
tools/aidlc-swarm.ts	—
tools/aidlc-testing-posture.ts	—
tools/aidlc-tiers.ts	The tier vocabulary, ordered HIGH to LOW. The order is load-bearing:
tools/aidlc-transaction.ts	—
tools/aidlc-uninstall-plan.ts	—
tools/aidlc-unit.ts	—
tools/aidlc-update.ts	—
tools/aidlc-usage.ts	—
tools/aidlc-utility.ts	—
tools/aidlc-validate.ts	Extract .md filenames from the Outputs header field.
tools/aidlc-validity.ts	Optional immutable receipt written on main-workflow STAGE_COMPLETED rows.
tools/aidlc-version.ts	—
tools/aidlc-windows-uninstall.ts	—
tools/aidlc-workspace-doctor.ts	One --doctor report row. Structurally matches handleDoctor's results[].
tools/aidlc-workspace-manifest.ts	—
tools/aidlc-workspace-sync.ts	and advertised OIDs
tools/aidlc-worktree.ts	—
tools/aidlc.ts	—
tools/data/agent-tiers.json	—
tools/data/aidlc-manifest.json	—
tools/data/aidlc-projection.json	—
tools/data/aidlc-settings.schema.json	—
tools/data/aidlc-stamp.json	—
tools/data/ars-priors.json	—
tools/data/harness.json	—
tools/data/memory-seed/org.md	Org-Level Rules
tools/data/memory-seed/phases/construction.md	Construction Phase Guardrails
tools/data/memory-seed/phases/ideation.md	Ideation Phase Guardrails
tools/data/memory-seed/phases/inception.md	Inception Phase Guardrails
tools/data/memory-seed/phases/operation.md	Operation Phase Guardrails
tools/data/memory-seed/project.md	Project-Level Rules
tools/data/memory-seed/team.md	Team-Level Rules
tools/data/memory-seed/templates/.gitkeep	—
tools/data/model-rates.json	—
tools/data/plugin-authoring-context.json	—
tools/data/plugin-hooks-template/aidlc-plugin-compose.ts	—
tools/data/plugin-hooks-template/compose.ts	—
tools/data/plugin-targets.json	—
tools/data/root-blocks/.mcp.json	—
tools/data/root-blocks/gitignore	—
tools/data/scope-grid.json	—
tools/data/stage-graph.json	—
tools/data/templates/.gitkeep	—

Every command, in one place

Where	Command	What it does
shell	`aidlc config [--harness claude]`	Install or refresh the harness in this project (step 3). Sections: models, runtime, providers, trust, flags, project; `--show` to look.
shell	`aidlc system workspace-sync [--force]`	Clone missing repos from `repos.json`, keep `.gitignore` and `aidlc.code-workspace` current (step 4).
shell	`aidlc doctor [--verbose]`	Check machine and project, with a fix for each problem (step 5).
shell	`aidlc version` · `update` · `use` · `uninstall`	Manage the install on this machine (step 1).
shell	`aidlc engine <noun> <verb>`	The engine the harness calls (state, gates, audit, knowledge, codekb…). Its own help says it is "not for human scripts"; the course uses a few read-only or knowledge verbs to show real output.
Claude Code	`/aidlc <scope> <what to build>`	Start a run, e.g. `/aidlc express Build what ./docs-in/request.md describes`. Naming the scope starts the run at once, with no scope question; without one, AI-DLC infers a scope from your request (the default in `settings.json` is `classic`). The first gate is the first stage that ends with a question: Reverse Engineering on existing code.
Claude Code	`/aidlc`	Resume the active run from its `aidlc-state.md`.
Claude Code	`/aidlc --doctor` · `--version`	The same checks from inside Claude Code.
Claude Code	`/aidlc --stage <slug>` · `--phase <name>`	Jump to a stage or phase.
Claude Code	`/aidlc --depth <level>` · `--test-strategy <level>` · `--review <class>`	Override how long artifacts are, how many tests, how much review.
Claude Code	`/aidlc compose "<task>"`	Get a stage plan tailored to the task, behind an approve/edit/reject gate.
Claude Code	`/aidlc-express`, `/aidlc-feature`, … · `/aidlc-<stage>` · `/aidlc-knowledge`	The skills in `.claude/skills/`: a scope baked in, one stage alone, or a helper.

What is real here

Steps 1–6 were run on 14 Oct 2026 with AI-DLC Workflows 2.11.0 on Windows, in an empty folder with exactly the commands of step 2 (the five team files they write are byte for byte those of aidlc-java-workspace main): every output, file count and commit size above comes from that run (paths shown as C:\work\…). The file lists and descriptions are generated from the files themselves. Steps 7 and 8 are the documented behaviour, not captured: step 7 needs an interactive Claude Code session, and step 8's gh login is your own account. The descriptions of what each part is for come from the files' own headers and AI-DLC's documentation.

Docs: CLI commands · spaces and intents · knowledge · Claude features.

Set up an AI-DLC workspace, and know what every file is for.

Install the aidlc command and Claude Code

Write the team's files: start from an empty folder

aidlc config: install the harness for Claude Code

aidlc system workspace-sync: bring in the code repos

aidlc doctor: check the machine and the project

Commit the workspace, after one team decision

Start Claude Code in the workspace

Where pull requests come from: files you already wrote

Every file in a set-up workspace, one by one

.claude/, folder by folder

(root) 3 files

agents/ 14 files

skills/ 44 files

scopes/ 11 files

aidlc-common/ 43 files

knowledge/ 60 files

hooks/ 19 files

sensors/ 6 files

tools/ 113 files

rules/ 1 file

When each hook runs

.claude/settings.json, explained

All 314 generated files

Every command, in one place

What is real here

`.claude/`, folder by folder

`.claude/settings.json`, explained