feat: add feature-folder isolation for multi-feature AI-DLC workflows

README.md

@@ -513,7 +513,7 @@ If your agent has no convention for rules files, place both folders at your proj
 4. Carefully review every plan that AI generates. Provide your oversight and validation
 5. Review the execution plan to see which stages will run
 6. Carefully review the artifacts and approve each stage to maintain control
-7. All the artifacts will be generated in the `aidlc-docs/` directory
+7. All the artifacts will be generated in the `aidlc-docs/{feature-name}/` directory
 
 ---
 

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

@@ -43,7 +43,12 @@
 **Error**: Existing `aidlc-state.md` is corrupted
 - **Cause**: Manual editing, incomplete previous run
 - **Solution**: Ask user if they want to start fresh or attempt recovery
-- **Recovery**: Create backup, start new state file
+- **Recovery**: Create backup, start new state file under `aidlc-docs/{feature-name}/`
+
+**Error**: Legacy flat structure detected
+- **Cause**: Project created before feature-folder isolation was introduced
+- **Solution**: Prompt user for a feature name and migrate all artifacts from `aidlc-docs/` into `aidlc-docs/{feature-name}/`
+- **Recovery**: Move files, update state file with feature name, continue workflow
 
 **Error**: Cannot determine required stages
 - **Cause**: Insufficient information from user

aidlc-rules/aws-aidlc-rule-details/common/session-continuity.md

@@ -1,13 +1,45 @@
 # Session Continuity Templates
 
+## Feature Detection on Resume
+When a user returns, scan `aidlc-docs/` for existing feature folders (subdirectories containing `aidlc-state.md`):
+
+**Single feature found**: Auto-select and present the Welcome Back prompt below.
+
+**Multiple features found**: Present a feature selection prompt first:
+```markdown
+**Welcome back! I found multiple AI-DLC features in progress.**
+
+Available features:
+1. **{feature-name-1}** - [Current Stage from aidlc-state.md]
+2. **{feature-name-2}** - [Current Stage from aidlc-state.md]
+...
+
+A) Continue feature 1: {feature-name-1}
+B) Continue feature 2: {feature-name-2}
+...
+N) Start a new feature
+
+[Answer]: 
+```
+
+**Legacy flat structure found** (aidlc-state.md directly in aidlc-docs/ with no feature subfolder):
+```markdown
+**Welcome back! I found an existing AI-DLC project using the legacy flat structure.**
+
+To support concurrent feature development, I need to migrate your existing docs into a feature folder.
+
+What name should I use for this feature? (e.g., "User Authentication", "Payment Processing")
+```
+After receiving the name, move all artifacts from `aidlc-docs/` into `aidlc-docs/{feature-name}/`.
+
 ## Welcome Back Prompt Template
-When a user returns to continue work on an existing AI-DLC project, present this prompt:
+After feature selection, present this prompt:
 
 ```markdown
-**Welcome back! I can see you have an existing AI-DLC project in progress.**
+**Welcome back! Resuming feature: {feature-name}**
 
 Based on your aidlc-state.md, here's your current status:
-- **Project**: [project-name]
+- **Feature**: {feature-name}
 - **Current Phase**: [INCEPTION/CONSTRUCTION/OPERATIONS]
 - **Current Stage**: [Stage Name]
 - **Last Completed**: [Last completed step]
@@ -22,26 +54,28 @@ B) Review a previous stage ([Show available stages])
 ```
 
 ## MANDATORY: Session Continuity Instructions
