Imported from aws-samples/sample-aidlc-skill-for-amazon-quick (skill/SKILL.md). Install upstream with npx skills add aws-samples/sample-aidlc-skill-for-amazon-quick --skill skill. Copyright stays with the author.

AI-DLC Workflow Skill for Amazon Quick

Overview

This skill implements the AI-Driven Development Life Cycle (AI-DLC) methodology as an Amazon Quick workflow. It orchestrates structured software development through three phases — Inception, Construction, and Operations — while delegating code execution to ACP coding agents (Kiro, Claude Code, Q Dev CLI).

Architecture: The main agent is a pure orchestrator — it never generates heavy documents itself. Instead:

• Sub-agents (background tasks) handle all document generation (requirements, designs, user stories, plans)
• ACP agents handle code execution (generation, refactoring, testing, building)

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

Document Generation Architecture

Principle: The orchestrator's context is precious. All substantial document generation is delegated to sub-agents via start_task. The orchestrator only:

• Reads rule files and gathers context
• Makes decisions about what to execute
• Spawns document-writing sub-agents with targeted objectives
• Validates output (lightweight checks)
• Presents approvals to the user
• Maintains audit.md and aidlc-state.md (small, immediate writes)

Sub-Agent Delegation Pattern:

start_task(
    objective="Generate [document type] for AI-DLC workflow.
      ## Context
      [project info, phase, depth level]
      ## Input Data
      [relevant context summary — requirements, design specs, etc.]
      ## Rules
      Read formatting and content rules from: [skill_path]/[rule_file]
      Read content validation rules from: [skill_path]/common/content-validation.md
      ## Output
      Write document to: [exact output path]
      Follow the structure defined in the rules file exactly.",
    tools="file_only",
    share_workspace=True,
    fork=False,
    model="smart"
)

Post-Delegation Validation (deterministic): After every start_task, verify the expected artifacts exist and are non-trivial. This is mechanical work with an exact answer — use run_python rather than asking the model to eyeball it:

import os
expected = [
    # absolute paths the sub-agent was told to write
]
missing = [p for p in expected if not os.path.isfile(p)]
empty = [p for p in expected if os.path.isfile(p) and os.path.getsize(p) < 200]
print({"missing": missing, "suspiciously_small": empty})

Treat a non-empty missing list as a stage failure and follow the step's On failure: branch. Treat suspiciously_small as a warning to inspect with file_read before accepting — a file that exists can still be a stub.

What the orchestrator writes directly (small, immediate state updates):

• aidlc-docs/audit.md — append-only log entries (via file_edit)
• aidlc-docs/aidlc-state.md — status/progress updates (via file_edit)
• Initial directory creation (via folder_create)

What sub-agents write (all substantial documents):

• Requirements documents
• User stories
• Architecture/design documents
• Reverse engineering documentation
• Functional/NFR/infrastructure design docs
• Workflow plans and unit decompositions
• Code generation plans
• Build & test instruction documents

Workflow

Step 1: Initialize Workflow

• Mode: agentic
• Input: User's software development request
• Output: Workflow initialized with welcome message displayed, common rules loaded
• Validate: Welcome message shown once; all common rule files read; extensions/**/*.opt-in.md found; project folder resolved; ACP availability determined
• On failure: If the project folder is unresolvable, ask the user for an explicit path — never guess. If a common rule file is missing, name it, continue with the remainder, and log the gap in audit.md. If no ACP agent is reachable, follow the Step 1 precondition decision card.
• Instructions:

  1. Read and display the welcome message from common/welcome-message.md (do this ONCE at workflow start only)

  2. Load common rules for reference throughout the workflow:

     • Read common/process-overview.md for workflow overview
     • Read common/terminology.md for AI-DLC term definitions (phase, stage, unit, extension)
     • Read common/session-continuity.md for session resumption guidance
     • Read common/content-validation.md for content validation requirements
     • Read common/question-format-guide.md for question formatting rules
     • Read common/overconfidence-prevention.md for verification-before-assertion rules

  3. Scan extensions/ directory — load ONLY *.opt-in.md files (NOT full rule files yet)

  4. Identify the project folder (ask user if not obvious from context)

  5. Check if <project_folder>/aidlc-docs/aidlc-state.md exists:

     • If YES: resume workflow from last recorded state (see common/session-continuity.md)
     • If NO: proceed to Step 2 (fresh workflow)

  6. Get current timestamp via get_current_time for audit logging

  7. Verify ACP agent availability (precondition): this skill declares depends-on: [acp_agents] and cannot run Code Generation or Build & Test without a connected coding agent. Confirm one is reachable via send_message_to_acp_agent NOW, before the user invests time in Inception. If none is connected, tell them:

     No coding agent is connected. Inception (requirements, design, planning) will work, but Code Generation and Build & Test cannot run. Connect Kiro, Claude Code, or Q Dev CLI at Settings → Capabilities → Agents.

     Then offer:

     <decision question="No ACP coding agent is connected. How would you like to proceed?">
     <option>I'll connect one now — wait for me</option>
     <option>Continue with Inception only (documentation, no code generation)</option>
     </decision>
     

     Log the choice in audit.md. If the user continues without an agent, record ## ACP Available: No in aidlc-state.md, and when Step 9e is reached produce the code generation plan only — do NOT attempt delegation.

