AI-DLC (AI-Driven Development Life Cycle) Workflows

When running an AI-DLC workflow, all documentation artifacts are generated in the aidlc-docs/ directory at your workspace root. The contents of this directory depend on your project type (greenfield vs. brownfield), complexity, and which workflow stages are executed.

Key Directories:

• inception/: Contains plans, requirements, and design documents (the "WHAT" and "WHY").
• construction/: Contains per-unit design plans, unit-specific implementation details, and build/test instructions (the "HOW").
• operations/: Placeholder for future expansion.

Important Notes:

• {unit-name} in file paths is a placeholder for your actual unit name (e.g., api-service).
• Application code is NOT stored in aidlc-docs/; it is placed in your workspace root. Only markdown documentation resides in this directory.
• Plans in inception/plans/ and construction/plans/ use [Answer]: tags for user input and [ ]/[x] checkboxes to track progress.

The AI-DLC (AI-Driven Development Life Cycle) workflow is structured into two primary phases: Inception and Construction.

1. Inception Phase

This phase focuses on discovery, planning, and design:

• Workspace Detection: Scanning the target directory (e.g., workspace/) to determine project state.
• Requirements Analysis: Generating clarifying questions and producing requirements.md.
• User Stories: Defining epics, personas, and user stories.
• Workflow Planning: Creating an execution plan with specific stages to be executed.
• Application Design: Defining services, components, and dependencies (producing files like components.md, services.md, component-methods.md, and component-dependency.md).
• Units Generation: Decomposing the application into buildable units (e.g., specific services) and determining build order.

2. Construction Phase

This phase focuses on implementation and verification:

• Functional Design: Defining domain entities and business rules.
• NFR (Non-Functional Requirements) Requirements: Defining technical constraints like authentication (e.g., JWT+bcrypt), logging, and storage.
• Code Generation: Executing a step-by-step plan to generate application code.
• Build and Test: Verifying the generated code through builds and automated tests, resulting in a build-and-test-summary.md and coverage reports.

The BookShelf Community Library is a cloud-deployed platform consisting of two independently deployable microservices: the Catalog Service and the Lending Service. The system manages community library operations including book inventory, member management, checkouts, holds, and fee tracking using a Role-Based Access Control (RBAC) model.

Core Services

• Catalog Service: Manages book CRUD operations, full-text search, and real-time availability tracking (total_copies and available_copies).
• Lending Service: Manages member registration, authentication (JWT), checkouts, returns, renewals, holds, and fee management.

User Roles

• Admin: Full access to all endpoints in both services.
• Librarian: Catalog management (CRUD, search), lending operations (returns, holds), and viewing reports.
• Member: Self-service access (own checkouts, holds, fees, profile, and catalog search).
• Public: Access to registration, login, and health checks only.

The AI-DLC Evaluation Framework is organized as a monorepo using a uv workspace. The architecture separates the execution engine from the evaluation logic.

Core Components

• aidlc-runner/: The execution framework. It is a standalone engine that runs the AIDLC workflow (using a two-agent system) and produces output in runs/ folders.
• packages/: A collection of specialized evaluation modules:
  • qualitative/: Handles semantic evaluation (scoring, comparison, and document mapping).
  • quantitative/: Handles code evaluation (linting, security, and code organization).
  • nonfunctional/: Handles NFR (Non-Functional Requirement) evaluation (token tracking, timing, and consistency).
  • reporting/: Aggregates results from all evaluation packages to generate comprehensive reports.
  • shared/: Common utilities used across all packages.
• test_cases/: Contains 'Golden test cases' which serve as versioned, reproducible inputs for the AIDLC workflow.
• runs/: The destination for evaluation outputs. Each run is stored in a {timestamp}-{uuid}/ directory containing metadata, metrics, test results, and the generated workspace/documentation.