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

[mpearcy13]

Summary

Users that want to run AI-DLC multiple times in a repo are currently blocked from syncing the AI-DLC files to Git, as they create merge conflicts. To mitigate this, all generated documentation is now scoped under aidlc-docs/{feature-name}/ instead of a flat aidlc-docs/ directory, allowing retention of AI-DLC context per feature and minimizing merge conflicts.

Changes

Core Workflow (core-workflow.md)

• Added "MANDATORY: Feature Name Capture and Path Resolution" section — prompts for feature name on new workflows, detects from existing state on resume, and offers migration for legacy flat
• Added Global Path Resolution Rule — all aidlc-docs/ paths implicitly resolve to aidlc-docs/{feature-name}/ throughout the workflow and rule detail files
• Updated Workspace Detection stage to include feature name capture as an explicit sub-step
• Updated directory structure diagram to reflect {feature-name}/ nesting level

Workspace Detection (inception/workspace-detection.md)

• Rewrote Step 1 to scan aidlc-docs/ for subdirectories containing aidlc-state.md (handles single feature, multiple features, and legacy flat structure)
• Added new Step 2 for feature name capture with sanitization rules (lowercase, alphanumeric + hyphens, max 50 chars)
• Updated all subsequent steps with aidlc-docs/{feature-name}/ paths and renumbered accordingly

Session Continuity (common/session-continuity.md)

• Added "Feature Detection on Resume" section with auto-select, multi-feature list, and legacy migration logic
• Updated Welcome Back prompt to show Resuming feature: {feature-name}
• Updated session continuity instructions to scan for feature folders before loading state

Error Handling (common/error-handling.md)

• Added "Legacy flat structure detected" error case with migration guidance
• Updated existing error recovery paths to reference aidlc-docs/{feature-name}/

Workflow Changes (common/workflow-changes.md)

• Updated pause/resume handling to reference feature-scoped paths and scan for feature folders on resume

Reverse Engineering (inception/reverse-engineering.md)

• Updated state tracking paths to aidlc-docs/{feature-name}/

Workflow Planning (inception/workflow-planning.md)

• Updated state tracking paths and added Feature Name field to state template

User Experience

Users are prompted for a feature name when starting the AI-DLC workflow. This creates a partition under aidlc-docs/{feature-name}/, allowing users to keep AI-DLC documents in the repo and run multiple iterations in the same repo while maintaining historical context. On resume, existing features are auto-detected; legacy flat structures are offered a migration path.

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented

Test Plan

1. Create a new AI-DLC project and initialize the AI-DLC workflow.
2. When prompted, enter a feature name. Verify the aidlc-docs/{feature-name}/ directory is created with audit files and phase folders.
3. Complete or pause the workflow, then resume. Verify the feature is auto-detected and state is restored correctly.
4. Start a second AI-DLC run with a different feature name. Verify both feature folders coexist under aidlc-docs/ without conflicts.
5. Test legacy migration: create a flat aidlc-docs/aidlc-state.md structure, start the workflow, and verify the migration prompt moves artifacts into a named feature folder.
6. Test feature name sanitization: enter names with uppercase, special characters, and >50 chars. Verify they are slugified correctly.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[dreamorosi]

Hi @mpearcy13 - thank you for opening this pull request.

In case I have missed it, could you please link the issue where you discussed this change with maintainers (this is mentioned in the contributing guidelines, bullet point no3 in this list)?

I'd like to get more context since I'm unsure we should be adding this at this point, while the feature is definitely something we should be doing - the team is working on a new iteration of the aidlc-workflow rules that already incorporates this idea but that we're not yet ready to share with the public.

[augie09]

Hi @mpearcy13 - thank you for opening this pull request.

In case I have missed it, could you please link the issue where you discussed this change with maintainers (this is mentioned in the contributing guidelines, bullet point no3 in this list)?

I'd like to get more context since I'm unsure we should be adding this at this point, while the feature is definitely something we should be doing - the team is working on a new iteration of the aidlc-workflow rules that already incorporates this idea but that we're not yet ready to share with the public.

Is there a rough timeframe when this will be shared? Weeks or longer?
I put in a similar request today, then found this one. #208

[mpearcy13]

This is the issue I was working to resolve.
#72

[dreamorosi]

@augie09 we're planning on sharing news on the new version soon - no exact date yet, but it's going to be (few) weeks and not months.

@mpearcy13 - understood, the issue was already assigned there was no further discussion with the maintainers. I'm inclined to leave the do-not-merge label and/or close it, but we're open to discuss whether this is still needed once we have the new version out.