Loading
Also from Kynth Studios
Also from Kynth Studios
Also from Kynth Studios
1<!-- forgecat:@forgecat/awslabs_aidlc-workflows:core-workflow:start -->2# PRIORITY: This workflow OVERRIDES all other built-in workflows3# When user requests software development, ALWAYS follow this workflow FIRST45## Adaptive Workflow Principle6**The workflow adapts to the work, not the other way around.**78The AI model intelligently assesses what stages are needed based on:91. User's stated intent and clarity102. Existing codebase state (if any)113. Complexity and scope of change124. Risk and impact assessment1314## MANDATORY: Rule Details Loading15**CRITICAL**: When performing any phase, you MUST read and use relevant content from rule detail files. Check these paths in order and use the first one that exists:16- `.aidlc-rule-details/` (Cursor, Cline, Claude Code, GitHub Copilot)17- `.kiro/aws-aidlc-rule-details/` (Kiro IDE and CLI)18- `.amazonq/aws-aidlc-rule-details/` (Amazon Q Developer)1920All subsequent rule detail file references (e.g., `common/process-overview.md`, `inception/workspace-detection.md`) are relative to whichever rule details directory was resolved above.2122**Common Rules**: ALWAYS load common rules at workflow start:23- Load `common/process-overview.md` for workflow overview24- Load `common/session-continuity.md` for session resumption guidance25- Load `common/content-validation.md` for content validation requirements26- Load `common/question-format-guide.md` for question formatting rules27- Reference these throughout the workflow execution2829## MANDATORY: Extensions Loading (Context-Optimized)30**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.3132**Loading process**:331. List all subdirectories under `extensions/` (e.g., `extensions/security/`, `extensions/compliance/`)342. 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`)353. Do NOT load full rule files (e.g., `security-baseline.md`) at this stage3637**Deferred Rule Loading**:38- During Requirements Analysis, opt-in prompts from the loaded `*.opt-in.md` files are presented to the user39- When the user opts IN for an extension, load the corresponding rules file (derived by naming convention) at that point40- When the user opts OUT, the full rules file is never loaded — saving context41- Extensions without a matching `*.opt-in.md` file are always enforced — load their rule files immediately at workflow start4243**Enforcement** (applies only to loaded/enabled extensions):44- Extension rules are hard constraints, not optional guidance45- 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 relevant46- 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)47- Non-compliance with any applicable enabled extension rule is a **blocking finding** — do NOT present stage completion until resolved48- 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)4950**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.5152## MANDATORY: Content Validation53**CRITICAL**: Before creating ANY file, you MUST validate content according to `common/content-validation.md` rules:54- Validate Mermaid diagram syntax55- Validate ASCII art diagrams (see `common/ascii-diagram-standards.md`)56- Escape special characters properly57- Provide text alternatives for complex visual content58- Test content parsing compatibility5960## MANDATORY: Question File Format61**CRITICAL**: When asking questions at any phase, you MUST follow question format guidelines.6263**See `common/question-format-guide.md` for complete question formatting rules including**:64- Multiple choice format (A, B, C, D, E options)65- [Answer]: tag usage66- Answer validation and ambiguity resolution6768## MANDATORY: Custom Welcome Message69**CRITICAL**: When starting ANY software development request, you MUST display the welcome message.7071**How to Display Welcome Message**:721. Load the welcome message from `common/welcome-message.md` (in the resolved rule details directory)732. Display the complete message to the user743. This should only be done ONCE at the start of a new workflow754. Do NOT load this file in subsequent interactions to save context space7677# Adaptive Software Development Workflow7879---8081# INCEPTION PHASE8283**Purpose**: Planning, requirements gathering, and architectural decisions8485**Focus**: Determine WHAT to build and WHY8687**Stages in INCEPTION PHASE**:88- Workspace Detection (ALWAYS)89- Reverse Engineering (CONDITIONAL - Brownfield only)90- Requirements Analysis (ALWAYS - Adaptive depth)91- User Stories (CONDITIONAL)92- Workflow Planning (ALWAYS)93- Application Design (CONDITIONAL)94- Units Generation (CONDITIONAL)9596---9798## Workspace Detection (ALWAYS EXECUTE)991001. **MANDATORY**: Log initial user request in audit.md with complete raw input1012. Load all steps from `inception/workspace-detection.md`1023. Execute workspace detection:103 - Check for existing aidlc-state.md (resume if found)104 - Scan workspace for existing code105 - Determine if brownfield or greenfield106 - Check for existing reverse engineering artifacts1074. Determine next phase: Reverse Engineering (if brownfield and no artifacts) OR Requirements Analysis1085. **MANDATORY**: Log findings in audit.md1096. Present completion message to user (see workspace-detection.md for message formats)1107. Automatically proceed to next phase111112## Reverse Engineering (CONDITIONAL - Brownfield Only)113114**Execute IF**:115- Existing codebase detected116- No previous reverse engineering artifacts found117118**Skip IF**:119- Greenfield project120- Previous reverse engineering artifacts exist121122**Execution**:1231. **MANDATORY**: Log start of reverse engineering in audit.md1242. Load all steps from `inception/reverse-engineering.md`1253. Execute reverse engineering:126 - Analyze all packages and components127 - Generate a business overview of the whole system covering the business transactions128 - Generate architecture documentation129 - Generate code structure documentation130 - Generate API documentation131 - Generate component inventory132 - Generate Interaction Diagrams depicting how business transactions are implemented across components133 - Generate technology stack documentation134 - Generate dependencies documentation1351364. **Wait for Explicit Approval**: Present detailed completion message (see reverse-engineering.md for message format) - DO NOT PROCEED until user confirms1375. **MANDATORY**: Log user's response in audit.md with complete raw input138139## Requirements Analysis (ALWAYS EXECUTE - Adaptive Depth)140141**Always executes** but depth varies based on request clarity and complexity:142- **Minimal**: Simple, clear request - just document intent analysis143- **Standard**: Normal complexity - gather functional and non-functional requirements144- **Comprehensive**: Complex, high-risk - detailed requirements with traceability145146**Execution**:1471. **MANDATORY**: Log any user input during this phase in audit.md1482. Load all steps from `inception/requirements-analysis.md`1493. Execute requirements analysis:150 - Load reverse engineering artifacts (if brownfield)151 - Analyze user request (intent analysis)152 - Determine requirements depth needed153 - Assess current requirements154 - Ask clarifying questions (if needed)155 - Generate requirements document1564. Execute at appropriate depth (minimal/standard/comprehensive)1575. **Wait for Explicit Approval**: Follow approval format from requirements-analysis.md detailed steps - DO NOT PROCEED until user confirms1586. **MANDATORY**: Log user's response in audit.md with complete raw input159160## User Stories (CONDITIONAL)161162**INTELLIGENT ASSESSMENT**: Use multi-factor analysis to determine if user stories add value:163164**ALWAYS Execute IF** (High Priority Indicators):165- New user-facing features or functionality166- Changes affecting user workflows or interactions167- Multiple user types or personas involved168- Complex business requirements with acceptance criteria needs169- Cross-functional team collaboration required170- Customer-facing API or service changes171- New product capabilities or enhancements172173**LIKELY Execute IF** (Medium Priority - Assess Complexity):174- Modifications to existing user-facing features175- Backend changes that indirectly affect user experience176- Integration work that impacts user workflows177- Performance improvements with user-visible benefits178- Security enhancements affecting user interactions179- Data model changes affecting user data or reports180181**COMPLEXITY-BASED ASSESSMENT**: For medium priority cases, execute user stories if:182- Request involves multiple components or services183- Changes span multiple user touchpoints184- Business logic is complex or has multiple scenarios185- Requirements have ambiguity that stories could clarify186- Implementation affects multiple user journeys187- Change has significant business impact or risk188189**SKIP ONLY IF** (Low Priority - Simple Cases):190- Pure internal refactoring with zero user impact191- Simple bug fixes with clear, isolated scope192- Infrastructure changes with no user-facing effects193- Technical debt cleanup with no functional changes194- Developer tooling or build process improvements195- Documentation-only updates196197**ASSESSMENT CRITERIA**: When in doubt, favor inclusion of user stories for:198- Requests with business stakeholder involvement199- Changes requiring user acceptance testing200- Features with multiple implementation approaches201- Work that benefits from shared team understanding202- Projects where requirements clarity is valuable203204**ASSESSMENT PROCESS**:2051. Analyze request complexity and scope2062. Identify user impact (direct or indirect)2073. Evaluate business context and stakeholder needs2084. Consider team collaboration benefits2095. Default to inclusion for borderline cases210211**Note**: If Requirements Analysis executed, Stories can reference and build upon those requirements.212213**User Stories has two parts within one stage**:2141. **Part 1 - Planning**: Create story plan with questions, collect answers, analyze for ambiguities, get approval2152. **Part 2 - Generation**: Execute approved plan to generate stories and personas216217**Execution**:2181. **MANDATORY**: Log any user input during this phase in audit.md2192. Load all steps from `inception/user-stories.md`2203. **MANDATORY**: Perform intelligent assessment (Step 1 in user-stories.md) to validate user stories are needed2214. Load reverse engineering artifacts (if brownfield)2225. If Requirements exist, reference them when creating stories2236. Execute at appropriate depth (minimal/standard/comprehensive)2247. **PART 1 - Planning**: Create story plan with questions, wait for user answers, analyze for ambiguities, get approval2258. **PART 2 - Generation**: Execute approved plan to generate stories and personas2269. **Wait for Explicit Approval**: Follow approval format from user-stories.md detailed steps - DO NOT PROCEED until user confirms22710. **MANDATORY**: Log user's response in audit.md with complete raw input228229## Workflow Planning (ALWAYS EXECUTE)2302311. **MANDATORY**: Log any user input during this phase in audit.md2322. Load all steps from `inception/workflow-planning.md`2333. **MANDATORY**: Load content validation rules from `common/content-validation.md`2344. Load all prior context:235 - Reverse engineering artifacts (if brownfield)236 - Intent analysis237 - Requirements (if executed)238 - User stories (if executed)2395. Execute workflow planning:240 - Determine which phases to execute241 - Determine depth level for each phase242 - Create multi-package change sequence (if brownfield)243 - Generate workflow visualization (VALIDATE Mermaid syntax before writing)2446. **MANDATORY**: Validate all content before file creation per content-validation.md rules2457. **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 confirms2468. **MANDATORY**: Log user's response in audit.md with complete raw input247248## Application Design (CONDITIONAL)249250**Execute IF**:251- New components or services needed252- Component methods and business rules need definition253- Service layer design required254- Component dependencies need clarification255256**Skip IF**:257- Changes within existing component boundaries258- No new components or methods259- Pure implementation changes260261**Execution**:2621. **MANDATORY**: Log any user input during this phase in audit.md2632. Load all steps from `inception/application-design.md`2643. Load reverse engineering artifacts (if brownfield)2654. Execute at appropriate depth (minimal/standard/comprehensive)2665. **Wait for Explicit Approval**: Present detailed completion message (see application-design.md for message format) - DO NOT PROCEED until user confirms2676. **MANDATORY**: Log user's response in audit.md with complete raw input268269## Units Generation (CONDITIONAL)270271**Execute IF**:272- System needs decomposition into multiple units of work273- Multiple services or modules required274- Complex system requiring structured breakdown275276**Skip IF**:277- Single simple unit278- No decomposition needed279- Straightforward single-component implementation280281**Execution**:2821. **MANDATORY**: Log any user input during this phase in audit.md2832. Load all steps from `inception/units-generation.md`2843. Load reverse engineering artifacts (if brownfield)2854. Execute at appropriate depth (minimal/standard/comprehensive)2865. **Wait for Explicit Approval**: Present detailed completion message (see units-generation.md for message format) - DO NOT PROCEED until user confirms2876. **MANDATORY**: Log user's response in audit.md with complete raw input288289---290291# 🟢 CONSTRUCTION PHASE292293**Purpose**: Detailed design, NFR implementation, and code generation294295**Focus**: Determine HOW to build it296297**Stages in CONSTRUCTION PHASE**:298- Per-Unit Loop (executes for each unit):299 - Functional Design (CONDITIONAL, per-unit)300 - NFR Requirements (CONDITIONAL, per-unit)301 - NFR Design (CONDITIONAL, per-unit)302 - Infrastructure Design (CONDITIONAL, per-unit)303 - Code Generation (ALWAYS, per-unit)304- Build and Test (ALWAYS - after all units complete)305306**Note**: Each unit is completed fully (design + code) before moving to the next unit.307308---309310## Per-Unit Loop (Executes for Each Unit)311312**For each unit of work, execute the following stages in sequence:**313314### Functional Design (CONDITIONAL, per-unit)315316**Execute IF**:317- New data models or schemas318- Complex business logic319- Business rules need detailed design320321**Skip IF**:322- Simple logic changes323- No new business logic324325**Execution**:3261. **MANDATORY**: Log any user input during this stage in audit.md3272. Load all steps from `construction/functional-design.md`3283. Execute functional design for this unit3294. **MANDATORY**: Present standardized 2-option completion message as defined in functional-design.md - DO NOT use emergent 3-option behavior3305. **Wait for Explicit Approval**: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms3316. **MANDATORY**: Log user's response in audit.md with complete raw input332333### NFR Requirements (CONDITIONAL, per-unit)334335**Execute IF**:336- Performance requirements exist337- Security considerations needed338- Scalability concerns present339- Tech stack selection required340341**Skip IF**:342- No NFR requirements343- Tech stack already determined344345**Execution**:3461. **MANDATORY**: Log any user input during this stage in audit.md3472. Load all steps from `construction/nfr-requirements.md`3483. Execute NFR assessment for this unit3494. **MANDATORY**: Present standardized 2-option completion message as defined in nfr-requirements.md - DO NOT use emergent behavior3505. **Wait for Explicit Approval**: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms3516. **MANDATORY**: Log user's response in audit.md with complete raw input352353### NFR Design (CONDITIONAL, per-unit)354355**Execute IF**:356- NFR Requirements was executed357- NFR patterns need to be incorporated358359**Skip IF**:360- No NFR requirements361- NFR Requirements was skipped362363**Execution**:3641. **MANDATORY**: Log any user input during this stage in audit.md3652. Load all steps from `construction/nfr-design.md`3663. Execute NFR design for this unit3674. **MANDATORY**: Present standardized 2-option completion message as defined in nfr-design.md - DO NOT use emergent behavior3685. **Wait for Explicit Approval**: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms3696. **MANDATORY**: Log user's response in audit.md with complete raw input370371### Infrastructure Design (CONDITIONAL, per-unit)372373**Execute IF**:374- Infrastructure services need mapping375- Deployment architecture required376- Cloud resources need specification377378**Skip IF**:379- No infrastructure changes380- Infrastructure already defined381382**Execution**:3831. **MANDATORY**: Log any user input during this stage in audit.md3842. Load all steps from `construction/infrastructure-design.md`3853. Execute infrastructure design for this unit3864. **MANDATORY**: Present standardized 2-option completion message as defined in infrastructure-design.md - DO NOT use emergent behavior3875. **Wait for Explicit Approval**: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms3886. **MANDATORY**: Log user's response in audit.md with complete raw input389390### Code Generation (ALWAYS EXECUTE, per-unit)391392**Always executes for each unit**393394**Code Generation has two parts within one stage**:3951. **Part 1 - Planning**: Create detailed code generation plan with explicit steps3962. **Part 2 - Generation**: Execute approved plan to generate code, tests, and artifacts397398**Execution**:3991. **MANDATORY**: Log any user input during this stage in audit.md4002. Load all steps from `construction/code-generation.md`4013. **PART 1 - Planning**: Create code generation plan with checkboxes, get user approval4024. **PART 2 - Generation**: Execute approved plan to generate code for this unit4035. **MANDATORY**: Present standardized 2-option completion message as defined in code-generation.md - DO NOT use emergent behavior4046. **Wait for Explicit Approval**: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms4057. **MANDATORY**: Log user's response in audit.md with complete raw input406407---408409## Build and Test (ALWAYS EXECUTE)4104111. **MANDATORY**: Log any user input during this phase in audit.md4122. Load all steps from `construction/build-and-test.md`4133. Generate comprehensive build and test instructions:414 - Build instructions for all units415 - Unit test execution instructions416 - Integration test instructions (test interactions between units)417 - Performance test instructions (if applicable)418 - Additional test instructions as needed (contract tests, security tests, e2e tests)4194. 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.md4205. **Wait for Explicit Approval**: Ask: "**Build and test instructions complete. Ready to proceed to Operations stage?**" - DO NOT PROCEED until user confirms4216. **MANDATORY**: Log user's response in audit.md with complete raw input422423---424425# 🟡 OPERATIONS PHASE426427**Purpose**: Placeholder for future deployment and monitoring workflows428429**Focus**: How to DEPLOY and RUN it (future expansion)430431**Stages in OPERATIONS PHASE**:432- Operations (PLACEHOLDER)433434---435436## Operations (PLACEHOLDER)437438**Status**: This stage is currently a placeholder for future expansion.439440The Operations stage will eventually include:441- Deployment planning and execution442- Monitoring and observability setup443- Incident response procedures444- Maintenance and support workflows445- Production readiness checklists446447**Current State**: All build and test activities are handled in the CONSTRUCTION phase.448449## Key Principles450451- **Adaptive Execution**: Only execute stages that add value452- **Transparent Planning**: Always show execution plan before starting453- **User Control**: User can request stage inclusion/exclusion454- **Progress Tracking**: Update aidlc-state.md with executed and skipped stages455- **Complete Audit Trail**: Log ALL user inputs and AI responses in audit.md with timestamps456 - **CRITICAL**: Capture user's COMPLETE RAW INPUT exactly as provided457 - **CRITICAL**: Never summarize or paraphrase user input in audit log458 - **CRITICAL**: Log every interaction, not just approvals459- **Quality Focus**: Complex changes get full treatment, simple changes stay efficient460- **Content Validation**: Always validate content before file creation per content-validation.md rules461- **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.462463## MANDATORY: Plan-Level Checkbox Enforcement464465### MANDATORY RULES FOR PLAN EXECUTION4661. **NEVER complete any work without updating plan checkboxes**4672. **IMMEDIATELY after completing ANY step described in a plan file, mark that step [x]**4683. **This must happen in the SAME interaction where the work is completed**4694. **NO EXCEPTIONS**: Every plan step completion MUST be tracked with checkbox updates470471### Two-Level Checkbox Tracking System472- **Plan-Level**: Track detailed execution progress within each stage473- **Stage-Level**: Track overall workflow progress in aidlc-state.md474- **Update immediately**: All progress updates in SAME interaction where work is completed475476## Prompts Logging Requirements477- **MANDATORY**: Log EVERY user input (prompts, questions, responses) with timestamp in audit.md478- **MANDATORY**: Capture user's COMPLETE RAW INPUT exactly as provided (never summarize)479- **MANDATORY**: Log every approval prompt with timestamp before asking the user480- **MANDATORY**: Record every user response with timestamp after receiving it481- **CRITICAL**: ALWAYS append changes to EDIT audit.md file, NEVER use tools and commands that completely overwrite its contents482- **CRITICAL**: NEVER use file writing tools and commands that overwrite the entire contents of audit.md, as this causes duplication483- Use ISO 8601 format for timestamps (YYYY-MM-DDTHH:MM:SSZ)484- Include stage context for each entry485486### Audit Log Format:487```markdown488## [Stage Name or Interaction Type]489**Timestamp**: [ISO timestamp]490**User Input**: "[Complete raw user input - never summarized]"491**AI Response**: "[AI's response or action taken]"492**Context**: [Stage, action, or decision made]493494---495```496497### Correct Tool Usage for audit.md498499✅ CORRECT:5005011. Read the audit.md file5022. Append/Edit the file to make changes503504❌ WRONG:5055061. Read the audit.md file5072. Completely overwrite the audit.md with the contents of what you read, plus the new changes you want to add to it508509## Directory Structure510511```text512<WORKSPACE-ROOT>/ # ⚠️ APPLICATION CODE HERE513├── [project-specific structure] # Varies by project (see code-generation.md)514│515├── aidlc-docs/ # 📄 DOCUMENTATION ONLY516│ ├── inception/ # 🔵 INCEPTION PHASE517│ │ ├── plans/518│ │ ├── reverse-engineering/ # Brownfield only519│ │ ├── requirements/520│ │ ├── user-stories/521│ │ └── application-design/522│ ├── construction/ # 🟢 CONSTRUCTION PHASE523│ │ ├── plans/524│ │ ├── {unit-name}/525│ │ │ ├── functional-design/526│ │ │ ├── nfr-requirements/527│ │ │ ├── nfr-design/528│ │ │ ├── infrastructure-design/529│ │ │ └── code/ # Markdown summaries only530│ │ └── build-and-test/531│ ├── operations/ # 🟡 OPERATIONS PHASE (placeholder)532│ ├── aidlc-state.md533│ └── audit.md534```535536**CRITICAL RULE**:537- Application code: Workspace root (NEVER in aidlc-docs/)538- Documentation: aidlc-docs/ only539- Project structure: See code-generation.md for patterns by project type540<!-- forgecat:@forgecat/awslabs_aidlc-workflows:core-workflow:end -->541542<!-- forgecat:@forgecat/awslabs_aidlc-workflows:ascii-diagram-standards:start -->543# ASCII Diagram Standards544545## MANDATORY: Use Basic ASCII Only546547**CRITICAL**: ALWAYS use basic ASCII characters for diagrams (maximum compatibility).548549### ✅ ALLOWED: `+` `-` `|` `^` `v` `<` `>` and alphanumeric text550551### ❌ FORBIDDEN: Unicode box-drawing characters552- NO: `┌` `─` `│` `└` `┐` `┘` `├` `┤` `┬` `┴` `┼` `▼` `▲` `►` `◄`553- Reason: Inconsistent rendering across fonts/platforms554555## Standard ASCII Diagram Patterns556557### CRITICAL: Character Width Rule558**Every line in a box MUST have EXACTLY the same character count (including spaces)**559560✅ CORRECT (all lines = 67 chars):561```562+---------------------------------------------------------------+563| Component Name |564| Description text here |565+---------------------------------------------------------------+566```567568❌ WRONG (inconsistent widths):569```570+---------------------------------------------------------------+571| Component Name |572| Description text here |573+---------------------------------------------------------------+574```575576### Box Pattern577```578+-----------------------------------------------------+579| |580| Calculator Application |581| |582| Provides basic arithmetic operations for users |583| through a web-based interface |584| |585+-----------------------------------------------------+586```587588### Nested Boxes589```590+-------------------------------------------------------+591| Web Server (PHP Runtime) |592| +-------------------------------------------------+ |593| | index.php (Monolithic Application) | |594| | +-------------------------------------------+ | |595| | | HTML Template (View Layer) | | |596| | | - Form rendering | | |597| | | - Result display | | |598| | +-------------------------------------------+ | |599| +-------------------------------------------------+ |600+-------------------------------------------------------+601```602603### Arrows and Connections604```605+----------+606| Source |607+----------+608 |609 | HTTP POST610 v611+----------+612| Target |613+----------+614```615616### Horizontal Flow617```618+-------+ +-------+ +-------+619| Step1 | --> | Step2 | --> | Step3 |620+-------+ +-------+ +-------+621```622623### Vertical Flow with Labels624```625User Action Flow:626 |627 v628+----------+629| Input |630+----------+631 |632 | validates633 v634+----------+635| Process |636+----------+637 |638 | returns639 v640+----------+641| Output |642+----------+643```644645## Validation646647Before creating diagrams:648- [ ] Basic ASCII only: `+` `-` `|` `^` `v` `<` `>`649- [ ] No Unicode box-drawing650- [ ] Spaces (not tabs) for alignment651- [ ] Corners use `+`652- [ ] **ALL box lines same character width** (count characters including spaces)653- [ ] Test: Verify corners align vertically in monospace font654655## Alternative656657For complex diagrams, use Mermaid (see `content-validation.md`)658<!-- forgecat:@forgecat/awslabs_aidlc-workflows:ascii-diagram-standards:end -->659660<!-- forgecat:@forgecat/awslabs_aidlc-workflows:content-validation:start -->661# Content Validation Rules662663## MANDATORY: Content Validation Before File Creation664665**CRITICAL**: All generated content MUST be validated before writing to files to prevent parsing errors.666667## ASCII Diagram Standards668669**CRITICAL**: Before creating ANY file with ASCII diagrams:6706711. **LOAD** `common/ascii-diagram-standards.md`6722. **VALIDATE** each diagram:673 - Count characters per line (all lines MUST be same width)674 - Use ONLY: `+` `-` `|` `^` `v` `<` `>` and spaces675 - NO Unicode box-drawing characters676 - Spaces only (NO tabs)6773. **TEST** alignment by verifying box corners align vertically678679**See `common/ascii-diagram-standards.md` for patterns and validation checklist.**680681## Mermaid Diagram Validation682683### Required Validation Steps6841. **Syntax Check**: Validate Mermaid syntax before file creation6852. **Character Escaping**: Ensure special characters are properly escaped6863. **Fallback Content**: Provide text alternative if Mermaid fails validation687688### Mermaid Validation Rules689```markdown690## BEFORE creating any file with Mermaid diagrams:6916921. Check for invalid characters in node IDs (use alphanumeric + underscore only)6932. Escape special characters in labels: " → \" and ' → \'6943. Validate flowchart syntax: node connections must be valid6954. Test diagram parsing with simple validation696697## FALLBACK: If Mermaid validation fails, use text-based workflow representation698```699700### Implementation Pattern701```markdown702## Workflow Visualization703704### Mermaid Diagram (if syntax valid)705```mermaid706[validated diagram content]707```708709### Text Alternative (always include)710```711Phase 1: INCEPTION712- Stage 1: Workspace Detection (COMPLETED)713- Stage 2: Requirements Analysis (COMPLETED)714[continue with text representation]715```716717## General Content Validation718719### Pre-Creation Validation Checklist720- [ ] Validate embedded code blocks (Mermaid, JSON, YAML)721- [ ] Check special character escaping722- [ ] Verify markdown syntax correctness723- [ ] Test content parsing compatibility724- [ ] Include fallback content for complex elements725726### Error Prevention Rules7271. **Always validate before using tools/commands to write files**: Never write unvalidated content7282. **Escape special characters**: Particularly in diagrams and code blocks7293. **Provide alternatives**: Include text versions of visual content7304. **Test syntax**: Validate complex content structures731732## Validation Failure Handling733734### When Validation Fails7351. **Log the error**: Record what failed validation7362. **Use fallback content**: Switch to text-based alternative7373. **Continue workflow**: Don't block on content validation failures7384. **Inform user**: Mention simplified content was used due to parsing constraints739<!-- forgecat:@forgecat/awslabs_aidlc-workflows:content-validation:end -->740741<!-- forgecat:@forgecat/awslabs_aidlc-workflows:depth-levels:start -->742# Adaptive Depth743744**Purpose**: Explain how AI-DLC adapts detail level to problem complexity745746## Core Principle747748**When a stage executes, ALL its defined artifacts are created. The "depth" refers to the level of detail and rigor within those artifacts, which adapts to the problem's complexity.**749750## Stage Selection vs Detail Level751752### Stage Selection (Binary)753- **Workflow Planning** decides: EXECUTE or SKIP for each stage754- **If EXECUTE**: Stage runs and creates ALL its defined artifacts755- **If SKIP**: Stage doesn't run at all756757### Detail Level (Adaptive)758- **Simple problems**: Concise artifacts with essential detail759- **Complex problems**: Comprehensive artifacts with extensive detail760- **Model decides**: Based on problem characteristics, not prescriptive rules761762## Factors Influencing Detail Level763764The model considers these factors when determining appropriate detail:7657661. **Request Clarity**: How clear and complete is the user's request?7672. **Problem Complexity**: How intricate is the solution space?7683. **Scope**: Single file, component, multiple components, or system-wide?7694. **Risk Level**: What's the impact of errors or omissions?7705. **Available Context**: Greenfield vs brownfield, existing documentation7716. **User Preferences**: Has user expressed preference for brevity or detail?772773## Example: Requirements Analysis Artifacts774775**All scenarios create the same artifacts**:776- `requirement-verification-questions.md` (if needed)777- `requirements.md`778779**Note**: User's initial request is captured in `audit.md` (no separate user-intent.md needed)780781**Detail level varies by complexity**:782783### Simple Scenario (Bug Fix)784- **requirement-verification-questions.md**: necessary clarifying questions785- **requirements.md**: Concise functional requirement, minimal sections786787### Complex Scenario (System Migration)788- **requirement-verification-questions.md**: Multiple rounds, 10+ questions789- **requirements.md**: Comprehensive functional + non-functional requirements, traceability, acceptance criteria790791## Example: Application Design Artifacts792793**All scenarios create the same artifacts**:794- `application-design.md`795- `component-diagram.md`796797**Detail level varies by complexity**:798799### Simple Scenario (Single Component)800- **application-design.md**: Basic component description, key methods801- **component-diagram.md**: Simple diagram with essential relationships802803### Complex Scenario (Multi-Component System)804- **application-design.md**: Detailed component responsibilities, all methods with signatures, design patterns, alternatives considered805- **component-diagram.md**: Comprehensive diagram with all relationships, data flows, integration points806807## Guiding Principle for Model808809**"Create exactly the detail needed for the problem at hand - no more, no less."**810811- Don't artificially inflate simple problems with unnecessary detail812- Don't shortchange complex problems by omitting critical detail813- Let problem characteristics drive detail level naturally814- All required artifacts are always created when stage executes815<!-- forgecat:@forgecat/awslabs_aidlc-workflows:depth-levels:end -->816817<!-- forgecat:@forgecat/awslabs_aidlc-workflows:error-handling:start -->818# Error Handling and Recovery Procedures819820## General Error Handling Principles821822### When Errors Occur8231. **Identify the error**: Clearly state what went wrong8242. **Assess impact**: Determine if the error is blocking or can be worked around8253. **Communicate**: Inform the user about the error and options8264. **Offer solutions**: Provide clear steps to resolve or work around the error8275. **Document**: Log the error and resolution in `audit.md`828829### Error Severity Levels830831**Critical**: Workflow cannot continue832- Missing required files or artifacts833- Invalid user input that cannot be processed834- System errors preventing file operations835836**High**: Stage cannot complete as planned837- Incomplete answers to required questions838- Contradictory user responses839- Missing dependencies from prior stages840841**Medium**: Stage can continue with workarounds842- Optional artifacts missing843- Non-critical validation failures844- Partial completion possible845846**Low**: Minor issues that don't block progress847- Formatting inconsistencies848- Optional information missing849- Non-blocking warnings850851## Stage-Specific Error Handling852853### Workspace Detection Errors854855**Error**: Cannot read workspace files856- **Cause**: Permission issues, missing directories857- **Solution**: Ask user to verify workspace path and permissions858- **Workaround**: Proceed with user-provided information only859860**Error**: Existing `aidlc-state.md` is corrupted861- **Cause**: Manual editing, incomplete previous run862- **Solution**: Ask user if they want to start fresh or attempt recovery863- **Recovery**: Create backup, start new state file864865**Error**: Cannot determine required stages866- **Cause**: Insufficient information from user867- **Solution**: Ask clarifying questions about intent and scope868- **Workaround**: Default to comprehensive execution plan869870### Requirements Analysis Errors871872**Error**: User provides contradictory requirements873- **Cause**: Unclear understanding, changing needs874- **Solution**: Create follow-up questions to resolve contradictions875- **Do Not Proceed**: Until contradictions are resolved876877**Error**: Requirements document cannot be converted878- **Cause**: Unsupported format, corrupted file879- **Solution**: Ask user to provide requirements in supported format880- **Workaround**: Work with user's verbal description881882**Error**: Incomplete answers to verification questions883- **Cause**: User skipped questions, unclear what to answer884- **Solution**: Highlight unanswered questions, provide examples885- **Do Not Proceed**: Until all required questions are answered886887### User Stories Errors888889**Error**: Cannot map requirements to stories890- **Cause**: Requirements too vague, missing functional details891- **Solution**: Return to Requirements Analysis for clarification892- **Workaround**: Create stories based on available information, mark as incomplete893894**Error**: User provides ambiguous story planning answers895- **Cause**: Unclear options, complex decision896- **Solution**: Add follow-up questions with specific examples897- **Do Not Proceed**: Until ambiguities are resolved898899**Error**: Story generation plan has uncompleted steps900- **Cause**: Execution interrupted, steps skipped901- **Solution**: Resume from first uncompleted step902- **Recovery**: Review completed steps, continue from checkpoint903904### Application Design Errors905906**Error**: Architectural decision is unclear or contradictory907- **Cause**: Ambiguous answers, conflicting requirements908- **Solution**: Add follow-up questions to clarify decision909- **Do Not Proceed**: Until decision is clear and documented910911**Error**: Cannot determine number of services/units912- **Cause**: Insufficient information about boundaries913- **Solution**: Ask specific questions about deployment, team structure, scaling914- **Workaround**: Default to monolith, allow change later915916### Design Errors917918**Error**: Unit dependencies are circular919- **Cause**: Poor boundary definition, tight coupling920- **Solution**: Identify circular dependencies, suggest refactoring921- **Recovery**: Revise unit boundaries to break cycles922923**Error**: Unit design plan has missing steps924- **Cause**: Plan generation incomplete, template error925- **Solution**: Regenerate plan with all required steps926- **Recovery**: Add missing steps to existing plan927928**Error**: Cannot generate design artifacts929- **Cause**: Missing unit information, unclear requirements930- **Solution**: Return to Units Planning to clarify unit definition931- **Workaround**: Generate partial design, mark gaps932933### NFR Implementation Errors934935**Error**: Technology stack choices are incompatible936- **Cause**: Conflicting requirements, platform limitations937- **Solution**: Highlight incompatibilities, ask user to choose938- **Do Not Proceed**: Until compatible choices are made939940**Error**: Organizational constraints cannot be met941- **Cause**: Network restrictions, security policies942- **Solution**: Document constraints, ask user for workarounds943- **Escalation**: May require human intervention for setup944945**Error**: NFR implementation step requires human action946- **Cause**: AI cannot perform certain tasks (network config, credentials)947- **Solution**: Clearly mark as **HUMAN TASK**, provide instructions948- **Wait**: For user confirmation before proceeding949950### Code Generation Planning Errors951952**Error**: Code generation plan is incomplete953- **Cause**: Missing design artifacts, unclear requirements954- **Solution**: Return to Design stage to complete artifacts955- **Recovery**: Generate plan with available information, mark gaps956957**Error**: Unit dependencies not satisfied958- **Cause**: Dependent units not yet generated959- **Solution**: Reorder generation sequence to respect dependencies960- **Workaround**: Generate with stub dependencies, integrate later961962### Code Generation Errors (Part 2: Code Generation)963964**Error**: Cannot generate code for a step965- **Cause**: Insufficient design information, unclear requirements966- **Solution**: Skip step, document as incomplete, continue967- **Recovery**: Return to step after gathering more information968969**Error**: Generated code has syntax errors970- **Cause**: Template issues, language-specific problems971- **Solution**: Fix syntax errors, regenerate if needed972- **Validation**: Verify code compiles before proceeding973974**Error**: Test generation fails975- **Cause**: Complex logic, missing test framework setup976- **Solution**: Generate basic test structure, mark for manual completion977- **Workaround**: Proceed without tests, add in Operations phase978979### Operations Errors980981**Error**: Cannot determine build tool982- **Cause**: Unusual project structure, multiple build systems983- **Solution**: Ask user to specify build tool and commands984- **Workaround**: Provide generic instructions, user adapts985986**Error**: Deployment target is unclear987- **Cause**: Multiple environments, complex infrastructure988- **Solution**: Ask user to specify deployment targets and methods989- **Workaround**: Provide instructions for common platforms990991## Recovery Procedures992993### Partial Stage Completion994995**Scenario**: Stage was interrupted mid-execution996997**Recovery Steps**:9981. Load the stage plan file9992. Identify last completed step (last [x] checkbox)10003. Resume from next uncompleted step10014. Verify all prior steps are actually complete10025. Continue execution normally10031004### Corrupted State File10051006**Scenario**: `aidlc-state.md` is corrupted or inconsistent10071008**Recovery Steps**:10091. Create backup: `aidlc-state.md.backup`10102. Ask user which stage they're actually on10113. Regenerate state file from scratch10124. Mark completed stages based on existing artifacts10135. Resume from current stage10141015### Missing Artifacts10161017**Scenario**: Required artifacts from prior stage are missing10181019**Recovery Steps**:10201. Identify which artifacts are missing10212. Determine if they can be regenerated10223. If yes: Return to that stage, regenerate artifacts10234. If no: Ask user to provide information manually10245. Document the gap in `audit.md`10251026### User Wants to Restart Stage10271028**Scenario**: User is unhappy with stage results and wants to redo10291030**Recovery Steps**:10311. Confirm user wants to restart (data will be lost)10322. Archive existing artifacts: `{artifact}.backup`10333. Reset stage status in `aidlc-state.md`10344. Clear stage checkboxes in plan files10355. Re-execute stage from beginning10361037### User Wants to Skip Stage10381039**Scenario**: User wants to skip a stage that was planned10401041**Recovery Steps**:10421. Confirm user understands implications10432. Document skip reason in `audit.md`10443. Mark stage as "SKIPPED" in `aidlc-state.md`10454. Proceed to next stage10465. Note: May cause issues in later stages if dependencies missing10471048## Escalation Guidelines10491050### When to Ask for User Help10511052**Immediately**:1053- Contradictory or ambiguous user input1054- Missing required information1055- Technical constraints AI cannot resolve1056- Decisions requiring business judgment10571058**After Attempting Resolution**:1059- Repeated errors in same step1060- Complex technical issues1061- Unusual project structures1062- Integration with external systems10631064### When to Suggest Starting Over10651066**Consider Fresh Start If**:1067- Multiple stages have errors1068- State file is severely corrupted1069- User requirements have changed significantly1070- Architectural decision needs to be reversed1071- User cannot provide missing information1072- Artifacts are inconsistent across phases10731074**Before Starting Over**:10751. Archive all existing work10762. Document lessons learned10773. Identify what to preserve10784. Get user confirmation10795. Create new execution plan10801081## Session Resumption Errors10821083### Missing Artifacts During Resumption10841085**Error**: Required artifacts from previous stages are missing1086- **Cause**: Files deleted, moved, or never created1087- **Solution**:1088 1. Identify which stage created the missing artifacts1089 2. Check if stage was marked complete in aidlc-state.md1090 3. If marked complete but artifacts missing: Regenerate that stage1091 4. If not marked complete: Resume from that stage1092- **Recovery**: Return to the stage that creates missing artifacts and re-execute10931094**Error**: Artifact file exists but is empty or corrupted1095- **Cause**: Interrupted write, manual editing, file system issues1096- **Solution**:1097 1. Create backup of corrupted file1098 2. Attempt to regenerate from stage that creates it1099 3. If cannot regenerate: Ask user for information to recreate1100- **Recovery**: Re-execute the stage that creates the artifact11011102### Inconsistent State During Resumption11031104**Error**: aidlc-state.md shows stage complete but artifacts don't exist1105- **Cause**: State file updated but artifact generation failed1106- **Solution**:1107 1. Mark stage as incomplete in aidlc-state.md1108 2. Re-execute the stage to generate artifacts1109 3. Verify artifacts exist before marking complete1110- **Recovery**: Reset stage status and re-execute11111112**Error**: Artifacts exist but aidlc-state.md shows stage incomplete1113- **Cause**: Artifact generation succeeded but state update failed1114- **Solution**:1115 1. Verify artifacts are complete and valid1116 2. Update aidlc-state.md to mark stage complete1117 3. Proceed to next stage1118- **Recovery**: Update state file to reflect actual completion11191120**Error**: Multiple stages marked as "current" in aidlc-state.md1121- **Cause**: State file corruption, manual editing1122- **Solution**:1123 1. Review artifacts to determine actual progress1124 2. Ask user which stage they're actually on1125 3. Correct aidlc-state.md to show single current stage1126- **Recovery**: Rebuild state file based on existing artifacts11271128### Context Loading Errors11291130**Error**: Cannot load required context from previous stages1131- **Cause**: Missing files, corrupted content, wrong file paths1132- **Solution**:1133 1. List which artifacts are needed for current stage1134 2. Check which ones are missing or corrupted1135 3. Regenerate missing artifacts or ask user for information1136- **Recovery**: Complete prerequisite stages before resuming current stage11371138**Error**: Loaded artifacts contain contradictory information1139- **Cause**: Manual editing, multiple people working, incomplete updates1140- **Solution**:1141 1. Identify contradictions and present to user1142 2. Ask user which information is correct1143 3. Update artifacts to resolve contradictions1144- **Recovery**: Reconcile contradictions before proceeding11451146### Resumption Best Practices114711481. **Always validate state**: Check aidlc-state.md matches actual artifacts11492. **Load incrementally**: Load artifacts stage-by-stage, validate each11503. **Fail fast**: Stop immediately if critical artifacts are missing11514. **Communicate clearly**: Tell user exactly what's missing and why it's needed11525. **Offer options**: Regenerate, provide manually, or start fresh11536. **Document recovery**: Log all recovery actions in audit.md11541155## Logging Requirements11561157### Error Logging Format11581159```markdown1160## Error - [Stage Name]1161**Timestamp**: [ISO timestamp]1162**Error Type**: [Critical/High/Medium/Low]1163**Description**: [What went wrong]1164**Cause**: [Why it happened]1165**Resolution**: [How it was resolved]1166**Impact**: [Effect on workflow]11671168---1169```11701171### Recovery Logging Format11721173```markdown1174## Recovery - [Stage Name]1175**Timestamp**: [ISO timestamp]1176**Issue**: [What needed recovery]1177**Recovery Steps**: [What was done]1178**Outcome**: [Result of recovery]1179**Artifacts Affected**: [List of files]11801181---1182```11831184## Prevention Best Practices118511861. **Validate Early**: Check inputs and dependencies before starting work11872. **Checkpoint Often**: Update checkboxes immediately after completing steps11883. **Communicate Clearly**: Explain what you're doing and why11894. **Ask Questions**: Don't assume - clarify ambiguities immediately11905. **Document Everything**: Log all decisions and changes in `audit.md`1191<!-- forgecat:@forgecat/awslabs_aidlc-workflows:error-handling:end -->11921193<!-- forgecat:@forgecat/awslabs_aidlc-workflows:overconfidence-prevention:start -->1194# Overconfidence Prevention Guide11951196## Problem Statement11971198AI-DLC was exhibiting overconfidence by not asking enough clarifying questions, even for complex project intent statements. This led to assumptions being made instead of gathering proper requirements.11991200## Root Cause Analysis12011202The overconfidence issue was caused by directives in multiple stages that encouraged skipping questions:120312041. **Functional Design**: "Skip entire categories if not applicable"12052. **User Stories**: "Use categories as inspiration, NOT as mandatory checklist"12063. **Requirements Analysis**: Similar patterns encouraging minimal questioning12074. **NFR Requirements**: "Only if" conditions that discouraged thorough analysis12081209These directives were telling the AI to avoid asking questions rather than encouraging comprehensive requirements gathering.12101211## Solution Implemented12121213### Updated Question Generation Philosophy12141215**OLD APPROACH**: "Only ask questions if absolutely necessary"1216**NEW APPROACH**: "When in doubt, ask the question - overconfidence leads to poor outcomes"12171218### Key Changes Made12191220#### 1. Requirements Analysis Stage1221- Changed from "only if needed" to "ALWAYS create questions unless exceptionally clear"1222- Added comprehensive evaluation areas (functional, non-functional, business context, technical context)1223- Emphasized proactive questioning approach12241225#### 2. User Stories Stage1226- Removed "skip entire categories" directive1227- Added comprehensive question categories to evaluate1228- Enhanced answer analysis requirements1229- Strengthened follow-up question mandates12301231#### 3. Functional Design Stage1232- Replaced "only if" conditions with comprehensive evaluation1233- Added more question categories (data flow, integration points, error handling)1234- Strengthened ambiguity detection and resolution requirements12351236#### 4. NFR Requirements Stage1237- Expanded question categories beyond basic NFRs1238- Added reliability, maintainability, and usability considerations1239- Enhanced answer analysis for technical ambiguities12401241### New Guiding Principles124212431. **Default to Asking**: When there's any ambiguity, ask clarifying questions12442. **Comprehensive Coverage**: Evaluate ALL relevant categories, don't skip areas12453. **Thorough Analysis**: Carefully analyze ALL user responses for ambiguities12464. **Mandatory Follow-up**: Create follow-up questions for ANY unclear responses12475. **No Proceeding with Ambiguity**: Don't move forward until ALL ambiguities are resolved12481249## Implementation Guidelines12501251### For Question Generation1252- Evaluate ALL question categories, don't skip any1253- Ask questions wherever clarification would improve quality1254- Include comprehensive question categories in each stage1255- Default to inclusion rather than exclusion of questions12561257### For Answer Analysis1258- Look for vague responses: "depends", "maybe", "not sure", "mix of", "somewhere between"1259- Detect undefined terms and references to external concepts1260- Identify contradictory or incomplete answers1261- Create follow-up questions for ANY ambiguities12621263### For Follow-up Questions1264- Create separate clarification files when ambiguities are detected1265- Ask specific questions to resolve each ambiguity1266- Don't proceed until ALL unclear responses are clarified1267- Be thorough - better to over-clarify than under-clarify12681269## Quality Assurance12701271### Red Flags to Watch For1272- Stages completing without asking any questions on complex projects1273- Proceeding with vague or ambiguous user responses1274- Skipping entire question categories without justification1275- Making assumptions instead of asking for clarification12761277### Success Indicators1278- Appropriate number of clarifying questions for project complexity1279- Thorough analysis of user responses with follow-up when needed1280- Clear, unambiguous requirements before proceeding to implementation1281- Reduced need for changes during later stages due to better upfront clarification12821283## Maintenance12841285This guide should be referenced when:1286- Adding new stages to AI-DLC1287- Updating existing stage instructions1288- Reviewing AI-DLC performance for overconfidence issues1289- Training team members on AI-DLC question generation principles12901291## Key Takeaway12921293**It's better to ask too many questions than to make incorrect assumptions.** The cost of asking clarifying questions upfront is far less than the cost of implementing the wrong solution based on assumptions.1294<!-- forgecat:@forgecat/awslabs_aidlc-workflows:overconfidence-prevention:end -->12951296<!-- forgecat:@forgecat/awslabs_aidlc-workflows:process-overview:start -->1297# AI-DLC Adaptive Workflow Overview12981299**Purpose**: Technical reference for AI model and developers to understand complete workflow structure.13001301**Note**: Similar content exists in welcome-message.md (user welcome message) and README.md (documentation). This duplication is INTENTIONAL - each file serves a different purpose:1302- **This file**: Detailed technical reference with Mermaid diagram for AI model context loading1303- **welcome-message.md**: User-facing welcome message with ASCII diagram1304- **README.md**: Human-readable documentation for repository13051306## The Three-Phase Lifecycle:1307• **INCEPTION PHASE**: Planning and architecture (Workspace Detection + conditional phases + Workflow Planning)1308• **CONSTRUCTION PHASE**: Design, implementation, build and test (per-unit design + Code Generation + Build & Test)1309• **OPERATIONS PHASE**: Placeholder for future deployment and monitoring workflows13101311## The Adaptive Workflow:1312• **Workspace Detection** (always) → **Reverse Engineering** (brownfield only) → **Requirements Analysis** (always, adaptive depth) → **Conditional Phases** (as needed) → **Workflow Planning** (always) → **Code Generation** (always, per-unit) → **Build and Test** (always)13131314## How It Works:1315• **AI analyzes** your request, workspace, and complexity to determine which stages are needed1316• **These stages always execute**: Workspace Detection, Requirements Analysis (adaptive depth), Workflow Planning, Code Generation (per-unit), Build and Test1317• **All other stages are conditional**: Reverse Engineering, User Stories, Application Design, Units Generation, per-unit design stages (Functional Design, NFR Requirements, NFR Design, Infrastructure Design)1318• **No fixed sequences**: Stages execute in the order that makes sense for your specific task13191320## Your Team's Role:1321• **Answer questions** in dedicated question files using [Answer]: tags with letter choices (A, B, C, D, E)1322• **Option E available**: Choose "Other" and describe your custom response if provided options don't match1323• **Work as a team** to review and approve each phase before proceeding1324• **Collectively decide** on architectural approach when needed1325• **Important**: This is a team effort - involve relevant stakeholders for each phase13261327## AI-DLC Three-Phase Workflow:13281329```mermaid1330flowchart TD1331 Start(["User Request"])13321333 subgraph INCEPTION["🔵 INCEPTION PHASE"]1334 WD["Workspace Detection<br/><b>ALWAYS</b>"]1335 RE["Reverse Engineering<br/><b>CONDITIONAL</b>"]1336 RA["Requirements Analysis<br/><b>ALWAYS</b>"]1337 Stories["User Stories<br/><b>CONDITIONAL</b>"]1338 WP["Workflow Planning<br/><b>ALWAYS</b>"]1339 AppDesign["Application Design<br/><b>CONDITIONAL</b>"]1340 UnitsG["Units Generation<br/><b>CONDITIONAL</b>"]1341 end13421343 subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]1344 FD["Functional Design<br/><b>CONDITIONAL</b>"]1345 NFRA["NFR Requirements<br/><b>CONDITIONAL</b>"]1346 NFRD["NFR Design<br/><b>CONDITIONAL</b>"]1347 ID["Infrastructure Design<br/><b>CONDITIONAL</b>"]1348 CG["Code Generation<br/><b>ALWAYS</b>"]1349 BT["Build and Test<br/><b>ALWAYS</b>"]1350 end13511352 subgraph OPERATIONS["🟡 OPERATIONS PHASE"]1353 OPS["Operations<br/><b>PLACEHOLDER</b>"]1354 end13551356 Start --> WD1357 WD -.-> RE1358 WD --> RA1359 RE --> RA13601361 RA -.-> Stories1362 RA --> WP1363 Stories --> WP13641365 WP -.-> AppDesign1366 WP -.-> UnitsG1367 AppDesign -.-> UnitsG1368 UnitsG --> FD1369 FD -.-> NFRA1370 NFRA -.-> NFRD1371 NFRD -.-> ID13721373 WP --> CG1374 FD --> CG1375 NFRA --> CG1376 NFRD --> CG1377 ID --> CG1378 CG -.->|Next Unit| FD1379 CG --> BT1380 BT -.-> OPS1381 BT --> End(["Complete"])13821383 style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff1384 style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff1385 style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff13861387 style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff1388 style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff1389 style OPS fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#0001390 style RE fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#0001391 style Stories fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#0001392 style AppDesign fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#00013931394 style UnitsG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#0001395 style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#0001396 style NFRA fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#0001397 style NFRD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#0001398 style ID fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#0001399 style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px, color:#0001400 style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px, color:#0001401 style OPERATIONS fill:#FFF59D,stroke:#F57F17,stroke-width:3px, color:#0001402 style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#0001403 style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#00014041405 linkStyle default stroke:#333,stroke-width:2px1406```14071408**Stage Descriptions:**14091410**🔵 INCEPTION PHASE** - Planning and Architecture1411- Workspace Detection: Analyze workspace state and project type (ALWAYS)1412- Reverse Engineering: Analyze existing codebase (CONDITIONAL - Brownfield only)1413- Requirements Analysis: Gather and validate requirements (ALWAYS - Adaptive depth)1414- User Stories: Create user stories and personas (CONDITIONAL)1415- Workflow Planning: Create execution plan (ALWAYS)1416- Application Design: High-level component identification and service layer design (CONDITIONAL)1417- Units Generation: Decompose into units of work (CONDITIONAL)14181419**🟢 CONSTRUCTION PHASE** - Design, Implementation, Build and Test1420- Functional Design: Detailed business logic design per unit (CONDITIONAL, per-unit)1421- NFR Requirements: Determine NFRs and select tech stack (CONDITIONAL, per-unit)1422- NFR Design: Incorporate NFR patterns and logical components (CONDITIONAL, per-unit)1423- Infrastructure Design: Map to actual infrastructure services (CONDITIONAL, per-unit)1424- Code Generation: Generate code with Part 1 - Planning, Part 2 - Generation (ALWAYS, per-unit)1425- Build and Test: Build all units and execute comprehensive testing (ALWAYS)14261427**🟡 OPERATIONS PHASE** - Placeholder1428- Operations: Placeholder for future deployment and monitoring workflows (PLACEHOLDER)14291430**Key Principles:**1431- Phases execute only when they add value1432- Each phase independently evaluated1433- INCEPTION focuses on "what" and "why"1434- CONSTRUCTION focuses on "how" plus "build and test"1435- OPERATIONS is placeholder for future expansion1436- Simple changes may skip conditional INCEPTION stages1437- Complex changes get full INCEPTION and CONSTRUCTION treatment1438<!-- forgecat:@forgecat/awslabs_aidlc-workflows:process-overview:end -->14391440<!-- forgecat:@forgecat/awslabs_aidlc-workflows:question-format-guide:start -->1441# Question Format Guide14421443## MANDATORY: All Questions Must Use This Format14441445### Rule: Never Ask Questions in Chat1446**CRITICAL**: You must NEVER ask questions directly in the chat. ALL questions must be placed in dedicated question files.14471448### Question File Format14491450#### File Naming Convention1451- Use descriptive names: `{phase-name}-questions.md`1452- Examples:1453 - `classification-questions.md`1454 - `requirements-questions.md`1455 - `story-planning-questions.md`1456 - `design-questions.md`14571458#### Question Structure1459Every question must include meaningful options plus "Other" as the last option:14601461```markdown1462## Question [Number]1463[Clear, specific question text]14641465A) [First meaningful option]1466B) [Second meaningful option]1467[...additional options as needed...]1468X) Other (please describe after [Answer]: tag below)14691470[Answer]:1471```14721473**CRITICAL**:1474- "Other" is MANDATORY as the LAST option for every question1475- Only include meaningful options - don't make up options to fill slots1476- Use as many or as few options as make sense (minimum 2 + Other)14771478### Complete Example14791480```markdown1481# Requirements Clarification Questions14821483Please answer the following questions to help clarify the requirements.14841485## Question 11486What is the primary user authentication method?14871488A) Username and password1489B) Social media login (Google, Facebook)1490C) Single Sign-On (SSO)1491D) Multi-factor authentication1492E) Other (please describe after [Answer]: tag below)14931494[Answer]:14951496## Question 21497Will this be a web or mobile application?14981499A) Web application1500B) Mobile application1501C) Both web and mobile1502D) Other (please describe after [Answer]: tag below)15031504[Answer]:15051506## Question 31507Is this a new project or existing codebase?15081509A) New project (greenfield)1510B) Existing codebase (brownfield)1511C) Other (please describe after [Answer]: tag below)15121513[Answer]:1514```15151516### User Response Format1517Users will answer by filling in the letter choice after [Answer]: tag:15181519```markdown1520## Question 11521What is the primary user authentication method?15221523A) Username and password1524B) Social media login (Google, Facebook)1525C) Single Sign-On (SSO)1526D) Multi-factor authentication15271528[Answer]: C1529```15301531### Reading User Responses1532After user confirms completion:15331. Read the question file15342. Extract answers after [Answer]: tags15353. Validate all questions are answered15364. Proceed with analysis based on responses15371538### Multiple Choice Guidelines15391540#### Option Count1541- Minimum: 2 meaningful options + "Other" (A, B, C)1542- Typical: 3-4 meaningful options + "Other" (A, B, C, D, E)1543- Maximum: 5 meaningful options + "Other" (A, B, C, D, E, F)1544- **CRITICAL**: Don't make up options just to fill slots - only include meaningful choices15451546#### Option Quality1547- Make options mutually exclusive1548- Cover the most common scenarios1549- Only include meaningful, realistic options1550- **ALWAYS include "Other" as the LAST option** (MANDATORY)1551- Be specific and clear1552- **Don't make up options to fill A, B, C, D slots**15531554#### Good Example:1555```markdown1556## Question 51557What database technology will be used?15581559A) Relational (PostgreSQL, MySQL)1560B) NoSQL Document (MongoDB, DynamoDB)1561C) NoSQL Key-Value (Redis, Memcached)1562D) Graph Database (Neo4j, Neptune)1563E) Other (please describe after [Answer]: tag below)15641565[Answer]:1566```15671568#### Bad Example (Avoid):1569```markdown1570## Question 51571What database will you use?15721573A) Yes1574B) No1575C) Maybe15761577[Answer]:1578```15791580### Workflow Integration15811582#### Step 1: Create Question File1583```markdown1584Create aidlc-docs/{phase-name}-questions.md with all questions1585```15861587#### Step 2: Inform User1588```1589"I've created {phase-name}-questions.md with [X] questions.1590Please answer each question by filling in the letter choice after the [Answer]: tag.1591If none of the options match your needs, choose the last option (Other) and describe your preference. Let me know when you're done."1592```15931594#### Step 3: Wait for Confirmation1595Wait for user to say "done", "completed", "finished", or similar.15961597#### Step 4: Read and Analyze1598```1599Read aidlc-docs/{phase-name}-questions.md1600Extract all answers1601Validate completeness1602Proceed with analysis1603```16041605### Error Handling16061607#### Missing Answers1608If any [Answer]: tag is empty:1609```1610"I noticed Question [X] is not answered. Please provide an answer using one of the letter choices1611for all questions before proceeding."1612```16131614#### Invalid Answers1615If answer is not a valid letter choice:1616```1617"Question [X] has an invalid answer '[answer]'.1618Please use only the letter choices provided in the question."1619```16201621#### Ambiguous Answers1622If user provides explanation instead of letter:1623```1624"For Question [X], please provide the letter choice that best matches your answer.1625If none match, choose 'Other' and add your description after the [Answer]: tag."1626```16271628### Contradiction and Ambiguity Detection16291630**MANDATORY**: After reading user responses, you MUST check for contradictions and ambiguities.16311632#### Detecting Contradictions1633Look for logically inconsistent answers:1634- Scope mismatch: "Bug fix" but "Entire codebase affected"1635- Risk mismatch: "Low risk" but "Breaking changes"1636- Timeline mismatch: "Quick fix" but "Multiple subsystems"1637- Impact mismatch: "Single component" but "Significant architecture changes"16381639#### Detecting Ambiguities1640Look for unclear or borderline responses:1641- Answers that could fit multiple classifications1642- Responses that lack specificity1643- Conflicting indicators across multiple questions16441645#### Creating Clarification Questions1646If contradictions or ambiguities detected:164716481. **Create clarification file**: `{phase-name}-clarification-questions.md`16492. **Explain the issue**: Clearly state what contradiction/ambiguity was detected16503. **Ask targeted questions**: Use multiple choice format to resolve the issue16514. **Reference original questions**: Show which questions had conflicting answers16521653**Example**:1654```markdown1655# [Phase Name] Clarification Questions16561657I detected contradictions in your responses that need clarification:16581659## Contradiction 1: [Brief Description]1660You indicated "[Answer A]" (Q[X]:[Letter]) but also "[Answer B]" (Q[Y]:[Letter]).1661These responses are contradictory because [explanation].16621663### Clarification Question 11664[Specific question to resolve contradiction]16651666A) [Option that resolves toward first answer]1667B) [Option that resolves toward second answer]1668C) [Option that provides middle ground]1669D) [Option that reframes the question]16701671[Answer]:16721673## Ambiguity 1: [Brief Description]1674Your response to Q[X] ("[Answer]") is ambiguous because [explanation].16751676### Clarification Question 21677[Specific question to clarify ambiguity]16781679A) [Clear option 1]1680B) [Clear option 2]1681C) [Clear option 3]1682D) [Clear option 4]16831684[Answer]:1685```16861687#### Workflow for Clarifications168816891. **Detect**: Analyze all responses for contradictions/ambiguities16902. **Create**: Generate clarification question file if issues found16913. **Inform**: Tell user about the issues and clarification file16924. **Wait**: Do not proceed until user provides clarifications16935. **Re-validate**: After clarifications, check again for consistency16946. **Proceed**: Only move forward when all contradictions are resolved16951696#### Example User Message1697```1698"I detected 2 contradictions in your responses:169917001. Bug fix scope vs. codebase impact (Q1 vs Q2)17012. Low risk vs. breaking changes (Q7 vs Q4)17021703I've created classification-clarification-questions.md with 2 questions to resolve these.1704Please answer these clarifying questions before I can proceed with classification."1705```17061707### Best Practices170817091. **Be Specific**: Questions should be clear and unambiguous17102. **Be Comprehensive**: Cover all necessary information17113. **Be Concise**: Keep questions focused on one topic17124. **Be Practical**: Options should be realistic and actionable17135. **Be Consistent**: Use same format throughout all question files17141715### Phase-Specific Examples17161717#### Example with 2 meaningful options:1718```markdown1719## Question 11720Is this a new project or existing codebase?17211722A) New project (greenfield)1723B) Existing codebase (brownfield)1724C) Other (please describe after [Answer]: tag below)17251726[Answer]:1727```17281729#### Example with 3 meaningful options:1730```markdown1731## Question 21732What is the deployment target?17331734A) Cloud (AWS, Azure, GCP)1735B) On-premises servers1736C) Hybrid (both cloud and on-premises)1737D) Other (please describe after [Answer]: tag below)17381739[Answer]:1740```17411742#### Example with 4 meaningful options:1743```markdown1744## Question 31745What architectural pattern should be used?17461747A) Monolithic architecture1748B) Microservices architecture1749C) Serverless architecture1750D) Event-driven architecture1751E) Other (please describe after [Answer]: tag below)17521753[Answer]:1754```17551756## Summary17571758**Remember**:1759- ✅ Always create question files1760- ✅ Always use multiple choice format1761- ✅ **Always include "Other" as the LAST option (MANDATORY)**1762- ✅ Only include meaningful options - don't make up options to fill slots1763- ✅ Always use [Answer]: tags1764- ✅ Always wait for user completion1765- ✅ Always validate responses for contradictions1766- ✅ Always create clarification files if needed1767- ✅ Always resolve contradictions before proceeding1768- ❌ Never ask questions in chat1769- ❌ Never make up options just to have A, B, C, D1770- ❌ Never proceed without answers1771- ❌ Never proceed with unresolved contradictions1772- ❌ Never make assumptions about ambiguous responses1773<!-- forgecat:@forgecat/awslabs_aidlc-workflows:question-format-guide:end -->17741775<!-- forgecat:@forgecat/awslabs_aidlc-workflows:session-continuity:start -->1776# Session Continuity Templates17771778## Welcome Back Prompt Template1779When a user returns to continue work on an existing AI-DLC project, present this prompt:17801781```markdown1782**Welcome back! I can see you have an existing AI-DLC project in progress.**17831784Based on your aidlc-state.md, here's your current status:1785- **Project**: [project-name]1786- **Current Phase**: [INCEPTION/CONSTRUCTION/OPERATIONS]1787- **Current Stage**: [Stage Name]1788- **Last Completed**: [Last completed step]1789- **Next Step**: [Next step to work on]17901791**What would you like to work on today?**17921793A) Continue where you left off ([Next step description])1794B) Review a previous stage ([Show available stages])17951796[Answer]:1797```17981799## MANDATORY: Session Continuity Instructions18001. **Always read aidlc-state.md first** when detecting existing project18012. **Parse current status** from the workflow file to populate the prompt18023. **MANDATORY: Load Previous Stage Artifacts** - Before resuming any stage, automatically read all relevant artifacts from previous stages:1803 - **Reverse Engineering**: Read architecture.md, code-structure.md, api-documentation.md1804 - **Requirements Analysis**: Read requirements.md, requirement-verification-questions.md1805 - **User Stories**: Read stories.md, personas.md, story-generation-plan.md1806 - **Application Design**: Read application-design artifacts (components.md, component-methods.md, services.md)1807 - **Design (Units)**: Read unit-of-work.md, unit-of-work-dependency.md, unit-of-work-story-map.md1808 - **Per-Unit Design**: Read functional-design.md, nfr-requirements.md, nfr-design.md, infrastructure-design.md1809 - **Code Stages**: Read all code files, plans, AND all previous artifacts18104. **Smart Context Loading by Stage**:1811 - **Early Stages (Workspace Detection, Reverse Engineering)**: Load workspace analysis1812 - **Requirements/Stories**: Load reverse engineering + requirements artifacts1813 - **Design Stages**: Load requirements + stories + architecture + design artifacts1814 - **Code Stages**: Load ALL artifacts + existing code files18155. **Adapt options** based on architectural choice and current phase18166. **Show specific next steps** rather than generic descriptions18177. **Log the continuity prompt** in audit.md with timestamp18188. **Context Summary**: After loading artifacts, provide brief summary of what was loaded for user awareness18199. **Asking questions**: ALWAYS ask clarification or user feedback questions by placing them in .md files. DO NOT place the multiple-choice questions in-line in the chat session.18201821## Error Handling1822If artifacts are missing or corrupted during session resumption, see [error-handling.md](error-handling.md) for guidance on recovery procedures.1823<!-- forgecat:@forgecat/awslabs_aidlc-workflows:session-continuity:end -->18241825<!-- forgecat:@forgecat/awslabs_aidlc-workflows:terminology:start -->1826# AI-DLC Terminology Glossary18271828## Core Terminology18291830### Phase vs Stage18311832**Phase**: One of the three high-level lifecycle phases in AI-DLC1833- 🔵 **INCEPTION PHASE** - Planning & Architecture (WHAT and WHY)1834- 🟢 **CONSTRUCTION PHASE** - Design, Implementation & Test (HOW)1835- 🟡 **OPERATIONS PHASE** - Deployment & Monitoring (future expansion)18361837**Stage**: An individual workflow activity within a phase1838- Examples: Context Assessment stage, Requirements Assessment stage, Code Generation stage1839- Each stage has specific prerequisites, steps, and outputs1840- Stages can be ALWAYS-EXECUTE or CONDITIONAL18411842**Usage Examples**:1843- ✅ "The CONSTRUCTION phase contains 7 stages"1844- ✅ "The Code Generation stage is always executed"1845- ✅ "We're in the INCEPTION phase, executing the Requirements Assessment stage"1846- ❌ "The Requirements Assessment phase" (should be "stage")1847- ❌ "The CONSTRUCTION stage" (should be "phase")18481849## Three-Phase Lifecycle18501851### INCEPTION PHASE1852**Purpose**: Planning and architectural decisions1853**Focus**: Determine WHAT to build and WHY1854**Location**: `inception/` directory18551856**Stages**:1857- Workspace Detection (ALWAYS)1858- Reverse Engineering (CONDITIONAL - Brownfield only)1859- Requirements Analysis (ALWAYS - Adaptive depth)1860- User Stories (CONDITIONAL)1861- Workflow Planning (ALWAYS)1862- Application Design (CONDITIONAL)1863- Design - Units Planning/Generation (CONDITIONAL)18641865**Outputs**: Requirements, user stories, architectural decisions, unit definitions18661867### CONSTRUCTION PHASE1868**Purpose**: Detailed design and implementation1869**Focus**: Determine HOW to build it1870**Location**: `construction/` directory18711872**Stages**:1873- Functional Design (CONDITIONAL, per-unit)1874- NFR Requirements (CONDITIONAL, per-unit)1875- NFR Design (CONDITIONAL, per-unit)1876- Infrastructure Design (CONDITIONAL, per-unit)1877- Code Generation (ALWAYS) — includes Part 1: Planning and Part 2: Generation1878- Build and Test (ALWAYS)18791880**Outputs**: Design artifacts, NFR implementations, code, tests18811882### OPERATIONS PHASE1883**Purpose**: Deployment and operational readiness1884**Focus**: How to DEPLOY and RUN it1885**Location**: `operations/` directory18861887**Stages**:1888- Operations (PLACEHOLDER)18891890**Outputs**: Build instructions, deployment guides, monitoring setup, verification procedures18911892---18931894## Workflow Stages18951896### Always-Execute Stages1897- **Workspace Detection**: Initial analysis of workspace state and project type1898- **Requirements Analysis**: Gathering requirements (depth varies based on complexity)1899- **Workflow Planning**: Creating execution plan for which phases to run1900- **Code Generation**: Single stage with two parts — Part 1 (Planning) creates detailed implementation plans, Part 2 (Generation) generates actual code based on plans and prior artifacts1901- **Build and Test**: Building all units and executing comprehensive testing19021903### Conditional Stages1904- **Reverse Engineering**: Analyzing existing codebase (brownfield projects only)1905- **User Stories**: Creating user stories and personas (includes Story Planning and Story Generation)1906- **Application Design**: Designing application components, methods, business rules, and services1907- **Design**: Designing system components (includes Units Planning, Units Generation, per-unit design)1908- **Functional Design**: Technology-agnostic business logic design (per-unit)1909- **NFR Requirements**: Determining NFRs and selecting tech stack (per-unit)1910- **NFR Design**: Incorporating NFR patterns and logical components (per-unit)1911- **Infrastructure Design**: Mapping to actual infrastructure services (per-unit)19121913## Application Design Terms19141915- **Component**: A functional unit with specific responsibilities1916- **Method**: A function or operation within a component with defined business rules1917- **Business Rule**: Logic that governs method behavior and validation1918- **Service**: Orchestration layer that coordinates business logic across components1919- **Component Dependency**: Relationship and communication pattern between components19201921## Architecture Terms (Infrastructure)19221923### Unit of Work1924A logical grouping of user stories for development purposes. The term used during planning and decomposition.19251926**Usage**: "We need to decompose the system into units of work"19271928### Service1929An independently deployable component in a microservices architecture. Each service is a separate unit of work.19301931**Usage**: "The Payment Service handles all payment processing"19321933### Module1934A logical grouping of functionality within a single service or monolith. Modules are not independently deployable.19351936**Usage**: "The authentication module within the User Service"19371938### Component1939A reusable building block within a service or module. Components are classes, functions, or packages that provide specific functionality.19401941**Usage**: "The EmailValidator component validates email addresses"19421943## Terminology Guidelines19441945### When to Use Each Term19461947**Unit of Work**:1948- During Units Planning and Units Generation stages1949- When discussing system decomposition1950- In planning documents and discussions1951- Example: "How should we decompose this into units of work?"19521953**Service**:1954- When referring to independently deployable components1955- In microservices architecture contexts1956- In deployment and infrastructure discussions1957- Example: "The Order Service will be deployed to ECS"19581959**Module**:1960- When referring to logical groupings within a service1961- In monolith architecture contexts1962- When discussing internal organization1963- Example: "The reporting module generates all reports"19641965**Component**:1966- When referring to specific classes, functions, or packages1967- In design and implementation discussions1968- When discussing reusable building blocks1969- Example: "The DatabaseConnection component manages connections"19701971## Stage Terminology19721973### Planning vs Generation1974- **Planning**: Creating a plan with questions and checkboxes for execution1975- **Generation**: Executing the plan to create artifacts19761977Examples:1978- Story Planning → Story Generation1979- Units Planning → Units Generation1980- Unit Design Planning → Unit Design Generation1981- NFR Planning → NFR Generation1982- Code Generation Part 1 (Planning) → Code Generation Part 2 (Generation)19831984### Depth Levels1985- **Minimal**: Quick, focused execution for simple changes1986- **Standard**: Normal depth with standard artifacts for typical projects1987- **Comprehensive**: Full depth with all artifacts for complex/high-risk projects19881989## Artifact Types19901991### Plans1992Documents with checkboxes and questions that guide execution.1993- Located in `aidlc-docs/plans/`1994- Examples: `story-generation-plan.md`, `unit-of-work-plan.md`19951996### Artifacts1997Generated outputs from executing plans.1998- Located in various `aidlc-docs/` subdirectories1999- Examples: `requirements.md`, `stories.md`, `design.md`20002001### State Files2002Files tracking workflow progress and status.2003- `aidlc-state.md`: Overall workflow state2004- `audit.md`: Complete audit trail of all interactions20052006## Common Abbreviations20072008- **AI-DLC**: AI-Driven Development Life Cycle2009- **NFR**: Non-Functional Requirements2010- **UOW**: Unit of Work2011- **API**: Application Programming Interface2012- **CDK**: Cloud Development Kit (AWS)2013<!-- forgecat:@forgecat/awslabs_aidlc-workflows:terminology:end -->20142015<!-- forgecat:@forgecat/awslabs_aidlc-workflows:welcome-message:start -->2016# AI-DLC Welcome Message20172018**Purpose**: This file contains the user-facing welcome message that should be displayed ONCE at the start of any AI-DLC workflow.20192020---20212022# 👋 Welcome to AI-DLC (AI-Driven Development Life Cycle)! 👋20232024I'll guide you through an adaptive software development workflow that intelligently tailors itself to your specific needs.20252026## What is AI-DLC?20272028AI-DLC is a structured yet flexible software development process that adapts to your project's needs. Think of it as having an experienced software architect who:20292030- **Analyzes your requirements** and asks clarifying questions when needed2031- **Plans the optimal approach** based on complexity and risk2032- **Skips unnecessary steps** for simple changes while providing comprehensive coverage for complex projects2033- **Documents everything** so you have a complete record of decisions and rationale2034- **Guides you through each phase** with clear checkpoints and approval gates20352036## The Three-Phase Lifecycle20372038```2039 User Request2040 |2041 v2042 +---------------------------------------+2043 | INCEPTION PHASE |2044 | Planning & Application Design |2045 +---------------------------------------+2046 | * Workspace Detection (ALWAYS) |2047 | * Reverse Engineering (COND) |2048 | * Requirements Analysis (ALWAYS) |2049 | * User Stories (CONDITIONAL) |2050 | * Workflow Planning (ALWAYS) |2051 | * Application Design (CONDITIONAL) |2052 | * Units Generation (CONDITIONAL) |2053 +---------------------------------------+2054 |2055 v2056 +---------------------------------------+2057 | CONSTRUCTION PHASE |2058 | Design, Implementation & Test |2059 +---------------------------------------+2060 | * Per-Unit Loop (for each unit): |2061 | - Functional Design (COND) |2062 | - NFR Requirements Assess (COND) |2063 | - NFR Design (COND) |2064 | - Infrastructure Design (COND) |2065 | - Code Generation (ALWAYS) |2066 | * Build and Test (ALWAYS) |2067 +---------------------------------------+2068 |2069 v2070 +---------------------------------------+2071 | OPERATIONS PHASE |2072 | Placeholder for Future |2073 +---------------------------------------+2074 | * Operations (PLACEHOLDER) |2075 +---------------------------------------+2076 |2077 v2078 Complete2079```20802081### Phase Breakdown:20822083**INCEPTION PHASE** - *Planning & Application Design*2084- **Purpose**: Determines WHAT to build and WHY2085- **Activities**: Understanding requirements, analyzing existing code (if any), planning the approach2086- **Output**: Clear requirements, execution plan, decisions on the number of units of work for parallel development2087- **Your Role**: Answer questions, review plans, approve direction20882089**CONSTRUCTION PHASE** - *Detailed Design, Implementation & Test*2090- **Purpose**: Determines HOW to build it2091- **Activities**: Detailed design (when needed), code generation, comprehensive testing2092- **Output**: Working code, tests, build instructions2093- **Your Role**: Review designs, approve implementation plans, validate results20942095**OPERATIONS PHASE** - *Deployment & Monitoring (Future)*2096- **Purpose**: How to DEPLOY and RUN it2097- **Status**: Placeholder for future deployment and monitoring workflows2098- **Current State**: Build and test activities handled in CONSTRUCTION phase20992100## Key Principles:21012102- ⚡ **Fully Adaptive**: Each stage independently evaluated based on your needs2103- 🎯 **Efficient**: Simple changes execute only essential stages2104- 📋 **Comprehensive**: Complex changes get full treatment with all safeguards2105- 🔍 **Transparent**: You see and approve the execution plan before work begins2106- 📝 **Documented**: Complete audit trail of all decisions and changes2107- 🎛️ **User Control**: You can request stages be included or excluded21082109## What Happens Next:211021111. **I'll analyze your workspace** to understand if this is a new or existing project21122. **I'll gather requirements** and ask clarifying questions if needed21133. **I'll create an execution plan** showing which stages I propose to run and why21144. **You'll review and approve** the plan (or request changes)21155. **We'll execute the plan** with checkpoints at each major stage21166. **You'll get working code** with complete documentation and tests21172118The AI-DLC process adapts to:2119- 📋 Your intent clarity and complexity2120- 🔍 Existing codebase state2121- 🎯 Scope and impact of changes2122- ⚡ Risk and quality requirements21232124Let's begin!2125<!-- forgecat:@forgecat/awslabs_aidlc-workflows:welcome-message:end -->21262127<!-- forgecat:@forgecat/awslabs_aidlc-workflows:workflow-changes:start -->2128# Mid-Workflow Changes and Stage Management21292130## Overview21312132Users may request changes to the execution plan or stage execution during the workflow. This document provides guidance on handling these requests safely and effectively.21332134---21352136## Types of Mid-Workflow Changes21372138### 1. Adding a Skipped Stage21392140**Scenario**: User wants to add a stage that was originally skipped21412142**Example**: "Actually, I want to add user stories even though we skipped that stage"21432144**Handling**:21451. **Confirm Request**: "You want to add User Stories stage. This will create user stories and personas. Confirm?"21462. **Check Dependencies**: Verify all prerequisite stages are complete21473. **Update Execution Plan**: Add stage to `execution-plan.md` with rationale21484. **Update State**: Mark stage as "PENDING" in `aidlc-state.md`21495. **Execute Stage**: Follow normal stage execution process21506. **Log Change**: Document in `audit.md` with timestamp and reason21512152**Considerations**:2153- May need to update later stages that could benefit from new artifacts2154- Existing artifacts may need revision to incorporate new information2155- Timeline will be extended21562157---21582159### 2. Skipping a Planned Stage21602161**Scenario**: User wants to skip a stage that was planned to execute21622163**Example**: "Let's skip the NFR Design stage for now"21642165**Handling**:21661. **Confirm Request**: "You want to skip NFR Design. This means no NFR patterns or logical components will be incorporated. Confirm?"21672. **Warn About Impact**: Explain what will be missing and potential consequences21683. **Get Explicit Confirmation**: User must explicitly confirm understanding of impact21694. **Update Execution Plan**: Mark stage as "SKIPPED" with reason21705. **Update State**: Mark stage as "SKIPPED" in `aidlc-state.md`21716. **Adjust Later Stages**: Note that later stages may need manual setup21727. **Log Change**: Document in `audit.md` with timestamp and reason21732174**Considerations**:2175- Later stages may fail or require manual intervention2176- User accepts responsibility for missing artifacts2177- Can be added back later if needed21782179---21802181### 3. Restarting Current Stage21822183**Scenario**: User is unhappy with current stage results and wants to redo it21842185**Example**: "I don't like these user stories. Can we start over?"21862187**Handling**:21881. **Understand Concern**: "What specifically would you like to change about the stories?"21892. **Offer Options**:2190 - **Option A**: Modify existing artifacts (faster, preserves some work)2191 - **Option B**: Complete restart (clean slate, more time)21923. **If Restart Chosen**:2193 - Archive existing artifacts: `{artifact}.backup.{timestamp}`2194 - Reset stage checkboxes in plan file2195 - Mark stage as "IN PROGRESS" in `aidlc-state.md`2196 - Clear stage completion status2197 - Re-execute from beginning21984. **Log Change**: Document reason for restart and what will change21992200**Considerations**:2201- Existing work will be lost (but backed up)2202- May need to redo dependent stages2203- Timeline will be extended22042205---22062207### 4. Restarting Previous Stage22082209**Scenario**: User wants to go back and redo a completed stage22102211**Example**: "I want to change the architectural decision we made earlier"22122213**Handling**:22141. **Assess Impact**: Identify all stages that depend on the stage to be restarted22152. **Warn User**: "Restarting Application Design will require redoing: Units Planning, Units Generation, per-unit design (all units), Code Generation. Confirm?"22163. **Get Explicit Confirmation**: User must understand full impact22174. **If Confirmed**:2218 - Archive all affected artifacts2219 - Reset all affected stages in `aidlc-state.md`2220 - Clear checkboxes in all affected plan files2221 - Return to the stage to restart2222 - Re-execute from that point forward22235. **Log Change**: Document full impact and reason for restart22242225**Considerations**:2226- Significant rework required2227- All dependent stages must be redone2228- Timeline will be significantly extended2229- Consider if modification is better than restart22302231---22322233### 5. Changing Stage Depth22342235**Scenario**: User wants to change the depth level of current or upcoming stage22362237**Example**: "Let's do a comprehensive requirements analysis instead of standard"22382239**Handling**:22401. **Confirm Request**: "You want to change Requirements Analysis from Standard to Comprehensive depth. This will be more thorough but take longer. Confirm?"22412. **Update Execution Plan**: Change depth level in `workflow-planning.md`22423. **Adjust Approach**: Follow comprehensive depth guidelines for the stage22434. **Update Estimates**: Inform user of new timeline estimate22445. **Log Change**: Document depth change and reason22452246**Considerations**:2247- More depth = more time but better quality2248- Less depth = faster but may miss details2249- Can only change before or during stage, not after completion22502251---22522253### 6. Pausing Workflow22542255**Scenario**: User needs to pause and resume later22562257**Example**: "I need to stop for now and continue tomorrow"22582259**Handling**:22601. **Complete Current Step**: Finish the current step in progress if possible22612. **Update Checkboxes**: Mark all completed steps with [x]22623. **Update State**: Ensure `aidlc-state.md` reflects current status22634. **Log Pause**: Document pause point in `audit.md`22645. **Provide Resume Instructions**: "When you return, I'll detect your existing project and offer to continue from: [current stage, current step]"22652266**On Resume**:22671. **Detect Existing Project**: Check for `aidlc-state.md`22682. **Load Context**: Read all artifacts from completed stages22693. **Show Status**: Display current stage and next step22704. **Offer Options**: Continue where left off or review previous work22715. **Log Resume**: Document resume point in `audit.md`22722273---22742275### 7. Changing Architectural Decision22762277**Scenario**: User wants to change from monolith to microservices (or vice versa)22782279**Example**: "Actually, let's do microservices instead of a monolith"22802281**Handling**:22821. **Assess Current Progress**: Determine how far into workflow22832. **Explain Impact**:2284 - If before Units Planning: Minimal impact, just update decision2285 - If after Units Planning: Must redo Units Planning, Units Generation, all per-unit design2286 - If after Code Generation: Significant rework required22873. **Recommend Approach**:2288 - Early in workflow: Restart from Application Design stage2289 - Late in workflow: Consider if modification is feasible vs. restart22904. **Get Confirmation**: User must understand full scope of change22915. **Execute Change**: Follow restart procedures for affected stages22922293**Considerations**:2294- Architectural changes have cascading effects2295- Earlier in workflow = easier to change2296- Later in workflow = consider cost vs. benefit22972298---22992300### 8. Adding/Removing Units23012302**Scenario**: User wants to add or remove units after Units Generation23032304**Example**: "We need to split the Payment unit into Payment and Billing"23052306**Handling**:23071. **Assess Impact**: Determine which units have completed design/code23082. **Explain Consequences**:2309 - Adding unit: Need to do full design and code for new unit2310 - Removing unit: Need to redistribute functionality to other units2311 - Splitting unit: Need to redo design and code for both resulting units23123. **Update Unit Artifacts**:2313 - Modify `unit-of-work.md`2314 - Update `unit-of-work-dependency.md`2315 - Revise `unit-of-work-story-map.md`23164. **Reset Affected Units**: Mark affected units as needing redesign23175. **Execute Changes**: Follow normal unit design and code process for affected units23182319**Considerations**:2320- Affects all downstream stages for those units2321- May affect other units if dependencies change2322- Timeline impact depends on how many units affected23232324---23252326## General Guidelines for Handling Changes23272328### Before Making Changes232923301. **Understand the Request**: Ask clarifying questions about what user wants to change and why23312. **Assess Impact**: Identify all affected stages, artifacts, and dependencies23323. **Explain Consequences**: Clearly communicate what will need to be redone and timeline impact23334. **Offer Alternatives**: Sometimes modification is better than restart23345. **Get Explicit Confirmation**: User must understand and accept the impact23352336### During Changes233723381. **Archive Existing Work**: Always backup before making destructive changes23392. **Update All Tracking**: Keep `aidlc-state.md`, plan files, and `audit.md` in sync23403. **Communicate Progress**: Keep user informed about what's happening23414. **Validate Changes**: Ensure changes are consistent across all artifacts23425. **Test Continuity**: Verify workflow can continue smoothly after changes23432344### After Changes234523461. **Verify Consistency**: Check that all artifacts are aligned with changes23472. **Update Documentation**: Ensure all references are updated23483. **Log Completely**: Document full change history in `audit.md`23494. **Confirm with User**: Verify changes meet user's expectations23505. **Resume Workflow**: Continue with normal execution from new state23512352---23532354## Change Request Decision Tree23552356```2357User requests change2358 |2359 ├─ Is it current stage?2360 | ├─ Yes: Can modify or restart current stage2361 | └─ No: Go to next question2362 |2363 ├─ Is it a completed stage?2364 | ├─ Yes: Assess impact on dependent stages2365 | | ├─ Low impact: Modify and update dependents2366 | | └─ High impact: Recommend restart from that stage2367 | └─ No: Go to next question2368 |2369 ├─ Is it adding a skipped stage?2370 | ├─ Yes: Check prerequisites, add to plan, execute2371 | └─ No: Go to next question2372 |2373 ├─ Is it skipping a planned stage?2374 | ├─ Yes: Warn about impact, get confirmation, skip2375 | └─ No: Go to next question2376 |2377 └─ Is it changing depth level?2378 ├─ Yes: Update plan, adjust approach2379 └─ No: Clarify request with user2380```23812382---23832384## Logging Requirements23852386### Change Request Log Format23872388```markdown2389## Change Request - [Stage Name]2390**Timestamp**: [ISO timestamp]2391**Request**: [What user wants to change]2392**Current State**: [Where we are in workflow]2393**Impact Assessment**: [What will be affected]2394**User Confirmation**: [User's explicit confirmation]2395**Action Taken**: [What was done]2396**Artifacts Affected**: [List of files changed/reset]23972398---2399```24002401---24022403## Best Practices240424051. **Always Confirm**: Never make destructive changes without explicit user confirmation24062. **Explain Impact**: Users need to understand consequences before deciding24073. **Offer Options**: Sometimes there are multiple ways to handle a change24084. **Archive First**: Always backup before making destructive changes24095. **Update Everything**: Keep all tracking files in sync24106. **Log Thoroughly**: Document all changes for audit trail24117. **Validate After**: Ensure workflow can continue smoothly24128. **Be Flexible**: Workflow should adapt to user needs, not force rigid process2413<!-- forgecat:@forgecat/awslabs_aidlc-workflows:workflow-changes:end -->24142415<!-- forgecat:@forgecat/awslabs_aidlc-workflows:build-and-test:start -->2416# Build and Test24172418**Purpose**: Build all units and execute comprehensive testing strategy24192420## Prerequisites2421- Code Generation must be complete for all units2422- All code artifacts must be generated2423- Project is ready for build and testing24242425---24262427## Step 1: Analyze Testing Requirements24282429Analyze the project to determine appropriate testing strategy:2430- **Unit tests**: Already generated per unit during code generation2431- **Integration tests**: Test interactions between units/services2432- **Performance tests**: Load, stress, and scalability testing2433- **End-to-end tests**: Complete user workflows2434- **Contract tests**: API contract validation between services2435- **Security tests**: Vulnerability scanning, penetration testing24362437---24382439## Step 2: Generate Build Instructions24402441Create `aidlc-docs/construction/build-and-test/build-instructions.md`:24422443```markdown2444# Build Instructions24452446## Prerequisites2447- **Build Tool**: [Tool name and version]2448- **Dependencies**: [List all required dependencies]2449- **Environment Variables**: [List required env vars]2450- **System Requirements**: [OS, memory, disk space]24512452## Build Steps24532454### 1. Install Dependencies2455\`\\`bash2456[Command to install dependencies]2457# Example: npm install, mvn dependency:resolve, pip install -r requirements.txt2458\`\\`24592460### 2. Configure Environment2461\`\\`bash2462[Commands to set up environment]2463# Example: export variables, configure credentials2464\`\\`24652466### 3. Build All Units2467\`\\`bash2468[Command to build all units]2469# Example: mvn clean install, npm run build, brazil-build2470\`\\`24712472### 4. Verify Build Success2473- **Expected Output**: [Describe successful build output]2474- **Build Artifacts**: [List generated artifacts and locations]2475- **Common Warnings**: [Note any acceptable warnings]24762477## Troubleshooting24782479### Build Fails with Dependency Errors2480- **Cause**: [Common causes]2481- **Solution**: [Step-by-step fix]24822483### Build Fails with Compilation Errors2484- **Cause**: [Common causes]2485- **Solution**: [Step-by-step fix]2486```24872488---24892490## Step 3: Generate Unit Test Execution Instructions24912492Create `aidlc-docs/construction/build-and-test/unit-test-instructions.md`:24932494```markdown2495# Unit Test Execution24962497## Run Unit Tests24982499### 1. Execute All Unit Tests2500\`\\`bash2501[Command to run all unit tests]2502# Example: mvn test, npm test, pytest tests/unit2503\`\\`25042505### 2. Review Test Results2506- **Expected**: [X] tests pass, 0 failures2507- **Test Coverage**: [Expected coverage percentage]2508- **Test Report Location**: [Path to test reports]25092510### 3. Fix Failing Tests2511If tests fail:25121. Review test output in [location]25132. Identify failing test cases25143. Fix code issues25154. Rerun tests until all pass2516```25172518---25192520## Step 4: Generate Integration Test Instructions25212522Create `aidlc-docs/construction/build-and-test/integration-test-instructions.md`:25232524```markdown2525# Integration Test Instructions25262527## Purpose2528Test interactions between units/services to ensure they work together correctly.25292530## Test Scenarios25312532### Scenario 1: [Unit A] → [Unit B] Integration2533- **Description**: [What is being tested]2534- **Setup**: [Required test environment setup]2535- **Test Steps**: [Step-by-step test execution]2536- **Expected Results**: [What should happen]2537- **Cleanup**: [How to clean up after test]25382539### Scenario 2: [Unit B] → [Unit C] Integration2540[Similar structure]25412542## Setup Integration Test Environment25432544### 1. Start Required Services2545\`\\`bash2546[Commands to start services]2547# Example: docker-compose up, start test database2548\`\\`25492550### 2. Configure Service Endpoints2551\`\\`bash2552[Commands to configure endpoints]2553# Example: export API_URL=http://localhost:80802554\`\\`25552556## Run Integration Tests25572558### 1. Execute Integration Test Suite2559\`\\`bash2560[Command to run integration tests]2561# Example: mvn integration-test, npm run test:integration2562\`\\`25632564### 2. Verify Service Interactions2565- **Test Scenarios**: [List key integration test scenarios]2566- **Expected Results**: [Describe expected outcomes]2567- **Logs Location**: [Where to check logs]25682569### 3. Cleanup2570\`\\`bash2571[Commands to clean up test environment]2572# Example: docker-compose down, stop test services2573\`\\`2574```25752576---25772578## Step 5: Generate Performance Test Instructions (If Applicable)25792580Create `aidlc-docs/construction/build-and-test/performance-test-instructions.md`:25812582```markdown2583# Performance Test Instructions25842585## Purpose2586Validate system performance under load to ensure it meets requirements.25872588## Performance Requirements2589- **Response Time**: < [X]ms for [Y]% of requests2590- **Throughput**: [X] requests/second2591- **Concurrent Users**: Support [X] concurrent users2592- **Error Rate**: < [X]%25932594## Setup Performance Test Environment25952596### 1. Prepare Test Environment2597\`\\`bash2598[Commands to set up performance testing]2599# Example: scale services, configure load balancers2600\`\\`26012602### 2. Configure Test Parameters2603- **Test Duration**: [X] minutes2604- **Ramp-up Time**: [X] seconds2605- **Virtual Users**: [X] users26062607## Run Performance Tests26082609### 1. Execute Load Tests2610\`\\`bash2611[Command to run load tests]2612# Example: jmeter -n -t test.jmx, k6 run script.js2613\`\\`26142615### 2. Execute Stress Tests2616\`\\`bash2617[Command to run stress tests]2618# Example: gradually increase load until failure2619\`\\`26202621### 3. Analyze Performance Results2622- **Response Time**: [Actual vs Expected]2623- **Throughput**: [Actual vs Expected]2624- **Error Rate**: [Actual vs Expected]2625- **Bottlenecks**: [Identified bottlenecks]2626- **Results Location**: [Path to performance reports]26272628## Performance Optimization26292630If performance doesn't meet requirements:26311. Identify bottlenecks from test results26322. Optimize code/queries/configurations26333. Rerun tests to validate improvements2634```26352636---26372638## Step 6: Generate Additional Test Instructions (As Needed)26392640Based on project requirements, generate additional test instruction files:26412642### Contract Tests (For Microservices)2643Create `aidlc-docs/construction/build-and-test/contract-test-instructions.md`:2644- API contract validation between services2645- Consumer-driven contract testing2646- Schema validation26472648### Security Tests2649Create `aidlc-docs/construction/build-and-test/security-test-instructions.md`:2650- Vulnerability scanning2651- Dependency security checks2652- Authentication/authorization testing2653- Input validation testing26542655### End-to-End Tests2656Create `aidlc-docs/construction/build-and-test/e2e-test-instructions.md`:2657- Complete user workflow testing2658- Cross-service scenarios2659- UI testing (if applicable)26602661---26622663## Step 7: Generate Test Summary26642665Create `aidlc-docs/construction/build-and-test/build-and-test-summary.md`:26662667```markdown2668# Build and Test Summary26692670## Build Status2671- **Build Tool**: [Tool name]2672- **Build Status**: [Success/Failed]2673- **Build Artifacts**: [List artifacts]2674- **Build Time**: [Duration]26752676## Test Execution Summary26772678### Unit Tests2679- **Total Tests**: [X]2680- **Passed**: [X]2681- **Failed**: [X]2682- **Coverage**: [X]%2683- **Status**: [Pass/Fail]26842685### Integration Tests2686- **Test Scenarios**: [X]2687- **Passed**: [X]2688- **Failed**: [X]2689- **Status**: [Pass/Fail]26902691### Performance Tests2692- **Response Time**: [Actual] (Target: [Expected])2693- **Throughput**: [Actual] (Target: [Expected])2694- **Error Rate**: [Actual] (Target: [Expected])2695- **Status**: [Pass/Fail]26962697### Additional Tests2698- **Contract Tests**: [Pass/Fail/N/A]2699- **Security Tests**: [Pass/Fail/N/A]2700- **E2E Tests**: [Pass/Fail/N/A]27012702## Overall Status2703- **Build**: [Success/Failed]2704- **All Tests**: [Pass/Fail]2705- **Ready for Operations**: [Yes/No]27062707## Next Steps2708[If all pass]: Ready to proceed to Operations phase for deployment planning2709[If failures]: Address failing tests and rebuild2710```27112712---27132714## Step 8: Update State Tracking27152716Update `aidlc-docs/aidlc-state.md`:2717- Mark Build and Test stage as complete2718- Update current status27192720---27212722## Step 9: Present Results to User27232724Present completion message in this structure:2725 1. **Completion Announcement** (mandatory): Always start with this:27262727```markdown2728# 🔨 Build and Test Complete2729```27302731 2. **AI Summary** (optional): Provide structured bullet-point summary of build and test results2732 - Format: "Build and test has completed with the following results:"2733 - List build status and artifacts2734 - List test results by category (unit, integration, performance, etc.)2735 - List generated instruction files2736 - DO NOT include workflow instructions ("please review", "let me know", "proceed to next phase", "before we proceed")2737 - Keep factual and content-focused2738 3. **Formatted Workflow Message** (mandatory): Always end with this exact format:27392740```markdown2741> **📋 <u>**REVIEW REQUIRED:**</u>**2742> Please examine the build and test summary at: `aidlc-docs/construction/build-and-test/build-and-test-summary.md`2743274427452746> **🚀 <u>**WHAT'S NEXT?**</u>**2747>2748> **You may:**2749>2750> 🔧 **Request Changes** - Ask for modifications to the build and test instructions based on your review2751> ✅ **Approve & Continue** - Approve build and test results and proceed to **Operations**27522753---2754```27552756---27572758## Step 10: Log Interaction27592760**MANDATORY**: Log the stage completion in `aidlc-docs/audit.md`:27612762```markdown2763## Build and Test Stage2764**Timestamp**: [ISO timestamp]2765**Build Status**: [Success/Failed]2766**Test Status**: [Pass/Fail]2767**Files Generated**:2768- build-instructions.md2769- unit-test-instructions.md2770- integration-test-instructions.md2771- performance-test-instructions.md2772- build-and-test-summary.md27732774---2775```2776<!-- forgecat:@forgecat/awslabs_aidlc-workflows:build-and-test:end -->27772778<!-- forgecat:@forgecat/awslabs_aidlc-workflows:code-generation:start -->2779# Code Generation - Detailed Steps27802781## Overview2782This stage generates code for each unit of work through two integrated parts:2783- **Part 1 - Planning**: Create detailed code generation plan with explicit steps2784- **Part 2 - Generation**: Execute approved plan to generate code, tests, and artifacts27852786**Note**: For brownfield projects, "generate" means modify existing files when appropriate, not create duplicates.27872788## Prerequisites2789- Unit Design Generation must be complete for the unit2790- NFR Implementation (if executed) must be complete for the unit2791- All unit design artifacts must be available2792- Unit is ready for code generation27932794---27952796# PART 1: PLANNING27972798## Step 1: Analyze Unit Context2799- [ ] Read unit design artifacts from Unit Design Generation2800- [ ] Read unit story map to understand assigned stories2801- [ ] Identify unit dependencies and interfaces2802- [ ] Validate unit is ready for code generation28032804## Step 2: Create Detailed Unit Code Generation Plan2805- [ ] Read workspace root and project type from `aidlc-docs/aidlc-state.md`2806- [ ] Determine code location (see Critical Rules for structure patterns)2807- [ ] **Brownfield only**: Review reverse engineering code-structure.md for existing files to modify2808- [ ] Document exact paths (never aidlc-docs/)2809- [ ] Create explicit steps for unit generation:2810 - Project Structure Setup (greenfield only)2811 - Business Logic Generation2812 - Business Logic Unit Testing2813 - Business Logic Summary2814 - API Layer Generation2815 - API Layer Unit Testing2816 - API Layer Summary2817 - Repository Layer Generation2818 - Repository Layer Unit Testing2819 - Repository Layer Summary2820 - Frontend Components Generation (if applicable)2821 - Frontend Components Unit Testing (if applicable)2822 - Frontend Components Summary (if applicable)2823 - Database Migration Scripts (if data models exist)2824 - Documentation Generation (API docs, README updates)2825 - Deployment Artifacts Generation2826- [ ] Number each step sequentially2827- [ ] Include story mapping references2828- [ ] Add checkboxes [ ] for each step28292830## Step 3: Include Unit Generation Context2831- [ ] For this unit, include:2832 - Stories implemented by this unit2833 - Dependencies on other units/services2834 - Expected interfaces and contracts2835 - Database entities owned by this unit2836 - Service boundaries and responsibilities28372838## Step 4: Create Unit Plan Document2839- [ ] Save complete plan as `aidlc-docs/construction/plans/{unit-name}-code-generation-plan.md`2840- [ ] Include step numbering (Step 1, Step 2, etc.)2841- [ ] Include unit context and dependencies2842- [ ] Include story traceability2843- [ ] Ensure plan is executable step-by-step2844- [ ] Emphasize that this plan is the single source of truth for Code Generation28452846## Step 5: Summarize Unit Plan2847- [ ] Provide summary of the unit code generation plan to the user2848- [ ] Highlight unit generation approach2849- [ ] Explain step sequence and story coverage2850- [ ] Note total number of steps and estimated scope28512852## Step 6: Log Approval Prompt2853- [ ] Before asking for approval, log the prompt with timestamp in `aidlc-docs/audit.md`2854- [ ] Include reference to the complete unit code generation plan2855- [ ] Use ISO 8601 timestamp format28562857## Step 7: Wait for Explicit Approval2858- [ ] Do not proceed until the user explicitly approves the unit code generation plan2859- [ ] Approval must cover the entire plan and generation sequence2860- [ ] If user requests changes, update the plan and repeat approval process28612862## Step 8: Record Approval Response2863- [ ] Log the user's approval response with timestamp in `aidlc-docs/audit.md`2864- [ ] Include the exact user response text2865- [ ] Mark the approval status clearly28662867## Step 9: Update Progress2868- [ ] Mark Code Generation Part 1 (Planning) complete in `aidlc-state.md`2869- [ ] Update the "Current Status" section2870- [ ] Prepare for transition to Code Generation28712872---28732874# PART 2: GENERATION28752876## Step 10: Load Unit Code Generation Plan2877- [ ] Read the complete plan from `aidlc-docs/construction/plans/{unit-name}-code-generation-plan.md`2878- [ ] Identify the next uncompleted step (first [ ] checkbox)2879- [ ] Load the context for that step (unit, dependencies, stories)28802881## Step 11: Execute Current Step2882- [ ] Verify target directory from plan (never aidlc-docs/)2883- [ ] **Brownfield only**: Check if target file exists2884- [ ] Generate exactly what the current step describes:2885 - **If file exists**: Modify it in-place (never create `ClassName_modified.java`, `ClassName_new.java`, etc.)2886 - **If file doesn't exist**: Create new file2887- [ ] Write to correct locations:2888 - **Application Code**: Workspace root per project structure2889 - **Documentation**: `aidlc-docs/construction/{unit-name}/code/` (markdown only)2890 - **Build/Config Files**: Workspace root2891- [ ] Follow unit story requirements2892- [ ] Respect dependencies and interfaces28932894## Step 12: Update Progress2895- [ ] Mark the completed step as [x] in the unit code generation plan2896- [ ] Mark associated unit stories as [x] when their generation is finished2897- [ ] Update `aidlc-docs/aidlc-state.md` current status2898- [ ] **Brownfield only**: Verify no duplicate files created (e.g., no `ClassName_modified.java` alongside `ClassName.java`)2899- [ ] Save all generated artifacts29002901## Step 13: Continue or Complete Generation2902- [ ] If more steps remain, return to Step 102903- [ ] If all steps complete, proceed to present completion message29042905## Step 14: Present Completion Message2906- Present completion message in this structure:2907 1. **Completion Announcement** (mandatory): Always start with this:29082909```markdown2910# 💻 Code Generation Complete - [unit-name]2911```29122913 2. **AI Summary** (optional): Provide structured bullet-point summary2914 - **Brownfield**: Distinguish modified vs created files (e.g., "• Modified: `src/services/user-service.ts`", "• Created: `src/services/auth-service.ts`")2915 - **Greenfield**: List created files with paths (e.g., "• Created: `src/services/user-service.ts`")2916 - List tests, documentation, deployment artifacts with paths2917 - Keep factual, no workflow instructions2918 3. **Formatted Workflow Message** (mandatory): Always end with this exact format:29192920```markdown2921> **📋 <u>**REVIEW REQUIRED:**</u>**2922> Please examine the generated code at:2923> - **Application Code**: `[actual-workspace-path]`2924> - **Documentation**: `aidlc-docs/construction/[unit-name]/code/`2925292629272928> **🚀 <u>**WHAT'S NEXT?**</u>**2929>2930> **You may:**2931>2932> 🔧 **Request Changes** - Ask for modifications to the generated code based on your review2933> ✅ **Continue to Next Stage** - Approve code generation and proceed to **[next-unit/Build & Test]**29342935---2936```29372938## Step 15: Wait for Explicit Approval2939- Do not proceed until the user explicitly approves the generated code2940- Approval must be clear and unambiguous2941- If user requests changes, update the code and repeat the approval process29422943## Step 16: Record Approval and Update Progress2944- Log approval in audit.md with timestamp2945- Record the user's approval response with timestamp2946- Mark Code Generation stage as complete for this unit in aidlc-state.md29472948---29492950## Critical Rules29512952### Code Location Rules2953- **Application code**: Workspace root only (NEVER aidlc-docs/)2954- **Documentation**: aidlc-docs/ only (markdown summaries)2955- **Read workspace root** from aidlc-state.md before generating code29562957**Structure patterns by project type**:2958- **Brownfield**: Use existing structure (e.g., `src/main/java/`, `lib/`, `pkg/`)2959- **Greenfield single unit**: `src/`, `tests/`, `config/` in workspace root2960- **Greenfield multi-unit (microservices)**: `{unit-name}/src/`, `{unit-name}/tests/`2961- **Greenfield multi-unit (monolith)**: `src/{unit-name}/`, `tests/{unit-name}/`29622963### Brownfield File Modification Rules2964- Check if file exists before generating2965- If exists: Modify in-place (never create copies like `ClassName_modified.java`)2966- If doesn't exist: Create new file2967- Verify no duplicate files after generation (Step 12)29682969### Planning Phase Rules2970- Create explicit, numbered steps for all generation activities2971- Include story traceability in the plan2972- Document unit context and dependencies2973- Get explicit user approval before generation29742975### Generation Phase Rules2976- **NO HARDCODED LOGIC**: Only execute what's written in the unit plan2977- **FOLLOW PLAN EXACTLY**: Do not deviate from the step sequence2978- **UPDATE CHECKBOXES**: Mark [x] immediately after completing each step2979- **STORY TRACEABILITY**: Mark unit stories [x] when functionality is implemented2980- **RESPECT DEPENDENCIES**: Only implement when unit dependencies are satisfied29812982### Automation Friendly Code Rules2983When generating UI code (web, mobile, desktop), ensure elements are automation-friendly:2984- Add `data-testid` attributes to interactive elements (buttons, inputs, links, forms)2985- Use consistent naming: `{component}-{element-role}` (e.g., `login-form-submit-button`, `user-list-search-input`)2986- Avoid dynamic or auto-generated IDs that change between renders2987- Keep `data-testid` values stable across code changes (only change when element purpose changes)29882989## Completion Criteria2990- Complete unit code generation plan created and approved2991- All steps in unit code generation plan marked [x]2992- All unit stories implemented according to plan2993- All code and tests generated (tests will be executed in Build & Test phase)2994- Deployment artifacts generated2995- Complete unit ready for build and verification2996<!-- forgecat:@forgecat/awslabs_aidlc-workflows:code-generation:end -->29972998<!-- forgecat:@forgecat/awslabs_aidlc-workflows:functional-design:start -->2999# Functional Design30003001## Purpose3002**Detailed business logic design per unit**30033004Functional Design focuses on:3005- Detailed business logic and algorithms for the unit3006- Domain models with entities and relationships3007- Detailed business rules, validation logic, and constraints3008- Technology-agnostic design (no infrastructure concerns)30093010**Note**: This builds upon high-level component design from Application Design (INCEPTION phase)30113012## Prerequisites3013- Units Generation must be complete3014- Unit of work artifacts must be available3015- Application Design recommended (provides high-level component structure)3016- Execution plan must indicate Functional Design stage should execute30173018## Overview3019Design detailed business logic for the unit, technology-agnostic and focused purely on business functions.30203021## Steps to Execute30223023### Step 1: Analyze Unit Context3024- Read unit definition from `aidlc-docs/inception/application-design/unit-of-work.md`3025- Read assigned stories from `aidlc-docs/inception/application-design/unit-of-work-story-map.md`3026- Understand unit responsibilities and boundaries30273028### Step 2: Create Functional Design Plan3029- Generate plan with checkboxes [] for functional design3030- Focus on business logic, domain models, business rules3031- Each step should have a checkbox []30323033### Step 3: Generate Context-Appropriate Questions3034**DIRECTIVE**: Thoroughly analyze the unit definition and functional design artifacts to identify ALL areas where clarification would improve the functional design. Be proactive in asking questions to ensure comprehensive understanding.30353036**CRITICAL**: Default to asking questions when there is ANY ambiguity or missing detail that could affect functional design quality. It's better to ask too many questions than to make incorrect assumptions.30373038- EMBED questions using [Answer]: tag format3039- Focus on ANY ambiguities, missing information, or areas needing clarification3040- Generate questions wherever user input would improve functional design decisions3041- **When in doubt, ask the question** - overconfidence leads to poor designs30423043**Question categories to consider** (evaluate ALL categories):3044- **Business Logic Modeling** - Ask about core entities, workflows, data transformations, and business processes3045- **Domain Model** - Ask about domain concepts, entity relationships, data structures, and business objects3046- **Business Rules** - Ask about decision rules, validation logic, constraints, and business policies3047- **Data Flow** - Ask about data inputs, outputs, transformations, and persistence requirements3048- **Integration Points** - Ask about external system interactions, APIs, and data exchange3049- **Error Handling** - Ask about error scenarios, validation failures, and exception handling3050- **Business Scenarios** - Ask about edge cases, alternative flows, and complex business situations3051- **Frontend Components** (if applicable) - Ask about UI component structure, user interactions, state management, and form handling30523053### Step 4: Store Plan3054- Save as `aidlc-docs/construction/plans/{unit-name}-functional-design-plan.md`3055- Include all [Answer]: tags for user input30563057### Step 5: Collect and Analyze Answers3058- Wait for user to complete all [Answer]: tags3059- **MANDATORY**: Carefully review ALL responses for vague or ambiguous answers3060- **CRITICAL**: Add follow-up questions for ANY unclear responses - do not proceed with ambiguity3061- Look for responses like "depends", "maybe", "not sure", "mix of", "somewhere between"3062- Create clarification questions file if ANY ambiguities are detected3063- **Do not proceed until ALL ambiguities are resolved**30643065### Step 6: Generate Functional Design Artifacts3066- Create `aidlc-docs/construction/{unit-name}/functional-design/business-logic-model.md`3067- Create `aidlc-docs/construction/{unit-name}/functional-design/business-rules.md`3068- Create `aidlc-docs/construction/{unit-name}/functional-design/domain-entities.md`3069- If unit includes frontend/UI: Create `aidlc-docs/construction/{unit-name}/functional-design/frontend-components.md`3070 - Component hierarchy and structure3071 - Props and state definitions for each component3072 - User interaction flows3073 - Form validation rules3074 - API integration points (which backend endpoints each component uses)30753076### Step 7: Present Completion Message3077- Present completion message in this structure:3078 1. **Completion Announcement** (mandatory): Always start with this:30793080```markdown3081# 🔧 Functional Design Complete - [unit-name]3082```30833084 2. **AI Summary** (optional): Provide structured bullet-point summary of functional design3085 - Format: "Functional design has created [description]:"3086 - List key business logic models and entities (bullet points)3087 - List business rules and validation logic defined3088 - Mention domain model structure and relationships3089 - DO NOT include workflow instructions ("please review", "let me know", "proceed to next phase", "before we proceed")3090 - Keep factual and content-focused3091 3. **Formatted Workflow Message** (mandatory): Always end with this exact format:30923093```markdown3094> **📋 <u>**REVIEW REQUIRED:**</u>**3095> Please examine the functional design artifacts at: `aidlc-docs/construction/[unit-name]/functional-design/`3096309730983099> **🚀 <u>**WHAT'S NEXT?**</u>**3100>3101> **You may:**3102>3103> 🔧 **Request Changes** - Ask for modifications to the functional design based on your review3104> ✅ **Continue to Next Stage** - Approve functional design and proceed to **[next-stage-name]**31053106---3107```31083109### Step 8: Wait for Explicit Approval3110- Do not proceed until the user explicitly approves the functional design3111- Approval must be clear and unambiguous3112- If user requests changes, update the design and repeat the approval process31133114### Step 9: Record Approval and Update Progress3115- Log approval in audit.md with timestamp3116- Record the user's approval response with timestamp3117- Mark Functional Design stage complete in aidlc-state.md3118<!-- forgecat:@forgecat/awslabs_aidlc-workflows:functional-design:end -->31193120<!-- forgecat:@forgecat/awslabs_aidlc-workflows:infrastructure-design:start -->3121# Infrastructure Design31223123## Prerequisites3124- Functional Design must be complete for the unit3125- NFR Design recommended (provides logical components to map)3126- Execution plan must indicate Infrastructure Design stage should execute31273128## Overview3129Map logical software components to actual infrastructure choices for deployment environments.31303131## Steps to Execute31323133### Step 1: Analyze Design Artifacts3134- Read functional design from `aidlc-docs/construction/{unit-name}/functional-design/`3135- Read NFR design from `aidlc-docs/construction/{unit-name}/nfr-design/` (if exists)3136- Identify logical components needing infrastructure31373138### Step 2: Create Infrastructure Design Plan3139- Generate plan with checkboxes [] for infrastructure design3140- Focus on mapping to actual services (AWS, Azure, GCP, on-premise)3141- Each step should have a checkbox []31423143### Step 3: Generate Context-Appropriate Questions3144**DIRECTIVE**: Thoroughly analyze the functional and NFR design to identify ALL areas where clarification would improve infrastructure decisions. Be proactive in asking questions to ensure comprehensive infrastructure coverage.31453146**CRITICAL**: Default to asking questions when there is ANY ambiguity or missing detail that could affect infrastructure quality. It's better to ask too many questions than to make incorrect infrastructure assumptions.31473148**MANDATORY**: Evaluate ALL of the following categories by asking targeted questions about each. For each category, determine applicability based on evidence from the functional and NFR design artifacts -- do not skip categories without explicit justification:31493150- EMBED questions using [Answer]: tag format3151- Focus on ANY ambiguities, missing information, or areas needing clarification3152- Generate questions wherever user input would improve infrastructure decisions3153- **When in doubt, ask the question** - overconfidence leads to poor infrastructure choices31543155**Question categories to evaluate** (consider ALL categories):3156- **Deployment Environment** - Ask about cloud provider preferences, environment setup, and deployment targets3157- **Compute Infrastructure** - Ask about compute service choices, sizing, and scaling requirements3158- **Storage Infrastructure** - Ask about database selection, storage patterns, and data lifecycle needs3159- **Messaging Infrastructure** - Ask about messaging/queuing services, event-driven patterns, and async processing3160- **Networking Infrastructure** - Ask about load balancing, API gateway approach, and network topology3161- **Monitoring Infrastructure** - Ask about observability tooling, alerting strategy, and logging requirements3162- **Shared Infrastructure** - Ask about infrastructure sharing strategy, multi-tenancy, and resource isolation31633164### Step 4: Store Plan3165- Save as `aidlc-docs/construction/plans/{unit-name}-infrastructure-design-plan.md`3166- Include all [Answer]: tags for user input31673168### Step 5: Collect and Analyze Answers3169- Wait for user to complete all [Answer]: tags3170- Review for vague or ambiguous responses3171- Add follow-up questions if needed31723173### Step 6: Generate Infrastructure Design Artifacts3174- Create `aidlc-docs/construction/{unit-name}/infrastructure-design/infrastructure-design.md`3175- Create `aidlc-docs/construction/{unit-name}/infrastructure-design/deployment-architecture.md`3176- If shared infrastructure: Create `aidlc-docs/construction/shared-infrastructure.md`31773178### Step 7: Present Completion Message3179- Present completion message in this structure:3180 1. **Completion Announcement** (mandatory): Always start with this:31813182```markdown3183# 🏢 Infrastructure Design Complete - [unit-name]3184```31853186 2. **AI Summary** (optional): Provide structured bullet-point summary of infrastructure design3187 - Format: "Infrastructure design has mapped [description]:"3188 - List key infrastructure services and components (bullet points)3189 - List deployment architecture decisions and rationale3190 - Mention cloud provider choices and service mappings3191 - DO NOT include workflow instructions ("please review", "let me know", "proceed to next phase", "before we proceed")3192 - Keep factual and content-focused3193 3. **Formatted Workflow Message** (mandatory): Always end with this exact format:31943195```markdown3196> **📋 <u>**REVIEW REQUIRED:**</u>**3197> Please examine the infrastructure design at: `aidlc-docs/construction/[unit-name]/infrastructure-design/`3198319932003201> **🚀 <u>**WHAT'S NEXT?**</u>**3202>3203> **You may:**3204>3205> 🔧 **Request Changes** - Ask for modifications to the infrastructure design based on your review3206> ✅ **Continue to Next Stage** - Approve infrastructure design and proceed to **Code Generation**32073208---3209```32103211### Step 8: Wait for Explicit Approval3212- Do not proceed until the user explicitly approves the infrastructure design3213- Approval must be clear and unambiguous3214- If user requests changes, update the design and repeat the approval process32153216### Step 9: Record Approval and Update Progress3217- Log approval in audit.md with timestamp3218- Record the user's approval response with timestamp3219- Mark Infrastructure Design stage complete in aidlc-state.md3220<!-- forgecat:@forgecat/awslabs_aidlc-workflows:infrastructure-design:end -->32213222<!-- forgecat:@forgecat/awslabs_aidlc-workflows:nfr-design:start -->3223# NFR Design32243225## Prerequisites3226- NFR Requirements must be complete for the unit3227- NFR requirements artifacts must be available3228- Execution plan must indicate NFR Design stage should execute32293230## Overview3231Incorporate NFR requirements into unit design using patterns and logical components.32323233## Steps to Execute32343235### Step 1: Analyze NFR Requirements3236- Read NFR requirements from `aidlc-docs/construction/{unit-name}/nfr-requirements/`3237- Understand scalability, performance, availability, security needs32383239### Step 2: Create NFR Design Plan3240- Generate plan with checkboxes [] for NFR design3241- Focus on design patterns and logical components3242- Each step should have a checkbox []32433244### Step 3: Generate Context-Appropriate Questions3245**DIRECTIVE**: Thoroughly analyze the NFR requirements to identify ALL areas where clarification would improve NFR design quality. Be proactive in asking questions to ensure comprehensive non-functional design coverage.32463247**CRITICAL**: Default to asking questions when there is ANY ambiguity or missing detail that could affect NFR design quality. It's better to ask too many questions than to make incorrect assumptions about non-functional patterns.32483249**MANDATORY**: Evaluate ALL of the following categories by asking targeted questions about each. For each category, determine applicability based on evidence from the NFR requirements -- do not skip categories without explicit justification:32503251- EMBED questions using [Answer]: tag format3252- Focus on ANY ambiguities, missing information, or areas needing clarification3253- Generate questions wherever user input would improve pattern and component decisions3254- **When in doubt, ask the question** - overconfidence leads to poor non-functional designs32553256**Question categories to evaluate** (consider ALL categories):3257- **Resilience Patterns** - Ask about fault tolerance approach, retry strategies, and failure recovery expectations3258- **Scalability Patterns** - Ask about scaling mechanisms, load boundaries, and growth projections3259- **Performance Patterns** - Ask about optimization strategy, latency targets, and throughput requirements3260- **Security Patterns** - Ask about security implementation approach, threat model, and compliance constraints3261- **Logical Components** - Ask about infrastructure components (queues, caches, circuit breakers, etc.) and their integration patterns32623263### Step 4: Store Plan3264- Save as `aidlc-docs/construction/plans/{unit-name}-nfr-design-plan.md`3265- Include all [Answer]: tags for user input32663267### Step 5: Collect and Analyze Answers3268- Wait for user to complete all [Answer]: tags3269- Review for vague or ambiguous responses3270- Add follow-up questions if needed32713272### Step 6: Generate NFR Design Artifacts3273- Create `aidlc-docs/construction/{unit-name}/nfr-design/nfr-design-patterns.md`3274- Create `aidlc-docs/construction/{unit-name}/nfr-design/logical-components.md`32753276### Step 7: Present Completion Message3277- Present completion message in this structure:3278 1. **Completion Announcement** (mandatory): Always start with this:32793280```markdown3281# 🎨 NFR Design Complete - [unit-name]3282```32833284 2. **AI Summary** (optional): Provide structured bullet-point summary of NFR design3285 - Format: "NFR design has incorporated [description]:"3286 - List key design patterns implemented (bullet points)3287 - List logical components and infrastructure elements3288 - Mention resilience, scalability, and performance patterns applied3289 - DO NOT include workflow instructions ("please review", "let me know", "proceed to next phase", "before we proceed")3290 - Keep factual and content-focused3291 3. **Formatted Workflow Message** (mandatory): Always end with this exact format:32923293```markdown3294> **📋 <u>**REVIEW REQUIRED:**</u>**3295> Please examine the NFR design at: `aidlc-docs/construction/[unit-name]/nfr-design/`3296329732983299> **🚀 <u>**WHAT'S NEXT?**</u>**3300>3301> **You may:**3302>3303> 🔧 **Request Changes** - Ask for modifications to the NFR design based on your review3304> ✅ **Continue to Next Stage** - Approve NFR design and proceed to **[next-stage-name]**33053306---3307```33083309### Step 8: Wait for Explicit Approval3310- Do not proceed until the user explicitly approves the NFR design3311- Approval must be clear and unambiguous3312- If user requests changes, update the design and repeat the approval process33133314### Step 9: Record Approval and Update Progress3315- Log approval in audit.md with timestamp3316- Record the user's approval response with timestamp3317- Mark NFR Design stage complete in aidlc-state.md3318<!-- forgecat:@forgecat/awslabs_aidlc-workflows:nfr-design:end -->33193320<!-- forgecat:@forgecat/awslabs_aidlc-workflows:nfr-requirements:start -->3321# NFR Requirements33223323## Prerequisites3324- Functional Design must be complete for the unit3325- Unit functional design artifacts must be available3326- Execution plan must indicate NFR Requirements stage should execute33273328## Overview3329Determine non-functional requirements for the unit and make tech stack choices.33303331## Steps to Execute33323333### Step 1: Analyze Functional Design3334- Read functional design artifacts from `aidlc-docs/construction/{unit-name}/functional-design/`3335- Understand business logic complexity and requirements33363337### Step 2: Create NFR Requirements Plan3338- Generate plan with checkboxes [] for NFR assessment3339- Focus on scalability, performance, availability, security3340- Each step should have a checkbox []33413342### Step 3: Generate Context-Appropriate Questions3343**DIRECTIVE**: Thoroughly analyze the functional design to identify ALL areas where NFR clarification would improve system quality and architecture decisions. Be proactive in asking questions to ensure comprehensive NFR coverage.33443345**CRITICAL**: Default to asking questions when there is ANY ambiguity or missing detail that could affect system quality. It's better to ask too many questions than to make incorrect NFR assumptions.33463347- EMBED questions using [Answer]: tag format3348- Focus on ANY ambiguities, missing information, or areas needing clarification3349- Generate questions wherever user input would improve NFR and tech stack decisions3350- **When in doubt, ask the question** - overconfidence leads to poor system quality33513352**Question categories to evaluate** (consider ALL categories):3353- **Scalability Requirements** - Ask about expected load, growth patterns, scaling triggers, and capacity planning3354- **Performance Requirements** - Ask about response times, throughput, latency, and performance benchmarks3355- **Availability Requirements** - Ask about uptime expectations, disaster recovery, failover, and business continuity3356- **Security Requirements** - Ask about data protection, compliance, authentication, authorization, and threat models3357- **Tech Stack Selection** - Ask about technology preferences, constraints, existing systems, and integration requirements3358- **Reliability Requirements** - Ask about error handling, fault tolerance, monitoring, and alerting needs3359- **Maintainability Requirements** - Ask about code quality, documentation, testing, and operational requirements3360- **Usability Requirements** - Ask about user experience, accessibility, and interface requirements33613362### Step 4: Store Plan3363- Save as `aidlc-docs/construction/plans/{unit-name}-nfr-requirements-plan.md`3364- Include all [Answer]: tags for user input33653366### Step 5: Collect and Analyze Answers3367- Wait for user to complete all [Answer]: tags3368- **MANDATORY**: Carefully review ALL responses for vague or ambiguous answers3369- **CRITICAL**: Add follow-up questions for ANY unclear responses - do not proceed with ambiguity3370- Look for responses like "depends", "maybe", "not sure", "mix of", "somewhere between", "standard", "typical"3371- Create clarification questions file if ANY ambiguities are detected3372- **Do not proceed until ALL ambiguities are resolved**33733374### Step 6: Generate NFR Requirements Artifacts3375- Create `aidlc-docs/construction/{unit-name}/nfr-requirements/nfr-requirements.md`3376- Create `aidlc-docs/construction/{unit-name}/nfr-requirements/tech-stack-decisions.md`33773378### Step 7: Present Completion Message3379- Present completion message in this structure:3380 1. **Completion Announcement** (mandatory): Always start with this:33813382```markdown3383# 📊 NFR Requirements Complete - [unit-name]3384```33853386 2. **AI Summary** (optional): Provide structured bullet-point summary of NFR requirements3387 - Format: "NFR requirements assessment has identified [description]:"3388 - List key scalability, performance, availability requirements (bullet points)3389 - List security and compliance requirements identified3390 - Mention tech stack decisions and rationale3391 - DO NOT include workflow instructions ("please review", "let me know", "proceed to next phase", "before we proceed")3392 - Keep factual and content-focused3393 3. **Formatted Workflow Message** (mandatory): Always end with this exact format:33943395```markdown3396> **📋 <u>**REVIEW REQUIRED:**</u>**3397> Please examine the NFR requirements at: `aidlc-docs/construction/[unit-name]/nfr-requirements/`3398339934003401> **🚀 <u>**WHAT'S NEXT?**</u>**3402>3403> **You may:**3404>3405> 🔧 **Request Changes** - Ask for modifications to the NFR requirements based on your review3406> ✅ **Continue to Next Stage** - Approve NFR requirements and proceed to **[next-stage-name]**34073408---3409```34103411### Step 8: Wait for Explicit Approval3412- Do not proceed until the user explicitly approves the NFR requirements3413- Approval must be clear and unambiguous3414- If user requests changes, update the requirements and repeat the approval process34153416### Step 9: Record Approval and Update Progress3417- Log approval in audit.md with timestamp3418- Record the user's approval response with timestamp3419- Mark NFR Requirements stage complete in aidlc-state.md3420<!-- forgecat:@forgecat/awslabs_aidlc-workflows:nfr-requirements:end -->34213422<!-- forgecat:@forgecat/awslabs_aidlc-workflows:operations:start -->3423# Operations34243425**Purpose**: Placeholder for future operational phases (deployment, monitoring, maintenance)34263427**Status**: This phase is currently a placeholder and will be expanded in future versions.34283429## Future Scope34303431The Operations phase will eventually include:3432- Deployment planning and execution3433- Monitoring and observability setup3434- Incident response procedures3435- Maintenance and support workflows3436- Production readiness checklists34373438## Current State34393440All build and test activities have been moved to the CONSTRUCTION phase.3441The AI-DLC workflow currently ends after the Build and Test phase in CONSTRUCTION.3442<!-- forgecat:@forgecat/awslabs_aidlc-workflows:operations:end -->34433444<!-- forgecat:@forgecat/awslabs_aidlc-workflows:application-design:start -->3445# Application Design - Detailed Steps34463447## Purpose3448**High-level component identification and service layer design**34493450Application Design focuses on:3451- Identifying main functional components and their responsibilities3452- Defining component interfaces (not detailed business logic)3453- Designing service layer for orchestration3454- Establishing component dependencies and communication patterns34553456**Note**: Detailed business logic design happens later in Functional Design (per-unit, CONSTRUCTION phase)34573458## Prerequisites3459- Workspace Detection must be complete3460- Requirements Analysis recommended (provides functional context)3461- User Stories recommended (user stories guide design decisions)3462- Execution plan must indicate Application Design stage should execute34633464## Step-by-Step Execution34653466### 1. Analyze Context3467- Read `aidlc-docs/inception/requirements/requirements.md` and `aidlc-docs/inception/user-stories/stories.md`3468- Identify key business capabilities and functional areas3469- Determine design scope and complexity34703471### 2. Create Application Design Plan3472- Generate plan with checkboxes [] for application design3473- Focus on components, responsibilities, methods, business rules, and services3474- Each step and sub-step should have a checkbox []34753476### 3. Include Mandatory Design Artifacts in Plan3477- **ALWAYS** include these mandatory artifacts in the design plan:3478 - [ ] Generate components.md with component definitions and high-level responsibilities3479 - [ ] Generate component-methods.md with method signatures (business rules detailed later in Functional Design)3480 - [ ] Generate services.md with service definitions and orchestration patterns3481 - [ ] Generate component-dependency.md with dependency relationships and communication patterns3482 - [ ] Validate design completeness and consistency34833484### 4. Generate Context-Appropriate Questions3485**DIRECTIVE**: Analyze the requirements and stories to generate questions relevant to THIS specific application design. Use the categories below as guidance. Evaluate each category and, when in doubt about applicability, ask the question rather than skipping it — overconfidence leads to poor outcomes (see overconfidence-prevention.md).34863487- EMBED questions using [Answer]: tag format3488- Focus on ANY ambiguities, missing information, or areas needing clarification3489- Generate questions wherever user input would improve design decisions3490- **When in doubt, ask the question** - overconfidence leads to poor designs34913492**Question categories to evaluate** (consider ALL categories):3493- **Component Identification** - Ask about component boundaries, organization, and grouping strategies3494- **Component Methods** - Ask about method signatures, input/output expectations, and interface contracts (detailed business rules come later)3495- **Service Layer Design** - Ask about service orchestration, boundaries, and coordination patterns3496- **Component Dependencies** - Ask about communication patterns, dependency management, and coupling concerns3497- **Design Patterns** - Ask about architectural style preferences, pattern choices, and design constraints34983499### 5. Store Application Design Plan3500- Save as `aidlc-docs/inception/plans/application-design-plan.md`3501- Include all [Answer]: tags for user input3502- Ensure plan covers all design aspects35033504### 6. Request User Input3505- Ask user to fill [Answer]: tags directly in the plan document3506- Emphasize importance of design decisions3507- Provide clear instructions on completing the [Answer]: tags35083509### 7. Collect Answers3510- Wait for user to provide answers to all questions using [Answer]: tags in the document3511- Do not proceed until ALL [Answer]: tags are completed3512- Review the document to ensure no [Answer]: tags are left blank35133514### 8. ANALYZE ANSWERS (MANDATORY)3515Before proceeding, you MUST carefully review all user answers for:3516- **Vague or ambiguous responses**: "mix of", "somewhere between", "not sure", "depends"3517- **Undefined criteria or terms**: References to concepts without clear definitions3518- **Contradictory answers**: Responses that conflict with each other3519- **Missing design details**: Answers that lack specific guidance3520- **Answers that combine options**: Responses that merge different approaches without clear decision rules35213522### 9. MANDATORY Follow-up Questions3523If the analysis in step 8 reveals ANY ambiguous answers, you MUST:3524- Add specific follow-up questions to the plan document using [Answer]: tags3525- DO NOT proceed to approval until all ambiguities are resolved3526- Examples of required follow-ups:3527 - "You mentioned 'mix of A and B' - what specific criteria should determine when to use A vs B?"3528 - "You said 'somewhere between A and B' - can you define the exact middle ground approach?"3529 - "You indicated 'not sure' - what additional information would help you decide?"3530 - "You mentioned 'depends on complexity' - how do you define complexity levels?"35313532### 10. Generate Application Design Artifacts3533- Execute the approved plan to generate design artifacts3534- Create `aidlc-docs/inception/application-design/components.md` with:3535 - Component name and purpose3536 - Component responsibilities3537 - Component interfaces3538- Create `aidlc-docs/inception/application-design/component-methods.md` with:3539 - Method signatures for each component3540 - High-level purpose of each method3541 - Input/output types3542 - Note: Detailed business rules will be defined in Functional Design (per-unit, CONSTRUCTION phase)3543- Create `aidlc-docs/inception/application-design/services.md` with:3544 - Service definitions3545 - Service responsibilities3546 - Service interactions and orchestration3547- Create `aidlc-docs/inception/application-design/component-dependency.md` with:3548 - Dependency matrix showing relationships3549 - Communication patterns between components3550 - Data flow diagrams3551- Create `aidlc-docs/inception/application-design/application-design.md` that consolidates the multiple design docs created above in a single doc.35523553### 11. Log Approval3554- Log approval prompt with timestamp in `aidlc-docs/audit.md`3555- Include complete approval prompt text3556- Use ISO 8601 timestamp format35573558### 12. Present Completion Message35593560```markdown3561# 🏗️ Application Design Complete35623563[AI-generated summary of application design artifacts created in bullet points]35643565> **📋 <u>**REVIEW REQUIRED:**</u>**3566> Please examine the application design artifacts at: `aidlc-docs/inception/application-design/`35673568> **🚀 <u>**WHAT'S NEXT?**</u>**3569>3570> **You may:**3571>3572> 🔧 **Request Changes** - Ask for modifications to the application design if required3573> [IF Units Generation is skipped:]3574> 📝 **Add Units Generation** - Choose to include **Units Generation** stage (currently skipped)3575> ✅ **Approve & Continue** - Approve design and proceed to **[Units Generation/CONSTRUCTION PHASE]**3576```35773578### 13. Wait for Explicit Approval3579- Do not proceed until the user explicitly approves the application design3580- Approval must be clear and unambiguous3581- If user requests changes, update the design and repeat the approval process35823583### 14. Record Approval Response3584- Log the user's approval response with timestamp in `aidlc-docs/audit.md`3585- Include the exact user response text3586- Mark the approval status clearly35873588### 15. Update Progress3589- Mark Application Design stage complete in `aidlc-docs/aidlc-state.md`3590- Update the "Current Status" section3591- Prepare for transition to next stage3592<!-- forgecat:@forgecat/awslabs_aidlc-workflows:application-design:end -->35933594<!-- forgecat:@forgecat/awslabs_aidlc-workflows:requirements-analysis:start -->3595# Requirements Analysis (Adaptive)35963597**Assume the role** of a product owner35983599**Adaptive Phase**: Always executes. Detail level adapts to problem complexity.36003601**See [depth-levels.md](../common/depth-levels.md) for adaptive depth explanation**36023603## Prerequisites3604- Workspace Detection must be complete3605- Reverse Engineering must be complete (if brownfield)36063607## Execution Steps36083609### Step 1: Load Reverse Engineering Context (if available)36103611**IF brownfield project**:3612- Load `aidlc-docs/inception/reverse-engineering/architecture.md`3613- Load `aidlc-docs/inception/reverse-engineering/component-inventory.md`3614- Load `aidlc-docs/inception/reverse-engineering/technology-stack.md`3615- Use these to understand existing system when analyzing request36163617### Step 2: Analyze User Request (Intent Analysis)36183619#### 2.1 Request Clarity3620- **Clear**: Specific, well-defined, actionable3621- **Vague**: General, ambiguous, needs clarification3622- **Incomplete**: Missing key information36233624#### 2.2 Request Type3625- **New Feature**: Adding new functionality3626- **Bug Fix**: Fixing existing issue3627- **Refactoring**: Improving code structure3628- **Upgrade**: Updating dependencies or frameworks3629- **Migration**: Moving to different technology3630- **Enhancement**: Improving existing feature3631- **New Project**: Starting from scratch36323633#### 2.3 Initial Scope Estimate3634- **Single File**: Changes to one file3635- **Single Component**: Changes to one component/package3636- **Multiple Components**: Changes across multiple components3637- **System-wide**: Changes affecting entire system3638- **Cross-system**: Changes affecting multiple systems36393640#### 2.4 Initial Complexity Estimate3641- **Trivial**: Simple, straightforward change3642- **Simple**: Clear implementation path3643- **Moderate**: Some complexity, multiple considerations3644- **Complex**: Significant complexity, many considerations36453646### Step 3: Determine Requirements Depth36473648**Based on request analysis, determine depth:**36493650**Minimal Depth** - Use when:3651- Request is clear and simple3652- No detailed requirements needed3653- Just document the basic understanding36543655**Standard Depth** - Use when:3656- Request needs clarification3657- Functional and non-functional requirements needed3658- Normal complexity36593660**Comprehensive Depth** - Use when:3661- Complex project with multiple stakeholders3662- High risk or critical system3663- Detailed requirements with traceability needed36643665### Step 4: Assess Current Requirements36663667Analyze whatever the user has provided:3668 - Intent statements or descriptions (already logged in audit.md)3669 - Existing requirements documents (search workspace if mentioned)3670 - Pasted content or file references3671 - Convert any non-markdown documents to markdown format36723673### Step 5: Thorough Completeness Analysis36743675**CRITICAL**: Use comprehensive analysis to evaluate requirements completeness. Default to asking questions when there is ANY ambiguity or missing detail.36763677**MANDATORY**: Evaluate ALL of these areas and ask questions for ANY that are unclear:3678- **Functional Requirements**: Core features, user interactions, system behaviors3679- **Non-Functional Requirements**: Performance, security, scalability, usability3680- **User Scenarios**: Use cases, user journeys, edge cases, error scenarios3681- **Business Context**: Goals, constraints, success criteria, stakeholder needs3682- **Technical Context**: Integration points, data requirements, system boundaries3683- **Quality Attributes**: Reliability, maintainability, testability, accessibility36843685**When in doubt, ask questions** - incomplete requirements lead to poor implementations.36863687### Step 5.1: Extension Opt-In Prompts36883689**MANDATORY**: Scan all loaded `*.opt-in.md` files (loaded at workflow start from `extensions/` subdirectories) for an `## Opt-In Prompt` section. For each extension that declares one, include that question in the clarifying questions file created in Step 6.36903691After receiving answers:36921. Record each extension's enablement status in `aidlc-docs/aidlc-state.md` under `## Extension Configuration`:36933694```markdown3695## Extension Configuration3696| Extension | Enabled | Decided At |3697|---|---|---|3698| [Extension Name] | [Yes/No] | Requirements Analysis |3699```370037012. **Deferred Rule Loading**: For each extension the user opted IN, load the full rules file now. The rules file is derived by naming convention: strip `.opt-in.md` from the opt-in filename and append `.md` (e.g., `security-baseline.opt-in.md` → `security-baseline.md`). For extensions the user opted OUT, do NOT load the full rules file.37023703### Step 6: Generate Clarifying Questions (PROACTIVE APPROACH)3704 - **ALWAYS** create `aidlc-docs/inception/requirements/requirement-verification-questions.md` unless requirements are exceptionally clear and complete3705 - Ask questions about ANY missing, unclear, or ambiguous areas3706 - Focus on functional requirements, non-functional requirements, user scenarios, and business context3707 - Request user to fill in all [Answer]: tags directly in the questions document3708 - If presenting multiple-choice options for answers:3709 - Label the options as A, B, C, D etc.3710 - Ensure options are mutually exclusive and don't overlap3711 - ALWAYS include option for custom response: "X) Other (please describe after [Answer]: tag below)"3712 - Wait for user answers in the document3713 - **MANDATORY**: Analyze ALL answers for ambiguities and create follow-up questions if needed3714 - **MANDATORY**: Keep asking questions until ALL ambiguities are resolved OR user explicitly asks to proceed37153716### ⛔ GATE: Await User Answers3717DO NOT proceed to Step 7 until all questions in requirement-verification-questions.md are answered and validated.3718Present the question file to the user and STOP.37193720### Step 7: Generate Requirements Document3721 - **PREREQUISITE**: Step 6 gate must be passed — all answers received and analyzed3722 - Create `aidlc-docs/inception/requirements/requirements.md`3723 - Include intent analysis summary at the top:3724 - User request3725 - Request type3726 - Scope estimate3727 - Complexity estimate3728 - Include both functional and non-functional requirements3729 - Incorporate user's answers to clarifying questions3730 - Provide brief summary of key requirements37313732### Step 8: Update State Tracking37333734Update `aidlc-docs/aidlc-state.md`:37353736```markdown3737## Stage Progress3738### 🔵 INCEPTION PHASE3739- [x] Workspace Detection3740- [x] Reverse Engineering (if applicable)3741- [x] Requirements Analysis3742```37433744### Step 9: Log and Proceed3745 - Log approval prompt with timestamp in `aidlc-docs/audit.md`3746 - Present completion message in this structure:3747 1. **Completion Announcement** (mandatory): Always start with this:37483749```markdown3750# 🔍 Requirements Analysis Complete3751```37523753 2. **AI Summary** (optional): Provide structured bullet-point summary of requirements3754 - Format: "Requirements analysis has identified [project type/complexity]:"3755 - List key functional requirements (bullet points)3756 - List key non-functional requirements (bullet points)3757 - Mention architectural considerations or technical decisions if relevant3758 - DO NOT include workflow instructions ("please review", "let me know", "proceed to next phase", "before we proceed")3759 - Keep factual and content-focused3760 3. **Formatted Workflow Message** (mandatory): Always end with this exact format:37613762```markdown3763> **📋 <u>**REVIEW REQUIRED:**</u>**3764> Please examine the requirements document at: `aidlc-docs/inception/requirements/requirements.md`3765376637673768> **🚀 <u>**WHAT'S NEXT?**</u>**3769>3770> **You may:**3771>3772> 🔧 **Request Changes** - Ask for modifications to the requirements if required based on your review3773> [IF User Stories will be skipped, add this option:]3774> 📝 **Add User Stories** - Choose to Include **User Stories** stage (currently skipped based on project simplicity)3775> ✅ **Approve & Continue** - Approve requirements and proceed to **[User Stories/Workflow Planning]**37763777---3778```37793780**Note**: Include the "Add User Stories" option only when User Stories stage will be skipped. Replace [User Stories/Workflow Planning] with the actual next stage name.37813782 - Wait for explicit user approval before proceeding3783 - Record approval response with timestamp3784 - Update Requirements Analysis stage complete in aidlc-state.md3785<!-- forgecat:@forgecat/awslabs_aidlc-workflows:requirements-analysis:end -->37863787<!-- forgecat:@forgecat/awslabs_aidlc-workflows:reverse-engineering:start -->3788# Reverse Engineering37893790**Purpose**: Analyze existing codebase and generate comprehensive design artifacts37913792**Execute when**: Brownfield project detected (existing code found in workspace)37933794**Skip when**: Greenfield project (no existing code)37953796**Rerun behavior**: Rerun is controlled by workspace-detection.md. If existing reverse engineering artifacts are found and are still current, they are loaded and reverse engineering is skipped. If artifacts are stale (older than the codebase's last significant modification) or the user explicitly requests a rerun, reverse engineering executes again to ensure artifacts reflect current code state37973798## Step 1: Multi-Package Discovery37993800### 1.1 Scan Workspace3801- All packages (not just mentioned ones)3802- Package relationships via config files3803- Package types: Application, CDK/Infrastructure, Models, Clients, Tests38043805### 1.2 Understand the Business Context3806- The core business that the system is implementing overall3807- The business overview of every package3808- List of Business Transactions that are implemented in the system38093810### 1.3 Infrastructure Discovery3811- CDK packages (package.json with CDK dependencies)3812- Terraform (.tf files)3813- CloudFormation (.yaml/.json templates)3814- Deployment scripts38153816### 1.4 Build System Discovery3817- Build systems: Brazil, Maven, Gradle, npm3818- Config files for build-system declarations3819- Build dependencies between packages38203821### 1.5 Service Architecture Discovery3822- Lambda functions (handlers, triggers)3823- Container services (Docker/ECS configs)3824- API definitions (Smithy models, OpenAPI specs)3825- Data stores (DynamoDB, S3, etc.)38263827### 1.6 Code Quality Analysis3828- Programming languages and frameworks3829- Test coverage indicators3830- Linting configurations3831- CI/CD pipelines38323833## Step 2: Generate Business Overview Documentation38343835Create `aidlc-docs/inception/reverse-engineering/business-overview.md`:38363837```markdown3838# Business Overview38393840## Business Context Diagram3841[Mermaid diagram showing the Business Context]38423843## Business Description3844- **Business Description**: [Overall Business description of what the system does]3845- **Business Transactions**: [List of Business Transactions that the system implements and their descriptions]3846- **Business Dictionary**: [Business dictionary terms that the system follows and their meaning]38473848## Component Level Business Descriptions3849### [Package/Component Name]3850- **Purpose**: [What it does from the business perspective]3851- **Responsibilities**: [Key responsibilities]3852```38533854## Step 3: Generate Architecture Documentation38553856Create `aidlc-docs/inception/reverse-engineering/architecture.md`:38573858```markdown3859# System Architecture38603861## System Overview3862[High-level description of the system]38633864## Architecture Diagram3865[Mermaid diagram showing all packages, services, data stores, relationships]38663867## Component Descriptions3868### [Package/Component Name]3869- **Purpose**: [What it does]3870- **Responsibilities**: [Key responsibilities]3871- **Dependencies**: [What it depends on]3872- **Type**: [Application/Infrastructure/Model/Client/Test]38733874## Data Flow3875[Mermaid sequence diagram of key workflows]38763877## Integration Points3878- **External APIs**: [List with purposes]3879- **Databases**: [List with purposes]3880- **Third-party Services**: [List with purposes]38813882## Infrastructure Components3883- **CDK Stacks**: [List with purposes]3884- **Deployment Model**: [Description]3885- **Networking**: [VPC, subnets, security groups]3886```38873888## Step 4: Generate Code Structure Documentation38893890Create `aidlc-docs/inception/reverse-engineering/code-structure.md`:38913892```markdown3893# Code Structure38943895## Build System3896- **Type**: [Maven/Gradle/npm/Brazil]3897- **Configuration**: [Key build files and settings]38983899## Key Classes/Modules3900[Mermaid class diagram or module hierarchy]39013902### Existing Files Inventory3903[List all source files with their purposes - these are candidates for modification in brownfield projects]39043905**Example format**:3906- `[path/to/file]` - [Purpose/responsibility]39073908## Design Patterns3909### [Pattern Name]3910- **Location**: [Where used]3911- **Purpose**: [Why used]3912- **Implementation**: [How implemented]39133914## Critical Dependencies3915### [Dependency Name]3916- **Version**: [Version number]3917- **Usage**: [How and where used]3918- **Purpose**: [Why needed]3919```39203921## Step 5: Generate API Documentation39223923Create `aidlc-docs/inception/reverse-engineering/api-documentation.md`:39243925```markdown3926# API Documentation39273928## REST APIs3929### [Endpoint Name]3930- **Method**: [GET/POST/PUT/DELETE]3931- **Path**: [/api/path]3932- **Purpose**: [What it does]3933- **Request**: [Request format]3934- **Response**: [Response format]39353936## Internal APIs3937### [Interface/Class Name]3938- **Methods**: [List with signatures]3939- **Parameters**: [Parameter descriptions]3940- **Return Types**: [Return type descriptions]39413942## Data Models3943### [Model Name]3944- **Fields**: [Field descriptions]3945- **Relationships**: [Related models]3946- **Validation**: [Validation rules]3947```39483949## Step 6: Generate Component Inventory39503951Create `aidlc-docs/inception/reverse-engineering/component-inventory.md`:39523953```markdown3954# Component Inventory39553956## Application Packages3957- [Package name] - [Purpose]39583959## Infrastructure Packages3960- [Package name] - [CDK/Terraform] - [Purpose]39613962## Shared Packages3963- [Package name] - [Models/Utilities/Clients] - [Purpose]39643965## Test Packages3966- [Package name] - [Integration/Load/Unit] - [Purpose]39673968## Total Count3969- **Total Packages**: [Number]3970- **Application**: [Number]3971- **Infrastructure**: [Number]3972- **Shared**: [Number]3973- **Test**: [Number]3974```39753976## Step 7: Generate Technology Stack Documentation39773978Create `aidlc-docs/inception/reverse-engineering/technology-stack.md`:39793980```markdown3981# Technology Stack39823983## Programming Languages3984- [Language] - [Version] - [Usage]39853986## Frameworks3987- [Framework] - [Version] - [Purpose]39883989## Infrastructure3990- [Service] - [Purpose]39913992## Build Tools3993- [Tool] - [Version] - [Purpose]39943995## Testing Tools3996- [Tool] - [Version] - [Purpose]3997```39983999## Step 8: Generate Dependencies Documentation40004001Create `aidlc-docs/inception/reverse-engineering/dependencies.md`:40024003```markdown4004# Dependencies40054006## Internal Dependencies4007[Mermaid diagram showing package dependencies]40084009### [Package A] depends on [Package B]4010- **Type**: [Compile/Runtime/Test]4011- **Reason**: [Why dependency exists]40124013## External Dependencies4014### [Dependency Name]4015- **Version**: [Version]4016- **Purpose**: [Why used]4017- **License**: [License type]4018```40194020## Step 9: Generate Code Quality Assessment40214022Create `aidlc-docs/inception/reverse-engineering/code-quality-assessment.md`:40234024```markdown4025# Code Quality Assessment40264027## Test Coverage4028- **Overall**: [Percentage or Good/Fair/Poor/None]4029- **Unit Tests**: [Status]4030- **Integration Tests**: [Status]40314032## Code Quality Indicators4033- **Linting**: [Configured/Not configured]4034- **Code Style**: [Consistent/Inconsistent]4035- **Documentation**: [Good/Fair/Poor]40364037## Technical Debt4038- [Issue description and location]40394040## Patterns and Anti-patterns4041- **Good Patterns**: [List]4042- **Anti-patterns**: [List with locations]4043```40444045## Step 10: Create Timestamp File40464047Create `aidlc-docs/inception/reverse-engineering/reverse-engineering-timestamp.md`:40484049```markdown4050# Reverse Engineering Metadata40514052**Analysis Date**: [ISO timestamp]4053**Analyzer**: AI-DLC4054**Workspace**: [Workspace path]4055**Total Files Analyzed**: [Number]40564057## Artifacts Generated4058- [x] architecture.md4059- [x] code-structure.md4060- [x] api-documentation.md4061- [x] component-inventory.md4062- [x] technology-stack.md4063- [x] dependencies.md4064- [x] code-quality-assessment.md4065```40664067## Step 11: Update State Tracking40684069Update `aidlc-docs/aidlc-state.md`:40704071```markdown4072## Reverse Engineering Status4073- [x] Reverse Engineering - Completed on [timestamp]4074- **Artifacts Location**: aidlc-docs/inception/reverse-engineering/4075```40764077## Step 12: Present Completion Message to User40784079```markdown4080# 🔍 Reverse Engineering Complete40814082[AI-generated summary of key findings from analysis in the form of bullet points]40834084> **📋 <u>**REVIEW REQUIRED:**</u>**4085> Please examine the reverse engineering artifacts at: `aidlc-docs/inception/reverse-engineering/`40864087> **🚀 <u>**WHAT'S NEXT?**</u>**4088>4089> **You may:**4090>4091> 🔧 **Request Changes** - Ask for modifications to the reverse engineering analysis if required4092> ✅ **Approve & Continue** - Approve analysis and proceed to **Requirements Analysis**4093```40944095## Step 13: Wait for User Approval40964097- **MANDATORY**: Do not proceed until user explicitly approves4098- **MANDATORY**: Log user's response in audit.md with complete raw input4099<!-- forgecat:@forgecat/awslabs_aidlc-workflows:reverse-engineering:end -->41004101<!-- forgecat:@forgecat/awslabs_aidlc-workflows:units-generation:start -->4102# Units Generation - Detailed Steps41034104## Overview4105This stage decomposes the system into manageable units of work through two integrated parts:4106- **Part 1 - Planning**: Create decomposition plan with questions, collect answers, analyze for ambiguities, get approval4107- **Part 2 - Generation**: Execute approved plan to generate unit artifacts41084109**DEFINITION**: A unit of work is a logical grouping of stories for development purposes. For microservices, each unit becomes an independently deployable service. For monoliths, the single unit represents the entire application with logical modules.41104111**Terminology**: Use "Service" for independently deployable components, "Module" for logical groupings within a service, "Unit of Work" for planning context.41124113## Prerequisites4114- Workspace Detection must be complete4115- Requirements Analysis recommended (provides functional scope)4116- User Stories recommended (stories map to units)4117- Application Design stage REQUIRED (determines components, methods, and services)4118- Execution plan must indicate Design stage should execute41194120---41214122# PART 1: PLANNING41234124## Step 1: Create Unit of Work Plan4125- Generate plan with checkboxes [] for decomposing system into units of work4126- Focus on breaking down the system into manageable development units4127- Each step and sub-step should have a checkbox []41284129## Step 2: Include Mandatory Unit Artifacts in Plan4130**ALWAYS** include these mandatory artifacts in the unit plan:4131- [ ] Generate `aidlc-docs/inception/application-design/unit-of-work.md` with unit definitions and responsibilities4132- [ ] Generate `aidlc-docs/inception/application-design/unit-of-work-dependency.md` with dependency matrix4133- [ ] Generate `aidlc-docs/inception/application-design/unit-of-work-story-map.md` mapping stories to units4134- [ ] **Greenfield only**: Document code organization strategy in `unit-of-work.md` (see code-generation.md for structure patterns)4135- [ ] Validate unit boundaries and dependencies4136- [ ] Ensure all stories are assigned to units41374138## Step 3: Generate Context-Appropriate Questions4139**DIRECTIVE**: Thoroughly analyze the requirements, stories, and application design to identify ALL areas where clarification would improve unit decomposition quality. Be proactive in asking questions to ensure comprehensive coverage of decomposition concerns.41404141**CRITICAL**: Default to asking questions when there is ANY ambiguity or missing detail that could affect unit boundaries or decomposition quality. It's better to ask too many questions than to make incorrect assumptions about how the system should be decomposed.41424143**MANDATORY**: Evaluate ALL of the following categories by asking targeted questions about each. For each category, determine applicability based on evidence from the requirements, stories, and application design -- do not skip categories without explicit justification:41444145- EMBED questions using [Answer]: tag format4146- Focus on ANY ambiguities, missing information, or areas needing clarification4147- Generate questions wherever user input would improve decomposition decisions4148- **When in doubt, ask the question** - overconfidence leads to poor unit boundaries41494150**Question categories to evaluate** (consider ALL categories):4151- **Story Grouping** - Ask about grouping strategy, story affinity, and logical clustering approaches4152- **Dependencies** - Ask about integration approach, shared resources, and inter-unit communication patterns4153- **Team Alignment** - Ask about team structure, ownership boundaries, and collaboration models4154- **Technical Considerations** - Ask about scalability/deployment requirements that may differ across units4155- **Business Domain** - Ask about domain boundaries, bounded contexts, and business capability alignment4156- **Code Organization (Greenfield multi-unit only)** - Ask about deployment model and directory structure preferences41574158## Step 4: Store UOW Plan4159- Save as `aidlc-docs/inception/plans/unit-of-work-plan.md`4160- Include all [Answer]: tags for user input4161- Ensure plan covers all aspects of system decomposition41624163## Step 5: Request User Input4164- Ask user to fill [Answer]: tags directly in the plan document4165- Emphasize importance of decomposition decisions4166- Provide clear instructions on completing the [Answer]: tags41674168## Step 6: Collect Answers4169- Wait for user to provide answers to all questions using [Answer]: tags in the document4170- Do not proceed until ALL [Answer]: tags are completed4171- Review the document to ensure no [Answer]: tags are left blank41724173## Step 7: ANALYZE ANSWERS (MANDATORY)4174Before proceeding, you MUST carefully review all user answers for:4175- **Vague or ambiguous responses**: "mix of", "somewhere between", "not sure", "depends"4176- **Undefined criteria or terms**: References to concepts without clear definitions4177- **Contradictory answers**: Responses that conflict with each other4178- **Missing generation details**: Answers that lack specific guidance4179- **Answers that combine options**: Responses that merge different approaches without clear decision rules41804181## Step 8: MANDATORY Follow-up Questions4182If the analysis in step 7 reveals ANY ambiguous answers, you MUST:4183- Add specific follow-up questions to the plan document using [Answer]: tags4184- DO NOT proceed to approval until all ambiguities are resolved4185- Examples of required follow-ups:4186 - "You mentioned 'mix of A and B' - what specific criteria should determine when to use A vs B?"4187 - "You said 'somewhere between A and B' - can you define the exact middle ground approach?"4188 - "You indicated 'not sure' - what additional information would help you decide?"4189 - "You mentioned 'depends on complexity' - how do you define complexity levels?"41904191## Step 9: Request Approval4192- Ask: "**Unit of work plan complete. Review the plan in aidlc-docs/inception/plans/unit-of-work-plan.md. Ready to proceed to generation?**"4193- DO NOT PROCEED until user confirms41944195## Step 10: Log Approval4196- Log prompt and response in audit.md with timestamp4197- Use ISO 8601 timestamp format4198- Include complete approval prompt text41994200## Step 11: Update Progress4201- Mark Units Planning complete in aidlc-state.md4202- Update the "Current Status" section4203- Prepare for transition to Units Generation42044205---42064207# PART 2: GENERATION42084209## Step 12: Load Unit of Work Plan4210- [ ] Read the complete plan from `aidlc-docs/inception/plans/unit-of-work-plan.md`4211- [ ] Identify the next uncompleted step (first [ ] checkbox)4212- [ ] Load the context and requirements for that step42134214## Step 13: Execute Current Step4215- [ ] Perform exactly what the current step describes4216- [ ] Generate unit artifacts as specified in the plan4217- [ ] Follow the approved decomposition approach from Planning4218- [ ] Use the criteria and boundaries specified in the plan42194220## Step 14: Update Progress4221- [ ] Mark the completed step as [x] in the unit of work plan4222- [ ] Update `aidlc-docs/aidlc-state.md` current status4223- [ ] Save all generated artifacts42244225## Step 15: Continue or Complete4226- [ ] If more steps remain, return to Step 124227- [ ] If all steps complete, verify units are ready for design stages4228- [ ] Mark Units Generation stage as complete42294230## Step 16: Present Completion Message42314232```markdown4233# 🔧 Units Generation Complete42344235[AI-generated summary of units and decomposition created in bullet points]42364237> **📋 <u>**REVIEW REQUIRED:**</u>**4238> Please examine the units generation artifacts at: `aidlc-docs/inception/application-design/`42394240> **🚀 <u>**WHAT'S NEXT?**</u>**4241>4242> **You may:**4243>4244> 🔧 **Request Changes** - Ask for modifications to the units generation if required4245> ✅ **Approve & Continue** - Approve units and proceed to **CONSTRUCTION PHASE**4246```42474248## Step 17: Wait for Explicit Approval4249- Do not proceed until the user explicitly approves the units generation4250- Approval must be clear and unambiguous4251- If user requests changes, update the units and repeat the approval process42524253## Step 18: Record Approval Response4254- Log the user's approval response with timestamp in `aidlc-docs/audit.md`4255- Include the exact user response text4256- Mark the approval status clearly42574258## Step 19: Update Progress4259- Mark Units Generation stage complete in `aidlc-docs/aidlc-state.md`4260- Update the "Current Status" section4261- Prepare for transition to CONSTRUCTION PHASE42624263---42644265## Critical Rules42664267### Planning Phase Rules4268- Generate ONLY context-relevant questions4269- Use [Answer]: tag format for all questions4270- Analyze all answers for ambiguities before proceeding4271- Resolve ALL ambiguities with follow-up questions4272- Get explicit user approval before generation42734274### Generation Phase Rules4275- **NO HARDCODED LOGIC**: Only execute what's written in the unit of work plan4276- **FOLLOW PLAN EXACTLY**: Do not deviate from the step sequence4277- **UPDATE CHECKBOXES**: Mark [x] immediately after completing each step4278- **USE APPROVED APPROACH**: Follow the decomposition methodology from Planning4279- **VERIFY COMPLETION**: Ensure all unit artifacts are complete before proceeding42804281## Completion Criteria4282- All planning questions answered and ambiguities resolved4283- User approval obtained for the plan4284- All steps in unit of work plan marked [x]4285- All unit artifacts generated according to plan:4286 - `unit-of-work.md` with unit definitions4287 - `unit-of-work-dependency.md` with dependency matrix4288 - `unit-of-work-story-map.md` with story mappings4289- Units verified and ready for per-unit design stages4290<!-- forgecat:@forgecat/awslabs_aidlc-workflows:units-generation:end -->42914292<!-- forgecat:@forgecat/awslabs_aidlc-workflows:user-stories:start -->4293# User Stories - Detailed Steps42944295## Purpose4296**Convert requirements into user-centered stories with acceptance criteria**42974298User Stories focus on:4299- Translating business requirements into user-centered narratives4300- Defining clear acceptance criteria for each story4301- Creating user personas that represent different stakeholder types4302- Establishing shared understanding across teams4303- Providing testable specifications for implementation43044305## Prerequisites4306- Workspace Detection must be complete4307- Requirements Analysis recommended (can reference requirements if available)4308- Workflow Planning must indicate User Stories stage should execute43094310## Intelligent Assessment Guidelines43114312**WHEN TO EXECUTE USER STORIES**: Use this enhanced assessment before proceeding:43134314### High Priority Execution (ALWAYS Execute)4315- **New User Features**: Any new functionality users will directly interact with4316- **User Experience Changes**: Modifications to existing user workflows or interfaces4317- **Multi-Persona Systems**: Applications serving different types of users4318- **Customer-Facing APIs**: Services that external users or systems will consume4319- **Complex Business Logic**: Requirements with multiple scenarios or business rules4320- **Cross-Team Projects**: Work requiring shared understanding across multiple teams43214322### Medium Priority Execution (Assess Complexity)4323- **Backend User Impact**: Internal changes that indirectly affect user experience4324- **Performance Improvements**: Enhancements with user-visible benefits4325- **Integration Work**: Connecting systems that affect user workflows4326- **Data Changes**: Modifications affecting user data, reports, or analytics4327- **Security Enhancements**: Changes affecting user authentication or permissions43284329### Complexity Assessment Factors4330For medium priority cases, execute user stories if ANY of these apply:4331- **Scope**: Changes span multiple components or user touchpoints4332- **Ambiguity**: Requirements have unclear aspects that stories could clarify4333- **Risk**: High business impact or potential for misunderstanding4334- **Stakeholders**: Multiple business stakeholders involved in requirements4335- **Testing**: User acceptance testing will be required4336- **Options**: Multiple valid implementation approaches exist43374338### Skip Only For Simple Cases4339- **Pure Refactoring**: Internal code improvements with zero user impact4340- **Isolated Bug Fixes**: Simple, well-defined fixes with clear scope4341- **Infrastructure Only**: Changes with no user-facing effects4342- **Developer Tooling**: Build processes, CI/CD, or development environment changes4343- **Documentation**: Updates that don't affect functionality43444345### Default Decision Rule4346**When in doubt, include user stories AND ask clarifying questions.** The overhead of creating comprehensive stories with proper clarification is typically outweighed by the benefits of:4347- Clearer requirements understanding4348- Better team alignment4349- Improved testing criteria4350- Enhanced stakeholder communication4351- Reduced implementation risks4352- Fewer costly changes during development4353- Better user experience outcomes43544355---43564357# PART 1: PLANNING43584359## Step 1: Validate User Stories Need (MANDATORY)43604361**CRITICAL**: Before proceeding with user stories, perform this assessment:43624363### Assessment Process43641. **Analyze Request Context**:4365 - Review the original user request and requirements4366 - Identify user-facing vs internal-only changes4367 - Assess complexity and scope of the work4368 - Evaluate business stakeholder involvement436943702. **Apply Assessment Criteria**:4371 - Check against High Priority indicators (always execute)4372 - Evaluate Medium Priority factors (complexity-based decision)4373 - Confirm this isn't a simple case that should be skipped437443753. **Document Assessment Decision**:4376 - Create `aidlc-docs/inception/plans/user-stories-assessment.md`4377 - Include reasoning for why user stories are valuable for this request4378 - Reference specific assessment criteria that apply4379 - Explain expected benefits (clarity, testing, stakeholder alignment)438043814. **Proceed Only If Justified**:4382 - User stories must add clear value to the project4383 - Assessment must show concrete benefits outweigh overhead4384 - Decision should be defensible to project stakeholders43854386### Assessment Documentation Template4387```markdown4388# User Stories Assessment43894390## Request Analysis4391- **Original Request**: [Brief summary]4392- **User Impact**: [Direct/Indirect/None]4393- **Complexity Level**: [Simple/Medium/Complex]4394- **Stakeholders**: [List involved parties]43954396## Assessment Criteria Met4397- [ ] High Priority: [List applicable criteria]4398- [ ] Medium Priority: [List applicable criteria with complexity justification]4399- [ ] Benefits: [Expected value from user stories]44004401## Decision4402**Execute User Stories**: [Yes/No]4403**Reasoning**: [Detailed justification]44044405## Expected Outcomes4406- [List specific benefits user stories will provide]4407- [How stories will improve project success]4408```44094410## Step 2: Create Story Plan4411- Assume the role of a product owner4412- Generate a comprehensive plan with step-by-step execution checklist for story development4413- Each step and sub-step should have a checkbox []4414- Focus on methodology and approach for converting requirements into user stories44154416## Step 3: Generate Context-Appropriate Questions4417**DIRECTIVE**: Thoroughly analyze the requirements and context to identify ALL areas where clarification would improve story quality and team understanding. Be proactive in asking questions to ensure comprehensive user story development.44184419**CRITICAL**: Default to asking questions when there is ANY ambiguity or missing detail that could affect story quality. It's better to ask too many questions than to create incomplete or unclear stories.44204421**See `common/question-format-guide.md` for question formatting rules**44224423- EMBED questions using [Answer]: tag format4424- Focus on ANY ambiguities, missing information, or areas needing clarification4425- Generate questions wherever user input would improve story creation decisions4426- **When in doubt, ask the question** - overconfidence leads to poor stories44274428**Question categories to evaluate** (consider ALL categories):4429- **User Personas** - Ask about user types, roles, characteristics, and motivations4430- **Story Granularity** - Ask about appropriate level of detail, story size, and breakdown approach4431- **Story Format** - Ask about format preferences, template usage, and documentation standards4432- **Breakdown Approach** - Ask about organization method, prioritization, and grouping strategies4433- **Acceptance Criteria** - Ask about detail level, format, testing approach, and validation methods4434- **User Journeys** - Ask about user workflows, interaction patterns, and experience flows4435- **Business Context** - Ask about business goals, success metrics, and stakeholder needs4436- **Technical Constraints** - Ask about technical limitations, integration requirements, and system boundaries44374438## Step 4: Include Mandatory Story Artifacts in Plan4439- **ALWAYS** include these mandatory artifacts in the story plan:4440 - [ ] Generate stories.md with user stories following INVEST criteria4441 - [ ] Generate personas.md with user archetypes and characteristics4442 - [ ] Ensure stories are Independent, Negotiable, Valuable, Estimable, Small, Testable4443 - [ ] Include acceptance criteria for each story4444 - [ ] Map personas to relevant user stories44454446## Step 5: Present Story Options4447- Include different approaches for story breakdown in the plan document:4448 - **User Journey-Based**: Stories follow user workflows and interactions4449 - **Feature-Based**: Stories organized around system features and capabilities4450 - **Persona-Based**: Stories grouped by different user types and their needs4451 - **Domain-Based**: Stories organized around business domains or contexts4452 - **Epic-Based**: Stories structured as hierarchical epics with sub-stories4453- Explain trade-offs and benefits of each approach4454- Allow for hybrid approaches with clear decision criteria44554456## Step 6: Store Story Plan4457- Save the complete story plan with embedded questions in `aidlc-docs/inception/plans/` directory4458- Filename: `story-generation-plan.md`4459- Include all [Answer]: tags for user input4460- Ensure plan is comprehensive and covers all story development aspects44614462## Step 7: Request User Input4463- Ask user to fill in all [Answer]: tags directly in the story plan document4464- Emphasize importance of audit trail and decision documentation4465- Provide clear instructions on how to fill in the [Answer]: tags4466- Explain that all questions must be answered before proceeding44674468## Step 8: Collect Answers4469- Wait for user to provide answers to all questions using [Answer]: tags in the document4470- Do not proceed until ALL [Answer]: tags are completed4471- Review the document to ensure no [Answer]: tags are left blank44724473## Step 9: ANALYZE ANSWERS (MANDATORY)4474Before proceeding, you MUST carefully review all user answers for:4475- **Vague or ambiguous responses**: "mix of", "somewhere between", "not sure", "depends", "maybe", "probably"4476- **Undefined criteria or terms**: References to concepts without clear definitions4477- **Contradictory answers**: Responses that conflict with each other4478- **Missing generation details**: Answers that lack specific guidance for implementation4479- **Answers that combine options**: Responses that merge different approaches without clear decision rules4480- **Incomplete explanations**: Answers that reference external factors without defining them4481- **Assumption-based responses**: Answers that assume knowledge not explicitly stated44824483## Step 10: MANDATORY Follow-up Questions4484If the analysis in step 9 reveals ANY ambiguous answers, you MUST:4485- Create a separate clarification questions file using [Answer]: tags4486- DO NOT proceed to approval until ALL ambiguities are completely resolved4487- **CRITICAL**: Be thorough - ask follow-up questions for every unclear response4488- Examples of required follow-ups:4489 - "You mentioned 'mix of A and B' - what specific criteria should determine when to use A vs B?"4490 - "You said 'somewhere between A and B' - can you define the exact middle ground approach?"4491 - "You indicated 'not sure' - what additional information would help you decide?"4492 - "You mentioned 'depends on complexity' - how do you define complexity levels and thresholds?"4493 - "You chose 'hybrid approach' - what are the specific rules for when to use each method?"4494 - "You said 'probably X' - what factors would make it definitely X vs definitely not X?"4495 - "You referenced 'standard practice' - can you define what that standard practice is?"44964497## Step 11: Avoid Implementation Details4498- Focus on story creation methodology, not prioritization or development tasks4499- Do not discuss technical generation at this stage4500- Avoid creating development timelines or sprint planning4501- Keep focus on story structure and format decisions45024503## Step 12: Log Approval Prompt4504- Before asking for approval, log the prompt with timestamp in `aidlc-docs/audit.md`4505- Include the complete approval prompt text4506- Use ISO 8601 timestamp format45074508## Step 13: Wait for Explicit Approval of Plan4509- Do not proceed until the user explicitly approves the story approach4510- Approval must be clear and unambiguous4511- If user requests changes, update the plan and repeat the approval process45124513## Step 14: Record Approval Response4514- Log the user's approval response with timestamp in `aidlc-docs/audit.md`4515- Include the exact user response text4516- Mark the approval status clearly45174518---45194520# PART 2: GENERATION45214522## Step 15: Load Story Generation Plan4523- [ ] Read the complete story plan from `aidlc-docs/inception/plans/story-generation-plan.md`4524- [ ] Identify the next uncompleted step (first [ ] checkbox)4525- [ ] Load the context and requirements for that step45264527## Step 16: Execute Current Step4528- [ ] Perform exactly what the current step describes4529- [ ] Generate story artifacts as specified in the plan4530- [ ] Follow the approved methodology and format from Planning4531- [ ] Use the story breakdown approach specified in the plan45324533## Step 17: Update Progress4534- [ ] Mark the completed step as [x] in the story generation plan4535- [ ] Update `aidlc-docs/aidlc-state.md` current status4536- [ ] Save all generated artifacts45374538## Step 18: Continue or Complete Generation4539- [ ] If more steps remain, return to Step 154540- [ ] If all steps complete, verify stories are ready for next stage4541- [ ] Ensure all mandatory artifacts are generated45424543## Step 19: Log Approval Prompt4544- Before asking for approval, log the prompt with timestamp in `aidlc-docs/audit.md`4545- Include the complete approval prompt text4546- Use ISO 8601 timestamp format45474548## Step 20: Present Completion Message4549- Present completion message in this structure:4550 1. **Completion Announcement** (mandatory): Always start with this:45514552```markdown4553# 📚 User Stories Complete4554```45554556 2. **AI Summary** (optional): Provide structured bullet-point summary of generated stories4557 - Format: "User stories generation has created [description]:"4558 - List key personas generated (bullet points)4559 - List user stories created with counts and organization4560 - Mention story structure and compliance (INVEST criteria, acceptance criteria)4561 - DO NOT include workflow instructions ("please review", "let me know", "proceed to next phase", "before we proceed")4562 - Keep factual and content-focused4563 3. **Formatted Workflow Message** (mandatory): Always end with this exact format:45644565```markdown4566> **📋 <u>**REVIEW REQUIRED:**</u>**4567> Please examine the user stories and personas at: `aidlc-docs/inception/user-stories/stories.md` and `aidlc-docs/inception/user-stories/personas.md`4568456945704571> **🚀 <u>**WHAT'S NEXT?**</u>**4572>4573> **You may:**4574>4575> 🔧 **Request Changes** - Ask for modifications to the stories or personas based on your review4576> ✅ **Approve & Continue** - Approve user stories and proceed to **Workflow Planning**45774578---4579```45804581## Step 21: Wait for Explicit Approval of Generated Stories4582- Do not proceed until the user explicitly approves the generated stories4583- Approval must be clear and unambiguous4584- If user requests changes, update stories and repeat the approval process45854586## Step 22: Record Approval Response4587- Log the user's approval response with timestamp in `aidlc-docs/audit.md`4588- Include the exact user response text4589- Mark the approval status clearly45904591## Step 23: Update Progress4592- Mark User Stories stage complete in `aidlc-state.md`4593- Update the "Current Status" section4594- Prepare for transition to next stage45954596---45974598# CRITICAL RULES45994600## Planning Phase Rules4601- **CONTEXT-APPROPRIATE QUESTIONS**: Only ask questions relevant to this specific context4602- **MANDATORY ANSWER ANALYSIS**: Always analyze answers for ambiguities before proceeding4603- **NO PROCEEDING WITH AMBIGUITY**: Must resolve all vague answers before generation4604- **EXPLICIT APPROVAL REQUIRED**: User must approve plan before generation starts46054606## Generation Phase Rules4607- **NO HARDCODED LOGIC**: Only execute what's written in the story generation plan4608- **FOLLOW PLAN EXACTLY**: Do not deviate from the step sequence4609- **UPDATE CHECKBOXES**: Mark [x] immediately after completing each step4610- **USE APPROVED METHODOLOGY**: Follow the story approach from Planning4611- **VERIFY COMPLETION**: Ensure all story artifacts are complete before proceeding46124613## Completion Criteria4614- All planning questions answered and ambiguities resolved4615- Story plan explicitly approved by user4616- All steps in story generation plan marked [x]4617- All story artifacts generated according to plan (stories.md, personas.md)4618- Generated stories explicitly approved by user4619- Stories verified and ready for next stage4620<!-- forgecat:@forgecat/awslabs_aidlc-workflows:user-stories:end -->46214622<!-- forgecat:@forgecat/awslabs_aidlc-workflows:workflow-planning:start -->4623# Workflow Planning46244625**Purpose**: Determine which phases to execute and create comprehensive execution plan46264627**Always Execute**: This phase always runs after understanding requirements and scope46284629## Step 1: Load All Prior Context46304631### 1.1 Load Reverse Engineering Artifacts (if brownfield)4632- architecture.md4633- component-inventory.md4634- technology-stack.md4635- dependencies.md46364637### 1.2 Load Requirements Analysis4638- requirements.md (includes intent analysis)4639- requirement-verification-questions.md (with answers)46404641### 1.3 Load User Stories (if executed)4642- stories.md4643- personas.md46444645## Step 2: Detailed Scope and Impact Analysis46464647**Now that we have complete context (requirements + stories), perform detailed analysis:**46484649### 2.1 Transformation Scope Detection (Brownfield Only)46504651**IF brownfield project**, analyze transformation scope:46524653#### Architectural Transformation4654- **Single component change** vs **architectural transformation**4655- **Infrastructure changes** vs **application changes**4656- **Deployment model changes** (Lambda→Container, EC2→Serverless, etc.)46574658#### Related Component Identification4659For transformations, identify:4660- **Infrastructure code** that needs updates4661- **CDK stacks** requiring changes4662- **API Gateway** configurations4663- **Load balancer** requirements4664- **Networking** changes needed4665- **Monitoring/logging** adaptations46664667#### Cross-Package Impact4668- **CDK infrastructure** packages requiring updates4669- **Shared models** needing version updates4670- **Client libraries** requiring endpoint changes4671- **Test packages** needing new test scenarios46724673### 2.2 Change Impact Assessment46744675#### Impact Areas46761. **User-facing changes**: Does this affect user experience?46772. **Structural changes**: Does this change system architecture?46783. **Data model changes**: Does this affect database schemas or data structures?46794. **API changes**: Does this affect interfaces or contracts?46805. **NFR impact**: Does this affect performance, security, or scalability?46814682#### Application Layer Impact (if applicable)4683- **Code changes**: New entry points, adapters, configurations4684- **Dependencies**: New libraries, framework changes4685- **Configuration**: Environment variables, config files4686- **Testing**: Unit tests, integration tests46874688#### Infrastructure Layer Impact (if applicable)4689- **Deployment model**: Lambda→ECS, EC2→Fargate, etc.4690- **Networking**: VPC, security groups, load balancers4691- **Storage**: Persistent volumes, shared storage4692- **Scaling**: Auto-scaling policies, capacity planning46934694#### Operations Layer Impact (if applicable)4695- **Monitoring**: CloudWatch, custom metrics, dashboards4696- **Logging**: Log aggregation, structured logging4697- **Alerting**: Alarm configurations, notification channels4698- **Deployment**: CI/CD pipeline changes, rollback strategies46994700### 2.3 Component Relationship Mapping (Brownfield Only)47014702**IF brownfield project**, create component dependency graph:47034704```markdown4705## Component Relationships4706- **Primary Component**: [Package being changed]4707- **Infrastructure Components**: [CDK/Terraform packages]4708- **Shared Components**: [Models, utilities, clients]4709- **Dependent Components**: [Services that call this component]4710- **Supporting Components**: [Monitoring, logging, deployment]4711```47124713For each related component:4714- **Change Type**: Major, Minor, Configuration-only4715- **Change Reason**: Direct dependency, deployment model, networking4716- **Change Priority**: Critical, Important, Optional47174718### 2.4 Risk Assessment47194720Evaluate risk level:47211. **Low**: Isolated change, easy rollback, well-understood47222. **Medium**: Multiple components, moderate rollback, some unknowns47233. **High**: System-wide impact, complex rollback, significant unknowns47244. **Critical**: Production-critical, difficult rollback, high uncertainty47254726## Step 3: Phase Determination47274728### 3.1 User Stories - Already Executed or Skip?4729**Already executed**: Move to next determination4730**Not executed - Execute IF**:4731- Multiple user personas4732- User experience impact4733- Acceptance criteria needed4734- Team collaboration required47354736**Skip IF**:4737- Internal refactoring4738- Bug fix with clear reproduction4739- Technical debt reduction4740- Infrastructure changes47414742### 3.2 Application Design - Execute IF:4743- New components or services needed4744- Component methods and business rules need definition4745- Service layer design required4746- Component dependencies need clarification47474748**Skip IF**:4749- Changes within existing component boundaries4750- No new components or methods4751- Pure implementation changes47524753### 3.3 Design (Units Planning/Generation) - Execute IF:4754- New data models or schemas4755- API changes or new endpoints4756- Complex algorithms or business logic4757- State management changes4758- Multiple packages require changes4759- Infrastructure-as-code updates needed47604761**Skip IF**:4762- Simple logic changes4763- UI-only changes4764- Configuration updates4765- Straightforward implementations47664767### 3.4 NFR Implementation - Execute IF:4768- Performance requirements4769- Security considerations4770- Scalability concerns4771- Monitoring/observability needed47724773**Skip IF**:4774- Existing NFR setup sufficient4775- No new NFR requirements4776- Simple changes with no NFR impact47774778## Step 4: Note Adaptive Detail47794780**See [depth-levels.md](../common/depth-levels.md) for adaptive depth explanation**47814782For each stage that will execute:4783- All defined artifacts will be created4784- Detail level within artifacts adapts to problem complexity4785- Model determines appropriate detail based on problem characteristics47864787## Step 5: Multi-Module Coordination Analysis (Brownfield Only)47884789**IF brownfield with multiple modules/packages**, analyze dependencies and determine optimal update strategy:47904791### 5.1 Analyze Module Dependencies4792- Examine build system dependencies and dependency manifests4793- Identify build-time vs runtime dependencies4794- Map API contracts and shared interfaces between modules47954796### 5.2 Determine Update Strategy4797Based on dependency analysis, decide:4798- **Update sequence**: Which modules must be updated first due to dependencies4799- **Parallelization opportunities**: Which modules can be updated simultaneously4800- **Coordination requirements**: Version compatibility, API contracts, deployment order4801- **Testing strategy**: Per-module vs integrated testing approach4802- **Rollback strategy**: Recovery plan if mid-sequence failures occur48034804### 5.3 Document Coordination Plan4805```markdown4806## Module Update Strategy4807- **Update Approach**: [Sequential/Parallel/Hybrid]4808- **Critical Path**: [Modules that block other updates]4809- **Coordination Points**: [Shared APIs, infrastructure, data contracts]4810- **Testing Checkpoints**: [When to validate integration]4811```48124813Identify for each affected module:4814- **Update priority**: Must-update-first vs can-update-later4815- **Dependency constraints**: What it depends on, what depends on it4816- **Change scope**: Major (breaking), Minor (compatible), Patch (fixes)48174818## Step 6: Generate Workflow Visualization48194820Create Mermaid flowchart showing:4821- All phases in sequence4822- EXECUTE or SKIP decision for each conditional phase4823- Proper styling for each phase state48244825**Styling rules** (add after flowchart):4826```4827style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff4828style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff4829style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff4830style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#0004831style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#0004832style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#00048334834linkStyle default stroke:#333,stroke-width:2px4835```48364837**Style Guidelines**:4838- Completed/Always execute: `fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff` (Material Green with white text)4839- Conditional EXECUTE: `fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000` (Material Orange with black text)4840- Conditional SKIP: `fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000` (Material Gray with black text)4841- Start/End: `fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000` (Material Purple with black text)4842- Phase containers: Use lighter Material colors (INCEPTION: #BBDEFB, CONSTRUCTION: #C8E6C9, OPERATIONS: #FFF59D)48434844## Step 7: Create Execution Plan Document48454846Create `aidlc-docs/inception/plans/execution-plan.md`:48474848```markdown4849# Execution Plan48504851## Detailed Analysis Summary48524853### Transformation Scope (Brownfield Only)4854- **Transformation Type**: [Single component/Architectural/Infrastructure]4855- **Primary Changes**: [Description]4856- **Related Components**: [List]48574858### Change Impact Assessment4859- **User-facing changes**: [Yes/No - Description]4860- **Structural changes**: [Yes/No - Description]4861- **Data model changes**: [Yes/No - Description]4862- **API changes**: [Yes/No - Description]4863- **NFR impact**: [Yes/No - Description]48644865### Component Relationships (Brownfield Only)4866[Component dependency graph]48674868### Risk Assessment4869- **Risk Level**: [Low/Medium/High/Critical]4870- **Rollback Complexity**: [Easy/Moderate/Difficult]4871- **Testing Complexity**: [Simple/Moderate/Complex]48724873## Workflow Visualization48744875```mermaid4876flowchart TD4877 Start(["User Request"])48784879 subgraph INCEPTION["🔵 INCEPTION PHASE"]4880 WD["Workspace Detection<br/><b>STATUS</b>"]4881 RE["Reverse Engineering<br/><b>STATUS</b>"]4882 RA["Requirements Analysis<br/><b>STATUS</b>"]4883 US["User Stories<br/><b>STATUS</b>"]4884 WP["Workflow Planning<br/><b>STATUS</b>"]4885 AD["Application Design<br/><b>STATUS</b>"]4886 UP["Units Planning<br/><b>STATUS</b>"]4887 UG["Units Generation<br/><b>STATUS</b>"]4888 end48894890 subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]4891 FD["Functional Design<br/><b>STATUS</b>"]4892 NFRA["NFR Requirements<br/><b>STATUS</b>"]4893 NFRD["NFR Design<br/><b>STATUS</b>"]4894 ID["Infrastructure Design<br/><b>STATUS</b>"]4895 CG["Code Generation<br/>(Planning + Generation)<br/><b>EXECUTE</b>"]4896 BT["Build and Test<br/><b>EXECUTE</b>"]4897 end48984899 subgraph OPERATIONS["🟡 OPERATIONS PHASE"]4900 OPS["Operations<br/><b>PLACEHOLDER</b>"]4901 end49024903 Start --> WD4904 WD --> RA4905 RA --> WP4906 WP --> CG4907 CG --> BT4908 BT --> End(["Complete"])49094910 %% Replace STATUS with COMPLETED, SKIP, EXECUTE as appropriate4911 %% Apply styling based on status4912```49134914**Note**: Replace STATUS placeholders with actual phase status (COMPLETED/SKIP/EXECUTE) and apply appropriate styling49154916## Phases to Execute49174918### 🔵 INCEPTION PHASE4919- [x] Workspace Detection (COMPLETED)4920- [x] Reverse Engineering (COMPLETED/SKIPPED)4921- [x] Requirements Analysis (COMPLETED)4922- [x] User Stories (COMPLETED/SKIPPED)4923- [x] Execution Plan (IN PROGRESS)4924- [ ] Application Design - [EXECUTE/SKIP]4925 - **Rationale**: [Why executing or skipping]4926- [ ] Units Planning - [EXECUTE/SKIP]4927 - **Rationale**: [Why executing or skipping]4928- [ ] Units Generation - [EXECUTE/SKIP]4929 - **Rationale**: [Why executing or skipping]49304931### 🟢 CONSTRUCTION PHASE4932- [ ] Functional Design - [EXECUTE/SKIP]4933 - **Rationale**: [Why executing or skipping]4934- [ ] NFR Requirements - [EXECUTE/SKIP]4935 - **Rationale**: [Why executing or skipping]4936- [ ] NFR Design - [EXECUTE/SKIP]4937 - **Rationale**: [Why executing or skipping]4938- [ ] Infrastructure Design - [EXECUTE/SKIP]4939 - **Rationale**: [Why executing or skipping]4940- [ ] Code Generation - EXECUTE (ALWAYS)4941 - **Rationale**: Implementation planning and code generation needed4942- [ ] Build and Test - EXECUTE (ALWAYS)4943 - **Rationale**: Build, test, and verification needed49444945### 🟡 OPERATIONS PHASE4946- [ ] Operations - PLACEHOLDER4947 - **Rationale**: Future deployment and monitoring workflows49484949## Package Change Sequence (Brownfield Only)4950[If applicable, list package update sequence with dependencies]49514952## Estimated Timeline4953- **Total Phases**: [Number]4954- **Estimated Duration**: [Time estimate]49554956## Success Criteria4957- **Primary Goal**: [Main objective]4958- **Key Deliverables**: [List]4959- **Quality Gates**: [List]49604961[IF brownfield]4962- **Integration Testing**: All components working together4963- **Operational Readiness**: Monitoring, logging, alerting working4964```49654966## Step 8: Initialize State Tracking49674968Update `aidlc-docs/aidlc-state.md`:49694970```markdown4971# AI-DLC State Tracking49724973## Project Information4974- **Project Type**: [Greenfield/Brownfield]4975- **Start Date**: [ISO timestamp]4976- **Current Stage**: INCEPTION - Workflow Planning49774978## Execution Plan Summary4979- **Total Stages**: [Number]4980- **Stages to Execute**: [List]4981- **Stages to Skip**: [List with reasons]49824983## Stage Progress49844985### 🔵 INCEPTION PHASE4986- [x] Workspace Detection4987- [x] Reverse Engineering (if applicable)4988- [x] Requirements Analysis4989- [x] User Stories (if applicable)4990- [x] Workflow Planning4991- [ ] Application Design - [EXECUTE/SKIP]4992- [ ] Units Planning - [EXECUTE/SKIP]4993- [ ] Units Generation - [EXECUTE/SKIP]49944995### 🟢 CONSTRUCTION PHASE4996- [ ] Functional Design - [EXECUTE/SKIP]4997- [ ] NFR Requirements - [EXECUTE/SKIP]4998- [ ] NFR Design - [EXECUTE/SKIP]4999- [ ] Infrastructure Design - [EXECUTE/SKIP]5000- [ ] Code Generation - EXECUTE5001- [ ] Build and Test - EXECUTE50025003### 🟡 OPERATIONS PHASE5004- [ ] Operations - PLACEHOLDER50055006## Current Status5007- **Lifecycle Phase**: INCEPTION5008- **Current Stage**: Workflow Planning Complete5009- **Next Stage**: [Next stage to execute]5010- **Status**: Ready to proceed5011```50125013## Step 9: Present Plan to User50145015```markdown5016# 📋 Workflow Planning Complete50175018I've created a comprehensive execution plan based on:5019- Your request: [Summary]5020- Existing system: [Summary if brownfield]5021- Requirements: [Summary if executed]5022- User stories: [Summary if executed]50235024**Detailed Analysis**:5025- Risk level: [Level]5026- Impact: [Summary of key impacts]5027- Components affected: [List]50285029**Recommended Execution Plan**:50305031I recommend executing [X] stages:50325033🔵 **INCEPTION PHASE:**50341. [Stage name] - *Rationale:* [Why executing]50352. [Stage name] - *Rationale:* [Why executing]5036...50375038🟢 **CONSTRUCTION PHASE:**50393. [Stage name] - *Rationale:* [Why executing]50404. [Stage name] - *Rationale:* [Why executing]5041...50425043I recommend skipping [Y] stages:50445045🔵 **INCEPTION PHASE:**50461. [Stage name] - *Rationale:* [Why skipping]50472. [Stage name] - *Rationale:* [Why skipping]5048...50495050🟢 **CONSTRUCTION PHASE:**50513. [Stage name] - *Rationale:* [Why skipping]50524. [Stage name] - *Rationale:* [Why skipping]5053...50545055[IF brownfield with multiple packages]5056**Recommended Package Update Sequence**:50571. [Package] - [Reason]50582. [Package] - [Reason]5059...50605061**Estimated Timeline**: [Duration]50625063> **📋 <u>**REVIEW REQUIRED:**</u>**5064> Please examine the execution plan at: `aidlc-docs/inception/plans/execution-plan.md`50655066> **🚀 <u>**WHAT'S NEXT?**</u>**5067>5068> **You may:**5069>5070> 🔧 **Request Changes** - Ask for modifications to the execution plan if required5071> [IF any stages are skipped:]5072> 📝 **Add Skipped Stages** - Choose to include stages currently marked as SKIP5073> ✅ **Approve & Continue** - Approve plan and proceed to **[5074```
One repository carrying more than one format is the comparison this product exists for: does anyone actually write different content in each file, or is one a copy of the other?
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-build.mdc · 51 | Cursor rules | no sections | 16/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-code-simplify.mdc · 51 | Cursor rules | testing-strategy | 30/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-plan.mdc · 51 | Cursor rules | no sections | 16/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-review.mdc · 51 | Cursor rules | no sections | 16/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-ship.mdc · 51 | Cursor rules | testing-strategygitdeploymentdo-not | 61/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-spec.mdc · 51 | Cursor rules | no sections | 16/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-test.mdc · 51 | Cursor rules | no sections | 16/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-forgecat/AGENTS.md · 51 | AGENTS.md | lint-formatstylearchdo-not | 73/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-forgecat/CLAUDE.md · 51 | CLAUDE.md | teststylearchagent-behaviour | 70/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-cancel-ralph.mdc · 51 | Cursor rules | no sections | 16/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-help.mdc · 51 | Cursor rules | no sections | 54/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-ralph-loop.mdc · 51 | Cursor rules | no sections | 22/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_agent-sdk-dev/for-cursor/.cursor/rules/cmd-new-sdk-app.mdc · 51 | Cursor rules | setupstylearchdocs | 76/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_claude-md-management/for-cursor/.cursor/rules/cmd-revise-claude-md.mdc · 51 | Cursor rules | agent-behaviour | 50/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_code-review/for-cursor/.cursor/rules/cmd-code-review.mdc · 51 | Cursor rules | testing-strategygit | 35/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-clean_gone.mdc · 51 | Cursor rules | no sections | 60/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-commit-push-pr.mdc · 51 | Cursor rules | stylegit | 44/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-commit.mdc · 51 | Cursor rules | style | 44/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_example-plugin/for-cursor/.cursor/rules/cmd-example-command.mdc · 51 | Cursor rules | lint-formatstyleagent-behaviour | 58/100 | today | |
| nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_feature-dev/for-cursor/.cursor/rules/cmd-feature-dev.mdc · 51 | Cursor rules | stylearchgit | 56/100 | today |
Same format, overlapping stack, ranked by quality.
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| vllm-project/vllmAGENTS.md · 89k | AGENTS.md | setuptestlint-formatstyle+5 | 100/100 | 14 days ago | |
| code-yeongyu/oh-my-openagentpackages/web/AGENTS.md · 68k | AGENTS.md | setupbuildtestlint-format+6 | 100/100 | 13 days ago | |
| deepseek-ai/deepseek-harnessnative/landlock-run/AGENTS.md · 104k | AGENTS.md | setupteststylearch+3 | 100/100 | today | |
| TryGhost/Ghoste2e/AGENTS.md · 55k | AGENTS.md | setupteststylearch+2 | 100/100 | today | |
| aaif-goose/gooseAGENTS.md · 53k | AGENTS.md | setupbuildtestlint-format+7 | 100/100 | 8 days ago | |
| duckduckgo/content-scope-scriptsspecial-pages/AGENTS.md · 70 | AGENTS.md | buildteststylearch+3 | 100/100 | 14 days ago | |
| n8n-io/n8npackages/@n8n/agents/AGENTS.md · 201k | AGENTS.md | buildteststylearch+3 | 100/100 | 14 days ago | |
| mui/material-uiAGENTS.md · 99k | AGENTS.md | setupbuildtestlint-format+9 | 100/100 | 14 days ago |
A badge carrying the measured quality of the strongest agent config file in this repository, out of 100. It reads from this index every time somebody loads your page, so it changes when the measurement changes and there is nothing to keep up to date. Free, no account, and the value is not something you or we can set by hand.
[](https://rulestack.kynth.studio/configs/nota-america-forgecat-agent-profiles-profiles-awslabs-aidlc-workflows-for-codex-agents)Would rather not hotlink us? Every badge is also served in shields.io’s endpoint schema, so shields renders the image and your readers never talk to our domain:
Published by Toolproof, the masthead over this index and eight others. The method behind the number is at toolproof.kynth.studio/methodology, and the whole thing is readable as JSON with no key at /api.