AI-DLC Claude Code Plugin

AI-Driven Development Lifecycle: an iterative, effort-tracked methodology for LLM-augmented software work. Inception establishes the project baseline once; every subsequent feature, fix, refactor, or migration is tracked as a numbered effort with its own state, artifacts, and audit trail.

Quick Install

# Add the otc-awesome-llm marketplace
claude plugin marketplace add /path/to/otc-awesome-llm

# Install the AI-DLC plugin
claude plugin install ai-dlc@otc-awesome-llm

# Verify installation
claude plugin list | grep ai-dlc

Session-only (testing without install):

claude --plugin-dir /path/to/otc-awesome-llm/claude-code/plugins/ai-dlc

Prerequisites: Claude Code v2.0+, a git repository, and (optionally) the drzero plugin if you want construction stages to dispatch to the Dr. Zero swarm.

30-Second Mental Model

Two commands carry the workflow:

• /ai-dlc:inception runs once per project. It produces the baseline: requirements, architecture, components, technology stack. Re-run it (idempotently) only when the baseline itself needs revision.
• /ai-dlc:effort runs every time after that. Each feature, bug, refactor, or migration is a numbered effort (001, 002, ...) under aidlc-docs/efforts/, with its own effort-state.md, requirements delta, and construction artifacts.

The project baseline is the north star; efforts iterate against it. The registry (aidlc-docs/registry.md) is a derived view rebuilt from per-effort state files. Canonical glossary for every term used below (phase vs stage, unit of work, plans vs artifacts): rules/common/terminology.md.

Lifecycle at a Glance

flowchart TD
    start([Project start]) --> inc["/ai-dlc:inception<br/>(once per project)"]
    inc --> detect{Workspace detection}
    detect -->|Existing code| reveng["Reverse engineering<br/>(brownfield)"]
    detect -->|Empty workspace| req["Requirements analysis<br/>(interactive)"]
    reveng -->|Approved| req
    req --> design["Workflow planning +<br/>application design"]
    design --> baseline[("Inception baseline<br/>aidlc-docs/inception/")]
    baseline --> effort["/ai-dlc:effort<br/>(every change)"]
    effort --> kind{Effort type?}
    kind -->|Feature / refactor / migration| plan["Effort planning:<br/>requirements delta"]
    kind -->|"--fix (bug)"| fixchar["Fix fast-path:<br/>bug characterization"]
    plan -->|Delta approved| cons["Construction per unit<br/>(drzero or bundled)"]
    cons --> ops["Operations<br/>(placeholder)"]
    ops -->|Next change| effort
    fixchar -->|Characterized| testspec["Test specification<br/>(approval gate)"]
    testspec -->|Approved| builder["Builder handoff<br/>(Dr. Zero or code-generator)"]
    builder -->|Next change| effort
    fixchar -->|"2+ requirements-gap signals"| escape["Escape hatch"]
    escape -->|Re-scope| inc

The fix fast-path's escape hatch redirects to /ai-dlc:inception when a "bug" turns out to be a requirements gap; inside an effort context it redirects to re-scoped effort planning instead (the baseline already exists). Baseline revisions always re-run /ai-dlc:inception — never an effort.

Capability Matrix

Mode	Command	When to use
Greenfield	/ai-dlc:inception (fresh) → /ai-dlc:effort --type=construction for effort 001	New project from scratch
Brownfield	/ai-dlc:inception (workspace detection enables reverse engineering) → /ai-dlc:effort	Retrofit AI-DLC onto existing code
Iterative continuation	/ai-dlc:effort #42 / --fix #57 / --type=refactor / --type=migration	After the baseline exists
Baseline revision	/ai-dlc:inception (re-run; idempotent)	Architecture or requirements baseline changes
Visibility	/ai-dlc:status	Anytime, to see registry, active effort, next stage

Legacy commands: /ai-dlc:fix and /ai-dlc:construction still work and write to aidlc-docs/fix/ and aidlc-docs/construction/ respectively. Effort-tracked variants (/ai-dlc:effort --fix, /ai-dlc:effort --type=construction) are preferred — they namespace artifacts under aidlc-docs/efforts/{NNN}-{ref}/ for traceability.