Step 2: Workspace Detection (ALWAYS)

• Mode: agentic
• Input: Project folder path
• Output: Workspace classification (greenfield/brownfield), next phase determination
• Validate: aidlc-docs/ exists; audit.md contains the raw user request; aidlc-state.md written with phase, stage, and project type
• On failure: If folder_create or file_write is denied, tell the user to grant folder access (Settings → My computer) and stop — do not write elsewhere. If the scan finds no source files AND no config, that is greenfield, not an error.
• Instructions:
  1. Read detailed steps from inception/workspace-detection.md
  2. Create <project_folder>/aidlc-docs/ directory structure using folder_create
  3. Create initial audit.md with user's raw request using file_write
  4. Scan the project folder:
     • Use fdfind to detect existing source files (*.py, *.js, *.ts, *.java, *.rs, etc.)
     • Use folder_list to map top-level structure
     • Use ripgrep to find config files (package.json, Cargo.toml, pom.xml, etc.)
  5. Determine: Greenfield (no existing code) or Brownfield (existing codebase)
  6. Check for existing reverse engineering artifacts in aidlc-docs/inception/reverse-engineering/
  7. Create initial aidlc-state.md with file_write:

     # AI-DLC State
     ## Current Phase: INCEPTION
     ## Current Stage: Workspace Detection
     ## Project Type: [Greenfield|Brownfield]
     ## Started: [ISO timestamp]
     ## Extension Configuration
     [to be filled during Requirements Analysis]

  8. Log findings in audit.md using file_edit (append)
  9. Present findings to user and automatically proceed to next phase:
     • If Brownfield with no RE artifacts → Reverse Engineering
     • Otherwise → Requirements Analysis

Step 3: Reverse Engineering (CONDITIONAL — Brownfield Only)

• Mode: agentic
• Input: Brownfield project with no existing RE artifacts
• Output: Complete reverse engineering documentation
• Conditions: Execute ONLY if brownfield detected AND no previous RE artifacts exist. Skip for greenfield.
• Validate: run_python existence check confirms all 8 expected files under aidlc-docs/inception/reverse-engineering/
• On failure: If the ACP agent fails or times out, retry once with narrowed scope (one artifact at a time). If it still fails, keep what succeeded, record the gaps explicitly in each affected document, and ask the user whether to proceed or supply the information manually.
• Instructions:
  1. Read detailed steps from inception/reverse-engineering.md
  2. Log start in audit.md
  3. Delegate to ACP agent for deep codebase analysis:
     • Compose prompt asking the ACP agent to analyze the codebase and provide:
       • Business overview (what the system does)
       • Architecture documentation (layers, patterns, components)
       • Code structure documentation (packages, modules, key files)
       • API documentation (endpoints, contracts)
       • Component inventory
       • Interaction diagrams (how business transactions flow across components)
       • Technology stack documentation
       • Dependencies documentation
     • Send via send_message_to_acp_agent
  4. Delegate document formatting to sub-agent:
     • Spawn start_task with:
       • Objective: "Format reverse engineering output into structured AI-DLC documentation"
       • Pass: ACP agent's raw analysis output, output directory path
       • Include: "Read inception/reverse-engineering.md for document templates and structure"
       • Output path: <project_folder>/aidlc-docs/inception/reverse-engineering/
       • Expected files: business-overview.md, architecture.md, code-structure.md, api-documentation.md, component-inventory.md, interaction-diagrams.md, tech-stack.md, dependencies.md
       • tools: "file_only", share_workspace: true, model: "smart"
     • Wait for sub-agent completion
  5. Validate: confirm all 8 files exist at expected paths
  6. Update aidlc-state.md (orchestrator does this directly)
  7. Present completion to user with decision card:

     <decision question="Reverse Engineering complete. How would you like to proceed?">
     <option>Approve and continue to Requirements Analysis</option>
     <option>Request changes to the reverse engineering output</option>
     </decision>
     

  8. Log user's response in audit.md

