docs: comprehensive documentation review and remediation

README.md

@@ -3,6 +3,7 @@
 > [!IMPORTANT]
 > Generative AI can make mistakes. You should consider reviewing all output and costs generated by your chosen AI model and agentic coding assistant. See [AWS Responsible AI Policy](https://aws.amazon.com/ai/responsible-ai/policy/).
 
+<!-- TODO: Replace this Amplify URL with a permanent/stable URL when available -->
 AI-DLC is an intelligent software development workflow that adapts to your needs, maintains quality standards, and keeps you in control of the process. For learning more about AI-DLC Methodology, read this [blog](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/) and the [Method Definition Paper](https://prod.d13rzhkk8cj2z0.amplifyapp.com/) referred in it.
 
 ## Table of Contents
@@ -16,7 +17,10 @@ AI-DLC is an intelligent software development workflow that adapts to your needs
 - [Tenets](#tenets)
 - [Prerequisites](#prerequisites)
 - [Troubleshooting](#troubleshooting)
+- [Version Control Recommendations](#version-control-recommendations)
 - [Additional Resources](#additional-resources)
+- [Security](#security)
+- [License](#license)
 
 ---
 
@@ -38,6 +42,7 @@ AI-DLC is an intelligent software development workflow that adapts to your needs
   - [Cline](#cline)
   - [Claude Code](#claude-code)
   - [GitHub Copilot](#github-copilot)
+  - [Other Agents](#other-agents)
 
 ---
 
@@ -54,6 +59,13 @@ cp -R ~/Downloads/aidlc-rules/aws-aidlc-rules .kiro/steering/
 cp -R ~/Downloads/aidlc-rules/aws-aidlc-rule-details .kiro/
 ```
 
+On Windows (PowerShell):
+```powershell
+New-Item -ItemType Directory -Force -Path ".kiro\steering"
+Copy-Item -Recurse "$env:USERPROFILE\Downloads\aidlc-rules\aws-aidlc-rules" ".kiro\steering\"
+Copy-Item -Recurse "$env:USERPROFILE\Downloads\aidlc-rules\aws-aidlc-rule-details" ".kiro\"
+```
+
 On Windows (CMD):
 ```cmd
 mkdir .kiro\steering
@@ -72,15 +84,15 @@ Your project should look like:
 
 To verify the rules are loaded:
 
-#### Verify in Kiro IDE 
+#### Verify in Kiro IDE
 
 Open the steering files panel and confirm you see an entry for `core-workflow` under `Workspace` as shown in the screenshot below.
 
 <img src="./assets/images/kiro-ide-aidlc-rules-loaded.png?raw=true" alt="AI-DLC Rules in Kiro IDE" width="700" height="450">
 
 We use Kiro IDE in Vibe mode to run the AI-DLC workflow. This ensures that AI-DLC workflow guides the development workflow in Kiro. At times, Kiro may nudge you to switch to spec mode. Select `No` to such prompts to stay in Vibe mode.
 
-<img src="./assets/images/kiro-sdd-nudge.png" alt="Staying in Kiro Vibe mode" width="500" height="175">
+<img src="./assets/images/kiro-sdd-nudge.png?raw=true" alt="Staying in Kiro Vibe mode" width="500" height="175">
 
 #### Verify in Kiro CLI
 Run `kiro-cli`, then `/context show`, and confirm entries for `.kiro/steering/aws-aidlc-rules`.
@@ -102,6 +114,13 @@ cp -R ~/Downloads/aidlc-rules/aws-aidlc-rules .amazonq/rules/
 cp -R ~/Downloads/aidlc-rules/aws-aidlc-rule-details .amazonq/
 ```
 
+On Windows (PowerShell):
+```powershell
+New-Item -ItemType Directory -Force -Path ".amazonq\rules"
+Copy-Item -Recurse "$env:USERPROFILE\Downloads\aidlc-rules\aws-aidlc-rules" ".amazonq\rules\"
+Copy-Item -Recurse "$env:USERPROFILE\Downloads\aidlc-rules\aws-aidlc-rule-details" ".amazonq\"
+```
+
 On Windows (CMD):
 ```cmd
 mkdir .amazonq\rules
@@ -229,6 +248,7 @@ xcopy "%USERPROFILE%\Downloads\aidlc-rules\aws-aidlc-rule-details" ".aidlc-rule-
     ├── common/
     ├── inception/
     ├── construction/
+    ├── extensions/
     └── operations/
 ```
 
@@ -305,6 +325,7 @@ xcopy "%USERPROFILE%\Downloads\aidlc-rules\aws-aidlc-rule-details" ".aidlc-rule-
     ├── common/
     ├── inception/
     ├── construction/
+    ├── extensions/
     └── operations/
 ```
 
@@ -378,6 +399,7 @@ xcopy "%USERPROFILE%\Downloads\aidlc-rules\aws-aidlc-rule-details" ".aidlc-rule-
     ├── common/
     ├── inception/
     ├── construction/
+    ├── extensions/
     └── operations/
 ```
 
@@ -428,6 +450,7 @@ xcopy "%USERPROFILE%\Downloads\aidlc-rules\aws-aidlc-rule-details" ".aidlc-rule-
     ├── common/
     ├── inception/
     ├── construction/
+    ├── extensions/
     └── operations/
 ```
 
@@ -535,7 +558,7 @@ The workflow currently ships with a baseline security extension.
 aws-aidlc-rule-details/
 └── extensions/
     └── security/                      # Extension category
-        └── baseline/
+        ├── baseline/
         │   └── security-baseline.md   # Baseline security rules
         ├── compliance/                # Proposed folder hierarchy
         │   ├── hipaa/                 # HIPAA compliance rules
@@ -553,7 +576,7 @@ To add rules to an existing category (e.g., security):
 1. Create a new directory under `extensions/security/` (e.g., `compliance/hipaa/`).
 2. Add one or more markdown files with your rules. Follow the same structure as `security-baseline.md`:
    - Give each rule a unique ID.
-   - Include an **Applicabality Question** described above
+   - Include an **Applicability Question** described above
    - Include a **Rule** section describing the requirement.
    - Include a **Verification** section with concrete checks the model should evaluate.
 3. Rules are blocking by default — if verification criteria are not met, the stage cannot proceed until the finding is resolved.
@@ -607,9 +630,15 @@ Have one of our supported platforms/tools for Assisted AI Coding installed:
 
 ### Platform-Specific Issues
 
-#### Amazon Q Developer / Kiro
-- Use `/context show` to verify rules are loaded
-- Check `.amazonq/rules/` or `.kiro/steering/` directory structure
+#### Kiro
+- Use `/context show` in Kiro CLI to verify rules are loaded
+- Check `.kiro/steering/` directory structure
+- Note: Kiro uses `aws-aidlc-rule-details` (not `.aidlc-rule-details/`) under the `.kiro/` directory
+
+#### Amazon Q Developer
+- Check `.amazonq/rules/` directory structure
+- Verify rules are listed in the Amazon Q Chat Rules panel
+- Note: Amazon Q uses `aws-aidlc-rule-details` (not `.aidlc-rule-details/`) under the `.amazonq/` directory
 
 #### Cursor
 - For "Apply Intelligently", ensure a description is defined in frontmatter
@@ -643,7 +672,9 @@ Have one of our supported platforms/tools for Assisted AI Coding installed:
 CLAUDE.md
 AGENTS.md
 .amazonq/rules/
+.amazonq/aws-aidlc-rule-details/
 .kiro/steering/
+.kiro/aws-aidlc-rule-details/
 .cursor/rules/
 .clinerules/
 .github/copilot-instructions.md
@@ -660,6 +691,7 @@ AGENTS.md
 
 ## Additional Resources
 
+<!-- TODO: Replace this Amplify URL with a permanent/stable URL when available -->
 | Resource | Link |
 |----------|------|
 | AI-DLC Method Definition Paper | [Paper](https://prod.d13rzhkk8cj2z0.amplifyapp.com/) |
@@ -682,4 +714,4 @@ See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more inform
 
 ## License
 
-This library is licensed under the MIT-0 License. See the LICENSE file.
+This library is licensed under the MIT-0 License. See the [LICENSE](LICENSE) file.

aidlc-rules/aws-aidlc-rule-details/common/error-handling.md

@@ -16,12 +16,12 @@
 - Invalid user input that cannot be processed
 - System errors preventing file operations
 
-**High**: Phase cannot complete as planned
+**High**: Stage cannot complete as planned
 - Incomplete answers to required questions
 - Contradictory user responses
-- Missing dependencies from prior phases
+- Missing dependencies from prior stages
 
-**Medium**: Phase can continue with workarounds
+**Medium**: Stage can continue with workarounds
 - Optional artifacts missing
 - Non-critical validation failures
 - Partial completion possible
@@ -31,9 +31,9 @@
 - Optional information missing
 - Non-blocking warnings
 
-## Phase-Specific Error Handling
+## Stage-Specific Error Handling
 
-### Context Assessment Errors
+### Workspace Detection Errors
 
 **Error**: Cannot read workspace files
 - **Cause**: Permission issues, missing directories
@@ -45,12 +45,12 @@
 - **Solution**: Ask user if they want to start fresh or attempt recovery
 - **Recovery**: Create backup, start new state file
 
-**Error**: Cannot determine required phases
+**Error**: Cannot determine required stages
 - **Cause**: Insufficient information from user
 - **Solution**: Ask clarifying questions about intent and scope
 - **Workaround**: Default to comprehensive execution plan
 
-### Requirements Assessment Errors
+### Requirements Analysis Errors
 
 **Error**: User provides contradictory requirements
 - **Cause**: Unclear understanding, changing needs
@@ -67,11 +67,11 @@
 - **Solution**: Highlight unanswered questions, provide examples
 - **Do Not Proceed**: Until all required questions are answered
 
-### Story Development Errors
+### User Stories Errors
 
 **Error**: Cannot map requirements to stories
 - **Cause**: Requirements too vague, missing functional details
-- **Solution**: Return to Requirements Assessment for clarification
+- **Solution**: Return to Requirements Analysis for clarification
 - **Workaround**: Create stories based on available information, mark as incomplete
 
 **Error**: User provides ambiguous story planning answers
@@ -130,19 +130,19 @@
 - **Solution**: Clearly mark as **HUMAN TASK**, provide instructions
 - **Wait**: For user confirmation before proceeding
 
-### Code Planning Errors
+### Code Generation Errors (Part 1: Code Planning)
 
 **Error**: Code generation plan is incomplete
 - **Cause**: Missing design artifacts, unclear requirements
-- **Solution**: Return to Design phase to complete artifacts
+- **Solution**: Return to Design stage to complete artifacts
 - **Recovery**: Generate plan with available information, mark gaps
 
 **Error**: Unit dependencies not satisfied
 - **Cause**: Dependent units not yet generated
 - **Solution**: Reorder generation sequence to respect dependencies
 - **Workaround**: Generate with stub dependencies, integrate later
 
-### Code Generation Errors
+### Code Generation Errors (Part 2: Code Generation)
 
 **Error**: Cannot generate code for a step
 - **Cause**: Insufficient design information, unclear requirements
@@ -173,12 +173,12 @@
 
 ## Recovery Procedures
 
-### Partial Phase Completion
+### Partial Stage Completion
 
-**Scenario**: Phase was interrupted mid-execution
+**Scenario**: Stage was interrupted mid-execution
 
 **Recovery Steps**:
-1. Load the phase plan file
+1. Load the stage plan file
 2. Identify last completed step (last [x] checkbox)
 3. Resume from next uncompleted step
 4. Verify all prior steps are actually complete
@@ -190,43 +190,43 @@
 
 **Recovery Steps**:
 1. Create backup: `aidlc-state.md.backup`
-2. Ask user which phase they're actually on
+2. Ask user which stage they're actually on
 3. Regenerate state file from scratch
-4. Mark completed phases based on existing artifacts
-5. Resume from current phase
+4. Mark completed stages based on existing artifacts
+5. Resume from current stage
 
 ### Missing Artifacts
 
-**Scenario**: Required artifacts from prior phase are missing
+**Scenario**: Required artifacts from prior stage are missing
 
 **Recovery Steps**:
 1. Identify which artifacts are missing
 2. Determine if they can be regenerated
-3. If yes: Return to that phase, regenerate artifacts
+3. If yes: Return to that stage, regenerate artifacts
 4. If no: Ask user to provide information manually
 5. Document the gap in `audit.md`
 
-### User Wants to Restart Phase
+### User Wants to Restart Stage
 
-**Scenario**: User is unhappy with phase results and wants to redo
+**Scenario**: User is unhappy with stage results and wants to redo
 
 **Recovery Steps**:
 1. Confirm user wants to restart (data will be lost)
 2. Archive existing artifacts: `{artifact}.backup`
-3. Reset phase status in `aidlc-state.md`
-4. Clear phase checkboxes in plan files
-5. Re-execute phase from beginning
+3. Reset stage status in `aidlc-state.md`
+4. Clear stage checkboxes in plan files
+5. Re-execute stage from beginning
 
-### User Wants to Skip Phase
+### User Wants to Skip Stage
 
-**Scenario**: User wants to skip a phase that was planned
+**Scenario**: User wants to skip a stage that was planned
 
 **Recovery Steps**:
 1. Confirm user understands implications
 2. Document skip reason in `audit.md`
-3. Mark phase as "SKIPPED" in `aidlc-state.md`
-4. Proceed to next phase
-5. Note: May cause issues in later phases if dependencies missing
+3. Mark stage as "SKIPPED" in `aidlc-state.md`
+4. Proceed to next stage
+5. Note: May cause issues in later stages if dependencies missing
 
 ## Escalation Guidelines
 
@@ -247,7 +247,7 @@
 ### When to Suggest Starting Over
 
 **Consider Fresh Start If**:
-- Multiple phases have errors
+- Multiple stages have errors
 - State file is severely corrupted
 - User requirements have changed significantly
 - Architectural decision needs to be reversed
@@ -340,7 +340,7 @@
 ### Error Logging Format
 
 ```markdown
-## Error - [Phase Name]
+## Error - [Stage Name]
 **Timestamp**: [ISO timestamp]
 **Error Type**: [Critical/High/Medium/Low]
 **Description**: [What went wrong]
@@ -354,7 +354,7 @@
 ### Recovery Logging Format
 
 ```markdown
-## Recovery - [Phase Name]
+## Recovery - [Stage Name]
 **Timestamp**: [ISO timestamp]
 **Issue**: [What needed recovery]
 **Recovery Steps**: [What was done]

aidlc-rules/aws-aidlc-rule-details/common/process-overview.md

@@ -2,9 +2,9 @@
 
 **Purpose**: Technical reference for AI model and developers to understand complete workflow structure.
 
-**Note**: Similar content exists in core-workflow.md (user welcome message) and README.md (documentation). This duplication is INTENTIONAL - each file serves a different purpose:
+**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:
 - **This file**: Detailed technical reference with Mermaid diagram for AI model context loading
-- **core-workflow.md**: User-facing welcome message with ASCII diagram
+- **welcome-message.md**: User-facing welcome message with ASCII diagram
 - **README.md**: Human-readable documentation for repository
 
 ## The Three-Phase Lifecycle: