Skip to content

SKILL.md

Latest commit

 

History

History
462 lines (351 loc) · 22.7 KB

SKILL.md

File metadata and controls

462 lines (351 loc) · 22.7 KB

AI-DLC (AI-Driven Development Life Cycle)

Description

An adaptive software development workflow that intelligently tailors itself to project needs. It guides through a structured three-phase lifecycle: Inception (planning), Construction (design & implementation), and Operations (deployment - future).

When to Use

  • When the user requests software development work (new features, bug fixes, refactoring, migrations, enhancements, new projects)
  • When starting any coding task that benefits from structured planning and requirements gathering
  • When the user says "start aidlc", "use aidlc", or requests a structured development workflow

Session Resumption

If aidlc-docs/aidlc-state.md exists, follow common/session-continuity.md to resume from where the user left off.

Instructions

Adaptive Workflow Principle

The workflow adapts to the work, not the other way around.

The AI model intelligently assesses what stages are needed based on:

  1. User's stated intent and clarity
  2. Existing codebase state (if any)
  3. Complexity and scope of change
  4. Risk and impact assessment

MANDATORY: Startup Rules

CRITICAL: At workflow start, you MUST:

  1. Display welcome message from common/welcome-message.md (ONCE per workflow, skip on subsequent interactions)
  2. Load common rules and reference throughout execution:
    • common/process-overview.md - workflow overview
    • common/session-continuity.md - session resumption guidance
    • common/content-validation.md - content validation requirements
    • common/question-format-guide.md - question formatting rules
  3. Validate content before creating ANY file per common/content-validation.md (Mermaid syntax, ASCII diagrams via common/ascii-diagram-standards.md, special character escaping, text alternatives)
  4. Format questions per common/question-format-guide.md (multiple choice A/B/C/D/E, [Answer]: tags, never ask in chat)

MANDATORY: Extensions Loading (Context-Optimized)

CRITICAL: At workflow start, scan the extensions/ directory recursively but load ONLY lightweight opt-in files — NOT full rule files. Full rule files are loaded on-demand after the user opts in.

Loading process:

  1. List all subdirectories under extensions/ (e.g., extensions/security/, extensions/compliance/)
  2. In each subdirectory, load ONLY *.opt-in.md files — these contain the extension's opt-in prompt. The corresponding rules file is derived by convention: strip the .opt-in.md suffix and append .md (e.g., security-baseline.opt-in.md → security-baseline.md)
  3. Do NOT load full rule files (e.g., security-baseline.md) at this stage

Deferred Rule Loading:

  • During Requirements Analysis, opt-in prompts from the loaded *.opt-in.md files are presented to the user
  • When the user opts IN for an extension, load the corresponding rules file (derived by naming convention) at that point
  • When the user opts OUT, the full rules file is never loaded — saving context
  • Extensions without a matching *.opt-in.md file are always enforced — load their rule files immediately at workflow start

Enforcement (applies only to loaded/enabled extensions):

  • Extension rules are hard constraints, not optional guidance
  • At each stage, the model intelligently evaluates which extension rules are applicable based on the stage's purpose, the artifacts being produced, and the context of the work — enforce only those rules that are relevant
  • Rules that are not applicable to the current stage should be marked as N/A in the compliance summary (this is not a blocking finding)
  • Non-compliance with any applicable enabled extension rule is a blocking finding — do NOT present stage completion until resolved
  • When presenting stage completion, include a summary of extension rule compliance (compliant/non-compliant/N/A per rule, with brief rationale for N/A determinations)

Conditional Enforcement: Extensions may be conditionally enabled/disabled. See inception/requirements-analysis.md for the opt-in mechanism. Before enforcing any extension at ANY stage, check its Enabled status in aidlc-docs/aidlc-state.md under ## Extension Configuration. Skip disabled extensions and log the skip in audit.md. Default to enforced if no configuration exists.

Supporting Rules

  • common/depth-levels.md - How detail adapts to complexity
  • common/terminology.md - Glossary of AI-DLC terms
  • common/overconfidence-prevention.md - Question generation philosophy
  • common/workflow-changes.md - Handling mid-workflow changes
  • common/error-handling.md - Recovery procedures