Step 4: Requirements Analysis (ALWAYS — Adaptive Depth)

• Mode: agentic
• Input: User request + reverse engineering artifacts (if brownfield)
• Output: Requirements document at appropriate depth
• Validate: requirements.md exists with the sections its depth level requires; extension configuration recorded in aidlc-state.md; all [Answer]: tags filled; contradiction check run
• On failure: If questions are unanswered or contradictory, do NOT proceed — create the clarification file per common/question-format-guide.md. If the sub-agent returned a document missing required sections, re-delegate naming the specific gaps.
• Instructions:
  1. Read detailed steps from inception/requirements-analysis.md
  2. Log phase start in audit.md
  3. If brownfield, read reverse engineering artifacts for context
  4. Analyze user request — determine depth needed:
     • Minimal: Simple, clear request → document intent only
     • Standard: Normal complexity → functional + non-functional requirements
     • Comprehensive: Complex, high-risk → detailed requirements with traceability
  5. Present opt-in prompts for extensions (from loaded *.opt-in.md files):

     <decision question="Would you like to enable these workflow extensions?" multi="true">
     <option>Security Baseline — encryption, logging, input validation, least privilege, secure design (SECURITY-01..15)</option>
     <option>Property-Based Testing — invariants, round-trip, idempotency, stateful properties (PBT-01..10)</option>
     <option>Resiliency Baseline — availability targets, DR strategy, observability, failover (RESILIENCY-01..15)</option>
     <option>Skip all extensions</option>
     </decision>
     

  6. For each opted-in extension, read its full rules file (e.g., extensions/security/baseline/security-baseline.md)
  7. Record extension configuration in aidlc-state.md
  8. Ask clarifying questions if needed (follow common/question-format-guide.md format). Wait for answers, then run the MANDATORY contradiction and ambiguity check in common/question-format-guide.md. Do NOT proceed to sub-step 9 while any clarification question is unanswered.
  9. Delegate document generation to sub-agent:
     • Spawn start_task with:
       • Objective: "Generate requirements document for AI-DLC workflow"
       • Pass: user request, depth level (minimal/standard/comprehensive), brownfield context summary, enabled extensions list
       • Include: "Read inception/requirements-analysis.md for structure and templates. Read common/content-validation.md for validation rules."
       • Output path: <project_folder>/aidlc-docs/inception/requirements/requirements.md
       • tools: "file_only", share_workspace: true, model: "smart"
     • Wait for sub-agent completion
  10. Validate: confirm file exists and contains expected sections for the chosen depth
  11. Present for approval:

      <decision question="Requirements Analysis complete. How would you like to proceed?">
      <option>Approve and continue</option>
      <option>Request changes</option>
      </decision>
      

  12. Log response in audit.md

Step 5: User Stories (CONDITIONAL)

