AI-DLC is a three-phase adaptive workflow:

┌─────────────────────────────────────────────────────────────┐
│                  AI-DLC Workflow                             │
├─────────────────────────────────────────────────────────────┤
│  🔵 INCEPTION      Planning & Architecture (WHAT & WHY)     │
│    ├─ Workspace Detection     ▸ ALWAYS                      │
│    ├─ Reverse Engineering     ▸ if brownfield               │
│    ├─ Requirements Analysis   ▸ ALWAYS (adaptive depth)     │
│    ├─ User Stories            ▸ if needed                   │
│    ├─ Workflow Planning       ▸ ALWAYS                      │
│    ├─ Application Design      ▸ if complex                  │
│    └─ Units Generation        ▸ if multi-unit               │
│                                                             │
│  🟢 CONSTRUCTION    Design, Implementation & Test (HOW)     │
│    ├─ Functional Design       ▸ per-unit, if needed         │
│    ├─ NFR Requirements        ▸ per-unit, if needed         │
│    ├─ NFR Design              ▸ per-unit, if needed         │
│    ├─ Infrastructure Design   ▸ per-unit, if needed         │
│    ├─ Code Generation         ▸ ALWAYS (2 parts)            │
│    └─ Build & Test            ▸ ALWAYS                      │
│                                                             │
│  🟡 OPERATIONS     Deployment & Monitoring (future)         │
│    └─ Operations              ▸ PLACEHOLDER                 │
└─────────────────────────────────────────────────────────────┘

Stage Types

How Extensions Work

1. Startup scan — At workflow start, scan the extensions/ directory recursively
2. Load opt-in prompts — Only load *.opt-in.md files (lightweight). Full rule files are deferred.
3. Present to user — During Requirements Analysis, present opt-in prompts for each extension
4. Deferred loading — When user opts IN, load the corresponding full rule file at that point
5. Enforcement — Loaded extensions become hard constraints. Non-compliance is a blocking finding.
6. N/A marking — Rules not applicable to the current stage are marked N/A in compliance summary

extensions/
├── security/
│   ├── baseline/
│   │   ├── security-baseline.opt-in.md    ← 1KB prompt
│   │   └── security-baseline.md           ← 10KB rules (deferred)
├── testing/
│   └── property-based/
│       ├── property-based-testing.opt-in.md
│       └── property-based-testing.md
└── resiliency/
    └── baseline/
        ├── resiliency-baseline.opt-in.md
        └── resiliency-baseline.md

Purpose: Initial analysis of workspace state and project type.

Determines:

• Is this greenfield (empty dir) or brownfield (existing code)?
• Project type, language, framework from existing files
• Build system, dependency management, testing framework
• Any existing documentation or configuration

Output: Worksheet state recorded in aidlc-state.md, workspace type determined

Purpose: Analyze existing codebase to understand architecture before making changes.

Produces these artifacts in aidlc-docs/inception/reverse-engineering/:

• architecture.md — System architecture overview, layers, patterns
• component-inventory.md — All components, their responsibilities, and locations
• technology-stack.md — Languages, frameworks, libraries, versions
• code-structure.md — Directory layout, naming conventions, module organization
• api-documentation.md — API endpoints, contracts, data flow (if applicable)
• dependencies.md — Internal and external dependencies with versions

Always loads common rules first: process-overview.md, session-continuity.md, content-validation.md, question-format-guide.md

Purpose: Understand user intent and gather requirements at appropriate depth.

Assumes the role of a product owner. Steps:

1. Load Reverse Engineering Context — If brownfield, load architecture artifacts
2. Analyze User Request — Clarity (clear/vague/incomplete), Type (new feature, bug fix, refactor, etc.), Scope (single file to cross-system), Complexity (trivial to complex)
3. Determine Depth — Minimal / Standard / Comprehensive based on analysis
4. Assess Current Requirements — Document what the user has already provided
5. Completeness Analysis — Functional, data, UI, integration, NFR, security, compliance
6. Generate Verification Questions — Embedded in requirement-verification-questions.md

Output: requirements.md, requirement-verification-questions.md

Purpose: Create user stories and personas when requirements need human-centered framing.

Two sub-stages:

• Story Planning — Create generation plan for stories and personas
• Story Generation — Generate stories.md and personas.md with acceptance criteria

Output: stories.md (stories with acceptance criteria), personas.md

Purpose: Determine which phases to execute and create comprehensive execution plan.

Critical decision point — analyzes all prior context to decide:

• Which stages execute (always vs conditional)
• Execution order (not necessarily sequential)
• Unit breakdown (how to split the work)
• Parallelization opportunities

For brownfield projects, performs Transformation Scope Detection: architectural vs single-component change, infrastructure impact, related component identification.

Output: execution-plan.md with stage-by-stage plan, unit definitions, scope analysis

Purpose: High-level component identification and service layer design.

Focuses on:

• Identifying main functional components and their responsibilities
• Defining component interfaces (not detailed business logic)
• Service layer for orchestration
• Component dependencies and communication patterns

Outputs: components.md, component-methods.md, services.md, component-dependency.md

Purpose: Break the application into independent units of work for parallel or sequential execution.

Outputs include:

• unit-of-work.md — Each unit's definition, scope, and boundaries
• unit-of-work-dependency.md — Dependency graph showing which units depend on which
• unit-of-work-story-map.md — Stories mapped to each unit