INCEPTION PHASE

Purpose: Planning, requirements gathering, and architectural decisions

Focus: Determine WHAT to build and WHY

Workspace Detection (ALWAYS EXECUTE)

Detail: inception/workspace-detection.md

  1. MANDATORY: Log initial user request in audit.md with complete raw input
  2. Load all steps from inception/workspace-detection.md
  3. Execute workspace detection:
    • Check for existing aidlc-state.md (resume if found)
    • Scan workspace for existing code
    • Determine if brownfield or greenfield
    • Check for existing reverse engineering artifacts
  4. Determine next phase: Reverse Engineering (if brownfield and no artifacts) OR Requirements Analysis
  5. MANDATORY: Log findings in audit.md
  6. Present completion message to user (see workspace-detection.md for message formats)
  7. Automatically proceed to next phase

Reverse Engineering (CONDITIONAL - Brownfield Only)

Detail: inception/reverse-engineering.md

Execute IF: Existing codebase detected, no previous reverse engineering artifacts found

Skip IF: Greenfield project, or previous reverse engineering artifacts exist

Execution:

  1. MANDATORY: Log start of reverse engineering in audit.md
  2. Load all steps from inception/reverse-engineering.md
  3. Execute reverse engineering:
    • Analyze all packages and components
    • Generate a business overview of the whole system covering the business transactions
    • Generate architecture documentation
    • Generate code structure documentation
    • Generate API documentation
    • Generate component inventory
    • Generate Interaction Diagrams depicting how business transactions are implemented across components
    • Generate technology stack documentation
    • Generate dependencies documentation
  4. Wait for Explicit Approval: Present detailed completion message (see reverse-engineering.md for message format) - DO NOT PROCEED until user confirms
  5. MANDATORY: Log user's response in audit.md with complete raw input

Requirements Analysis (ALWAYS EXECUTE - Adaptive Depth)

Detail: inception/requirements-analysis.md

Always executes but depth varies based on request clarity and complexity:

  • Minimal: Simple, clear request - just document intent analysis
  • Standard: Normal complexity - gather functional and non-functional requirements
  • Comprehensive: Complex, high-risk - detailed requirements with traceability

Execution:

  1. MANDATORY: Log any user input during this phase in audit.md
  2. Load all steps from inception/requirements-analysis.md
  3. Execute requirements analysis:
    • Load reverse engineering artifacts (if brownfield)
    • Analyze user request (intent analysis)
    • Determine requirements depth needed
    • Assess current requirements
    • Ask clarifying questions (if needed)
    • Generate requirements document
  4. Execute at appropriate depth (minimal/standard/comprehensive)
  5. Wait for Explicit Approval: Follow approval format from requirements-analysis.md detailed steps - DO NOT PROCEED until user confirms
  6. MANDATORY: Log user's response in audit.md with complete raw input

User Stories (CONDITIONAL)

Detail: inception/user-stories.md

INTELLIGENT ASSESSMENT: Use multi-factor analysis to determine if user stories add value:

ALWAYS Execute IF (High Priority Indicators):

  • New user-facing features or functionality
  • Changes affecting user workflows or interactions
  • Multiple user types or personas involved
  • Complex business requirements with acceptance criteria needs
  • Cross-functional team collaboration required
  • Customer-facing API or service changes
  • New product capabilities or enhancements

LIKELY Execute IF (Medium Priority - Assess Complexity):

  • Modifications to existing user-facing features
  • Backend changes that indirectly affect user experience
  • Integration work that impacts user workflows
  • Performance improvements with user-visible benefits
  • Security enhancements affecting user interactions
  • Data model changes affecting user data or reports

COMPLEXITY-BASED ASSESSMENT: For medium priority cases, execute user stories if:

  • Request involves multiple components or services
  • Changes span multiple user touchpoints
  • Business logic is complex or has multiple scenarios
  • Requirements have ambiguity that stories could clarify
  • Implementation affects multiple user journeys
  • Change has significant business impact or risk