• Mode: agentic
• Input: Approved requirements
• Output: User stories with acceptance criteria
• Conditions: Execute if new user-facing features, multiple personas, complex business requirements, or cross-functional needs. Skip for pure refactoring, simple bug fixes, or infrastructure-only changes.
• Validate: assessment file written; if executing, story-generation-plan.md approved with all checkboxes [x], and every story in user-stories.md has acceptance criteria
• On failure: If requirements are too vague to map to stories, return to Step 4 for clarification rather than inventing stories. If the plan has unchecked steps, resume at the first - [ ].
• Instructions:
  1. Read detailed steps from inception/user-stories.md
  2. Assess whether user stories add value (use the multi-factor analysis from the detail file). A borderline or inconclusive assessment defaults to executing.
  3. MANDATORY: Write the assessment to <project_folder>/aidlc-docs/inception/plans/user-stories-assessment.md via file_write — on BOTH paths, executing or skipping. Use the template in inception/user-stories.md.
  4. If skipping, log rationale in audit.md and proceed to Workflow Planning
  5. If executing — Part 1: Planning:
     • Delegate plan creation to sub-agent:
       • Spawn start_task with:
         • Objective: "Create story generation plan (methodology only) for AI-DLC workflow"
         • Pass: approved requirements summary, personas identified, extension constraints
         • Include: "Read inception/user-stories.md Part 1 for plan content and the mandatory artifact steps. Write every executable step as an unchecked - [ ] checkbox item — including nested sub-steps that represent real work, but NOT descriptive attributes like file lists or purposes. The plan is the resumption source of truth."
         • Output path: <project_folder>/aidlc-docs/inception/plans/story-generation-plan.md
         • tools: "file_only", share_workspace: true, model: "smart"
       • Wait for sub-agent completion
     • Validate: confirm plan file exists and every executable step is an unchecked - [ ] item
     • Present the breakdown-approach decision card (User Journey / Feature / Persona / Epic) from inception/user-stories.md Step P2 and record the choice in the plan
     • Create <project_folder>/aidlc-docs/inception/plans/story-planning-questions.md via file_write (follow common/question-format-guide.md). Wait for answers, then run the MANDATORY contradiction and ambiguity check in common/question-format-guide.md. Do NOT proceed while any clarification question is unanswered.
     • Log the plan approval prompt in audit.md, then gate on approval:

       <decision question="Story generation plan ready. Review at aidlc-docs/inception/plans/story-generation-plan.md">
       <option>Approve plan and generate the user stories</option>
       <option>Modify the plan</option>
       </decision>
       

     • Log response in audit.md. Do NOT begin Part 2 until approved.
  6. Part 2: Generation (only after the Part 1 gate passes):
     • Delegate generation to sub-agent:
       • Spawn start_task with:
         • Objective: "Generate user stories with acceptance criteria by executing the approved story generation plan"
         • Pass: approved requirements summary, the approved plan, answered planning questions, chosen breakdown approach, extension constraints
         • Include: "Read inception/user-stories.md Part 2 and its Content Reference for format and templates. Execute the plan at aidlc-docs/inception/plans/story-generation-plan.md — find the first unchecked - [ ] item, do exactly that step, mark it [x] in the same interaction, then continue. No deviation from the approved methodology."
         • Output path: <project_folder>/aidlc-docs/inception/user-stories/user-stories.md
         • tools: "file_only", share_workspace: true, model: "smart"
       • Wait for sub-agent completion
     • Validate: confirm file exists, every plan step is [x], and the document has a personas section, acceptance criteria per story, and persona-to-story mapping
     • Present for approval with decision card
     • Log response in audit.md

Step 6: Workflow Planning (ALWAYS)

• Mode: agentic
• Input: Requirements + user stories (if generated)
• Output: Execution plan with stages and units
• Validate: workflow-plan.md exists, lists every stage with an execute/skip decision and rationale, and uses - [ ] checkboxes
• On failure: If stage needs cannot be determined, default to the comprehensive plan and say so — under-planning is the more expensive error. If the plan lacks checkboxes, reject it and regenerate.
• Instructions:
  1. Read detailed steps from inception/workflow-planning.md
  2. Determine which Construction stages are needed for each unit
  3. Delegate plan generation to sub-agent:
     • Spawn start_task with:
       • Objective: "Generate workflow execution plan for AI-DLC Construction phase"
       • Pass: requirements summary, depth level (from requirements.md), user stories (if generated), stage assessments (which to execute/skip with rationale), unit dependencies
       • Include: "Read inception/workflow-planning.md for plan structure and templates. Write every executable step as an unchecked - [ ] checkbox item — including nested sub-steps that represent real work, but NOT descriptive attributes like file lists or purposes. The plan is the resumption source of truth."
       • Output path: <project_folder>/aidlc-docs/inception/plans/workflow-plan.md
       • tools: "file_only", share_workspace: true, model: "smart"
     • Wait for sub-agent completion
  4. Validate: confirm plan file exists and lists all stages with execution/skip decisions
  5. Present plan for approval:

     <decision question="Workflow Plan ready. Shall I proceed with this execution plan?">
     <option>Approve plan and begin Construction</option>
     <option>Modify the plan</option>
     </decision>
     

  6. Log in audit.md

Step 7: Application Design (CONDITIONAL)

