AI-DLC commands and agents

Complete reference for the AI-DLC plugin's slash commands, specialized agents, artifact structure, state management, and depth levels.

Commands

AI-DLC provides five slash commands that drive the lifecycle.

/ai-dlc:inception

Execute the Inception phase to determine WHAT to build and WHY.

Arguments:

Always executes:

• Workspace detection
• Requirements analysis (interactive questionnaire)
• Workflow planning

Conditionally executes (based on complexity assessment):

• Reverse engineering (brownfield projects with no existing artifacts)
• Feasibility analysis (product features, not internal tooling)
• Value case (projects requiring ROI justification)
• User stories (user-facing features with multiple personas)
• Application design (new components or services needed)
• Units generation (system decomposition for multi-component work)

Output: Inception artifacts in aidlc-docs/inception/

/ai-dlc:construction

Execute the Construction phase to determine HOW to build it and generate the implementation.

Arguments:

Per-unit stages (conditionally executed based on workflow plan):

• Functional design (new data models or complex business logic)
• NFR requirements (performance, security, scalability concerns)
• NFR design (patterns for implementing NFRs)
• Infrastructure design (cloud resources, deployment architecture)
• Code generation (always executes, two-phase plan-then-execute)

After all units:

• Build and test (always executes, generates comprehensive instructions)

Output: Construction artifacts in aidlc-docs/construction/

/ai-dlc:fix

Fast-path TDD-first bug-fix workflow for well-understood bugs that do not need the full Inception→Construction pipeline. Runs three stages inline (no sub-agent dispatch except the optional builder handoff) and includes an escape hatch that redirects to /ai-dlc:inception when requirements gaps are detected mid-flow.

Arguments:

Stages:

1. Bug Characterization — analyse the bug, locate affected code, assess impact
2. Test Specification — write failing tests first; present an approval gate before code changes
3. Builder Handoff — dispatch to Dr Zero or code-generator to make the tests pass

Output: Fix artifacts in aidlc-docs/fix/<issue-id>/

/ai-dlc:status

Check the current workflow state and progress at any time.

Arguments:

Displays:

• Current phase and stage
• Completed stages with approval status
• Skipped stages with rationale
• Pending stages
• Recent audit entries (last 10)
• Generated artifacts list
• Next recommended action

/ai-dlc:config

View or modify AI-DLC configuration.

View current configuration:

/ai-dlc:config

Set a configuration value:

/ai-dlc:config --set auto_approval=false
/ai-dlc:config --set verbose_logging=true

Configuration options:

You can also configure these values in a .ai-dlc.json file at the project root:

{
  "rules_directory": "~/.claude/aidlc-rules/aws-aidlc-rules",
  "output_directory": "aidlc-docs",
  "auto_approval": false,
  "verbose_logging": true,
  "skip_phases": [],
  "depth_preference": "standard"
}

Agents

AI-DLC delegates specialized work to purpose-built agents. Each agent operates within a specific phase and produces artifacts in a defined domain.

requirements-analyst

The key innovation of AI-DLC. Uses the Claude Agent SDK's AskUserQuestion tool to gather requirements through interactive questionnaires instead of manual markdown editing.

Inputs:

• Workspace detection results
• Reverse engineering artifacts (brownfield projects)
• AI-DLC rules from ~/.claude/aidlc-rules/

Outputs:

• aidlc-docs/inception/requirements/requirements.md

Process:

1. Loads workspace context
2. Analyzes intent to determine depth level
3. Generates adaptive question set (5--30 questions based on depth)
4. Presents questions one at a time with multiple-choice options
5. Uses branching logic to skip irrelevant questions
6. Generates requirements document with traceability matrix
7. Requests user approval

workflow-planner

Analyzes request complexity and determines which stages to execute at what depth.

Assessment factors:

• Request clarity (well-defined vs. ambiguous)
• Scope (single file vs. multi-component)
• Complexity (simple logic vs. complex system)
• Risk (low impact vs. security-critical)
• Codebase state (greenfield vs. brownfield)