SKIP ONLY IF (Low Priority - Simple Cases):

  • Pure internal refactoring with zero user impact
  • Simple bug fixes with clear, isolated scope
  • Infrastructure changes with no user-facing effects
  • Technical debt cleanup with no functional changes
  • Developer tooling or build process improvements
  • Documentation-only updates

ASSESSMENT CRITERIA: When in doubt, favor inclusion of user stories.

User Stories has two parts within one stage:

  1. Part 1 - Planning: Create story plan with questions, collect answers, analyze for ambiguities, get approval
  2. Part 2 - Generation: Execute approved plan to generate stories and personas

Execution:

  1. MANDATORY: Log any user input during this phase in audit.md
  2. Load all steps from inception/user-stories.md
  3. MANDATORY: Perform intelligent assessment (Step 1 in user-stories.md) to validate user stories are needed
  4. Load reverse engineering artifacts (if brownfield)
  5. If Requirements exist, reference them when creating stories
  6. Execute at appropriate depth (minimal/standard/comprehensive)
  7. PART 1 - Planning: Create story plan with questions, wait for user answers, analyze for ambiguities, get approval
  8. PART 2 - Generation: Execute approved plan to generate stories and personas
  9. Wait for Explicit Approval: Follow approval format from user-stories.md detailed steps - DO NOT PROCEED until user confirms
  10. MANDATORY: Log user's response in audit.md with complete raw input

Workflow Planning (ALWAYS EXECUTE)

Detail: inception/workflow-planning.md

  1. MANDATORY: Log any user input during this phase in audit.md
  2. Load all steps from inception/workflow-planning.md
  3. MANDATORY: Load content validation rules from common/content-validation.md
  4. Load all prior context:
    • Reverse engineering artifacts (if brownfield)
    • Intent analysis
    • Requirements (if executed)
    • User stories (if executed)
  5. Execute workflow planning:
    • Determine which phases to execute
    • Determine depth level for each phase
    • Create multi-package change sequence (if brownfield)
    • Generate workflow visualization (VALIDATE Mermaid syntax before writing)
  6. MANDATORY: Validate all content before file creation per content-validation.md rules
  7. Wait for Explicit Approval: Present recommendations using language from workflow-planning.md Step 9, emphasizing user control to override recommendations - DO NOT PROCEED until user confirms
  8. MANDATORY: Log user's response in audit.md with complete raw input

Application Design (CONDITIONAL)

Detail: inception/application-design.md

Execute IF: New components or services needed, component methods and business rules need definition, service layer design required, component dependencies need clarification

Skip IF: Changes within existing component boundaries, no new components or methods, pure implementation changes

Execution:

  1. MANDATORY: Log any user input during this phase in audit.md
  2. Load all steps from inception/application-design.md
  3. Load reverse engineering artifacts (if brownfield)
  4. Execute at appropriate depth (minimal/standard/comprehensive)
  5. Wait for Explicit Approval: Present detailed completion message (see application-design.md for message format) - DO NOT PROCEED until user confirms
  6. MANDATORY: Log user's response in audit.md with complete raw input

Units Generation (CONDITIONAL)

Detail: inception/units-generation.md

Execute IF: System needs decomposition into multiple units of work, multiple services or modules required, complex system requiring structured breakdown

Skip IF: Single simple unit, no decomposition needed, straightforward single-component implementation

Execution:

  1. MANDATORY: Log any user input during this phase in audit.md
  2. Load all steps from inception/units-generation.md
  3. Load reverse engineering artifacts (if brownfield)
  4. Execute at appropriate depth (minimal/standard/comprehensive)
  5. Wait for Explicit Approval: Present detailed completion message (see units-generation.md for message format) - DO NOT PROCEED until user confirms
  6. MANDATORY: Log user's response in audit.md with complete raw input

CONSTRUCTION PHASE

Purpose: Detailed design, NFR implementation, and code generation

Focus: Determine HOW to build it

Note: Each unit is completed fully (design + code) before moving to the next unit.

Per-Unit Loop (Executes for Each Unit)

For each unit of work, execute the following stages in sequence:

Functional Design (CONDITIONAL, per-unit)

