Your first AI-DLC project

This tutorial walks you through a complete AI-DLC lifecycle from inception to construction. By the end, you will understand how the interactive requirements gathering works, how the adaptive workflow selects stages, and what artifacts the process produces.

Prerequisites

Before starting, make sure you have:

• Claude Code CLI installed and authenticated (version 2.0 or later for Agent SDK support)
• AI-DLC plugin installed (we will cover this in Step 1)
• AI-DLC rules installed at ~/.claude/aidlc-rules/aws-aidlc-rules/
• A git repository to work in (AI-DLC uses git context for workspace detection)

Verify your Claude Code version:

claude --version

What you will build

We will walk through creating documentation infrastructure for a hypothetical Ansible role called ohemr-ansible-role-widget. This is a realistic scenario for this team: you need to add Diataxis-structured docs, molecule test configuration, and a README for an existing role that currently has no documentation.

This is a brownfield, standard-depth project -- complex enough to see most stages in action, but not so complex that it requires comprehensive depth.

Step 1: Install the AI-DLC plugin

If you have not already installed the AI-DLC plugin, install it from the otc-awesome-llm marketplace:

claude plugin install ai-dlc@otc-awesome-llm

Verify the installation by checking that AI-DLC commands appear:

claude /help | grep ai-dlc

You should see entries for /ai-dlc:inception, /ai-dlc:construction, /ai-dlc:status, and /ai-dlc:config.

Step 2: Start inception

Navigate to your repository and launch the inception phase:

cd ~/scm/optum-tech-compute/ohemr-ansible-role-widget

Then in your Claude Code session, run:

/ai-dlc:inception

AI-DLC begins with workspace detection. It scans the repository to understand the existing codebase:

[Workspace Detection]
Agent: "Existing code detected (Ansible role). Running workspace analysis..."
Agent: "Workspace analysis complete:"
  - Ansible role structure (tasks/, defaults/, handlers/, meta/)
  - YAML-based configuration
  - No existing docs/ directory
  - No mkdocs.yml found
  - molecule/ directory present with default scenario
Agent: "Workspace detection complete. Proceeding to requirements analysis."

Because this is a brownfield project with existing code, AI-DLC notes the existing structure and may offer to run reverse engineering. For a documentation-focused project, you might see this skipped automatically.

Step 3: Answer requirements questions

This is where the key innovation happens. Instead of asking you to fill out a markdown template, AI-DLC presents an interactive questionnaire using the AskUserQuestion tool.

The agent first analyzes your request to determine the appropriate depth level. For adding documentation to an Ansible role, it typically selects standard depth (12--15 questions).

Here is an example of what the Q&A interaction looks like:

Requirements Analysis - Question 1/12

Project goal

What is the primary goal of this project?

A) New feature
   Adding new capabilities to the codebase

B) Documentation
   Creating or improving documentation

C) Bug fix
   Fixing an existing defect

D) Refactoring
   Restructuring code without changing behavior

[Other - custom response]

You select B) Documentation.

The agent adapts its follow-up questions based on your answer. Since you selected documentation, it skips questions about API design and database schemas and instead asks about documentation structure, target audience, and content scope:

Requirements Analysis - Question 2/12

Documentation scope

What documentation deliverables are needed?

A) Full Diataxis structure (tutorials, how-to, reference, explanation)
   Complete documentation set following the Diataxis framework

B) README and basic usage
   Minimal documentation for getting started

C) API/module reference only
   Auto-generated reference documentation

D) Runbook/operational guides only
   Operational how-to guides for day-to-day use

[Other - custom response]

You select A) Full Diataxis structure.

The questionnaire continues through topics like target audience, existing content to preserve, integration with the megadoc site, testing documentation needs, and acceptance criteria. Each question builds on previous answers through branching logic.

Step 4: Review the workflow plan

After requirements gathering completes, AI-DLC generates a requirements document and asks for your approval:

Agent: "Requirements complete. Generated:"
  - aidlc-docs/inception/requirements/requirements.md

Review the document and respond:
  A) Approve - proceed to workflow planning
  B) Request changes - re-run requirements with feedback

After you approve, the workflow planner analyzes your requirements and determines which stages to execute:

[Workflow Planning]
Agent: "Workflow analysis complete. Recommended plan:"

Inception:
  Workspace Detection .......... COMPLETED
  Reverse Engineering .......... SKIP (documentation project, no architecture analysis needed)
  Requirements Analysis ........ COMPLETED
  User Stories ................. SKIP (internal tooling, no user personas)
  Workflow Planning ............. COMPLETED
  Application Design ........... SKIP (no new components)
  Units Generation ............. SKIP (single deliverable)

Construction:
  Functional Design ............ SKIP (no business logic)
  NFR Requirements ............. SKIP (documentation has no NFR concerns)
  NFR Design ................... SKIP (no NFR patterns needed)
  Infrastructure Design ........ SKIP (no infrastructure changes)
  Code Generation .............. EXECUTE (generate documentation files)
  Build and Test ............... EXECUTE (validate mkdocs build)