-1. **Always read aidlc-state.md first** when detecting existing project
-2. **Parse current status** from the workflow file to populate the prompt
-3. **MANDATORY: Load Previous Stage Artifacts** - Before resuming any stage, automatically read all relevant artifacts from previous stages:
+1. **Always scan aidlc-docs/ for feature folders first** when detecting existing projects
+2. **Resolve feature selection** before loading any state (single feature auto-selects, multiple features prompt user)
+3. **Read aidlc-docs/{feature-name}/aidlc-state.md** after feature is selected
+4. **Parse current status** from the workflow file to populate the prompt
+5. **MANDATORY: Load Previous Stage Artifacts** - Before resuming any stage, automatically read all relevant artifacts from previous stages (all paths resolve under `aidlc-docs/{feature-name}/`):
    - **Reverse Engineering**: Read architecture.md, code-structure.md, api-documentation.md
    - **Requirements Analysis**: Read requirements.md, requirement-verification-questions.md
    - **User Stories**: Read stories.md, personas.md, story-generation-plan.md
    - **Application Design**: Read application-design artifacts (components.md, component-methods.md, services.md)
    - **Design (Units)**: Read unit-of-work.md, unit-of-work-dependency.md, unit-of-work-story-map.md
    - **Per-Unit Design**: Read functional-design.md, nfr-requirements.md, nfr-design.md, infrastructure-design.md
    - **Code Stages**: Read all code files, plans, AND all previous artifacts
-4. **Smart Context Loading by Stage**:
+6. **Smart Context Loading by Stage**:
    - **Early Stages (Workspace Detection, Reverse Engineering)**: Load workspace analysis
    - **Requirements/Stories**: Load reverse engineering + requirements artifacts
    - **Design Stages**: Load requirements + stories + architecture + design artifacts
    - **Code Stages**: Load ALL artifacts + existing code files
-5. **Adapt options** based on architectural choice and current phase
-6. **Show specific next steps** rather than generic descriptions
-7. **Log the continuity prompt** in audit.md with timestamp
-8. **Context Summary**: After loading artifacts, provide brief summary of what was loaded for user awareness
-9. **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.
+7. **Adapt options** based on architectural choice and current phase
+8. **Show specific next steps** rather than generic descriptions
+9. **Log the continuity prompt** in audit.md with timestamp
+10. **Context Summary**: After loading artifacts, provide brief summary of what was loaded for user awareness
+11. **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.
 
 ## Error Handling
 If artifacts are missing or corrupted during session resumption, see [error-handling.md](error-handling.md) for guidance on recovery procedures. 

aidlc-rules/aws-aidlc-rule-details/common/workflow-changes.md

@@ -132,16 +132,17 @@ Users may request changes to the execution plan or stage execution during the wo
 **Handling**:
 1. **Complete Current Step**: Finish the current step in progress if possible
 2. **Update Checkboxes**: Mark all completed steps with [x]
-3. **Update State**: Ensure `aidlc-state.md` reflects current status
-4. **Log Pause**: Document pause point in `audit.md`
-5. **Provide Resume Instructions**: "When you return, I'll detect your existing project and offer to continue from: [current stage, current step]"
+3. **Update State**: Ensure `aidlc-docs/{feature-name}/aidlc-state.md` reflects current status
+4. **Log Pause**: Document pause point in `aidlc-docs/{feature-name}/audit.md`
+5. **Provide Resume Instructions**: "When you return, I'll detect your feature folder and offer to continue from: [current stage, current step]"
 
 **On Resume**:
-1. **Detect Existing Project**: Check for `aidlc-state.md`
-2. **Load Context**: Read all artifacts from completed stages
-3. **Show Status**: Display current stage and next step
-4. **Offer Options**: Continue where left off or review previous work
-5. **Log Resume**: Document resume point in `audit.md`
+1. **Detect Existing Features**: Scan `aidlc-docs/` for feature folders containing `aidlc-state.md`
+2. **Select Feature**: If multiple features exist, present list for user to choose; if single feature, auto-select
+3. **Load Context**: Read all artifacts from completed stages under `aidlc-docs/{feature-name}/`
+4. **Show Status**: Display current stage and next step
+5. **Offer Options**: Continue where left off or review previous work
+6. **Log Resume**: Document resume point in `aidlc-docs/{feature-name}/audit.md`
 
 ---
 

aidlc-rules/aws-aidlc-rule-details/inception/reverse-engineering.md

@@ -279,12 +279,12 @@ Create `aidlc-docs/inception/reverse-engineering/reverse-engineering-timestamp.m
 
 ## Step 11: Update State Tracking
 
-Update `aidlc-docs/aidlc-state.md`:
+Update `aidlc-docs/{feature-name}/aidlc-state.md`:
 
 ```markdown
 ## Reverse Engineering Status
 - [x] Reverse Engineering - Completed on [timestamp]