• Mode: agentic
• Input: Requirements and workflow plan
• Output: Application architecture design
• Conditions: Execute if new architecture needed, multiple components, or complex integrations. Skip for simple changes to existing architecture.
• Validate: design.md exists with a system context diagram, component diagram, and technology rationale
• On failure: If an architectural decision is unclear or contradictory, ask a targeted follow-up and do NOT proceed on an assumption. If diagram syntax is invalid, fix it with file_edit per common/ascii-diagram-standards.md.
• Instructions:
  1. Read detailed steps from inception/application-design.md
  2. Delegate design generation to sub-agent:
     • Spawn start_task with:
       • Objective: "Generate application architecture design document for AI-DLC workflow"
       • Pass: requirements summary, technology choices, integration needs, constraints from extensions
       • Include: "Read inception/application-design.md for structure. Read common/ascii-diagram-standards.md for diagram rules. Read common/content-validation.md for validation."
       • Output path: <project_folder>/aidlc-docs/inception/application-design/design.md
       • tools: "file_only", share_workspace: true, model: "smart"
     • Wait for sub-agent completion
  3. Validate: confirm file exists and contains system context diagram, component diagram, tech choices
  4. Present for approval with decision card
  5. Log in audit.md

Step 8: Units Generation (CONDITIONAL)

• Mode: agentic
• Input: Design + workflow plan
• Output: Decomposed work units
• Conditions: Execute if work can be decomposed into multiple independent units. Skip for single-unit work.
• Validate: units.md exists with unit definitions and a dependency section; aidlc-state.md updated with the unit list; no circular dependencies
• On failure: If dependencies are circular, name the exact cycle and get user approval on revised boundaries. If unit count cannot be determined, default to a single unit, say so, and note it can be split later.
• Instructions:
  1. Read detailed steps from inception/units-generation.md
  2. Determine unit decomposition strategy (single vs multi-unit, monolith vs microservices)
  3. Delegate units document to sub-agent:
     • Spawn start_task with:
       • Objective: "Generate work unit decomposition document for AI-DLC workflow"
       • Pass: design summary, requirements, decomposition strategy, user stories mapping
       • Include: "Read inception/units-generation.md for unit structure and templates. Write every executable step as an unchecked - [ ] checkbox item — including nested sub-steps that represent real work, but NOT descriptive attributes like file lists or purposes. The plan is the resumption source of truth."
       • Output path: <project_folder>/aidlc-docs/inception/plans/units.md
       • tools: "file_only", share_workspace: true, model: "smart"
     • Wait for sub-agent completion
  4. Validate: confirm units file exists. Update aidlc-state.md with unit list (orchestrator does this directly)
  5. Present units for approval with decision card
  6. Log in audit.md
  7. Transition to Construction Phase

Step 9: Construction Phase — Per-Unit Loop

• Mode: agentic

• Input: Approved units from Inception

• Output: Complete implementation per unit

• Validate: per unit, each executed sub-stage's artifact exists; the code generation plan is approved before any ACP delegation; generated code is at the project root and NOT in aidlc-docs/; extension compliance summary produced

• On failure: If the ACP agent returns incomplete or non-compliant code, send a targeted correction request naming the specific violation, then re-validate — do not accept and move on. If a dependency unit is not yet built, reorder or generate against stubs and record the integration debt. If code landed in aidlc-docs/, move it to the project root before proceeding.