Brownfield in depth: the step-by-step retrofit recipe (what workspace detection looks for, the nine reverse-engineering artifacts, the approval gates) lives in How to run AI-DLC on brownfield code.

Depth Levels

Two separate dials control how much lifecycle a project gets, and they must not be conflated. Stage selection is binary and belongs to Workflow Planning: each stage is marked EXECUTE or SKIP, and an executed stage always produces all of its defined artifacts. Depth governs the rigor inside those artifacts — the same files are created at every depth; what changes is how much detail, traceability, and verification they carry:

Depth	Artifact rigor	Typical use
minimal	Concise artifacts, essential detail only, few clarifying questions	Simple changes, prototypes
standard (default)	Normal detail for typical scope and risk	Typical projects
comprehensive	Extensive detail: traceability, acceptance criteria, multiple question rounds	Complex or high-risk work

The default_depth config key (/ai-dlc:config --set default_depth=...) expresses your prior on rigor and informs Workflow Planning's defaults, but the EXECUTE/SKIP decision per stage remains Workflow Planning's call, driven by the problem's characteristics. Canonical (including the factors the model weighs per artifact): rules/common/depth-levels.md.

Decision Tree

"I want to ___ — which command?"

Is there an aidlc-docs/inception/ baseline yet?
├── No  → /ai-dlc:inception                    (greenfield or brownfield, run once)
└── Yes → What kind of work?
    ├── New feature                            → /ai-dlc:effort #ISSUE
    ├── Bug fix                                → /ai-dlc:effort --fix #ISSUE
    ├── Refactor                               → /ai-dlc:effort --type=refactor "summary"
    ├── Migration / large rewrite              → /ai-dlc:effort --type=migration "summary"
    ├── Initial build (effort 001)             → /ai-dlc:effort --type=construction
    ├── Architecture / requirements changed    → /ai-dlc:inception   (idempotent re-run)
    └── Just want to see status                → /ai-dlc:status

If you start an effort and discover the baseline is wrong, finish or abandon the effort, then re-run /ai-dlc:inception to revise the baseline. Inception always writes to aidlc-docs/inception/; it never writes inside an effort directory.

Worked Examples

Example 1: Greenfield project

$ cd ~/scm/my-new-service
$ git init
$ /ai-dlc:inception
# Workspace detection: no existing code → greenfield
# Interactive questionnaire: stakeholders, features, NFRs, constraints
# Approval gates: requirements → user stories → workflow plan → application design
# Result: aidlc-docs/inception/ populated, aidlc-state.md status=complete

$ /ai-dlc:effort --type=construction
# Allocates effort 001-initial-build
# Creates aidlc-docs/efforts/001-initial-build/effort-state.md (status=planning)
# Runs construction stages (functional design, NFR, code generation, build/test)
# Artifacts land in aidlc-docs/efforts/001-initial-build/construction/{unit}/

What gets created:

aidlc-docs/
├── inception/                          # baseline (run once)
├── aidlc-state.md                      # phase=construction
├── audit.md
├── registry.md                         # 001 row regenerated from filesystem
└── efforts/
    └── 001-initial-build/
        ├── effort-state.md
        ├── plans/
        └── construction/{unit}/

Example 2: Brownfield retrofit

$ cd ~/scm/legacy-api      # existing Node.js codebase, no aidlc-docs/
$ /ai-dlc:inception
# Workspace detection: existing code present → brownfield path enabled
# Reverse-engineering stage runs first: scans codebase, infers components,
#   technology stack, current architecture; writes aidlc-docs/inception/reverse-engineering/
# Approval gate on reverse-engineering output, then proceeds with normal inception
#   (requirements + design baseline) using the inferred architecture as input

$ /ai-dlc:effort "import existing services"
# Optional: register an effort 000-legacy-import to formally claim pre-AI-DLC work
# Or skip and start at 001 with the next real change