-- **Artifacts Location**: aidlc-docs/inception/reverse-engineering/
+- **Artifacts Location**: aidlc-docs/{feature-name}/inception/reverse-engineering/
 ```
 
 ## Step 12: Present Completion Message to User

aidlc-rules/aws-aidlc-rule-details/inception/workflow-planning.md

@@ -343,12 +343,13 @@ flowchart TD
 
 ## Step 8: Initialize State Tracking
 
-Update `aidlc-docs/aidlc-state.md`:
+Update `aidlc-docs/{feature-name}/aidlc-state.md`:
 
 ```markdown
 # AI-DLC State Tracking
 
 ## Project Information
+- **Feature Name**: [{feature-name}]
 - **Project Type**: [Greenfield/Brownfield]
 - **Start Date**: [ISO timestamp]
 - **Current Stage**: INCEPTION - Workflow Planning

aidlc-rules/aws-aidlc-rule-details/inception/workspace-detection.md

@@ -1,14 +1,40 @@
 # Workspace Detection
 
-**Purpose**: Determine workspace state and check for existing AI-DLC projects
+**Purpose**: Determine workspace state, capture feature name, and check for existing AI-DLC projects
 
-## Step 1: Check for Existing AI-DLC Project
+## Step 1: Check for Existing AI-DLC Projects
 
-Check if `aidlc-docs/aidlc-state.md` exists:
-- **If exists**: Resume from last phase (load context from previous phases)
-- **If not exists**: Continue with new project assessment
+Scan `aidlc-docs/` for existing feature folders:
 
-## Step 2: Scan Workspace for Existing Code
+**IF `aidlc-docs/` contains one or more subdirectories with `aidlc-state.md`**:
+- **Single feature folder found**: Auto-select it, confirm with user, resume from last phase
+- **Multiple feature folders found**: Present list of features for user to choose which to resume, or start a new feature
+- **Legacy flat structure** (aidlc-state.md directly in aidlc-docs/ with no feature subfolder): Offer to migrate into a named feature folder
+
+**IF no existing projects found**: Continue with new project assessment (Step 2)
+
+## Step 2: Capture Feature Name (New Workflows)
+
+**MANDATORY for new workflows**: Prompt the user for a short, descriptive feature name.
+
+**Prompt**:
+```markdown
+What is the name of the feature you're working on? This will be used to organize all documentation for this feature.
+
+Example: "User Authentication", "Payment Processing", "Search API"
+```
+
+**Sanitization rules**:
+- Convert to lowercase
+- Replace spaces and special characters with hyphens
+- Remove leading/trailing hyphens
+- Allow only alphanumeric characters and hyphens
+- Maximum 50 characters
+- Example: "User Authentication" → `user-authentication`
+
+**Store the feature name** — all subsequent `aidlc-docs/` paths resolve to `aidlc-docs/{feature-name}/` per the Global Path Resolution Rule in core-workflow.md.
+
+## Step 3: Scan Workspace for Existing Code
 
 **Determine if workspace has existing code:**
 - Scan workspace for source code files (.java, .py, .js, .ts, .jsx, .tsx, .kt, .kts, .scala, .groovy, .go, .rs, .rb, .php, .c, .h, .cpp, .hpp, .cc, .cs, .fs, etc.)