• Instructions: For each unit of work, execute the following sub-stages in sequence:

  9a. Functional Design (CONDITIONAL, per-unit)

  • Execute IF: new data models, complex business logic, business rules need design
  • Read construction/functional-design.md for context on what's needed
  • Delegate to sub-agent:
    • Objective: "Generate functional design for unit [unit-name]"
    • Pass: unit context, requirements, user stories for this unit, extension constraints
    • Include: "Read construction/functional-design.md for templates"
    • Output path: <project_folder>/aidlc-docs/construction/<unit-name>/functional-design/
    • tools: "file_only", share_workspace: true, model: "smart"
  • Validate: confirm file exists
  • Present for approval with decision card:

    <decision question="Functional Design for [unit] complete.">
    <option>Continue to next stage</option>
    <option>Request changes</option>
    </decision>
    

  9b. NFR Requirements (CONDITIONAL, per-unit)

  • Execute IF: performance, security, scalability, or tech stack concerns
  • Read construction/nfr-requirements.md for context
  • Delegate to sub-agent:
    • Objective: "Generate NFR requirements analysis for unit [unit-name]"
    • Pass: unit context, functional design summary, extension constraints
    • Include: "Read construction/nfr-requirements.md for templates"
    • Output path: <project_folder>/aidlc-docs/construction/<unit-name>/nfr-requirements/
    • tools: "file_only", share_workspace: true, model: "smart"
  • Validate: confirm file exists
  • Present for approval with decision card

  9c. NFR Design (CONDITIONAL, per-unit)

  • Execute IF: NFR Requirements was executed
  • Read construction/nfr-design.md for context
  • Delegate to sub-agent:
    • Objective: "Generate NFR design patterns for unit [unit-name]"
    • Pass: NFR requirements output, functional design, tech stack
    • Include: "Read construction/nfr-design.md for templates"
    • Output path: <project_folder>/aidlc-docs/construction/<unit-name>/nfr-design/
    • tools: "file_only", share_workspace: true, model: "smart"
  • Validate: confirm file exists
  • Present for approval with decision card

  9d. Infrastructure Design (CONDITIONAL, per-unit)

  • Execute IF: cloud resources, deployment architecture, or infrastructure services needed
  • Read construction/infrastructure-design.md for context
  • Delegate to sub-agent:
    • Objective: "Generate infrastructure design for unit [unit-name]"
    • Pass: NFR design output, functional design, cloud requirements
    • Include: "Read construction/infrastructure-design.md for templates"
    • Output path: <project_folder>/aidlc-docs/construction/<unit-name>/infrastructure-design/
    • tools: "file_only", share_workspace: true, model: "smart"
  • Validate: confirm file exists
  • Present for approval with decision card

  9e. Code Generation (ALWAYS, per-unit)

  • Read construction/code-generation.md
  • Part 1 — Planning (Quick does this):
    • Delegate plan creation to sub-agent:
      • Objective: "Create detailed code generation plan for unit [unit-name]"
      • Pass: functional design, NFR design, infrastructure design, tech stack, brownfield context
      • Include: "Read construction/code-generation.md for plan format and rules. Write every executable step as an unchecked - [ ] checkbox item — including nested sub-steps that represent real work, but NOT descriptive attributes like file lists or purposes. The plan is the resumption source of truth."
      • Output path: <project_folder>/aidlc-docs/construction/plans/<unit-name>-code-generation-plan.md
      • tools: "file_only", share_workspace: true, model: "smart"
    • Validate: confirm plan file exists and every step is an unchecked - [ ] item
    • Present plan for approval:

      <decision question="Code generation plan for [unit] ready.">
      <option>Approve plan — delegate to coding agent</option>
      <option>Modify plan</option>
      </decision>
      

  • Part 2 — Execution (ACP agent does this):
    • Compose structured prompt with: unit name, design spec, tech stack, constraints, plan
    • Include enabled extension rules as constraints (e.g., security baseline)
    • Delegate to ACP agent via send_message_to_acp_agent
    • Validate ACP output against extension rules
    • If non-compliant: send correction request back to ACP agent
    • Log results in audit.md
    • Present completion:

      <decision question="Code generation for [unit] complete.">
      <option>Continue to next unit/stage</option>
      <option>Request changes</option>
      </decision>
      

Step 10: Build and Test (ALWAYS)

• Mode: agentic
• Input: All generated code from Construction
• Output: Build/test results and instructions
• Validate: all five instruction files exist (including performance-test-instructions.md); test results recorded with pass/fail counts; every NFR performance target has a verdict
• On failure: If the build or tests fail, present the exact errors with file:line and offer: send a fix request to the ACP agent / user fixes manually / skip and document. Never report success on a failing build. If the build tool cannot be determined, ask the user.
• Instructions:
  1. Read detailed steps from construction/build-and-test.md
  2. Log phase start in audit.md
  3. Delegate to ACP agent for build and test execution:
     • Compose prompt asking ACP agent to:
       • Build the project (install deps, compile, bundle)
       • Run unit tests
       • Run integration tests
       • Report: pass/fail, coverage, errors
     • Send via send_message_to_acp_agent
  4. Delegate test documentation to sub-agent:
     • Spawn start_task with:
       • Objective: "Generate build and test documentation from ACP agent results"
       • Pass: ACP agent's build/test output, project structure, test results summary
       • Include: "Read construction/build-and-test.md for document structure and templates"
       • Output path: <project_folder>/aidlc-docs/construction/build-and-test/
       • Expected files: build-instructions.md, unit-test-instructions.md, integration-test-instructions.md, performance-test-instructions.md, build-and-test-summary.md
       • performance-test-instructions.md is REQUIRED if NFR Requirements ran for any unit (it verifies the performance targets those stages set). If no unit ran NFR stages, write the file with an explicit "No performance targets defined — no performance tests required" statement rather than omitting it.
       • tools: "file_only", share_workspace: true, model: "smart"
     • Wait for sub-agent completion
  5. Validate: confirm all instruction files exist
  6. If tests fail: present failures and ask user how to proceed
  7. If tests pass: present completion:

     <decision question="Build and test complete. All tests passing.">
     <option>Proceed to Operations</option>
     <option>Request additional testing</option>
     </decision>
     

  8. Log in audit.md