Purpose: Detailed business logic design per unit, technology-agnostic.

Builds on Application Design with:

• Detailed business logic and algorithms
• Domain models with entities and relationships
• Business rules, validation logic, and constraints
• Technology-agnostic design (no infrastructure concerns)

Output: construction/{unit}/functional-design/functional-design.md

Purpose: Analyze and document non-functional requirements for the unit.

Covers: Performance, Scalability, Security, Availability, Reliability, Maintainability, Operability, Compliance, Accessibility.

Output: construction/{unit}/nfr-requirements/nfr-requirements.md

Purpose: Design solutions for each NFR requirement.

For each NFR, creates concrete implementation plan: Caching strategy, rate limiting, retry logic, circuit breakers, encryption approach, etc.

Output: construction/{unit}/nfr-design/nfr-design.md

Purpose: Design infrastructure requirements for the unit (compute, storage, networking).

Output: construction/{unit}/infrastructure-design/infrastructure-design.md

Part 1: Planning

• Analyze unit context (design artifacts, story map, dependencies)
• Create detailed code generation plan with explicit steps
• Determine code location (NEVER in aidlc-docs/)
• Brownfield: review reverse engineering code-structure.md for existing files to modify
• Each step gets a checkbox: Project Structure → Business Logic → API Layer → Repository Layer

Part 2: Generation

• Execute approved plan step by step
• Generate code, unit tests, and integration tests per layer
• Validate each generated file against requirements
• Update aidlc-state.md with generation status

Critical: For brownfield projects, "generate" means modify existing files when appropriate, not create duplicates.

Purpose: Build all units and execute comprehensive testing strategy.

Testing levels:

• Unit tests — Already generated per unit during code generation
• Integration tests — Test interactions between units/services
• End-to-end tests — Complete user workflows
• Contract tests — API contract validation between services

Outputs: build-instructions.md, build-and-test-report.md, test-summary.md

Status: PLACEHOLDER — Not yet implemented.

Future scope includes:

• Deployment planning and execution
• Monitoring and observability setup
• Incident response procedures
• Maintenance and support workflows
• Production readiness checklists

The workflow currently ends after Build & Test in the CONSTRUCTION phase.

Category: Security · Type: Opt-in extension

Adds security guardrails to every stage of AI-DLC. When opted in, applies rules for:

• OWASP Top 10 — Input validation, authentication, session management, access control
• Secure coding — Code injection prevention, secret management, encryption standards
• Dependency scanning — Known vulnerability checks, supply chain security
• Compliance tagging — Each artifact must note relevant compliance frameworks (SOC2, HIPAA, GDPR)
• Security review gate — Blocking finding if any security rule is non-compliant per stage

Category: Testing · Type: Opt-in extension

Adds property-based testing requirements to the CONSTRUCTION phase:

• Define invariant properties for each function/module
• Generate property-based tests alongside unit tests
• Include edge case generation strategies
• Verify properties across random inputs

Category: Resiliency · Type: Opt-in extension

Adds resilience engineering to design and construction:

• Circuit breakers, retry policies, timeout configurations
• Bulkhead patterns and rate limiting
• Graceful degradation strategies
• Chaos engineering readiness
• Disaster recovery planning

AI-DLC supports resuming interrupted sessions without losing context. The aidlc-state.md file tracks:

• Current phase and stage
• Last completed step
• Next step to work on
• Extension configuration (enabled/disabled)

On resumption, the model:

1. Reads aidlc-state.md first
2. Parses current status to present a "Welcome back" prompt
3. Loads all previous stage artifacts — architecture, requirements, stories, design docs, code
4. For in-progress units: loads that unit's design artifacts plus any unit it depends on
5. Continues from the exact next step

AI-DLC integrates with Hermes Agent at the profile level. The sandbox at /opt/data/aidlc-sandbox/ has AI-DLC rules pre-configured in CLAUDE.md and .aidlc-rule-details/.

To use AI-DLC with Hermes:

# Start a new session in the sandbox
cd /opt/data/aidlc-sandbox
hermes

# Or specify skills to load AI-DLC rules
hermes --skills aidlc

# The CLAUDE.md in the sandbox auto-loads the adaptive workflow

Profile setup for trading projects:

# Create a dedicated AI-DLC profile
hermes profile create aidlc-dev
# Copy the .aidlc-rule-details/ into that profile's context
cp -r /opt/data/aidlc-sandbox/.aidlc-rule-details /opt/data/<project>/

The AI-DLC sandbox at /opt/data/aidlc-sandbox/ is a safe environment for learning the workflow. Nothing in the sandbox affects trading bots.

# Enter sandbox
cd /opt/data/aidlc-sandbox

# Start Hermes with AI-DLC context
hermes -q "Create a Python CLI tool that tracks daily expenses"

# Or for an existing project modification:
hermes -q "Add export-to-CSV feature to the tracker"

The workflow will automatically guide you through:

1. Workspace Detection → detects it's greenfield
2. Requirements Analysis → asks clarifying questions
3. Workflow Planning → determines appropriate stages
4. Code Generation (Part 1: Plan) → creates implementation plan
5. Code Generation (Part 2: Execute) → generates code + tests
6. Build & Test → builds and runs tests