Outputs:

• aidlc-docs/inception/plans/workflow-planning.md (execution plan with rationale)
• Mermaid workflow visualization with color-coded stages

Color coding in workflow diagrams:

• Green (ALWAYS) -- will execute regardless
• Blue (CONDITIONAL-YES) -- will execute based on assessment
• Pink (CONDITIONAL-NO) -- skipped based on assessment

feasibility-agent

Performs competitive landscape analysis and feasibility assessment before committing to full requirements gathering.

Capabilities:

• Web search for competitive landscape scanning (max 5 queries)
• Go/no-go decision matrix with weighted scoring (Market Viability 40%, Technical Feasibility 35%, Differentiation 25%)
• Anti-hallucination safeguards: [Inferred -- needs validation] markers, source citations, confidence levels

Skips automatically for: internal tooling, bug fixes, simple enhancements, infrastructure work.

Outputs:

• aidlc-docs/inception/feasibility/feasibility-assessment.md

value-case-agent

Produces ROI analysis with cost estimation, benefit quantification, and scenario modeling.

Capabilities:

• Development, infrastructure, maintenance, and opportunity cost estimation
• Revenue, cost savings, and risk reduction benefit analysis
• Conservative (30% adoption) and optimistic (80% adoption) scenarios
• Break-even timeline and 3-year projections

Outputs:

• aidlc-docs/inception/value-case/value-case.md

application-design-agent

Designs application components, services, and their dependencies during the Inception phase.

Outputs (in aidlc-docs/inception/application-design/):

• components.md -- component catalog with responsibilities
• component-methods.md -- method signatures and business logic
• services.md -- service layer design and boundaries
• component-dependency.md -- dependency mapping diagrams

functional-design-agent

Designs business logic models, rules, and domain entities during the Construction phase (per-unit).

Outputs (in aidlc-docs/construction/{unit}/functional-design/):

• business-logic-model.md -- business rules and state machines
• business-rules.md -- structured rule catalog
• domain-entities.md -- data structures and relationships

nfr-analyst

Assesses and documents non-functional requirements during the Construction phase.

Analyzes: performance (latency, throughput), security (auth, encryption), scalability (load, concurrency), and tech stack selection.

Outputs (in aidlc-docs/construction/{unit}/nfr-requirements/):

• nfr-requirements.md -- categorized NFR specifications
• tech-stack-decisions.md -- technology selection with rationale

nfr-design-agent

Designs patterns for implementing non-functional requirements.

Outputs (in aidlc-docs/construction/{unit}/nfr-design/):

• nfr-design-patterns.md -- patterns for each NFR category (caching, rate limiting, etc.)
• logical-components.md -- NFR-specific components

infrastructure-design-agent

Maps services to cloud resources and designs deployment architecture.

Outputs (in aidlc-docs/construction/{unit}/infrastructure-design/):

• infrastructure-design.md -- service-to-infrastructure mapping
• deployment-architecture.md -- topology and resource specifications

code-generator

Generates implementation code with comprehensive tests using a two-phase approach.

Phase 1 (planning): Creates a detailed plan listing every file to generate, with checkboxes for tracking. Includes implementation steps, testing strategy, quality standards checklist, and dependency list.

Phase 2 (execution): After plan approval, generates source code, unit tests, integration tests, and documentation. Updates plan checkboxes as each file completes.

Quality targets:

• 80%+ statement coverage
• 75%+ branch coverage
• 90%+ function coverage
• No hardcoded secrets
• Input validation on all user inputs
• Comprehensive error handling

Outputs (in aidlc-docs/construction/{unit}/code/):

• Source code files
• Test files (unit, integration, fixtures, mocks)
• Documentation files
• Configuration files

critical-lens-agent

Performs adversarial review at stage boundaries. Challenges assumptions, identifies risks, and enforces quality gates.

Five challenge categories:

1. Assumption risk -- unstated assumptions, default values treated as facts
2. Scope discipline -- scope creep, gold-plating, unnecessary complexity
3. Feasibility risk -- technical feasibility, unproven technology, integration concerns
4. Security/compliance risk -- data handling, auth boundaries, trust boundary crossings
5. Operational risk -- deployment risks, monitoring gaps, error handling deficiencies

Severity levels: blocker, high, medium, low (with confidence scoring 0.0--1.0)

Gate enforcement:

• FAIL -- unresolved blocker or high findings (must resolve before proceeding)
• PASS-WITH-WARNINGS -- unresolved medium findings (workflow continues with notice)
• PASS -- no unresolved findings above low

Dispositions: accept (with justification), mitigate (with action plan), defer (with target milestone), reject (with evidence-based rationale)

Artifact directory structure

aidlc-docs/
  inception/
    plans/
      workspace-detection.md          # Codebase analysis results
      workflow-planning.md            # Approved execution plan
      story-generation-plan.md        # User stories plan (if executed)
      unit-of-work-plan.md            # Units breakdown (if executed)
    reverse-engineering/              # Brownfield only
      architecture.md                 # Existing architecture analysis
      component-inventory.md          # Component catalog
      api-documentation.md            # API surface documentation
      dependencies.md                 # Dependency graph
      technology-stack.md             # Tech stack inventory
    feasibility/                      # Product features only
      feasibility-assessment.md       # Competitive analysis and scoring
    value-case/                       # When ROI justification needed
      value-case.md                   # Cost/benefit analysis
    requirements/
      requirements.md                 # Generated from Q&A (key artifact)
      requirement-verification-questions.md
    user-stories/                     # When user-facing features
      stories.md                      # User stories with acceptance criteria
      personas.md                     # User personas
    application-design/               # When new components needed
      components.md                   # Component catalog
      component-methods.md            # Method signatures
      services.md                     # Service layer design
      component-dependency.md         # Dependency diagrams
    reviews/                          # Critical lens findings
      CLR-inception-{stage}-{ts}.md   # Review artifacts
  construction/
    plans/
      {unit}-functional-design-plan.md
      {unit}-nfr-requirements-plan.md
      {unit}-code-generation-plan.md  # File checklist with completion status
    {unit-name}/                      # One directory per unit of work
      functional-design/
        business-logic-model.md
        business-rules.md
        domain-entities.md
      nfr-requirements/
        nfr-requirements.md
        tech-stack-decisions.md
      nfr-design/
        nfr-design-patterns.md
        logical-components.md
      infrastructure-design/
        infrastructure-design.md
        deployment-architecture.md
      code/
        [generated source code, tests, docs]
      reviews/
        CLR-construction-{stage}-{ts}.md
    build-and-test/
      build-instructions.md
      unit-test-instructions.md
      integration-test-instructions.md
      build-and-test-summary.md
  operations/                         # Placeholder for future
    [deployment artifacts]
  aidlc-state.md                      # Workflow state tracking
  audit.md                            # Complete audit trail

State file reference

The file aidlc-state.md tracks workflow progress and enables session resumption.

Key fields:

When you resume an interrupted session, run /ai-dlc:status to see the current state. The workflow picks up at the last pending stage.

Audit trail reference

The file audit.md provides a complete, append-only log of every interaction.

Entry format:

Each entry includes:

• Timestamp -- ISO 8601 format
• Phase and stage -- where in the lifecycle this occurred
• Actor -- user or agent name
• Action type -- input, response, approval, stage-transition, or finding
• Content -- the raw content (user input is never summarized)

Example entry:

## Stage Transition

**Timestamp**: 2026-04-01T14:30:00Z
**Phase**: inception
**Stage**: requirements-analysis -> workflow-planning
**Actor**: system
**Action**: stage-transition
**Details**: Requirements analysis completed and approved.
Proceeding to workflow planning.

---

The audit trail serves as the compliance record for the entire workflow. It is append-only -- entries are never modified or deleted.

Depth levels

The workflow planner recommends a depth level based on its complexity assessment. You can override the recommendation at the approval gate by saying something like "Use minimal depth for faster execution" or "Use comprehensive depth -- this is security-critical."