$ /ai-dlc:effort --fix #173
# Once baseline exists, all change is effort-tracked

Note: legacy aidlc-docs/construction/ and aidlc-docs/fix/ directories from pre-effort versions are preserved untouched. The effort numbering starts at 001 or higher; nothing is moved or rewritten.

Example 3: New feature from a GitHub issue

$ cd ~/scm/my-service       # already has aidlc-docs/inception/
$ /ai-dlc:effort #42
# Reads inception baseline; verifies status=complete
# Pre-allocation repair scan reconciles registry.md from filesystem
# Allocates next number (e.g., 003); creates aidlc-docs/efforts/003-gh-42-add-webhooks/
# Effort planning: requirements-delta.md (NEW-FR / CHG-FR vs baseline)
# Approval gate on delta
# Dispatches construction stages within the effort directory

Effort directory:

aidlc-docs/efforts/003-gh-42-add-webhooks/
├── effort-state.md                     # status transitions: planning → awaiting-approval → in-progress → complete
├── requirements-delta.md
├── plans/
└── construction/
    └── webhook-dispatcher/
        ├── functional-design/
        ├── nfr-requirements/
        └── code/

Example 4: Bug fix (TDD fast-path)

$ /ai-dlc:effort --fix #57
# Allocates aidlc-docs/efforts/004-gh-57-fix-auth-timeout/
# Stage 1: bug characterization (root cause, affected files, impact)
# Stage 2: test specification (regression + edge + guard tests) — APPROVAL GATE
# Stage 3: builder handoff
#   default → drzero swarm dispatched by domain
#   --no-drzero → inline code-generator
# Escape hatch: if 2+ requirements gaps detected, redirects to /ai-dlc:inception

What gets created:

aidlc-docs/efforts/004-gh-57-fix-auth-timeout/
├── effort-state.md                     # type=fix
├── bug-characterization.md
├── test-specification.md
└── code/

The user reviews the test specification at the gate before any code is written — this is the TDD-first contract.

Example 5: Migration / refactor

$ /ai-dlc:effort --type=migration "migrate to v2 API"
# Allocates aidlc-docs/efforts/005-migrate-to-v2-api/
# Effort planning: requirements-delta.md captures CHG-FR rows for affected
#   endpoints, In-Scope / Out-of-Scope, new constraints
# Approval gate on delta
# Construction stages run with effort-aware paths

Use --type=refactor for internal restructuring with no behavior change, and --type=migration for cross-cutting rewrites that change interfaces or data shape. Both follow the same effort lifecycle as features; the type only labels the row in registry.md and informs scope expectations.

Commands Reference

One paragraph each. The full rule files are the authoritative source — these are intent summaries. The plugin ships 6 commands (commands/), 11 agents (agents/), and 3 skills (skills/). The austere flag-by-flag reference lives at docs/plugins/ai-dlc/reference/command-reference.md.

/ai-dlc:inception

Runs the project baseline: workspace detection (greenfield vs brownfield, with optional reverse-engineering for existing code), interactive requirements questionnaire, value case, user stories (when warranted), workflow planning, and application design. Idempotent — re-running on a project with existing inception artifacts detects each stage's prior status via the Stage Entry Protocol: complete stages offer Skip / Re-run / Update, while interrupted stages resume under the separate Resume Protocol. Always writes to aidlc-docs/inception/. See commands/inception.md.

/ai-dlc:effort