Detail: construction/functional-design.md

Execute IF: New data models or schemas, complex business logic, business rules need detailed design

Skip IF: Simple logic changes, no new business logic

Execution:

  1. MANDATORY: Log any user input during this stage in audit.md
  2. Load all steps from construction/functional-design.md
  3. Execute functional design for this unit
  4. MANDATORY: Present standardized 2-option completion message as defined in functional-design.md - DO NOT use emergent 3-option behavior
  5. Wait for Explicit Approval: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms
  6. MANDATORY: Log user's response in audit.md with complete raw input

NFR Requirements (CONDITIONAL, per-unit)

Detail: construction/nfr-requirements.md

Execute IF: Performance requirements exist, security considerations needed, scalability concerns present, tech stack selection required

Skip IF: No NFR requirements, tech stack already determined

Execution:

  1. MANDATORY: Log any user input during this stage in audit.md
  2. Load all steps from construction/nfr-requirements.md
  3. Execute NFR assessment for this unit
  4. MANDATORY: Present standardized 2-option completion message as defined in nfr-requirements.md - DO NOT use emergent behavior
  5. Wait for Explicit Approval: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms
  6. MANDATORY: Log user's response in audit.md with complete raw input

NFR Design (CONDITIONAL, per-unit)

Detail: construction/nfr-design.md

Execute IF: NFR Requirements was executed, NFR patterns need to be incorporated

Skip IF: No NFR requirements, NFR Requirements Assessment was skipped

Execution:

  1. MANDATORY: Log any user input during this stage in audit.md
  2. Load all steps from construction/nfr-design.md
  3. Execute NFR design for this unit
  4. MANDATORY: Present standardized 2-option completion message as defined in nfr-design.md - DO NOT use emergent behavior
  5. Wait for Explicit Approval: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms
  6. MANDATORY: Log user's response in audit.md with complete raw input

Infrastructure Design (CONDITIONAL, per-unit)

Detail: construction/infrastructure-design.md

Execute IF: Infrastructure services need mapping, deployment architecture required, cloud resources need specification

Skip IF: No infrastructure changes, infrastructure already defined

Execution:

  1. MANDATORY: Log any user input during this stage in audit.md
  2. Load all steps from construction/infrastructure-design.md
  3. Execute infrastructure design for this unit
  4. MANDATORY: Present standardized 2-option completion message as defined in infrastructure-design.md - DO NOT use emergent behavior
  5. Wait for Explicit Approval: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms
  6. MANDATORY: Log user's response in audit.md with complete raw input

Code Generation (ALWAYS EXECUTE, per-unit)

Detail: construction/code-generation.md

Always executes for each unit

Code Generation has two parts within one stage:

  1. Part 1 - Planning: Create detailed code generation plan with explicit steps
  2. Part 2 - Generation: Execute approved plan to generate code, tests, and artifacts

Execution:

  1. MANDATORY: Log any user input during this stage in audit.md
  2. Load all steps from construction/code-generation.md
  3. PART 1 - Planning: Create code generation plan with checkboxes, get user approval
  4. PART 2 - Generation: Execute approved plan to generate code for this unit
  5. MANDATORY: Present standardized 2-option completion message as defined in code-generation.md - DO NOT use emergent behavior
  6. Wait for Explicit Approval: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms
  7. MANDATORY: Log user's response in audit.md with complete raw input

Build and Test (ALWAYS EXECUTE)

Detail: construction/build-and-test.md

  1. MANDATORY: Log any user input during this phase in audit.md
  2. Load all steps from construction/build-and-test.md
  3. Generate comprehensive build and test instructions:
    • Build instructions for all units
    • Unit test execution instructions
    • Integration test instructions (test interactions between units)
    • Performance test instructions (if applicable)
    • Additional test instructions as needed (contract tests, security tests, e2e tests)
  4. Create instruction files in build-and-test/ subdirectory: build-instructions.md, unit-test-instructions.md, integration-test-instructions.md, performance-test-instructions.md, build-and-test-summary.md
  5. Wait for Explicit Approval: Ask: "Build and test instructions complete. Ready to proceed to Operations stage?" - DO NOT PROCEED until user confirms
  6. MANDATORY: Log user's response in audit.md with complete raw input