Depth: Standard
Estimated complexity: Low-Medium

You have full control to override these recommendations:
  - Request additional stages
  - Skip recommended stages
  - Adjust depth levels

Approve this plan, or request adjustments?

Notice how the adaptive workflow recognized that a documentation project does not need functional design, NFR analysis, or infrastructure design. It skips those stages automatically while keeping code generation (which will produce the actual documentation files) and build-and-test (which will validate the mkdocs build).

You can override any recommendation. For example, you might say "Include User Stories -- I want to define the documentation consumer personas." The planner will adjust the plan accordingly.

Step 5: Construction phase

Once you approve the workflow plan, inception is complete. Start the construction phase:

/ai-dlc:construction

The construction phase executes the stages marked EXECUTE in your approved plan. For this project, that means code generation and build-and-test.

Code generation follows a two-phase approach:

Phase 1 -- Planning: The agent creates a detailed plan listing every file it will generate, with checkboxes:

[Code Generation - Planning]
Agent: "Code generation plan for documentation unit:"

Files to create:
  - [ ] mkdocs.yml (minimal stub configuration)
  - [ ] docs/index.md (landing page with quick links)
  - [ ] docs/tutorials/getting-started.md (installation and first use)
  - [ ] docs/how-to/configuration.md (common configuration tasks)
  - [ ] docs/how-to/troubleshooting.md (common issues and solutions)
  - [ ] docs/reference/variables.md (all role variables with defaults)
  - [ ] docs/reference/tags.md (Ansible tags reference)
  - [ ] docs/explanation/architecture.md (role design decisions)
  - [ ] .markdownlint.yaml (linting configuration)

Approve this plan to begin file generation?

Phase 2 -- Execution: After you approve the plan, files are generated one by one. The plan checkboxes update as each file completes:

[Code Generation - Execution]
  [x] mkdocs.yml
  [x] docs/index.md
  [x] docs/tutorials/getting-started.md
  [x] docs/how-to/configuration.md
  ...generating...

Step 6: Review generated artifacts

After construction completes, examine the aidlc-docs/ directory to see all the artifacts the process produced:

aidlc-docs/
  inception/
    plans/
      workspace-detection.md        # What AI-DLC found in your repo
      workflow-planning.md          # The approved execution plan
    requirements/
      requirements.md               # Generated from your Q&A answers
  construction/
    plans/
      docs-unit-code-generation-plan.md  # The file generation checklist
    docs-unit/
      code/                         # The actual generated documentation files
        mkdocs.yml
        docs/
          index.md
          tutorials/
            getting-started.md
          how-to/
            configuration.md
            troubleshooting.md
          reference/
            variables.md
            tags.md
          explanation/
            architecture.md
    build-and-test/
      build-instructions.md         # How to build and validate
  aidlc-state.md                    # Current workflow state
  audit.md                          # Complete decision log

The generated documentation files live in construction/docs-unit/code/. You would copy these to the appropriate locations in your actual repository.

Step 7: Check status

At any point during or after the workflow, check progress with:

/ai-dlc:status

This shows completed stages, pending stages, approval status, generated artifacts, and the next recommended action:

AI-DLC Workflow Status

Current Phase: Construction (Complete)

--- Inception Phase ---
  Workspace Detection       [COMPLETED]
  Requirements Analysis     [COMPLETED] -> Approved
  Workflow Planning         [COMPLETED] -> Approved

--- Construction Phase ---
  Code Generation           [COMPLETED] -> Approved
  Build and Test            [COMPLETED] -> Approved

--- Files Generated ---
  aidlc-docs/inception/requirements/requirements.md
  aidlc-docs/construction/docs-unit/code/mkdocs.yml
  aidlc-docs/construction/docs-unit/code/docs/index.md
  ... (8 more files)
  aidlc-docs/audit.md (23 entries)

Workflow complete! Review artifacts and deploy.

Understanding the artifacts

Each artifact serves a specific purpose:

Tips for effective use

Answer requirements questions specifically. "Performance should be good" is not actionable. "Page load under 2 seconds" gives the AI concrete targets to design against.

Use the custom response option. If none of the multiple-choice answers fit your situation, type a custom answer. The AI will incorporate it into the requirements document.

Approve incrementally. Review each stage output before approving. It is much cheaper to catch issues during requirements than during code generation.

Match depth to complexity. Use minimal depth for simple tasks (bug fixes, config changes). Use standard for normal features. Reserve comprehensive for high-risk or multi-component work. Over-engineering a simple task wastes time; under-engineering a complex one creates risk.

Check /ai-dlc:status often. It tells you exactly where you are and what comes next, which is especially useful when resuming an interrupted session.

Next steps

Now that you have completed your first AI-DLC project, explore these resources:

• AI-DLC commands and agents -- complete reference for all commands, agents, and artifact structures
• AI-DLC workflow patterns -- practical patterns for common scenarios like bug fixes, new features, and documentation-only workflows
• AI-DLC methodology -- deeper understanding of the post-Agile philosophy and adaptive workflow principle