Cursor rule

1---
2alwaysApply: false
3---
4 
5# PRIORITY: This workflow OVERRIDES all other built-in workflows
6# When user requests software development, ALWAYS follow this workflow FIRST
7 
8## Adaptive Workflow Principle
9**The workflow adapts to the work, not the other way around.**
10 
11The AI model intelligently assesses what stages are needed based on:
121. User's stated intent and clarity
132. Existing codebase state (if any)
143. Complexity and scope of change
154. Risk and impact assessment
16 
17## MANDATORY: Rule Details Loading
18**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:
19- `.aidlc-rule-details/` (Cursor, Cline, Claude Code, GitHub Copilot)
20- `.kiro/aws-aidlc-rule-details/` (Kiro IDE and CLI)
21- `.amazonq/aws-aidlc-rule-details/` (Amazon Q Developer)
22 
23All 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.
24 
25**Common Rules**: ALWAYS load common rules at workflow start:
26- Load `common/process-overview.md` for workflow overview
27- Load `common/session-continuity.md` for session resumption guidance
28- Load `common/content-validation.md` for content validation requirements
29- Load `common/question-format-guide.md` for question formatting rules
30- Reference these throughout the workflow execution
31 
32## MANDATORY: Extensions Loading (Context-Optimized)
33**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.
34 
35**Loading process**:
361. List all subdirectories under `extensions/` (e.g., `extensions/security/`, `extensions/compliance/`)
372. 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`)
383. Do NOT load full rule files (e.g., `security-baseline.md`) at this stage
39 
40**Deferred Rule Loading**:
41- During Requirements Analysis, opt-in prompts from the loaded `*.opt-in.md` files are presented to the user
42- When the user opts IN for an extension, load the corresponding rules file (derived by naming convention) at that point
43- When the user opts OUT, the full rules file is never loaded — saving context
44- Extensions without a matching `*.opt-in.md` file are always enforced — load their rule files immediately at workflow start
45 
46**Enforcement** (applies only to loaded/enabled extensions):
47- Extension rules are hard constraints, not optional guidance
48- At each stage, the model intelligently evaluates which extension rules are applicable based on the stage's purpose, the artifacts being produced, and the context of the work — enforce only those rules that are relevant
49- 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)
50- Non-compliance with any applicable enabled extension rule is a **blocking finding** — do NOT present stage completion until resolved
51- 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)
52 
53**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. 
54 
55## MANDATORY: Content Validation
56**CRITICAL**: Before creating ANY file, you MUST validate content according to `common/content-validation.md` rules:
57- Validate Mermaid diagram syntax
58- Validate ASCII art diagrams (see `common/ascii-diagram-standards.md`)
59- Escape special characters properly
60- Provide text alternatives for complex visual content
61- Test content parsing compatibility
62 
63## MANDATORY: Question File Format
64**CRITICAL**: When asking questions at any phase, you MUST follow question format guidelines.
65 
66**See `common/question-format-guide.md` for complete question formatting rules including**:
67- Multiple choice format (A, B, C, D, E options)
68- [Answer]: tag usage
69- Answer validation and ambiguity resolution
70 
71## MANDATORY: Custom Welcome Message
72**CRITICAL**: When starting ANY software development request, you MUST display the welcome message.
73 
74**How to Display Welcome Message**:
751. Load the welcome message from `common/welcome-message.md` (in the resolved rule details directory)
762. Display the complete message to the user
773. This should only be done ONCE at the start of a new workflow
784. Do NOT load this file in subsequent interactions to save context space
79 
80# Adaptive Software Development Workflow
81 
82---
83 
84# INCEPTION PHASE
85 
86**Purpose**: Planning, requirements gathering, and architectural decisions
87 
88**Focus**: Determine WHAT to build and WHY
89 
90**Stages in INCEPTION PHASE**:
91- Workspace Detection (ALWAYS)
92- Reverse Engineering (CONDITIONAL - Brownfield only)
93- Requirements Analysis (ALWAYS - Adaptive depth)
94- User Stories (CONDITIONAL)
95- Workflow Planning (ALWAYS)
96- Application Design (CONDITIONAL)
97- Units Generation (CONDITIONAL)
98 
99---
100 
101## Workspace Detection (ALWAYS EXECUTE)
102 
1031. **MANDATORY**: Log initial user request in audit.md with complete raw input
1042. Load all steps from `inception/workspace-detection.md`
1053. Execute workspace detection:
106   - Check for existing aidlc-state.md (resume if found)
107   - Scan workspace for existing code
108   - Determine if brownfield or greenfield
109   - Check for existing reverse engineering artifacts
1104. Determine next phase: Reverse Engineering (if brownfield and no artifacts) OR Requirements Analysis
1115. **MANDATORY**: Log findings in audit.md
1126. Present completion message to user (see workspace-detection.md for message formats)
1137. Automatically proceed to next phase
114 
115## Reverse Engineering (CONDITIONAL - Brownfield Only)
116 
117**Execute IF**:
118- Existing codebase detected
119- No previous reverse engineering artifacts found
120 
121**Skip IF**:
122- Greenfield project
123- Previous reverse engineering artifacts exist
124 
125**Execution**:
1261. **MANDATORY**: Log start of reverse engineering in audit.md
1272. Load all steps from `inception/reverse-engineering.md`
1283. Execute reverse engineering:
129   - Analyze all packages and components
130   - Generate a business overview of the whole system covering the business transactions
131   - Generate architecture documentation
132   - Generate code structure documentation
133   - Generate API documentation
134   - Generate component inventory
135   - Generate Interaction Diagrams depicting how business transactions are implemented across components
136   - Generate technology stack documentation
137   - Generate dependencies documentation
138 
1394. **Wait for Explicit Approval**: Present detailed completion message (see reverse-engineering.md for message format) - DO NOT PROCEED until user confirms
1405. **MANDATORY**: Log user's response in audit.md with complete raw input
141 
142## Requirements Analysis (ALWAYS EXECUTE - Adaptive Depth)
143 
144**Always executes** but depth varies based on request clarity and complexity:
145- **Minimal**: Simple, clear request - just document intent analysis
146- **Standard**: Normal complexity - gather functional and non-functional requirements
147- **Comprehensive**: Complex, high-risk - detailed requirements with traceability
148 
149**Execution**:
1501. **MANDATORY**: Log any user input during this phase in audit.md
1512. Load all steps from `inception/requirements-analysis.md`
1523. Execute requirements analysis:
153   - Load reverse engineering artifacts (if brownfield)
154   - Analyze user request (intent analysis)
155   - Determine requirements depth needed
156   - Assess current requirements
157   - Ask clarifying questions (if needed)
158   - Generate requirements document
1594. Execute at appropriate depth (minimal/standard/comprehensive)
1605. **Wait for Explicit Approval**: Follow approval format from requirements-analysis.md detailed steps - DO NOT PROCEED until user confirms
1616. **MANDATORY**: Log user's response in audit.md with complete raw input
162 
163## User Stories (CONDITIONAL)
164 
165**INTELLIGENT ASSESSMENT**: Use multi-factor analysis to determine if user stories add value:
166 
167**ALWAYS Execute IF** (High Priority Indicators):
168- New user-facing features or functionality
169- Changes affecting user workflows or interactions
170- Multiple user types or personas involved
171- Complex business requirements with acceptance criteria needs
172- Cross-functional team collaboration required
173- Customer-facing API or service changes
174- New product capabilities or enhancements
175 
176**LIKELY Execute IF** (Medium Priority - Assess Complexity):
177- Modifications to existing user-facing features
178- Backend changes that indirectly affect user experience
179- Integration work that impacts user workflows
180- Performance improvements with user-visible benefits
181- Security enhancements affecting user interactions
182- Data model changes affecting user data or reports
183 
184**COMPLEXITY-BASED ASSESSMENT**: For medium priority cases, execute user stories if:
185- Request involves multiple components or services
186- Changes span multiple user touchpoints
187- Business logic is complex or has multiple scenarios
188- Requirements have ambiguity that stories could clarify
189- Implementation affects multiple user journeys
190- Change has significant business impact or risk
191 
192**SKIP ONLY IF** (Low Priority - Simple Cases):
193- Pure internal refactoring with zero user impact
194- Simple bug fixes with clear, isolated scope
195- Infrastructure changes with no user-facing effects
196- Technical debt cleanup with no functional changes
197- Developer tooling or build process improvements
198- Documentation-only updates
199 
200**ASSESSMENT CRITERIA**: When in doubt, favor inclusion of user stories for:
201- Requests with business stakeholder involvement
202- Changes requiring user acceptance testing
203- Features with multiple implementation approaches
204- Work that benefits from shared team understanding
205- Projects where requirements clarity is valuable
206 
207**ASSESSMENT PROCESS**: 
2081. Analyze request complexity and scope
2092. Identify user impact (direct or indirect)
2103. Evaluate business context and stakeholder needs
2114. Consider team collaboration benefits
2125. Default to inclusion for borderline cases
213 
214**Note**: If Requirements Analysis executed, Stories can reference and build upon those requirements.
215 
216**User Stories has two parts within one stage**:
2171. **Part 1 - Planning**: Create story plan with questions, collect answers, analyze for ambiguities, get approval
2182. **Part 2 - Generation**: Execute approved plan to generate stories and personas
219 
220**Execution**:
2211. **MANDATORY**: Log any user input during this phase in audit.md
2222. Load all steps from `inception/user-stories.md`
2233. **MANDATORY**: Perform intelligent assessment (Step 1 in user-stories.md) to validate user stories are needed
2244. Load reverse engineering artifacts (if brownfield)
2255. If Requirements exist, reference them when creating stories
2266. Execute at appropriate depth (minimal/standard/comprehensive)
2277. **PART 1 - Planning**: Create story plan with questions, wait for user answers, analyze for ambiguities, get approval
2288. **PART 2 - Generation**: Execute approved plan to generate stories and personas
2299. **Wait for Explicit Approval**: Follow approval format from user-stories.md detailed steps - DO NOT PROCEED until user confirms
23010. **MANDATORY**: Log user's response in audit.md with complete raw input
231 
232## Workflow Planning (ALWAYS EXECUTE)
233 
2341. **MANDATORY**: Log any user input during this phase in audit.md
2352. Load all steps from `inception/workflow-planning.md`
2363. **MANDATORY**: Load content validation rules from `common/content-validation.md`
2374. Load all prior context:
238   - Reverse engineering artifacts (if brownfield)
239   - Intent analysis
240   - Requirements (if executed)
241   - User stories (if executed)
2425. Execute workflow planning:
243   - Determine which phases to execute
244   - Determine depth level for each phase
245   - Create multi-package change sequence (if brownfield)
246   - Generate workflow visualization (VALIDATE Mermaid syntax before writing)
2476. **MANDATORY**: Validate all content before file creation per content-validation.md rules
2487. **Wait for Explicit Approval**: Present recommendations using language from workflow-planning.md Step 9, emphasizing user control to override recommendations - DO NOT PROCEED until user confirms
2498. **MANDATORY**: Log user's response in audit.md with complete raw input
250 
251## Application Design (CONDITIONAL)
252 
253**Execute IF**:
254- New components or services needed
255- Component methods and business rules need definition
256- Service layer design required
257- Component dependencies need clarification
258 
259**Skip IF**:
260- Changes within existing component boundaries
261- No new components or methods
262- Pure implementation changes
263 
264**Execution**:
2651. **MANDATORY**: Log any user input during this phase in audit.md
2662. Load all steps from `inception/application-design.md`
2673. Load reverse engineering artifacts (if brownfield)
2684. Execute at appropriate depth (minimal/standard/comprehensive)
2695. **Wait for Explicit Approval**: Present detailed completion message (see application-design.md for message format) - DO NOT PROCEED until user confirms
2706. **MANDATORY**: Log user's response in audit.md with complete raw input
271 
272## Units Generation (CONDITIONAL)
273 
274**Execute IF**:
275- System needs decomposition into multiple units of work
276- Multiple services or modules required
277- Complex system requiring structured breakdown
278 
279**Skip IF**:
280- Single simple unit
281- No decomposition needed
282- Straightforward single-component implementation
283 
284**Execution**:
2851. **MANDATORY**: Log any user input during this phase in audit.md
2862. Load all steps from `inception/units-generation.md`
2873. Load reverse engineering artifacts (if brownfield)
2884. Execute at appropriate depth (minimal/standard/comprehensive)
2895. **Wait for Explicit Approval**: Present detailed completion message (see units-generation.md for message format) - DO NOT PROCEED until user confirms
2906. **MANDATORY**: Log user's response in audit.md with complete raw input
291 
292---
293 
294# 🟢 CONSTRUCTION PHASE
295 
296**Purpose**: Detailed design, NFR implementation, and code generation
297 
298**Focus**: Determine HOW to build it
299 
300**Stages in CONSTRUCTION PHASE**:
301- Per-Unit Loop (executes for each unit):
302  - Functional Design (CONDITIONAL, per-unit)
303  - NFR Requirements (CONDITIONAL, per-unit)
304  - NFR Design (CONDITIONAL, per-unit)
305  - Infrastructure Design (CONDITIONAL, per-unit)
306  - Code Generation (ALWAYS, per-unit)
307- Build and Test (ALWAYS - after all units complete)
308 
309**Note**: Each unit is completed fully (design + code) before moving to the next unit.
310 
311---
312 
313## Per-Unit Loop (Executes for Each Unit)
314 
315**For each unit of work, execute the following stages in sequence:**
316 
317### Functional Design (CONDITIONAL, per-unit)
318 
319**Execute IF**:
320- New data models or schemas
321- Complex business logic
322- Business rules need detailed design
323 
324**Skip IF**:
325- Simple logic changes
326- No new business logic
327 
328**Execution**:
3291. **MANDATORY**: Log any user input during this stage in audit.md
3302. Load all steps from `construction/functional-design.md`
3313. Execute functional design for this unit
3324. **MANDATORY**: Present standardized 2-option completion message as defined in functional-design.md - DO NOT use emergent 3-option behavior
3335. **Wait for Explicit Approval**: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms
3346. **MANDATORY**: Log user's response in audit.md with complete raw input
335 
336### NFR Requirements (CONDITIONAL, per-unit)
337 
338**Execute IF**:
339- Performance requirements exist
340- Security considerations needed
341- Scalability concerns present
342- Tech stack selection required
343 
344**Skip IF**:
345- No NFR requirements
346- Tech stack already determined
347 
348**Execution**:
3491. **MANDATORY**: Log any user input during this stage in audit.md
3502. Load all steps from `construction/nfr-requirements.md`
3513. Execute NFR assessment for this unit
3524. **MANDATORY**: Present standardized 2-option completion message as defined in nfr-requirements.md - DO NOT use emergent behavior
3535. **Wait for Explicit Approval**: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms
3546. **MANDATORY**: Log user's response in audit.md with complete raw input
355 
356### NFR Design (CONDITIONAL, per-unit)
357 
358**Execute IF**:
359- NFR Requirements was executed
360- NFR patterns need to be incorporated
361 
362**Skip IF**:
363- No NFR requirements
364- NFR Requirements was skipped
365 
366**Execution**:
3671. **MANDATORY**: Log any user input during this stage in audit.md
3682. Load all steps from `construction/nfr-design.md`
3693. Execute NFR design for this unit
3704. **MANDATORY**: Present standardized 2-option completion message as defined in nfr-design.md - DO NOT use emergent behavior
3715. **Wait for Explicit Approval**: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms
3726. **MANDATORY**: Log user's response in audit.md with complete raw input
373 
374### Infrastructure Design (CONDITIONAL, per-unit)
375 
376**Execute IF**:
377- Infrastructure services need mapping
378- Deployment architecture required
379- Cloud resources need specification
380 
381**Skip IF**:
382- No infrastructure changes
383- Infrastructure already defined
384 
385**Execution**:
3861. **MANDATORY**: Log any user input during this stage in audit.md
3872. Load all steps from `construction/infrastructure-design.md`
3883. Execute infrastructure design for this unit
3894. **MANDATORY**: Present standardized 2-option completion message as defined in infrastructure-design.md - DO NOT use emergent behavior
3905. **Wait for Explicit Approval**: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms
3916. **MANDATORY**: Log user's response in audit.md with complete raw input
392 
393### Code Generation (ALWAYS EXECUTE, per-unit)
394 
395**Always executes for each unit**
396 
397**Code Generation has two parts within one stage**:
3981. **Part 1 - Planning**: Create detailed code generation plan with explicit steps
3992. **Part 2 - Generation**: Execute approved plan to generate code, tests, and artifacts
400 
401**Execution**:
4021. **MANDATORY**: Log any user input during this stage in audit.md
4032. Load all steps from `construction/code-generation.md`
4043. **PART 1 - Planning**: Create code generation plan with checkboxes, get user approval
4054. **PART 2 - Generation**: Execute approved plan to generate code for this unit
4065. **MANDATORY**: Present standardized 2-option completion message as defined in code-generation.md - DO NOT use emergent behavior
4076. **Wait for Explicit Approval**: User must choose between "Request Changes" or "Continue to Next Stage" - DO NOT PROCEED until user confirms
4087. **MANDATORY**: Log user's response in audit.md with complete raw input
409 
410---
411 
412## Build and Test (ALWAYS EXECUTE)
413 
4141. **MANDATORY**: Log any user input during this phase in audit.md
4152. Load all steps from `construction/build-and-test.md`
4163. Generate comprehensive build and test instructions:
417   - Build instructions for all units
418   - Unit test execution instructions
419   - Integration test instructions (test interactions between units)
420   - Performance test instructions (if applicable)
421   - Additional test instructions as needed (contract tests, security tests, e2e tests)
4224. Create instruction files in build-and-test/ subdirectory: build-instructions.md, unit-test-instructions.md, integration-test-instructions.md, performance-test-instructions.md, build-and-test-summary.md
4235. **Wait for Explicit Approval**: Ask: "**Build and test instructions complete. Ready to proceed to Operations stage?**" - DO NOT PROCEED until user confirms
4246. **MANDATORY**: Log user's response in audit.md with complete raw input
425 
426---
427 
428# 🟡 OPERATIONS PHASE
429 
430**Purpose**: Placeholder for future deployment and monitoring workflows
431 
432**Focus**: How to DEPLOY and RUN it (future expansion)
433 
434**Stages in OPERATIONS PHASE**:
435- Operations (PLACEHOLDER)
436 
437---
438 
439## Operations (PLACEHOLDER)
440 
441**Status**: This stage is currently a placeholder for future expansion.
442 
443The Operations stage will eventually include:
444- Deployment planning and execution
445- Monitoring and observability setup
446- Incident response procedures
447- Maintenance and support workflows
448- Production readiness checklists
449 
450**Current State**: All build and test activities are handled in the CONSTRUCTION phase.
451 
452## Key Principles
453 
454- **Adaptive Execution**: Only execute stages that add value
455- **Transparent Planning**: Always show execution plan before starting
456- **User Control**: User can request stage inclusion/exclusion
457- **Progress Tracking**: Update aidlc-state.md with executed and skipped stages
458- **Complete Audit Trail**: Log ALL user inputs and AI responses in audit.md with timestamps
459  - **CRITICAL**: Capture user's COMPLETE RAW INPUT exactly as provided
460  - **CRITICAL**: Never summarize or paraphrase user input in audit log
461  - **CRITICAL**: Log every interaction, not just approvals
462- **Quality Focus**: Complex changes get full treatment, simple changes stay efficient
463- **Content Validation**: Always validate content before file creation per content-validation.md rules
464- **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.
465 
466## MANDATORY: Plan-Level Checkbox Enforcement
467 
468### MANDATORY RULES FOR PLAN EXECUTION
4691. **NEVER complete any work without updating plan checkboxes**
4702. **IMMEDIATELY after completing ANY step described in a plan file, mark that step [x]**
4713. **This must happen in the SAME interaction where the work is completed**
4724. **NO EXCEPTIONS**: Every plan step completion MUST be tracked with checkbox updates
473 
474### Two-Level Checkbox Tracking System
475- **Plan-Level**: Track detailed execution progress within each stage
476- **Stage-Level**: Track overall workflow progress in aidlc-state.md
477- **Update immediately**: All progress updates in SAME interaction where work is completed
478 
479## Prompts Logging Requirements
480- **MANDATORY**: Log EVERY user input (prompts, questions, responses) with timestamp in audit.md
481- **MANDATORY**: Capture user's COMPLETE RAW INPUT exactly as provided (never summarize)
482- **MANDATORY**: Log every approval prompt with timestamp before asking the user
483- **MANDATORY**: Record every user response with timestamp after receiving it
484- **CRITICAL**: ALWAYS append changes to EDIT audit.md file, NEVER use tools and commands that completely overwrite its contents
485- **CRITICAL**: NEVER use file writing tools and commands that overwrite the entire contents of audit.md, as this causes duplication
486- Use ISO 8601 format for timestamps (YYYY-MM-DDTHH:MM:SSZ)
487- Include stage context for each entry
488 
489### Audit Log Format:
490```markdown
491## [Stage Name or Interaction Type]
492**Timestamp**: [ISO timestamp]
493**User Input**: "[Complete raw user input - never summarized]"
494**AI Response**: "[AI's response or action taken]"
495**Context**: [Stage, action, or decision made]
496 
497---
498```
499 
500### Correct Tool Usage for audit.md
501 
502✅ CORRECT:
503 
5041. Read the audit.md file
5052. Append/Edit the file to make changes
506 
507❌ WRONG:
508 
5091. Read the audit.md file
5102. Completely overwrite the audit.md with the contents of what you read, plus the new changes you want to add to it
511 
512## Directory Structure
513 
514```text
515<WORKSPACE-ROOT>/                   # ⚠️ APPLICATION CODE HERE
516├── [project-specific structure]    # Varies by project (see code-generation.md)
517│
518├── aidlc-docs/                     # 📄 DOCUMENTATION ONLY
519│   ├── inception/                  # 🔵 INCEPTION PHASE
520│   │   ├── plans/
521│   │   ├── reverse-engineering/    # Brownfield only
522│   │   ├── requirements/
523│   │   ├── user-stories/
524│   │   └── application-design/
525│   ├── construction/               # 🟢 CONSTRUCTION PHASE
526│   │   ├── plans/
527│   │   ├── {unit-name}/
528│   │   │   ├── functional-design/
529│   │   │   ├── nfr-requirements/
530│   │   │   ├── nfr-design/
531│   │   │   ├── infrastructure-design/
532│   │   │   └── code/               # Markdown summaries only
533│   │   └── build-and-test/
534│   ├── operations/                 # 🟡 OPERATIONS PHASE (placeholder)
535│   ├── aidlc-state.md
536│   └── audit.md
537```
538 
539**CRITICAL RULE**:
540- Application code: Workspace root (NEVER in aidlc-docs/)
541- Documentation: aidlc-docs/ only
542- Project structure: See code-generation.md for patterns by project type
543