Step 11: Operations (PLACEHOLDER)

• Mode: agentic
• Input: Successfully built and tested code
• Output: Operations readiness summary
• Validate: operations-summary.md exists; aidlc-state.md marked complete
• On failure: If the deployment target is unclear, ask; otherwise emit common-platform guidance and mark the assumption explicitly in the summary.
• Instructions:
  1. Read operations/operations.md
  2. Generate operations readiness summary:
     • Deployment recommendations
     • Monitoring suggestions
     • Maintenance notes
  3. Update aidlc-state.md to mark workflow complete
  4. Present final summary to user
  5. Final audit log entry

Error Handling

Every workflow step above has an explicit On failure: branch. When any of them triggers, follow common/error-handling.md:

1. Classify the error by category (filesystem, ACP agent, workflow state, content validation, extension compliance) and locate the stage-specific recovery procedure for the current stage.
2. Apply the matching recovery strategy (retry, fallback, reconstruct, skip and document, or escalate to user).
3. Log the error and its resolution in audit.md using the error record format.
4. Never silently continue past a failure — either recover it or surface it.

If an error is ambiguous, or still repeats after the retry budget in common/error-handling.md is exhausted, escalate to the user with a decision card rather than guessing.

Handling Change Requests

Most stages above offer the user a "Request changes" or "Modify the plan" option. When the user picks one — or asks for a change mid-stage — read common/workflow-changes.md at that moment and follow it. Load it lazily here rather than up front: most runs never need it, and the orchestrator's context is precious.

It covers scope changes (minor in-place vs. major requiring a return to an earlier Inception stage), how to assess impact on the current plan, and how to resume Construction with updated context.

Extension Enforcement Rules

When extensions are enabled:

• Extension rules are hard constraints, not optional guidance
• At each stage, evaluate which extension rules are applicable
• Non-compliance with any applicable enabled extension rule is a blocking finding
• Do NOT present stage completion until all blocking findings are resolved
• Include compliance summary when presenting stage completion:
  • ✅ Compliant / ❌ Non-compliant / ➖ N/A (with rationale)

Content Validation Rules

Sub-agents are instructed to validate content before writing. The orchestrator performs lightweight post-validation checks. Content rules:

• Validate Mermaid diagram syntax if present
• Validate ASCII art diagrams per common/ascii-diagram-standards.md
• Escape special characters properly
• Provide text alternatives for complex visual content

MANDATORY: Plan-Level Checkbox Enforcement

Amazon Quick agents have no memory between sessions. An unchecked box stays undone no matter what was discussed in chat. Checkboxes in plan files are therefore the sole source of truth for what has been completed.

Rules for plan execution

1. NEVER complete any work without updating the plan's checkboxes.
2. IMMEDIATELY after completing any step described in a plan file, mark it [x].
3. This MUST happen in the same interaction where the work was completed — not batched at the end of a stage, and never deferred to "later".
4. NO EXCEPTIONS. Every plan step completion is tracked with a checkbox update.

What [x] means

[x] means resolved — the step either completed, or was deliberately skipped with a recorded rationale. A conditional stage assessed as Execute: No is resolved, so it gets [x] with its skip reason, NOT left unchecked. Only genuinely outstanding work stays [ ].

This distinction matters on resume: an unchecked box is treated as work still to do, so leaving a deliberately-skipped stage unchecked would make a later session re-run or block on it.

Two-level tracking

• Plan-level — detailed execution progress inside each stage's plan file (aidlc-docs/inception/plans/*.md, aidlc-docs/construction/plans/*.md)
• Stage-level — overall workflow progress in aidlc-docs/aidlc-state.md

Both are updated in the same interaction as the work. Use file_edit for these updates so surrounding plan content is preserved.

Plans must be generated with checkboxes

Every sub-agent instructed to produce a plan document MUST be told to write each executable step as an unchecked - [ ] checkbox item — including nested sub-steps that represent real work, but NOT descriptive attributes like file lists or purposes. A plan without checkboxes cannot be resumed and is a defect — reject it and regenerate.