@@ -26,30 +52,31 @@ Check if `aidlc-docs/aidlc-state.md` exists:
 - **Workspace Root**: [Absolute path]
 ```
 
-## Step 3: Determine Next Phase
+## Step 4: Determine Next Phase
 
 **IF workspace is empty (no existing code)**:
 - Set flag: `brownfield = false`
 - Next phase: Requirements Analysis
 
 **IF workspace has existing code**:
 - Set flag: `brownfield = true`
-- Check for existing reverse engineering artifacts in `aidlc-docs/inception/reverse-engineering/`
+- Check for existing reverse engineering artifacts in `aidlc-docs/{feature-name}/inception/reverse-engineering/`
 - **IF reverse engineering artifacts exist**:
     - Check if artifacts are stale (compare artifact timestamps against codebase's last significant modification)
     - **IF artifacts are current**: Load them, skip to Requirements Analysis
     - **IF artifacts are stale**: Next phase is Reverse Engineering (rerun to refresh artifacts)
     - **IF user explicitly requests rerun**: Next phase is Reverse Engineering regardless of staleness
 - **IF no reverse engineering artifacts**: Next phase is Reverse Engineering
 
-## Step 4: Create Initial State File
+## Step 5: Create Initial State File
 
-Create `aidlc-docs/aidlc-state.md`:
+Create `aidlc-docs/{feature-name}/aidlc-state.md`:
 
 ```markdown
 # AI-DLC State Tracking
 
 ## Project Information
+- **Feature Name**: [{feature-name}]
 - **Project Type**: [Greenfield/Brownfield]
 - **Start Date**: [ISO timestamp]
 - **Current Stage**: INCEPTION - Workspace Detection
@@ -61,20 +88,21 @@ Create `aidlc-docs/aidlc-state.md`:
 
 ## Code Location Rules
 - **Application Code**: Workspace root (NEVER in aidlc-docs/)
-- **Documentation**: aidlc-docs/ only
+- **Documentation**: aidlc-docs/{feature-name}/ only
 - **Structure patterns**: See code-generation.md Critical Rules
 
 ## Stage Progress
 [Will be populated as workflow progresses]
 ```
 
-## Step 5: Present Completion Message
+## Step 6: Present Completion Message
 
 **For Brownfield Projects:**
 ```markdown
 # 🔍 Workspace Detection Complete
 
 Workspace analysis findings:
+• **Feature**: {feature-name}
 • **Project Type**: Brownfield project
 • [AI-generated summary of workspace findings in bullet points]
 • **Next Step**: Proceeding to **Reverse Engineering** to analyze existing codebase...
@@ -85,11 +113,12 @@ Workspace analysis findings:
 # 🔍 Workspace Detection Complete
 
 Workspace analysis findings:
+• **Feature**: {feature-name}
 • **Project Type**: Greenfield project
 • **Next Step**: Proceeding to **Requirements Analysis**...
 ```
 
-## Step 6: Automatically Proceed
+## Step 7: Automatically Proceed
 
 - **No user approval required** - this is informational only
 - Automatically proceed to next phase:

aidlc-rules/aws-aidlc-rules/core-workflow.md

@@ -73,6 +73,37 @@ All subsequent rule detail file references (e.g., `common/process-overview.md`,
 3. This should only be done ONCE at the start of a new workflow
 4. Do NOT load this file in subsequent interactions to save context space
 
+## MANDATORY: Feature Name Capture and Path Resolution
+
+### Feature Name Capture
+Every AI-DLC workflow MUST be scoped to a named feature. The feature name is captured during Workspace Detection and used as the root folder slug for all documentation.
+
+**For new workflows**:
+- Prompt the user for a short, descriptive feature name (e.g., "User Authentication", "Payment Processing")
+- Sanitize the name into a directory-safe slug: lowercase, alphanumeric and hyphens only, no leading/trailing hyphens, max 50 characters
+- Example: "User Authentication" → `user-authentication`
+
+**For resumed workflows**:
+- Detect the feature name from existing `aidlc-docs/{feature-name}/aidlc-state.md`
+- If multiple feature folders exist under `aidlc-docs/`, present a list for the user to choose which feature to resume
+- If a single feature folder exists, auto-select it and confirm with the user
+
+**Legacy migration**:
+- If a flat `aidlc-docs/aidlc-state.md` is found (no feature subfolder), offer to migrate it into a named feature folder by prompting the user for a feature name, then moving all artifacts under `aidlc-docs/{feature-name}/`
+
+### Global Path Resolution Rule
+**CRITICAL**: Throughout this document and ALL referenced rule detail files, any path beginning with `aidlc-docs/` is implicitly scoped to `aidlc-docs/{feature-name}/`. The `{feature-name}` is captured during Workspace Detection and used consistently for all paths.
+
+This means existing references like `aidlc-docs/inception/requirements/requirements.md` automatically resolve to `aidlc-docs/{feature-name}/inception/requirements/requirements.md` when the feature name is set.
+
+**Examples**:
+- `aidlc-docs/aidlc-state.md` → `aidlc-docs/user-authentication/aidlc-state.md`
+- `aidlc-docs/inception/plans/execution-plan.md` → `aidlc-docs/user-authentication/inception/plans/execution-plan.md`
+- `aidlc-docs/audit.md` → `aidlc-docs/user-authentication/audit.md`
+- `aidlc-docs/construction/{unit-name}/functional-design/` → `aidlc-docs/user-authentication/construction/{unit-name}/functional-design/`
+
+**Note**: Application code location is NOT affected — code always goes in the workspace root, never in `aidlc-docs/`.
+
 # Adaptive Software Development Workflow
 
 ---
@@ -99,7 +130,8 @@ All subsequent rule detail file references (e.g., `common/process-overview.md`,
 1. **MANDATORY**: Log initial user request in audit.md with complete raw input
 2. Load all steps from `inception/workspace-detection.md`
 3. Execute workspace detection:
-   - Check for existing aidlc-state.md (resume if found)
+   - **Capture Feature Name**: Prompt user for feature name (new workflow) or detect from existing feature folders (resume)
+   - Check for existing aidlc-docs/{feature-name}/aidlc-state.md (resume if found)
    - Scan workspace for existing code
    - Determine if brownfield or greenfield
    - Check for existing reverse engineering artifacts
@@ -512,27 +544,30 @@ The Operations stage will eventually include:
 ├── [project-specific structure]    # Varies by project (see code-generation.md)
 │
 ├── aidlc-docs/                     # 📄 DOCUMENTATION ONLY
-│   ├── inception/                  # 🔵 INCEPTION PHASE
-│   │   ├── plans/
-│   │   ├── reverse-engineering/    # Brownfield only
-│   │   ├── requirements/
-│   │   ├── user-stories/
-│   │   └── application-design/
-│   ├── construction/               # 🟢 CONSTRUCTION PHASE
-│   │   ├── plans/
-│   │   ├── {unit-name}/
-│   │   │   ├── functional-design/
-│   │   │   ├── nfr-requirements/
-│   │   │   ├── nfr-design/
-│   │   │   ├── infrastructure-design/
-│   │   │   └── code/               # Markdown summaries only
-│   │   └── build-and-test/
-│   ├── operations/                 # 🟡 OPERATIONS PHASE (placeholder)
-│   ├── aidlc-state.md
-│   └── audit.md
+│   └── {feature-name}/            # 🏷️ FEATURE-SCOPED FOLDER
+│       ├── inception/              # 🔵 INCEPTION PHASE
+│       │   ├── plans/
+│       │   ├── reverse-engineering/    # Brownfield only
+│       │   ├── requirements/
+│       │   ├── user-stories/
+│       │   └── application-design/
+│       ├── construction/           # 🟢 CONSTRUCTION PHASE
+│       │   ├── plans/
+│       │   ├── {unit-name}/
+│       │   │   ├── functional-design/
+│       │   │   ├── nfr-requirements/
+│       │   │   ├── nfr-design/
+│       │   │   ├── infrastructure-design/
+│       │   │   └── code/           # Markdown summaries only
+│       │   └── build-and-test/
+│       ├── operations/             # 🟡 OPERATIONS PHASE (placeholder)
+│       ├── aidlc-state.md
+│       └── audit.md
 ```
 
 **CRITICAL RULE**:
 - Application code: Workspace root (NEVER in aidlc-docs/)
-- Documentation: aidlc-docs/ only
+- Documentation: aidlc-docs/{feature-name}/ only
 - Project structure: See code-generation.md for patterns by project type
+- Feature isolation: Each feature gets its own subfolder under aidlc-docs/
+- All `aidlc-docs/` paths in rule detail files resolve to `aidlc-docs/{feature-name}/` per the Global Path Resolution Rule