OPERATIONS PHASE

Purpose: Placeholder for future deployment and monitoring workflows

Detail: operations/operations.md

Status: This stage is currently a placeholder for future expansion. All build and test activities are handled in the CONSTRUCTION phase.

Key Principles

  • Adaptive Execution: Only execute stages that add value
  • Transparent Planning: Always show execution plan before starting
  • User Control: User can request stage inclusion/exclusion
  • Progress Tracking: Update aidlc-state.md with executed and skipped stages
  • Complete Audit Trail: Log ALL user inputs and AI responses in audit.md with timestamps
    • CRITICAL: Capture user's COMPLETE RAW INPUT exactly as provided
    • CRITICAL: Never summarize or paraphrase user input in audit log
    • CRITICAL: Log every interaction, not just approvals
  • Quality Focus: Complex changes get full treatment, simple changes stay efficient
  • Content Validation: Always validate content before file creation per content-validation.md rules
  • NO EMERGENT BEHAVIOR: Construction phases MUST use standardized 2-option completion messages as defined in their respective rule files. DO NOT create 3-option menus or other emergent navigation patterns.

MANDATORY: Plan-Level Checkbox Enforcement

MANDATORY RULES FOR PLAN EXECUTION

  1. NEVER complete any work without updating plan checkboxes
  2. IMMEDIATELY after completing ANY step described in a plan file, mark that step [x]
  3. This must happen in the SAME interaction where the work is completed
  4. NO EXCEPTIONS: Every plan step completion MUST be tracked with checkbox updates

Two-Level Checkbox Tracking System

  • Plan-Level: Track detailed execution progress within each stage
  • Stage-Level: Track overall workflow progress in aidlc-state.md
  • Update immediately: All progress updates in SAME interaction where work is completed

Prompts Logging Requirements

  • MANDATORY: Log EVERY user input (prompts, questions, responses) with timestamp in audit.md
  • MANDATORY: Capture user's COMPLETE RAW INPUT exactly as provided (never summarize)
  • MANDATORY: Log every approval prompt with timestamp before asking the user
  • MANDATORY: Record every user response with timestamp after receiving it
  • CRITICAL: ALWAYS append changes to EDIT audit.md file, NEVER use tools and commands that completely overwrite its contents
  • Use ISO 8601 format for timestamps (YYYY-MM-DDTHH:MM:SSZ)
  • Include stage context for each entry

Audit Log Format:

## [Stage Name or Interaction Type]
**Timestamp**: [ISO timestamp]
**User Input**: "[Complete raw user input - never summarized]"
**AI Response**: "[AI's response or action taken]"
**Context**: [Stage, action, or decision made]

---

Correct Tool Usage for audit.md

CORRECT: Read the audit.md file, then append/edit to make changes.

WRONG: Read the audit.md file, then completely overwrite it with old contents plus new changes.

Directory Structure

<WORKSPACE-ROOT>/                   # Application code here
├── [project-specific structure]    # Varies by project (see code-generation.md)
│
├── aidlc-docs/                     # Documentation only
│   ├── inception/                  # INCEPTION PHASE
│   │   ├── plans/
│   │   ├── reverse-engineering/    # Brownfield only
│   │   ├── requirements/
│   │   ├── user-stories/
│   │   └── application-design/
│   ├── construction/               # CONSTRUCTION PHASE
│   │   ├── plans/
│   │   ├── {unit-name}/
│   │   │   ├── functional-design/
│   │   │   ├── nfr-requirements/
│   │   │   ├── nfr-design/
│   │   │   ├── infrastructure-design/
│   │   │   └── code/               # Markdown summaries only
│   │   └── build-and-test/
│   ├── operations/                 # OPERATIONS PHASE (placeholder)
│   ├── aidlc-state.md
│   └── audit.md

CRITICAL RULE:

  • Application code: Workspace root (NEVER in aidlc-docs/)
  • Documentation: aidlc-docs/ only
  • Project structure: See code-generation.md for patterns by project type