Creates and manages a numbered effort. Verifies the inception baseline, runs the pre-allocation repair scan (reconciles registry.md from filesystem state), atomically allocates the next effort number via a mkdir-without--p lock, writes effort-state.md, runs effort planning (requirements delta), then dispatches to construction stages or the fix fast-path. Supports [issue-ref], --fix, --type=feature|fix|refactor|migration|construction, --no-drzero, --skip-approval. Two maintenance flags operate on existing efforts instead of allocating a new one: --repair runs an interactive domain-routing repair pass (scans the effort plan's units for missing/invalid primary_domain, offers candidate routing or an execution_mode: bundled opt-out per unit, persists via Edit to the effort plan only, then exits — idempotent), and --effort=NNN targets a specific effort for repair (only meaningful with --repair; without it, repair targets the most recent non-terminal effort and prompts when several match). See commands/effort.md.

/ai-dlc:construction

Per-unit construction: functional design, NFR requirements, NFR design, infrastructure design, code generation, build-and-test. When invoked from an effort context, all artifacts land under aidlc-docs/efforts/{NNN}-{ref}/. When invoked standalone, uses legacy aidlc-docs/construction/ paths. Recommended usage is via /ai-dlc:effort --type=construction. See commands/construction.md.

/ai-dlc:fix

Inline 3-stage TDD-first fix flow (characterization → test spec → builder handoff). Suitable for well-understood bugs that don't need full inception/ construction. Includes an escape hatch that redirects to /ai-dlc:inception when 2+ requirements gaps are detected. Recommended usage is via /ai-dlc:effort --fix for full effort tracking; /ai-dlc:fix remains for standalone quick fixes outside the effort registry. See commands/fix.md.

/ai-dlc:status

Read-only. Displays project baseline status, the effort registry, the active effort (if any), the current phase and stage, completed/skipped stages, next recommended action, and recent audit entries. --verbose shows the full audit trail and artifact list. See commands/status.md.

/ai-dlc:config

View or modify configuration stored in aidlc-docs/.aidlc-config.json. Controls approval-gate behavior, output directory, audit verbosity, depth preference, and per-effort defaults (auto_number, require_issue, default_type). See commands/config.md.

Where Things Land

aidlc-docs/
├── aidlc-state.md                      # Project-level state (inception phase context)
├── audit.md                            # Global audit trail
├── registry.md                         # Effort registry (DERIVED VIEW — regenerated)
├── .aidlc-config.json                  # Optional configuration
├── inception/                          # Project baseline (run once)
│   ├── plans/
│   ├── reverse-engineering/            # brownfield only
│   ├── requirements/
│   ├── feasibility/
│   ├── value-case/
│   ├── user-stories/
│   └── application-design/
└── efforts/                            # Per-effort directories (accumulate)
    ├── 001-initial-build/
    │   ├── effort-state.md             # Effort-specific state
    │   ├── requirements-delta.md       # New/changed vs baseline (none for 001)
    │   ├── plans/
    │   ├── construction/
    │   │   └── {unit-name}/
    │   │       ├── functional-design/
    │   │       ├── nfr-requirements/
    │   │       ├── nfr-design/
    │   │       ├── infrastructure-design/
    │   │       └── code/
    │   └── build-and-test/
    ├── 002-gh-42-add-webhooks/
    └── 003-gh-57-fix-auth-timeout/
        ├── bug-characterization.md
        ├── test-specification.md
        └── ...

registry.md is regenerated from aidlc-docs/efforts/*/effort-state.md files — the filesystem is the source of truth, the registry table is a derived view. See rules/common/effort-management.md "Registry = Derived View".

Effort Naming and Allocation

Effort directories are named {NNN}-{ref}: {NNN} is the next available zero-padded number, computed as max(registry, filesystem) + 1; {ref} is gh-{N} for issue-linked efforts, the kebab-cased first words of the description otherwise, or manual-{ISO-date} as the fallback. Allocation is atomic: the claim is a plain mkdir (never -p) on the effort directory, which POSIX guarantees succeeds-and-creates or fails with EEXIST — a losing concurrent allocation increments and retries (capped at 5). The effort-state.md write that follows is the durable proof of allocation; empty directories without one are reaped as orphans by the next run's repair scan. The registry stays a derived view throughout — regenerated from state files, never the lock itself. Canonical: rules/common/effort-management.md.

Effort State Transitions

stateDiagram-v2
    state "planning" as planning
    state "awaiting-approval" as awaiting
    state "in-progress" as inprogress
    state "complete" as complete
    state "blocked" as blocked
    state "failed" as failed
    [*] --> planning : directory claimed
    planning --> awaiting : delta + plan authored
    awaiting --> inprogress : user approves
    inprogress --> complete : aggregate gate passes
    inprogress --> blocked : external dependency
    inprogress --> failed : unrecoverable error
    blocked --> inprogress : dependency resolved
    failed --> inprogress : Resume Protocol
    complete --> [*]

(abandoned and superseded are reachable from any non-terminal state; complete, abandoned, and superseded are terminal.) Every stage entry runs three protocols that make re-runs safe: the Stage Entry Protocol reads the active state file and branches on this stage's status; the Resume Protocol continues in-progress/failed/blocked/planning/ awaiting-approval stages from where they stopped (checkbox plans resume at the first unchecked item; pending gates are re-presented); and the Skip-if-Complete Protocol offers Skip / Re-run (archive first) / Update for stages already complete — prior artifacts are never silently overwritten. Canonical: rules/common/idempotency-guards.md.

Per-unit construction state (status, attempts, retry lineage, review records) lives in a separate durable manifest at construction/manifest.md; effort-level complete is derived from it, never set directly. Canonical: rules/common/unit-manifest-schema.md.

Approval Gates

Artifact-producing stages pause at a standardized 2-option gate (Request Changes / Continue); feasibility and fix use documented 3-option variants. Gates are presented via AskUserQuestion, never free text, and every raw response is recorded in audit.md. Disable for automation only, via --skip-approval or approval_gates=disabled.

In addition to human gates, the Critical Lens adversarial review runs after designated stages (reverse engineering, requirements, application design, NFR design, code generation, fix test specs): the critical-lens agent re-examines the approved artifacts against a registry of predicates before the next stage starts. Artifact predicates can be delegated to Dr. Zero's own review via drzero_review_covers; lifecycle predicates always run and cannot be skipped. Canonical: rules/critical-lens-review.md.

Hook Safety Story

Atomic effort allocation is enforced via PreToolUse hooks: a mkdir (without -p) lock guarantees that two concurrent allocations cannot claim the same effort number, and Write/Edit/MultiEdit on aidlc-state.md and per-effort effort-state.md files are protected against clobber (initial-creation only; subsequent updates must use Edit). See claude-code/plugins/ai-dlc/hooks/CLAUDE.md for the hook contract and hooks/block-state-file-clobber.sh, hooks/block-mkdir-p-on-efforts.sh, hooks/require-effort-dir-before-write.sh for the enforcement scripts.

Dr. Zero Integration

AI-DLC plans; Dr. Zero builds. Construction dispatches each unit of work to the Dr. Zero swarm by default, carrying a structured domain_routing: YAML block that names the unit's domains (1–8 slugs from the canonical 16-domain taxonomy), its primary_domain, its execution_mode (drzero default, or bundled to opt a unit out of the swarm and run it via the inline code-generator), and its advisory quality_gates (default empty — this plugin ships no reviewer agents; organizations inject their own review chain). The orchestrator validates routing before any work starts, fans units out in dependency order, and stamps results back into the effort's state and manifest as runtime verdicts.

Use --no-drzero on /ai-dlc:effort, /ai-dlc:construction, or /ai-dlc:fix to bypass the swarm entirely; if the drzero plugin simply isn't installed, construction falls back to the bundled path with a warning. The full integration story — payload schema with examples, the 16-domain table, the H1–H6 orchestrator procedure, failure and resume semantics — is at docs/plugins/ai-dlc/explanation/drzero-integration.md. Canonical contract: rules/common/drzero-domain-mapping.md.

Configuration

Settings live in aidlc-docs/.aidlc-config.json. View, set, or reset via /ai-dlc:config. Common keys:

• approval_gates — enabled (default), disabled, or selective
• output_dir — defaults to aidlc-docs/
• audit_verbosity — minimal | standard (default) | detailed
• default_depth — minimal | standard (default) | comprehensive
• rules_directory — path to custom organization rules (see below)
• effort.auto_number — auto-allocate next effort number (default: true)
• effort.require_issue — require GitHub issue ref for new efforts (default: false)
• effort.default_type — default effort type (feature)
• fix.drzero_enabled / construction.drzero_enabled — Dr. Zero as default builder (default: true)

A realistic config for a team project that requires issue-linked efforts and keeps Dr. Zero as the construction builder:

{
  "workflow_mode": "repo",
  "approval_gates": "enabled",
  "output_dir": "aidlc-docs/",
  "audit_verbosity": "standard",
  "content_validation": "enabled",
  "default_depth": "standard",
  "question_format": "interactive",
  "effort": {
    "auto_number": true,
    "require_issue": true,
    "default_type": "feature"
  },
  "fix": {
    "drzero_enabled": true,
    "skip_tests": false,
    "critical_lens_enabled": true
  },
  "construction": {
    "drzero_enabled": true
  },
  "rules_directory": null
}

See commands/config.md for the full option list, presets (quick-start / prototype / team / solo / production), and the precedence chain (defaults → config file → AIDLC_* env vars → CLI flags).

Using Organization-Specific Rules

Organizations can maintain their own AI-DLC rules repositories with custom workflows, questions, coding standards, and compliance checks. This allows teams to adapt AI-DLC to their domain (healthcare, finance, government) without forking the plugin.

Setup:

1. Create organization rules repository:

   # Clone and customize base rules
   git clone https://github.com/your-org/aidlc-rules.git ~/.aidlc-rules
   cd ~/.aidlc-rules
   
   # Structure follows AI-DLC conventions
   rules/
   ├── common/           # Core workflow patterns
   ├── inception/        # Planning phase rules
   ├── construction/     # Implementation phase rules
   ├── effort/           # Effort planning rules
   └── operations/       # Deployment phase rules
   

2. Configure in your project:

   cd /path/to/your-project
   /ai-dlc:config --set rules_directory=$HOME/.aidlc-rules/rules
   
   # Verify configuration
   /ai-dlc:config --list
   # Rules Directory: /Users/you/.aidlc-rules/rules
   # Rules Source: Custom (/Users/you/.aidlc-rules/rules)
   

3. Run AI-DLC with custom rules:

   /ai-dlc:inception
   # ━━━ Using custom rules: /Users/you/.aidlc-rules/rules ━━━
   # [Executes using your organization's requirements questions,
   #  approval gates, coding standards, and compliance checks]
   

Example: Healthcare organization rules

Your platform team might customize:

• inception/requirements-analysis.md — Add HIPAA-specific questions
• construction/code-generation.md — Enforce secure coding standards
• common/terminology.md — Define healthcare domain terms
• construction/build-and-test.md — Add FDA validation requirements

Fallback behavior:

If rules_directory is configured but the path is missing or invalid, AI-DLC fails closed: it logs a FATAL error to audit.md and stops execution — it does NOT fall through to bundled rules. Fix the path with /ai-dlc:config --set rules_directory=... or remove it with /ai-dlc:config --reset rules_directory. Bundled rules are only used when no rules_directory is configured at all: the commands resolve the installed plugin's rules via installed_plugins.json, with claude-code/plugins/ai-dlc/rules/ (relative to the working repo) as the development-mode fallback when the plugin is not installed.

Team distribution:

Your organization can provide a setup script:

#!/bin/bash
# setup-aidlc.sh
git clone https://github.com/acme-health/aidlc-rules.git ~/.aidlc-rules
echo "Custom AI-DLC rules installed at ~/.aidlc-rules"
echo "Configure in projects with: /ai-dlc:config --set rules_directory=\$HOME/.aidlc-rules/rules"

Recommended installation (download, verify, then execute):

# Download a pinned version of the setup script
curl -fsSL https://setup.acme.com/aidlc-v1.2.0.sh -o /tmp/setup-aidlc.sh

# Verify checksum before execution
echo "expected_sha256_hash  /tmp/setup-aidlc.sh" | sha256sum --check

# Execute only after verification passes
bash /tmp/setup-aidlc.sh

Security note: Avoid piping remote scripts directly into bash. Always download, verify the checksum or signature against a pinned version, and then execute. This prevents supply-chain attacks on the setup path.

Troubleshooting

Effort number collision

Two concurrent allocations can theoretically race. The mkdir lock prevents both succeeding, but a partial allocation (directory created, effort-state.md not yet written) leaves an anomaly. The pre-allocation repair scan in commands/effort.md Step 0.3 reconciles the registry with filesystem state on every effort start: empty orphan directories are reaped, partial allocations are preserved and surfaced in the audit trail, and registry.md is regenerated.

Plugin not loading

claude plugin validate /path/to/otc-awesome-llm/claude-code/plugins/ai-dlc
claude plugin uninstall ai-dlc@otc-awesome-llm
claude plugin install ai-dlc@otc-awesome-llm

Rule files not found

The commands resolve rules in this order:

1. Custom rules — Check aidlc-docs/.aidlc-config.json for rules_directory
2. Bundled plugin rules — Use installPath from ~/.claude/plugins/installed_plugins.json
3. Development fallback — Try claude-code/plugins/ai-dlc/rules/ relative to working repo

Steps 2 and 3 apply only when no rules_directory is configured. If rules_directory IS configured but missing or invalid, execution fails closed with a FATAL error — there is no fallback to bundled rules. Repair with /ai-dlc:config --set rules_directory=... or /ai-dlc:config --reset rules_directory. Reinstalling the plugin refreshes the bundled path. Never use wildcard Glob to find rules — it can match stale caches.

Approval gates not pausing

Set approval_gates: enabled in .aidlc-config.json (or run /ai-dlc:config --set approval_gates=enabled). Never use --skip-approval for production workflows; it exists for testing and automation only.

Effort state appears stuck (in-progress after a crash)

Re-running the same /ai-dlc:effort invocation triggers the Resume Protocol (see rules/common/idempotency-guards.md). Stages with status in-progress, failed, blocked, planning, or awaiting-approval resume; stages with status complete or skipped are skipped under the Skip-if-Complete Protocol. Manual recovery: edit effort-state.md (Edit tool only — Write is blocked) to flip the stuck stage's status, then re-invoke the command.

Registry shows stale rows

registry.md is a derived view and is regenerated on every allocation. If you hand-edited it (don't), or pulled in a partial merge, run /ai-dlc:effort once on any new work — Step 0.3 regenerates the registry from filesystem state.

Documentation

The plugin's documentation set under docs/plugins/ai-dlc/, organized by Diataxis quadrant:

• Tutorial: Getting started with AI-DLC — guided first session, greenfield
• How-to: Run AI-DLC on brownfield code — retrofit recipe with reverse engineering
• Reference: Command reference — all 6 commands, every flag, artifact paths, gate behavior
• Explanation: AI-DLC methodology — post-Agile framing and the baseline + effort architecture
• Explanation: Effort lifecycle — state machine, allocation, registry, idempotency
• Explanation: Dr. Zero integration — the handoff contract end to end

See Also

• rules/common/process-overview.md — full lifecycle reference, agent catalog, decision points
• docs/explanation/aidlc-iterative-process.md — narrative explanation with sequence diagrams
• docs/explanation/lifecycles.md — Product / Software / Operations lifecycle framing (PDL / SDL / OPS)
• rules/common/effort-management.md — effort architecture canonical
• rules/common/drzero-domain-mapping.md — AI-DLC ↔ drzero swarm contract
• rules/common/idempotency-guards.md — Stage Entry / Skip-if-Complete / Resume protocols
• rules/common/terminology.md — canonical glossary (phase vs stage, unit of work, depth levels)
• rules/common/unit-manifest-schema.md — per-unit construction manifest and aggregate gate
• rules/common/CLAUDE.md — common rules conventions
• rules/construction/CLAUDE.md — construction stage rule template
• hooks/CLAUDE.md — hook contract and effort-allocation guardrails
• ../drzero/agents/CLAUDE.md — Dr. Zero agent directory contract

Support

• GitHub Issues: https://github.com/optum-tech-compute/otc-awesome-llm/issues
• Contact: [email protected]
• License: Internal use only — Optum Technology