Audit Logging Rules

CRITICAL: ALWAYS append to audit.md using file_edit (never overwrite):

• Log EVERY user input with complete raw text
• Log every approval prompt before asking
• Log every user response after receiving
• Use ISO 8601 timestamps
• Include stage context

Format:

## [Stage Name]
**Timestamp**: [ISO timestamp]
**User Input**: "[Complete raw input]"
**AI Response**: "[Action taken]"
**Context**: [Stage, decision made]
---

ACP Agent Integration

When delegating to ACP agents:

1. Compose structured prompts — include all relevant design specs, constraints, and tech stack info
2. Include extension constraints — if security baseline is enabled, tell the agent about OWASP rules, input validation requirements, etc.
3. Validate output — check ACP agent's code against enabled extension rules before accepting
4. Log everything — record what was delegated, what was returned, validation results
5. Iterate if needed — send correction requests back to ACP agent for non-compliant code

Session Continuity

On workflow start, always check for existing aidlc-state.md:

• If found: read it, determine last completed stage, resume from next stage
• If not found: fresh workflow start
• Reference common/session-continuity.md for detailed resumption logic

Directory Structure (Output)

<project_folder>/
├── [application code — at workspace root, NEVER in aidlc-docs/]
└── aidlc-docs/
    ├── inception/
    │   ├── plans/
    │   ├── reverse-engineering/    (brownfield only)
    │   ├── requirements/
    │   ├── user-stories/
    │   └── application-design/
    ├── construction/
    │   ├── plans/
    │   ├── <unit-name>/
    │   │   ├── functional-design/
    │   │   ├── nfr-requirements/
    │   │   ├── nfr-design/
    │   │   ├── infrastructure-design/
    │   │   └── code/
    │   └── build-and-test/
    ├── operations/
    ├── aidlc-state.md
    └── audit.md

Lessons Learned

Do

• Delegate every substantial document to a sub-agent via start_task. The orchestrator's context is the scarcest resource in this workflow — spend it on decisions, not prose.
• Validate artifacts deterministically with run_python after each delegation, using the Post-Delegation Validation snippet above. Existence and size are facts, not judgements.
• Append to audit.md with file_edit, capturing the user's complete raw input verbatim.
• Mark plan checkboxes [x] in the same interaction as the work they describe.
• On resume, load only the in-progress unit's artifacts plus the artifacts of the units it depends on. Everything else stays on disk until needed.
• Ask the user when a decision is architectural or carries a cost trade-off.
• Scan extensions/**/*.opt-in.md at start, but load a full extension rules file only after the user opts in.

Don't

• Don't write application code into aidlc-docs/ — code belongs at the project root. aidlc-docs/ holds documentation about the code, never the code itself.
• Don't overwrite audit.md with file_write. It is append-only.
• Don't proceed past an unresolved contradiction in the user's answers.
• Don't load every unit's design artifacts on resume.
• Don't present a stage as complete while a blocking extension finding is open.
• Don't report tests as passing without the test runner's actual output.
• Don't decide RTO/RPO, rollback strategy, or regional topology on the user's behalf.

Common Failures

• Resume loads the wrong files. The artifact paths named in common/session-continuity.md must match what the stages actually write. When they drift, a resumed session reads nothing and silently starts over.
• Unchecked boxes silently lose work. Quick has no memory between sessions, so a step that was done but left - [ ] is indistinguishable from one never started.
• ACP agent absent, discovered late. Step 1 probes for a coding agent precisely so this surfaces before the user spends an hour on Inception.
• A sub-agent writes a stub. A file that exists can still be near-empty; the run_python size check catches what a bare existence check does not.
• Extension rules cut to fit context. Extension files load lazily on opt-in, so they cost nothing at rest — compress common/ instead.

When to Ask the User

• The project folder is ambiguous, or folder access has not been granted.
• Answers contradict each other, or contain "depends", "not sure", or "mix of".
• An architectural choice carries a real cost or risk trade-off — DR strategy, multi-region, monolith vs. microservices.
• The build or tests fail and the fix is not mechanical.
• A step needs credentials, network changes, or anything else you cannot do.
• The same step has failed twice after one recovery attempt.

Output

A complete, documented software development workflow with:

• Full audit trail in audit.md
• All SDLC artifacts in aidlc-docs/
• Working code at the project root (generated by ACP agent)
• Extension compliance verified at every stage