chore(release): 4.27.6 [skip ci]

## [4.27.6](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.5...v4.27.6) (2025-07-08)

### Bug Fixes

* installer improvement ([db30230](db302309f4))

CHANGELOG.md

@@ -1,3 +1,31 @@
+## [4.27.6](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.5...v4.27.6) (2025-07-08)
+
+
+### Bug Fixes
+
+* installer improvement ([db30230](https://github.com/bmadcode/BMAD-METHOD/commit/db302309f42da49daa309b5ba1a625c719e5bb14))
+
+## [4.27.5](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.4...v4.27.5) (2025-07-08)
+
+
+### Bug Fixes
+
+* installer for github copilot asks follow up questions right away now so it does not seem to hang, and some minor doc improvements ([cadf8b6](https://github.com/bmadcode/BMAD-METHOD/commit/cadf8b6750afd5daa32eb887608c614584156a69))
+
+## [4.27.4](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.3...v4.27.4) (2025-07-07)
+
+
+### Bug Fixes
+
+* doc updates ([1b86cd4](https://github.com/bmadcode/BMAD-METHOD/commit/1b86cd4db3644ca2b2b4a94821cc8b5690d78e0a))
+
+## [4.27.3](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.2...v4.27.3) (2025-07-07)
+
+
+### Bug Fixes
+
+* remove test zoo folder ([908dcd7](https://github.com/bmadcode/BMAD-METHOD/commit/908dcd7e9afae3fd23cd894c0d09855fc9c42d0e))
+
 ## [4.27.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.1...v4.27.2) (2025-07-07)
 
 

CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thank you for considering contributing to this project! This document outlines t
 
 🆕 **New to GitHub or pull requests?** Check out our [beginner-friendly Pull Request Guide](docs/how-to-contribute-with-pull-requests.md) first!
 
-📋 **Before contributing**, please read our [Guiding Principles](GUIDING-PRINCIPLES.md) to understand the BMad Method's core philosophy and architectural decisions.
+📋 **Before contributing**, please read our [Guiding Principles](docs/GUIDING-PRINCIPLES.md) to understand the BMad Method's core philosophy and architectural decisions.
 
 Also note, we use the discussions feature in GitHub to have a community to discuss potential ideas, uses, additions and enhancements.
 
@@ -52,7 +52,7 @@ By participating in this project, you agree to abide by our Code of Conduct. Ple
 
 Please only propose small granular commits! If its large or significant, please discuss in the discussions tab and open up an issue first. I do not want you to waste your time on a potentially very large PR to have it rejected because it is not aligned or deviates from other planned changes. Communicate and lets work together to build and improve this great community project!
 
-**Important**: All contributions must align with our [Guiding Principles](GUIDING-PRINCIPLES.md). Key points:
+**Important**: All contributions must align with our [Guiding Principles](docs/GUIDING-PRINCIPLES.md). Key points:
 
 - Keep dev agents lean - they need context for coding, not documentation
 - Web/planning agents can be larger with more complex tasks

bmad-core/agents/analyst.md

@@ -1,11 +1,10 @@
 # analyst
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/agents/architect.md

@@ -1,11 +1,10 @@
 # architect
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/agents/bmad-master.md

@@ -1,62 +1,42 @@
 # BMad Master
 
-CRITICAL: Read the full YAML to understand your operating params, start activation to alter your state of being, follow startup instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Greet the user with your name and role, and inform of the *help command.
-  - Check for active workflow plan using the utils plan-management
-  - If plan exists: Show brief status - Active plan {workflow} in progress
-  - If plan exists: Suggest next step based on plan
   - CRITICAL: Do NOT scan filesystem or load any resources during startup, ONLY when commanded
   - CRITICAL: Do NOT run discovery tasks automatically
+  - CRITICAL: NEVER LOAD data/bmad-kb.md UNLESS USER TYPES *kb
 agent:
   name: BMad Master
   id: bmad-master
   title: BMad Master Task Executor
   icon: 🧙
-  whenToUse: Use when you need comprehensive expertise across all domains or rapid context switching between multiple agent capabilities
+  whenToUse: Use when you need comprehensive expertise across all domains, running 1 off tasks that do not require a persona, or just wanting to use the same agent for many things.
 persona:
   role: Master Task Executor & BMad Method Expert
-  style: Efficient, direct, action-oriented. Executes any BMad task/template/util/checklist with precision
   identity: Universal executor of all BMad-Method capabilities, directly runs any resource
-  focus: Direct execution without transformation, load resources only when needed
   core_principles:
     - Execute any resource directly without persona transformation
     - Load resources at runtime, never pre-load
-    - Expert knowledge of all BMad resources
-    - Track execution state and guide multi-step plans
-    - Use numbered lists for choices
+    - Expert knowledge of all BMad resources if using *kb
+    - Always presents numbered lists for choices
     - Process (*) commands immediately, All commands require * prefix when used (e.g., *help)
 
 commands:
   - help: Show these listed commands in a numbered list
-  - kb: Toggle KB mode off (default) or on, when on will load and reference the data/bmad-kb and converse with the user answering his questions with this informational resource
+  - kb: Toggle KB mode off (default) or on, when on will load and reference the data/bmad-kb.md and converse with the user answering his questions with this informational resource
   - task {task}: Execute task, if not found or none specified, ONLY list available dependencies/tasks listed below
-  - list {task|template|util|checklist|workflow}: List resources by type ONLY from the corresponding dependencies sub item below
   - create-doc {template}: execute task create-doc (no template = ONLY show available templates listed under dependencies/templates below)
-  - create-prd-alpha: Execute task create-doc2 with .bmad-core/templates/prd-tmpl2.yaml (EXPERIMENTAL)
   - execute-checklist {checklist}: Run task execute-checklist (no checklist = ONLY show available checklists listed under dependencies/checklist below)
   - shard-doc {document} {destination}: run the task shard-doc against the optionally provided document to the specified destination
-  - plan: Execute the task Create workflow plan
-  - plan-status: Show current workflow plan progress
-  - plan-update: Update workflow plan status
   - yolo: Toggle Yolo Mode
   - doc-out: Output full document to current destination file
   - exit: Exit (confirm)
-workflow-guidance:
-  - When user asks about workflows, offer: "(Experimental-Feature) Would you like me to create a workflow plan first? (*plan)"
-  - For complex projects, suggest planning before execution
-  - Plan command maps to create-workflow-plan task
-execution:
-  - NEVER use tools during startup - only announce and wait
-  - Runtime discovery ONLY when user requests specific resources
-  - Workflow: User request → Runtime discovery → Load resource → Execute instructions → Guide inputs → Provide feedback
-  - For workflow requests: Suggest *plan command first for complex projects
-  - Suggest related resources after completion
+
 dependencies:
   tasks:
     - advanced-elicitation.md
@@ -91,10 +71,6 @@ dependencies:
     - brainstorming-techniques.md
     - elicitation-methods.md
     - technical-preferences.md
-  utils:
-    - plan-management.md
-    - template-format.md
-    - workflow-management.md
   workflows:
     - brownfield-fullstack.md
     - brownfield-service.md

bmad-core/agents/bmad-orchestrator.md

@@ -1,18 +1,14 @@
 # BMad Web Orchestrator
 
-CRITICAL: Read the full YAML to understand your operating params, start activation to alter your state of being, follow startup instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Announce: Introduce yourself as the BMad Orchestrator, explain you can coordinate agents and workflows
   - IMPORTANT: Tell users that all commands start with * (e.g., *help, *agent, *workflow)
   - Mention *help shows all available commands and options
-  - Check for active workflow plan using {root}/utils/plan-management.md
-  - "If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details."
-  - "If plan exists: Suggest next action based on plan progress"
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -135,7 +131,5 @@ dependencies:
     - bmad-kb.md
     - elicitation-methods.md
   utils:
-    - plan-management.md
     - workflow-management.md
-    - template-format.md
 ```

bmad-core/agents/dev.md

@@ -1,11 +1,10 @@
 # dev
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Announce: Greet the user with your name and role, and inform of the *help command.
   - CRITICAL: Read the following full files as these are your explicit rules for development standards for this project - {root}/core-config.yaml devLoadAlwaysFiles list

bmad-core/agents/pm.md

@@ -1,11 +1,10 @@
 # pm
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/agents/po.md

@@ -1,11 +1,10 @@
 # po
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/agents/qa.md

@@ -1,11 +1,10 @@
 # qa
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/agents/sm.md

@@ -1,11 +1,10 @@
 # sm
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - The customization field ALWAYS takes precedence over any conflicting instructions

bmad-core/agents/ux-expert.md

@@ -1,11 +1,10 @@
 # ux-expert
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}.md where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/data/bmad-kb.md

@@ -403,17 +403,10 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 
 BMad employs a sophisticated template system with three key components:
 
-1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
-2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+1. **Template Format** (`utils/bmad-doc-template.md`): Defines markup language for variable substitution and AI processing directives from yaml templates
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction to transform yaml spec to final markdown output
 3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
 
-**Template Features**:
-
-- **Self-contained**: Templates embed both output structure and processing instructions
-- **Variable Substitution**: `{{placeholders}}` for dynamic content
-- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
-- **Interactive Refinement**: Built-in elicitation processes for quality improvement
-
 ### Technical Preferences Integration
 
 The `technical-preferences.md` file serves as a persistent technical profile that:
@@ -733,7 +726,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -803,8 +796,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines

bmad-core/tasks/create-next-story.md

@@ -11,7 +11,6 @@ To identify the next logical story based on project progress and epic definition
 - Load `.bmad-core/core-config.yaml` from the project root
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can either: 1) Copy it from GITHUB bmad-core/core-config.yaml and configure it for your project OR 2) Run the BMad installer against your project to upgrade and add the file automatically. Please add and configure core-config.yaml before proceeding."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`, `workflow.*`
-- If `workflow.trackProgress: true`, use `utils/plan-management.md` to check plan sequence and warn if out of order
 
 ### 1. Identify Next Story for Preparation
 

bmad-core/tasks/validate-next-story.md

@@ -8,7 +8,7 @@ To comprehensively validate a story draft before implementation begins, ensuring
 
 ### 0. Load Core Configuration and Inputs
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `.bmad-core/core-config.yaml`
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story validation."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`
 - Identify and load the following inputs:

bmad-core/utils/plan-management.md

@@ -1,219 +0,0 @@
-# Plan Management Utility
-
-## Purpose
-
-Provides utilities for agents and tasks to interact with workflow plans, check progress, update status, and ensure workflow steps are executed in the appropriate sequence.
-
-## Core Functions
-
-### 1. Check Plan Existence
-
-Check for workflow plan:
-
-1. Look for docs/workflow-plan.md (default location)
-2. Return plan status to user (exists/not exists) - if not exists then HALT.
-
-### 2. Parse Plan Status
-
-[[LLM: Extract current progress from the plan document]]
-
-**Plan Parsing Logic:**
-
-1. **Identify Step Structure**:
-   - Look for checkbox lines: `- [ ]` or `- [x]`
-   - Extract step IDs from comments: `<!-- step-id: X.Y -->`
-   - Identify agent assignments: `<!-- agent: pm -->`
-
-2. **Determine Current State**:
-   - Last completed step (highest numbered `[x]`)
-   - Next expected step (first `[ ]` after completed steps)
-   - Overall progress percentage
-
-3. **Extract Metadata**:
-   - Workflow type from plan header
-   - Decision points and their status
-   - Any deviation notes
-
-### 3. Sequence Validation
-
-[[LLM: Check if requested action aligns with plan sequence]]
-
-**Validation Rules:**
-
-1. **Strict Mode** (enforceSequence: true):
-   - Must complete steps in exact order
-   - Warn and block if out of sequence
-   - Require explicit override justification
-
-2. **Flexible Mode** (enforceSequence: false):
-   - Warn about sequence deviation
-   - Allow with confirmation
-   - Log deviation reason
-
-**Warning Templates:**
-
-```text
-SEQUENCE WARNING: 
-The workflow plan shows you should complete "{expected_step}" next.
-You're attempting to: "{requested_action}"
-
-In strict mode: Block and require plan update
-In flexible mode: Allow with confirmation
-```
-
-### 4. Plan Update Operations
-
-[[LLM: Provide consistent way to update plan progress]]
-
-**Update Actions:**
-
-1. **Mark Step Complete**:
-   - Change `- [ ]` to `- [x]`
-   - Add completion timestamp comment
-   - Update any status metadata
-
-2. **Add Deviation Note**:
-   - Insert note explaining why sequence changed
-   - Reference the deviation in plan
-
-3. **Update Current Step Pointer**:
-   - Add/move `<!-- current-step -->` marker
-   - Update last-modified timestamp
-
-### 5. Integration Instructions
-
-[[LLM: How agents and tasks should use this utility]]
-
-**For Agents (startup sequence)**:
-
-```text
-1. Check if plan exists using this utility
-2. If exists:
-   - Parse current status
-   - Show user: "Active workflow plan detected. Current step: {X}"
-   - Suggest: "Next recommended action: {next_step}"
-3. Continue with normal startup
-```
-
-**For Tasks (pre-execution)**:
-
-```text
-1. Check if plan exists
-2. If exists:
-   - Verify this task aligns with plan
-   - If not aligned:
-     - In strict mode: Show warning and stop
-     - In flexible mode: Show warning and ask for confirmation
-3. After task completion:
-   - Update plan if task was a planned step
-   - Add note if task was unplanned
-```
-
-### 6. Plan Status Report Format
-
-[[LLM: Standard format for showing plan status]]
-
-```text
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Progress: {X}% complete ({completed}/{total} steps)
-
-✅ Completed:
-- {completed_step_1}
-- {completed_step_2}
-
-🔄 Current Step:
-- {current_step_description}
-
-📌 Upcoming:
-- {next_step_1}
-- {next_step_2}
-
-⚠️ Notes:
-- {any_deviations_or_notes}
-```
-
-### 7. Decision Point Handling
-
-[[LLM: Special handling for workflow decision points]]
-
-When encountering a decision point in the plan:
-
-1. **Identify Decision Marker**: `<!-- decision: {decision_id} -->`
-2. **Check Decision Status**: Made/Pending
-3. **If Pending**: 
-   - Block progress until decision made
-   - Show options to user
-   - Record decision when made
-4. **If Made**: 
-   - Verify current path aligns with decision
-   - Warn if attempting alternate path
-
-### 8. Plan Abandonment
-
-[[LLM: Graceful handling when user wants to stop following plan]]
-
-If user wants to abandon plan:
-
-1. Confirm abandonment intent
-2. Add abandonment note to plan
-3. Mark plan as "Abandoned" in header
-4. Stop plan checking for remainder of session
-5. Suggest creating new plan if needed
-
-## Usage Examples
-
-### Example 1: Agent Startup Check
-
-```text
-BMad Master starting...
-
-[Check for plan]
-Found active workflow plan: brownfield-fullstack
-Progress: 40% complete (4/10 steps)
-Current step: Create PRD (pm agent)
-
-Suggestion: Based on your plan, you should work with the PM agent next.
-Use *agent pm to switch, or *plan-status to see full progress.
-```
-
-### Example 2: Task Sequence Warning
-
-```text
-User: *task create-next-story
-
-[Plan check triggered]
-⚠️ SEQUENCE WARNING: 
-Your workflow plan indicates the PRD hasn't been created yet.
-Creating stories before the PRD may lead to incomplete requirements.
-
-Would you like to:
-1. Continue anyway (will note deviation in plan)
-2. Switch to creating PRD first (*agent pm)
-3. View plan status (*plan-status)
-```
-
-### Example 3: Automatic Plan Update
-
-```text
-[After completing create-doc task for PRD]
-
-✅ Plan Updated: Marked "Create PRD" as complete
-📍 Next step: Create Architecture Document (architect agent)
-```
-
-## Implementation Notes
-
-- This utility should be lightweight and fast
-- Plan parsing should be resilient to format variations
-- Always preserve user agency - warnings not blocks (unless strict mode)
-- Plan updates should be atomic to prevent corruption
-- Consider plan versioning for rollback capability
-
-## Error Handling
-
-- Missing plan: Return null, don't error
-- Malformed plan: Warn but continue, treat as no plan
-- Update failures: Log but don't block task completion
-- Parse errors: Fallback to basic text search

bmad-core/workflows/brownfield-fullstack.yaml

@@ -182,7 +182,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: {root}/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

bmad-core/workflows/brownfield-service.yaml

@@ -128,7 +128,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: {root}/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

bmad-core/workflows/brownfield-ui.yaml

@@ -135,7 +135,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: {root}/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

bmad-core/workflows/greenfield-fullstack.yaml

@@ -160,7 +160,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: {root}/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

bmad-core/workflows/greenfield-ui.yaml

@@ -155,7 +155,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: {root}/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

common/utils/template-format.md

@@ -1,26 +0,0 @@
-# Template Format Conventions
-
-Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
-
-## Template Markup Elements
-
-- **{{placeholders}}**: Variables to be replaced with actual content
-- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
-- **REPEAT** sections: Content blocks that may be repeated as needed
-- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
-- **@{examples}**: Example content for guidance (never output to users)
-
-## Processing Rules
-
-- Replace all {{placeholders}} with project-specific content
-- Execute all [[LLM: instructions]] internally without showing users
-- Process conditional and repeat blocks as specified
-- Use examples for guidance but never include them in final output
-- Present only clean, formatted content to users
-
-## Critical Guidelines
-
-- **NEVER display template markup, LLM instructions, or examples to users**
-- Template elements are for AI processing only
-- Focus on faithful template execution and clean output
-- All template-specific instructions are embedded within templates

dist/agents/analyst.txt

@@ -2409,17 +2409,10 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 
 BMad employs a sophisticated template system with three key components:
 
-1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
-2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+1. **Template Format** (`utils/bmad-doc-template.md`): Defines markup language for variable substitution and AI processing directives from yaml templates
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction to transform yaml spec to final markdown output
 3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
 
-**Template Features**:
-
-- **Self-contained**: Templates embed both output structure and processing instructions
-- **Variable Substitution**: `{{placeholders}}` for dynamic content
-- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
-- **Interactive Refinement**: Built-in elicitation processes for quality improvement
-
 ### Technical Preferences Integration
 
 The `technical-preferences.md` file serves as a persistent technical profile that:
@@ -2739,7 +2732,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -2809,8 +2802,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines

dist/agents/architect.txt

@@ -1535,7 +1535,6 @@ sections:
       After completing the architecture:
       
       1. If project has UI components:
-      - Recommend engaging Design Architect agent
       - Use "Frontend Architecture Mode"
       - Provide this document as input
       
@@ -1546,22 +1545,15 @@ sections:
       
       3. Include specific prompts for next agents if needed
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
+      - id: architect-prompt
+        title: Architect Prompt
         condition: Project has UI components
         instruction: |
-          Create a brief prompt to hand off to Design Architect for Frontend Architecture creation. Include:
+          Create a brief prompt to hand off to Architect for Frontend Architecture creation. Include:
           - Reference to this architecture document
           - Key UI requirements from PRD
           - Any frontend-specific decisions made here
           - Request for detailed frontend architecture
-      - id: developer-handoff
-        title: Developer Handoff
-        instruction: |
-          Create a brief prompt for developers starting implementation. Include:
-          - Reference to this architecture and coding standards
-          - First epic/story to implement
-          - Key technical decisions to follow
 ==================== END: .bmad-core/templates/architecture-tmpl.yaml ====================
 
 ==================== START: .bmad-core/templates/front-end-architecture-tmpl.yaml ====================

dist/agents/bmad-master.txt

@@ -47,50 +47,31 @@ CRITICAL: Read the full YAML, start activation to alter your state of being, fol
 ```yaml
 activation-instructions:
   - Greet the user with your name and role, and inform of the *help command.
-  - Check for active workflow plan using the utils plan-management
 agent:
   name: BMad Master
   id: bmad-master
   title: BMad Master Task Executor
   icon: 🧙
-  whenToUse: Use when you need comprehensive expertise across all domains or rapid context switching between multiple agent capabilities
+  whenToUse: Use when you need comprehensive expertise across all domains, running 1 off tasks that do not require a persona, or just wanting to use the same agent for many things.
 persona:
   role: Master Task Executor & BMad Method Expert
-  style: Efficient, direct, action-oriented. Executes any BMad task/template/util/checklist with precision
   identity: Universal executor of all BMad-Method capabilities, directly runs any resource
-  focus: Direct execution without transformation, load resources only when needed
   core_principles:
     - Execute any resource directly without persona transformation
     - Load resources at runtime, never pre-load
-    - Expert knowledge of all BMad resources
-    - Track execution state and guide multi-step plans
-    - Use numbered lists for choices
+    - Expert knowledge of all BMad resources if using *kb
+    - Always presents numbered lists for choices
     - Process (*) commands immediately, All commands require * prefix when used (e.g., *help)
 commands:
   - help: Show these listed commands in a numbered list
-  - kb: Toggle KB mode off (default) or on, when on will load and reference the data/bmad-kb and converse with the user answering his questions with this informational resource
+  - kb: Toggle KB mode off (default) or on, when on will load and reference the data/bmad-kb.md and converse with the user answering his questions with this informational resource
   - task {task}: Execute task, if not found or none specified, ONLY list available dependencies/tasks listed below
-  - list {task|template|util|checklist|workflow}: List resources by type ONLY from the corresponding dependencies sub item below
   - create-doc {template}: execute task create-doc (no template = ONLY show available templates listed under dependencies/templates below)
-  - create-prd-alpha: Execute task create-doc2 with .bmad-core/templates/prd-tmpl2.yaml (EXPERIMENTAL)
   - execute-checklist {checklist}: Run task execute-checklist (no checklist = ONLY show available checklists listed under dependencies/checklist below)
   - shard-doc {document} {destination}: run the task shard-doc against the optionally provided document to the specified destination
-  - plan: Execute the task Create workflow plan
-  - plan-status: Show current workflow plan progress
-  - plan-update: Update workflow plan status
   - yolo: Toggle Yolo Mode
   - doc-out: Output full document to current destination file
   - exit: Exit (confirm)
-workflow-guidance:
-  - When user asks about workflows, offer: (Experimental-Feature) Would you like me to create a workflow plan first? (*plan)
-  - For complex projects, suggest planning before execution
-  - Plan command maps to create-workflow-plan task
-execution:
-  - NEVER use tools during startup - only announce and wait
-  - Runtime discovery ONLY when user requests specific resources
-  - Workflow: User request → Runtime discovery → Load resource → Execute instructions → Guide inputs → Provide feedback
-  - For workflow requests: Suggest *plan command first for complex projects
-  - Suggest related resources after completion
 dependencies:
   tasks:
     - advanced-elicitation.md
@@ -125,10 +106,6 @@ dependencies:
     - brainstorming-techniques.md
     - elicitation-methods.md
     - technical-preferences.md
-  utils:
-    - plan-management.md
-    - template-format.md
-    - workflow-management.md
   workflows:
     - brownfield-fullstack.md
     - brownfield-service.md
@@ -1806,7 +1783,6 @@ To identify the next logical story based on project progress and epic definition
 - Load `.bmad-core/core-config.yaml` from the project root
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can either: 1) Copy it from GITHUB bmad-core/core-config.yaml and configure it for your project OR 2) Run the BMad installer against your project to upgrade and add the file automatically. Please add and configure core-config.yaml before proceeding."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`, `workflow.*`
-- If `workflow.trackProgress: true`, use `utils/plan-management.md` to check plan sequence and warn if out of order
 
 ### 1. Identify Next Story for Preparation
 
@@ -3318,7 +3294,6 @@ sections:
       After completing the architecture:
       
       1. If project has UI components:
-      - Recommend engaging Design Architect agent
       - Use "Frontend Architecture Mode"
       - Provide this document as input
       
@@ -3329,22 +3304,15 @@ sections:
       
       3. Include specific prompts for next agents if needed
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
+      - id: architect-prompt
+        title: Architect Prompt
         condition: Project has UI components
         instruction: |
-          Create a brief prompt to hand off to Design Architect for Frontend Architecture creation. Include:
+          Create a brief prompt to hand off to Architect for Frontend Architecture creation. Include:
           - Reference to this architecture document
           - Key UI requirements from PRD
           - Any frontend-specific decisions made here
           - Request for detailed frontend architecture
-      - id: developer-handoff
-        title: Developer Handoff
-        instruction: |
-          Create a brief prompt for developers starting implementation. Include:
-          - Reference to this architecture and coding standards
-          - First epic/story to implement
-          - Key technical decisions to follow
 ==================== END: .bmad-core/templates/architecture-tmpl.yaml ====================
 
 ==================== START: .bmad-core/templates/brownfield-architecture-tmpl.yaml ====================
@@ -6226,9 +6194,9 @@ sections:
   - id: next-steps
     title: Next Steps
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
-        instruction: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.
+      - id: ux-expert-prompt
+        title: UX Expert Prompt
+        instruction: This section will contain the prompt for the UX Expert, keep it short and to the point to initiate create architecture mode using this document as input.
       - id: architect-prompt
         title: Architect Prompt
         instruction: This section will contain the prompt for the Architect, keep it short and to the point to initiate create architecture mode using this document as input.
@@ -8720,17 +8688,10 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 
 BMad employs a sophisticated template system with three key components:
 
-1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
-2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+1. **Template Format** (`utils/bmad-doc-template.md`): Defines markup language for variable substitution and AI processing directives from yaml templates
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction to transform yaml spec to final markdown output
 3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
 
-**Template Features**:
-
-- **Self-contained**: Templates embed both output structure and processing instructions
-- **Variable Substitution**: `{{placeholders}}` for dynamic content
-- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
-- **Interactive Refinement**: Built-in elicitation processes for quality improvement
-
 ### Technical Preferences Integration
 
 The `technical-preferences.md` file serves as a persistent technical profile that:
@@ -9050,7 +9011,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -9120,8 +9081,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines
@@ -9308,326 +9269,3 @@ Use the **expansion-creator** pack to build your own:
 
 None Listed
 ==================== END: .bmad-core/data/technical-preferences.md ====================
-
-==================== START: .bmad-core/utils/plan-management.md ====================
-# Plan Management Utility
-
-## Purpose
-
-Provides utilities for agents and tasks to interact with workflow plans, check progress, update status, and ensure workflow steps are executed in the appropriate sequence.
-
-## Core Functions
-
-### 1. Check Plan Existence
-
-Check for workflow plan:
-
-1. Look for docs/workflow-plan.md (default location)
-2. Return plan status to user (exists/not exists) - if not exists then HALT.
-
-### 2. Parse Plan Status
-
-[[LLM: Extract current progress from the plan document]]
-
-**Plan Parsing Logic:**
-
-1. **Identify Step Structure**:
-   - Look for checkbox lines: `- [ ]` or `- [x]`
-   - Extract step IDs from comments: `<!-- step-id: X.Y -->`
-   - Identify agent assignments: `<!-- agent: pm -->`
-
-2. **Determine Current State**:
-   - Last completed step (highest numbered `[x]`)
-   - Next expected step (first `[ ]` after completed steps)
-   - Overall progress percentage
-
-3. **Extract Metadata**:
-   - Workflow type from plan header
-   - Decision points and their status
-   - Any deviation notes
-
-### 3. Sequence Validation
-
-[[LLM: Check if requested action aligns with plan sequence]]
-
-**Validation Rules:**
-
-1. **Strict Mode** (enforceSequence: true):
-   - Must complete steps in exact order
-   - Warn and block if out of sequence
-   - Require explicit override justification
-
-2. **Flexible Mode** (enforceSequence: false):
-   - Warn about sequence deviation
-   - Allow with confirmation
-   - Log deviation reason
-
-**Warning Templates:**
-
-```text
-SEQUENCE WARNING: 
-The workflow plan shows you should complete "{expected_step}" next.
-You're attempting to: "{requested_action}"
-
-In strict mode: Block and require plan update
-In flexible mode: Allow with confirmation
-```
-
-### 4. Plan Update Operations
-
-[[LLM: Provide consistent way to update plan progress]]
-
-**Update Actions:**
-
-1. **Mark Step Complete**:
-   - Change `- [ ]` to `- [x]`
-   - Add completion timestamp comment
-   - Update any status metadata
-
-2. **Add Deviation Note**:
-   - Insert note explaining why sequence changed
-   - Reference the deviation in plan
-
-3. **Update Current Step Pointer**:
-   - Add/move `<!-- current-step -->` marker
-   - Update last-modified timestamp
-
-### 5. Integration Instructions
-
-[[LLM: How agents and tasks should use this utility]]
-
-**For Agents (startup sequence)**:
-
-```text
-1. Check if plan exists using this utility
-2. If exists:
-   - Parse current status
-   - Show user: "Active workflow plan detected. Current step: {X}"
-   - Suggest: "Next recommended action: {next_step}"
-3. Continue with normal startup
-```
-
-**For Tasks (pre-execution)**:
-
-```text
-1. Check if plan exists
-2. If exists:
-   - Verify this task aligns with plan
-   - If not aligned:
-     - In strict mode: Show warning and stop
-     - In flexible mode: Show warning and ask for confirmation
-3. After task completion:
-   - Update plan if task was a planned step
-   - Add note if task was unplanned
-```
-
-### 6. Plan Status Report Format
-
-[[LLM: Standard format for showing plan status]]
-
-```text
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Progress: {X}% complete ({completed}/{total} steps)
-
-✅ Completed:
-- {completed_step_1}
-- {completed_step_2}
-
-🔄 Current Step:
-- {current_step_description}
-
-📌 Upcoming:
-- {next_step_1}
-- {next_step_2}
-
-⚠️ Notes:
-- {any_deviations_or_notes}
-```
-
-### 7. Decision Point Handling
-
-[[LLM: Special handling for workflow decision points]]
-
-When encountering a decision point in the plan:
-
-1. **Identify Decision Marker**: `<!-- decision: {decision_id} -->`
-2. **Check Decision Status**: Made/Pending
-3. **If Pending**: 
-   - Block progress until decision made
-   - Show options to user
-   - Record decision when made
-4. **If Made**: 
-   - Verify current path aligns with decision
-   - Warn if attempting alternate path
-
-### 8. Plan Abandonment
-
-[[LLM: Graceful handling when user wants to stop following plan]]
-
-If user wants to abandon plan:
-
-1. Confirm abandonment intent
-2. Add abandonment note to plan
-3. Mark plan as "Abandoned" in header
-4. Stop plan checking for remainder of session
-5. Suggest creating new plan if needed
-
-## Usage Examples
-
-### Example 1: Agent Startup Check
-
-```text
-BMad Master starting...
-
-[Check for plan]
-Found active workflow plan: brownfield-fullstack
-Progress: 40% complete (4/10 steps)
-Current step: Create PRD (pm agent)
-
-Suggestion: Based on your plan, you should work with the PM agent next.
-Use *agent pm to switch, or *plan-status to see full progress.
-```
-
-### Example 2: Task Sequence Warning
-
-```text
-User: *task create-next-story
-
-[Plan check triggered]
-⚠️ SEQUENCE WARNING: 
-Your workflow plan indicates the PRD hasn't been created yet.
-Creating stories before the PRD may lead to incomplete requirements.
-
-Would you like to:
-1. Continue anyway (will note deviation in plan)
-2. Switch to creating PRD first (*agent pm)
-3. View plan status (*plan-status)
-```
-
-### Example 3: Automatic Plan Update
-
-```text
-[After completing create-doc task for PRD]
-
-✅ Plan Updated: Marked "Create PRD" as complete
-📍 Next step: Create Architecture Document (architect agent)
-```
-
-## Implementation Notes
-
-- This utility should be lightweight and fast
-- Plan parsing should be resilient to format variations
-- Always preserve user agency - warnings not blocks (unless strict mode)
-- Plan updates should be atomic to prevent corruption
-- Consider plan versioning for rollback capability
-
-## Error Handling
-
-- Missing plan: Return null, don't error
-- Malformed plan: Warn but continue, treat as no plan
-- Update failures: Log but don't block task completion
-- Parse errors: Fallback to basic text search
-==================== END: .bmad-core/utils/plan-management.md ====================
-
-==================== START: .bmad-core/utils/template-format.md ====================
-# Template Format Conventions
-
-Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
-
-## Template Markup Elements
-
-- **{{placeholders}}**: Variables to be replaced with actual content
-- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
-- **REPEAT** sections: Content blocks that may be repeated as needed
-- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
-- **@{examples}**: Example content for guidance (never output to users)
-
-## Processing Rules
-
-- Replace all {{placeholders}} with project-specific content
-- Execute all [[LLM: instructions]] internally without showing users
-- Process conditional and repeat blocks as specified
-- Use examples for guidance but never include them in final output
-- Present only clean, formatted content to users
-
-## Critical Guidelines
-
-- **NEVER display template markup, LLM instructions, or examples to users**
-- Template elements are for AI processing only
-- Focus on faithful template execution and clean output
-- All template-specific instructions are embedded within templates
-==================== END: .bmad-core/utils/template-format.md ====================
-
-==================== START: .bmad-core/utils/workflow-management.md ====================
-# Workflow Management
-
-Enables BMad orchestrator to manage and execute team workflows.
-
-## Dynamic Workflow Loading
-
-Read available workflows from current team configuration's `workflows` field. Each team bundle defines its own supported workflows.
-
-**Key Commands**:
-
-- `/workflows` - List workflows in current bundle or workflows folder
-- `/agent-list` - Show agents in current bundle
-
-## Workflow Commands
-
-### /workflows
-
-Lists available workflows with titles and descriptions.
-
-### /workflow-start {workflow-id}
-
-Starts workflow and transitions to first agent.
-
-### /workflow-status
-
-Shows current progress, completed artifacts, and next steps.
-
-### /workflow-resume
-
-Resumes workflow from last position. User can provide completed artifacts.
-
-### /workflow-next
-
-Shows next recommended agent and action.
-
-## Execution Flow
-
-1. **Starting**: Load definition → Identify first stage → Transition to agent → Guide artifact creation
-
-2. **Stage Transitions**: Mark complete → Check conditions → Load next agent → Pass artifacts
-
-3. **Artifact Tracking**: Track status, creator, timestamps in workflow_state
-
-4. **Interruption Handling**: Analyze provided artifacts → Determine position → Suggest next step
-
-## Context Passing
-
-When transitioning, pass:
-
-- Previous artifacts
-- Current workflow stage
-- Expected outputs
-- Decisions/constraints
-
-## Multi-Path Workflows
-
-Handle conditional paths by asking clarifying questions when needed.
-
-## Best Practices
-
-1. Show progress
-2. Explain transitions
-3. Preserve context
-4. Allow flexibility
-5. Track state
-
-## Agent Integration
-
-Agents should be workflow-aware: know active workflow, their role, access artifacts, understand expected outputs.
-==================== END: .bmad-core/utils/workflow-management.md ====================

dist/agents/bmad-orchestrator.txt

@@ -47,9 +47,6 @@ CRITICAL: Read the full YAML, start activation to alter your state of being, fol
 ```yaml
 activation-instructions:
   - Mention *help shows all available commands and options
-  - Check for active workflow plan using .bmad-core/utils/plan-management.md
-  - 'If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details.'
-  - 'If plan exists: Suggest next action based on plan progress'
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -171,9 +168,7 @@ dependencies:
     - bmad-kb.md
     - elicitation-methods.md
   utils:
-    - plan-management.md
     - workflow-management.md
-    - template-format.md
 ```
 ==================== END: .bmad-core/agents/bmad-orchestrator.md ====================
 
@@ -1401,17 +1396,10 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 
 BMad employs a sophisticated template system with three key components:
 
-1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
-2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+1. **Template Format** (`utils/bmad-doc-template.md`): Defines markup language for variable substitution and AI processing directives from yaml templates
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction to transform yaml spec to final markdown output
 3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
 
-**Template Features**:
-
-- **Self-contained**: Templates embed both output structure and processing instructions
-- **Variable Substitution**: `{{placeholders}}` for dynamic content
-- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
-- **Interactive Refinement**: Built-in elicitation processes for quality improvement
-
 ### Technical Preferences Integration
 
 The `technical-preferences.md` file serves as a persistent technical profile that:
@@ -1731,7 +1719,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -1801,8 +1789,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines
@@ -1945,228 +1933,6 @@ Use the **expansion-creator** pack to build your own:
 - Prepare to continue without additional elicitation
 ==================== END: .bmad-core/data/elicitation-methods.md ====================
 
-==================== START: .bmad-core/utils/plan-management.md ====================
-# Plan Management Utility
-
-## Purpose
-
-Provides utilities for agents and tasks to interact with workflow plans, check progress, update status, and ensure workflow steps are executed in the appropriate sequence.
-
-## Core Functions
-
-### 1. Check Plan Existence
-
-Check for workflow plan:
-
-1. Look for docs/workflow-plan.md (default location)
-2. Return plan status to user (exists/not exists) - if not exists then HALT.
-
-### 2. Parse Plan Status
-
-[[LLM: Extract current progress from the plan document]]
-
-**Plan Parsing Logic:**
-
-1. **Identify Step Structure**:
-   - Look for checkbox lines: `- [ ]` or `- [x]`
-   - Extract step IDs from comments: `<!-- step-id: X.Y -->`
-   - Identify agent assignments: `<!-- agent: pm -->`
-
-2. **Determine Current State**:
-   - Last completed step (highest numbered `[x]`)
-   - Next expected step (first `[ ]` after completed steps)
-   - Overall progress percentage
-
-3. **Extract Metadata**:
-   - Workflow type from plan header
-   - Decision points and their status
-   - Any deviation notes
-
-### 3. Sequence Validation
-
-[[LLM: Check if requested action aligns with plan sequence]]
-
-**Validation Rules:**
-
-1. **Strict Mode** (enforceSequence: true):
-   - Must complete steps in exact order
-   - Warn and block if out of sequence
-   - Require explicit override justification
-
-2. **Flexible Mode** (enforceSequence: false):
-   - Warn about sequence deviation
-   - Allow with confirmation
-   - Log deviation reason
-
-**Warning Templates:**
-
-```text
-SEQUENCE WARNING: 
-The workflow plan shows you should complete "{expected_step}" next.
-You're attempting to: "{requested_action}"
-
-In strict mode: Block and require plan update
-In flexible mode: Allow with confirmation
-```
-
-### 4. Plan Update Operations
-
-[[LLM: Provide consistent way to update plan progress]]
-
-**Update Actions:**
-
-1. **Mark Step Complete**:
-   - Change `- [ ]` to `- [x]`
-   - Add completion timestamp comment
-   - Update any status metadata
-
-2. **Add Deviation Note**:
-   - Insert note explaining why sequence changed
-   - Reference the deviation in plan
-
-3. **Update Current Step Pointer**:
-   - Add/move `<!-- current-step -->` marker
-   - Update last-modified timestamp
-
-### 5. Integration Instructions
-
-[[LLM: How agents and tasks should use this utility]]
-
-**For Agents (startup sequence)**:
-
-```text
-1. Check if plan exists using this utility
-2. If exists:
-   - Parse current status
-   - Show user: "Active workflow plan detected. Current step: {X}"
-   - Suggest: "Next recommended action: {next_step}"
-3. Continue with normal startup
-```
-
-**For Tasks (pre-execution)**:
-
-```text
-1. Check if plan exists
-2. If exists:
-   - Verify this task aligns with plan
-   - If not aligned:
-     - In strict mode: Show warning and stop
-     - In flexible mode: Show warning and ask for confirmation
-3. After task completion:
-   - Update plan if task was a planned step
-   - Add note if task was unplanned
-```
-
-### 6. Plan Status Report Format
-
-[[LLM: Standard format for showing plan status]]
-
-```text
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Progress: {X}% complete ({completed}/{total} steps)
-
-✅ Completed:
-- {completed_step_1}
-- {completed_step_2}
-
-🔄 Current Step:
-- {current_step_description}
-
-📌 Upcoming:
-- {next_step_1}
-- {next_step_2}
-
-⚠️ Notes:
-- {any_deviations_or_notes}
-```
-
-### 7. Decision Point Handling
-
-[[LLM: Special handling for workflow decision points]]
-
-When encountering a decision point in the plan:
-
-1. **Identify Decision Marker**: `<!-- decision: {decision_id} -->`
-2. **Check Decision Status**: Made/Pending
-3. **If Pending**: 
-   - Block progress until decision made
-   - Show options to user
-   - Record decision when made
-4. **If Made**: 
-   - Verify current path aligns with decision
-   - Warn if attempting alternate path
-
-### 8. Plan Abandonment
-
-[[LLM: Graceful handling when user wants to stop following plan]]
-
-If user wants to abandon plan:
-
-1. Confirm abandonment intent
-2. Add abandonment note to plan
-3. Mark plan as "Abandoned" in header
-4. Stop plan checking for remainder of session
-5. Suggest creating new plan if needed
-
-## Usage Examples
-
-### Example 1: Agent Startup Check
-
-```text
-BMad Master starting...
-
-[Check for plan]
-Found active workflow plan: brownfield-fullstack
-Progress: 40% complete (4/10 steps)
-Current step: Create PRD (pm agent)
-
-Suggestion: Based on your plan, you should work with the PM agent next.
-Use *agent pm to switch, or *plan-status to see full progress.
-```
-
-### Example 2: Task Sequence Warning
-
-```text
-User: *task create-next-story
-
-[Plan check triggered]
-⚠️ SEQUENCE WARNING: 
-Your workflow plan indicates the PRD hasn't been created yet.
-Creating stories before the PRD may lead to incomplete requirements.
-
-Would you like to:
-1. Continue anyway (will note deviation in plan)
-2. Switch to creating PRD first (*agent pm)
-3. View plan status (*plan-status)
-```
-
-### Example 3: Automatic Plan Update
-
-```text
-[After completing create-doc task for PRD]
-
-✅ Plan Updated: Marked "Create PRD" as complete
-📍 Next step: Create Architecture Document (architect agent)
-```
-
-## Implementation Notes
-
-- This utility should be lightweight and fast
-- Plan parsing should be resilient to format variations
-- Always preserve user agency - warnings not blocks (unless strict mode)
-- Plan updates should be atomic to prevent corruption
-- Consider plan versioning for rollback capability
-
-## Error Handling
-
-- Missing plan: Return null, don't error
-- Malformed plan: Warn but continue, treat as no plan
-- Update failures: Log but don't block task completion
-- Parse errors: Fallback to basic text search
-==================== END: .bmad-core/utils/plan-management.md ====================
-
 ==================== START: .bmad-core/utils/workflow-management.md ====================
 # Workflow Management
 
@@ -2238,32 +2004,3 @@ Handle conditional paths by asking clarifying questions when needed.
 
 Agents should be workflow-aware: know active workflow, their role, access artifacts, understand expected outputs.
 ==================== END: .bmad-core/utils/workflow-management.md ====================
-
-==================== START: .bmad-core/utils/template-format.md ====================
-# Template Format Conventions
-
-Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
-
-## Template Markup Elements
-
-- **{{placeholders}}**: Variables to be replaced with actual content
-- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
-- **REPEAT** sections: Content blocks that may be repeated as needed
-- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
-- **@{examples}**: Example content for guidance (never output to users)
-
-## Processing Rules
-
-- Replace all {{placeholders}} with project-specific content
-- Execute all [[LLM: instructions]] internally without showing users
-- Process conditional and repeat blocks as specified
-- Use examples for guidance but never include them in final output
-- Present only clean, formatted content to users
-
-## Critical Guidelines
-
-- **NEVER display template markup, LLM instructions, or examples to users**
-- Template elements are for AI processing only
-- Focus on faithful template execution and clean output
-- All template-specific instructions are embedded within templates
-==================== END: .bmad-core/utils/template-format.md ====================

dist/agents/dev.txt

@@ -193,7 +193,7 @@ To comprehensively validate a story draft before implementation begins, ensuring
 
 ### 0. Load Core Configuration and Inputs
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `.bmad-core/core-config.yaml`
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story validation."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`
 - Identify and load the following inputs:

dist/agents/pm.txt

@@ -1360,9 +1360,9 @@ sections:
   - id: next-steps
     title: Next Steps
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
-        instruction: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.
+      - id: ux-expert-prompt
+        title: UX Expert Prompt
+        instruction: This section will contain the prompt for the UX Expert, keep it short and to the point to initiate create architecture mode using this document as input.
       - id: architect-prompt
         title: Architect Prompt
         instruction: This section will contain the prompt for the Architect, keep it short and to the point to initiate create architecture mode using this document as input.

dist/agents/po.txt

@@ -792,7 +792,7 @@ To comprehensively validate a story draft before implementation begins, ensuring
 
 ### 0. Load Core Configuration and Inputs
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `.bmad-core/core-config.yaml`
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story validation."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`
 - Identify and load the following inputs:

dist/agents/sm.txt

@@ -98,7 +98,6 @@ To identify the next logical story based on project progress and epic definition
 - Load `.bmad-core/core-config.yaml` from the project root
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can either: 1) Copy it from GITHUB bmad-core/core-config.yaml and configure it for your project OR 2) Run the BMad installer against your project to upgrade and add the file automatically. Please add and configure core-config.yaml before proceeding."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`, `workflow.*`
-- If `workflow.trackProgress: true`, use `utils/plan-management.md` to check plan sequence and warn if out of order
 
 ### 1. Identify Next Story for Preparation
 

dist/expansion-packs/bmad-2d-phaser-game-dev/teams/phaser-2d-nodejs-game-team.txt

@@ -128,9 +128,6 @@ CRITICAL: Read the full YAML, start activation to alter your state of being, fol
 ```yaml
 activation-instructions:
   - Mention *help shows all available commands and options
-  - Check for active workflow plan using .bmad-2d-phaser-game-dev/utils/plan-management.md
-  - 'If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details.'
-  - 'If plan exists: Suggest next action based on plan progress'
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -252,9 +249,7 @@ dependencies:
     - bmad-kb.md
     - elicitation-methods.md
   utils:
-    - plan-management.md
     - workflow-management.md
-    - template-format.md
 ```
 ==================== END: .bmad-2d-phaser-game-dev/agents/bmad-orchestrator.md ====================
 
@@ -3375,228 +3370,6 @@ The update is successful when:
 - Prepare to continue without additional elicitation
 ==================== END: .bmad-2d-phaser-game-dev/data/elicitation-methods.md ====================
 
-==================== START: .bmad-2d-phaser-game-dev/utils/plan-management.md ====================
-# Plan Management Utility
-
-## Purpose
-
-Provides utilities for agents and tasks to interact with workflow plans, check progress, update status, and ensure workflow steps are executed in the appropriate sequence.
-
-## Core Functions
-
-### 1. Check Plan Existence
-
-Check for workflow plan:
-
-1. Look for docs/workflow-plan.md (default location)
-2. Return plan status to user (exists/not exists) - if not exists then HALT.
-
-### 2. Parse Plan Status
-
-[[LLM: Extract current progress from the plan document]]
-
-**Plan Parsing Logic:**
-
-1. **Identify Step Structure**:
-   - Look for checkbox lines: `- [ ]` or `- [x]`
-   - Extract step IDs from comments: `<!-- step-id: X.Y -->`
-   - Identify agent assignments: `<!-- agent: pm -->`
-
-2. **Determine Current State**:
-   - Last completed step (highest numbered `[x]`)
-   - Next expected step (first `[ ]` after completed steps)
-   - Overall progress percentage
-
-3. **Extract Metadata**:
-   - Workflow type from plan header
-   - Decision points and their status
-   - Any deviation notes
-
-### 3. Sequence Validation
-
-[[LLM: Check if requested action aligns with plan sequence]]
-
-**Validation Rules:**
-
-1. **Strict Mode** (enforceSequence: true):
-   - Must complete steps in exact order
-   - Warn and block if out of sequence
-   - Require explicit override justification
-
-2. **Flexible Mode** (enforceSequence: false):
-   - Warn about sequence deviation
-   - Allow with confirmation
-   - Log deviation reason
-
-**Warning Templates:**
-
-```text
-SEQUENCE WARNING: 
-The workflow plan shows you should complete "{expected_step}" next.
-You're attempting to: "{requested_action}"
-
-In strict mode: Block and require plan update
-In flexible mode: Allow with confirmation
-```
-
-### 4. Plan Update Operations
-
-[[LLM: Provide consistent way to update plan progress]]
-
-**Update Actions:**
-
-1. **Mark Step Complete**:
-   - Change `- [ ]` to `- [x]`
-   - Add completion timestamp comment
-   - Update any status metadata
-
-2. **Add Deviation Note**:
-   - Insert note explaining why sequence changed
-   - Reference the deviation in plan
-
-3. **Update Current Step Pointer**:
-   - Add/move `<!-- current-step -->` marker
-   - Update last-modified timestamp
-
-### 5. Integration Instructions
-
-[[LLM: How agents and tasks should use this utility]]
-
-**For Agents (startup sequence)**:
-
-```text
-1. Check if plan exists using this utility
-2. If exists:
-   - Parse current status
-   - Show user: "Active workflow plan detected. Current step: {X}"
-   - Suggest: "Next recommended action: {next_step}"
-3. Continue with normal startup
-```
-
-**For Tasks (pre-execution)**:
-
-```text
-1. Check if plan exists
-2. If exists:
-   - Verify this task aligns with plan
-   - If not aligned:
-     - In strict mode: Show warning and stop
-     - In flexible mode: Show warning and ask for confirmation
-3. After task completion:
-   - Update plan if task was a planned step
-   - Add note if task was unplanned
-```
-
-### 6. Plan Status Report Format
-
-[[LLM: Standard format for showing plan status]]
-
-```text
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Progress: {X}% complete ({completed}/{total} steps)
-
-✅ Completed:
-- {completed_step_1}
-- {completed_step_2}
-
-🔄 Current Step:
-- {current_step_description}
-
-📌 Upcoming:
-- {next_step_1}
-- {next_step_2}
-
-⚠️ Notes:
-- {any_deviations_or_notes}
-```
-
-### 7. Decision Point Handling
-
-[[LLM: Special handling for workflow decision points]]
-
-When encountering a decision point in the plan:
-
-1. **Identify Decision Marker**: `<!-- decision: {decision_id} -->`
-2. **Check Decision Status**: Made/Pending
-3. **If Pending**: 
-   - Block progress until decision made
-   - Show options to user
-   - Record decision when made
-4. **If Made**: 
-   - Verify current path aligns with decision
-   - Warn if attempting alternate path
-
-### 8. Plan Abandonment
-
-[[LLM: Graceful handling when user wants to stop following plan]]
-
-If user wants to abandon plan:
-
-1. Confirm abandonment intent
-2. Add abandonment note to plan
-3. Mark plan as "Abandoned" in header
-4. Stop plan checking for remainder of session
-5. Suggest creating new plan if needed
-
-## Usage Examples
-
-### Example 1: Agent Startup Check
-
-```text
-BMad Master starting...
-
-[Check for plan]
-Found active workflow plan: brownfield-fullstack
-Progress: 40% complete (4/10 steps)
-Current step: Create PRD (pm agent)
-
-Suggestion: Based on your plan, you should work with the PM agent next.
-Use *agent pm to switch, or *plan-status to see full progress.
-```
-
-### Example 2: Task Sequence Warning
-
-```text
-User: *task create-next-story
-
-[Plan check triggered]
-⚠️ SEQUENCE WARNING: 
-Your workflow plan indicates the PRD hasn't been created yet.
-Creating stories before the PRD may lead to incomplete requirements.
-
-Would you like to:
-1. Continue anyway (will note deviation in plan)
-2. Switch to creating PRD first (*agent pm)
-3. View plan status (*plan-status)
-```
-
-### Example 3: Automatic Plan Update
-
-```text
-[After completing create-doc task for PRD]
-
-✅ Plan Updated: Marked "Create PRD" as complete
-📍 Next step: Create Architecture Document (architect agent)
-```
-
-## Implementation Notes
-
-- This utility should be lightweight and fast
-- Plan parsing should be resilient to format variations
-- Always preserve user agency - warnings not blocks (unless strict mode)
-- Plan updates should be atomic to prevent corruption
-- Consider plan versioning for rollback capability
-
-## Error Handling
-
-- Missing plan: Return null, don't error
-- Malformed plan: Warn but continue, treat as no plan
-- Update failures: Log but don't block task completion
-- Parse errors: Fallback to basic text search
-==================== END: .bmad-2d-phaser-game-dev/utils/plan-management.md ====================
-
 ==================== START: .bmad-2d-phaser-game-dev/utils/workflow-management.md ====================
 # Workflow Management
 
@@ -3669,35 +3442,6 @@ Handle conditional paths by asking clarifying questions when needed.
 Agents should be workflow-aware: know active workflow, their role, access artifacts, understand expected outputs.
 ==================== END: .bmad-2d-phaser-game-dev/utils/workflow-management.md ====================
 
-==================== START: .bmad-2d-phaser-game-dev/utils/template-format.md ====================
-# Template Format Conventions
-
-Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
-
-## Template Markup Elements
-
-- **{{placeholders}}**: Variables to be replaced with actual content
-- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
-- **REPEAT** sections: Content blocks that may be repeated as needed
-- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
-- **@{examples}**: Example content for guidance (never output to users)
-
-## Processing Rules
-
-- Replace all {{placeholders}} with project-specific content
-- Execute all [[LLM: instructions]] internally without showing users
-- Process conditional and repeat blocks as specified
-- Use examples for guidance but never include them in final output
-- Present only clean, formatted content to users
-
-## Critical Guidelines
-
-- **NEVER display template markup, LLM instructions, or examples to users**
-- Template elements are for AI processing only
-- Focus on faithful template execution and clean output
-- All template-specific instructions are embedded within templates
-==================== END: .bmad-2d-phaser-game-dev/utils/template-format.md ====================
-
 ==================== START: .bmad-2d-phaser-game-dev/tasks/execute-checklist.md ====================
 # Checklist Validation Task
 

dist/teams/team-all.txt

@@ -64,9 +64,6 @@ CRITICAL: Read the full YAML, start activation to alter your state of being, fol
 ```yaml
 activation-instructions:
   - Mention *help shows all available commands and options
-  - Check for active workflow plan using .bmad-core/utils/plan-management.md
-  - 'If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details.'
-  - 'If plan exists: Suggest next action based on plan progress'
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -188,9 +185,7 @@ dependencies:
     - bmad-kb.md
     - elicitation-methods.md
   utils:
-    - plan-management.md
     - workflow-management.md
-    - template-format.md
 ```
 ==================== END: .bmad-core/agents/bmad-orchestrator.md ====================
 
@@ -1866,17 +1861,10 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 
 BMad employs a sophisticated template system with three key components:
 
-1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
-2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+1. **Template Format** (`utils/bmad-doc-template.md`): Defines markup language for variable substitution and AI processing directives from yaml templates
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction to transform yaml spec to final markdown output
 3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
 
-**Template Features**:
-
-- **Self-contained**: Templates embed both output structure and processing instructions
-- **Variable Substitution**: `{{placeholders}}` for dynamic content
-- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
-- **Interactive Refinement**: Built-in elicitation processes for quality improvement
-
 ### Technical Preferences Integration
 
 The `technical-preferences.md` file serves as a persistent technical profile that:
@@ -2196,7 +2184,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -2266,8 +2254,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines
@@ -2410,228 +2398,6 @@ Use the **expansion-creator** pack to build your own:
 - Prepare to continue without additional elicitation
 ==================== END: .bmad-core/data/elicitation-methods.md ====================
 
-==================== START: .bmad-core/utils/plan-management.md ====================
-# Plan Management Utility
-
-## Purpose
-
-Provides utilities for agents and tasks to interact with workflow plans, check progress, update status, and ensure workflow steps are executed in the appropriate sequence.
-
-## Core Functions
-
-### 1. Check Plan Existence
-
-Check for workflow plan:
-
-1. Look for docs/workflow-plan.md (default location)
-2. Return plan status to user (exists/not exists) - if not exists then HALT.
-
-### 2. Parse Plan Status
-
-[[LLM: Extract current progress from the plan document]]
-
-**Plan Parsing Logic:**
-
-1. **Identify Step Structure**:
-   - Look for checkbox lines: `- [ ]` or `- [x]`
-   - Extract step IDs from comments: `<!-- step-id: X.Y -->`
-   - Identify agent assignments: `<!-- agent: pm -->`
-
-2. **Determine Current State**:
-   - Last completed step (highest numbered `[x]`)
-   - Next expected step (first `[ ]` after completed steps)
-   - Overall progress percentage
-
-3. **Extract Metadata**:
-   - Workflow type from plan header
-   - Decision points and their status
-   - Any deviation notes
-
-### 3. Sequence Validation
-
-[[LLM: Check if requested action aligns with plan sequence]]
-
-**Validation Rules:**
-
-1. **Strict Mode** (enforceSequence: true):
-   - Must complete steps in exact order
-   - Warn and block if out of sequence
-   - Require explicit override justification
-
-2. **Flexible Mode** (enforceSequence: false):
-   - Warn about sequence deviation
-   - Allow with confirmation
-   - Log deviation reason
-
-**Warning Templates:**
-
-```text
-SEQUENCE WARNING: 
-The workflow plan shows you should complete "{expected_step}" next.
-You're attempting to: "{requested_action}"
-
-In strict mode: Block and require plan update
-In flexible mode: Allow with confirmation
-```
-
-### 4. Plan Update Operations
-
-[[LLM: Provide consistent way to update plan progress]]
-
-**Update Actions:**
-
-1. **Mark Step Complete**:
-   - Change `- [ ]` to `- [x]`
-   - Add completion timestamp comment
-   - Update any status metadata
-
-2. **Add Deviation Note**:
-   - Insert note explaining why sequence changed
-   - Reference the deviation in plan
-
-3. **Update Current Step Pointer**:
-   - Add/move `<!-- current-step -->` marker
-   - Update last-modified timestamp
-
-### 5. Integration Instructions
-
-[[LLM: How agents and tasks should use this utility]]
-
-**For Agents (startup sequence)**:
-
-```text
-1. Check if plan exists using this utility
-2. If exists:
-   - Parse current status
-   - Show user: "Active workflow plan detected. Current step: {X}"
-   - Suggest: "Next recommended action: {next_step}"
-3. Continue with normal startup
-```
-
-**For Tasks (pre-execution)**:
-
-```text
-1. Check if plan exists
-2. If exists:
-   - Verify this task aligns with plan
-   - If not aligned:
-     - In strict mode: Show warning and stop
-     - In flexible mode: Show warning and ask for confirmation
-3. After task completion:
-   - Update plan if task was a planned step
-   - Add note if task was unplanned
-```
-
-### 6. Plan Status Report Format
-
-[[LLM: Standard format for showing plan status]]
-
-```text
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Progress: {X}% complete ({completed}/{total} steps)
-
-✅ Completed:
-- {completed_step_1}
-- {completed_step_2}
-
-🔄 Current Step:
-- {current_step_description}
-
-📌 Upcoming:
-- {next_step_1}
-- {next_step_2}
-
-⚠️ Notes:
-- {any_deviations_or_notes}
-```
-
-### 7. Decision Point Handling
-
-[[LLM: Special handling for workflow decision points]]
-
-When encountering a decision point in the plan:
-
-1. **Identify Decision Marker**: `<!-- decision: {decision_id} -->`
-2. **Check Decision Status**: Made/Pending
-3. **If Pending**: 
-   - Block progress until decision made
-   - Show options to user
-   - Record decision when made
-4. **If Made**: 
-   - Verify current path aligns with decision
-   - Warn if attempting alternate path
-
-### 8. Plan Abandonment
-
-[[LLM: Graceful handling when user wants to stop following plan]]
-
-If user wants to abandon plan:
-
-1. Confirm abandonment intent
-2. Add abandonment note to plan
-3. Mark plan as "Abandoned" in header
-4. Stop plan checking for remainder of session
-5. Suggest creating new plan if needed
-
-## Usage Examples
-
-### Example 1: Agent Startup Check
-
-```text
-BMad Master starting...
-
-[Check for plan]
-Found active workflow plan: brownfield-fullstack
-Progress: 40% complete (4/10 steps)
-Current step: Create PRD (pm agent)
-
-Suggestion: Based on your plan, you should work with the PM agent next.
-Use *agent pm to switch, or *plan-status to see full progress.
-```
-
-### Example 2: Task Sequence Warning
-
-```text
-User: *task create-next-story
-
-[Plan check triggered]
-⚠️ SEQUENCE WARNING: 
-Your workflow plan indicates the PRD hasn't been created yet.
-Creating stories before the PRD may lead to incomplete requirements.
-
-Would you like to:
-1. Continue anyway (will note deviation in plan)
-2. Switch to creating PRD first (*agent pm)
-3. View plan status (*plan-status)
-```
-
-### Example 3: Automatic Plan Update
-
-```text
-[After completing create-doc task for PRD]
-
-✅ Plan Updated: Marked "Create PRD" as complete
-📍 Next step: Create Architecture Document (architect agent)
-```
-
-## Implementation Notes
-
-- This utility should be lightweight and fast
-- Plan parsing should be resilient to format variations
-- Always preserve user agency - warnings not blocks (unless strict mode)
-- Plan updates should be atomic to prevent corruption
-- Consider plan versioning for rollback capability
-
-## Error Handling
-
-- Missing plan: Return null, don't error
-- Malformed plan: Warn but continue, treat as no plan
-- Update failures: Log but don't block task completion
-- Parse errors: Fallback to basic text search
-==================== END: .bmad-core/utils/plan-management.md ====================
-
 ==================== START: .bmad-core/utils/workflow-management.md ====================
 # Workflow Management
 
@@ -2704,35 +2470,6 @@ Handle conditional paths by asking clarifying questions when needed.
 Agents should be workflow-aware: know active workflow, their role, access artifacts, understand expected outputs.
 ==================== END: .bmad-core/utils/workflow-management.md ====================
 
-==================== START: .bmad-core/utils/template-format.md ====================
-# Template Format Conventions
-
-Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
-
-## Template Markup Elements
-
-- **{{placeholders}}**: Variables to be replaced with actual content
-- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
-- **REPEAT** sections: Content blocks that may be repeated as needed
-- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
-- **@{examples}**: Example content for guidance (never output to users)
-
-## Processing Rules
-
-- Replace all {{placeholders}} with project-specific content
-- Execute all [[LLM: instructions]] internally without showing users
-- Process conditional and repeat blocks as specified
-- Use examples for guidance but never include them in final output
-- Present only clean, formatted content to users
-
-## Critical Guidelines
-
-- **NEVER display template markup, LLM instructions, or examples to users**
-- Template elements are for AI processing only
-- Focus on faithful template execution and clean output
-- All template-specific instructions are embedded within templates
-==================== END: .bmad-core/utils/template-format.md ====================
-
 ==================== START: .bmad-core/tasks/facilitate-brainstorming-session.md ====================
 ---
 docOutputLocation: docs/brainstorming-session-results.md
@@ -5197,7 +4934,6 @@ sections:
       After completing the architecture:
       
       1. If project has UI components:
-      - Recommend engaging Design Architect agent
       - Use "Frontend Architecture Mode"
       - Provide this document as input
       
@@ -5208,22 +4944,15 @@ sections:
       
       3. Include specific prompts for next agents if needed
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
+      - id: architect-prompt
+        title: Architect Prompt
         condition: Project has UI components
         instruction: |
-          Create a brief prompt to hand off to Design Architect for Frontend Architecture creation. Include:
+          Create a brief prompt to hand off to Architect for Frontend Architecture creation. Include:
           - Reference to this architecture document
           - Key UI requirements from PRD
           - Any frontend-specific decisions made here
           - Request for detailed frontend architecture
-      - id: developer-handoff
-        title: Developer Handoff
-        instruction: |
-          Create a brief prompt for developers starting implementation. Include:
-          - Reference to this architecture and coding standards
-          - First epic/story to implement
-          - Key technical decisions to follow
 ==================== END: .bmad-core/templates/architecture-tmpl.yaml ====================
 
 ==================== START: .bmad-core/templates/front-end-architecture-tmpl.yaml ====================
@@ -7185,7 +6914,7 @@ To comprehensively validate a story draft before implementation begins, ensuring
 
 ### 0. Load Core Configuration and Inputs
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `.bmad-core/core-config.yaml`
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story validation."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`
 - Identify and load the following inputs:
@@ -8195,9 +7924,9 @@ sections:
   - id: next-steps
     title: Next Steps
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
-        instruction: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.
+      - id: ux-expert-prompt
+        title: UX Expert Prompt
+        instruction: This section will contain the prompt for the UX Expert, keep it short and to the point to initiate create architecture mode using this document as input.
       - id: architect-prompt
         title: Architect Prompt
         instruction: This section will contain the prompt for the Architect, keep it short and to the point to initiate create architecture mode using this document as input.
@@ -9795,7 +9524,6 @@ To identify the next logical story based on project progress and epic definition
 - Load `.bmad-core/core-config.yaml` from the project root
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can either: 1) Copy it from GITHUB bmad-core/core-config.yaml and configure it for your project OR 2) Run the BMad installer against your project to upgrade and add the file automatically. Please add and configure core-config.yaml before proceeding."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`, `workflow.*`
-- If `workflow.trackProgress: true`, use `utils/plan-management.md` to check plan sequence and warn if out of order
 
 ### 1. Identify Next Story for Preparation
 
@@ -10648,7 +10376,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid
@@ -10894,7 +10622,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid
@@ -11091,7 +10819,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid
@@ -11316,7 +11044,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid
@@ -11763,7 +11491,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

dist/teams/team-fullstack.txt

@@ -68,9 +68,6 @@ CRITICAL: Read the full YAML, start activation to alter your state of being, fol
 ```yaml
 activation-instructions:
   - Mention *help shows all available commands and options
-  - Check for active workflow plan using .bmad-core/utils/plan-management.md
-  - 'If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details.'
-  - 'If plan exists: Suggest next action based on plan progress'
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -192,9 +189,7 @@ dependencies:
     - bmad-kb.md
     - elicitation-methods.md
   utils:
-    - plan-management.md
     - workflow-management.md
-    - template-format.md
 ```
 ==================== END: .bmad-core/agents/bmad-orchestrator.md ====================
 
@@ -1724,17 +1719,10 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 
 BMad employs a sophisticated template system with three key components:
 
-1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
-2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+1. **Template Format** (`utils/bmad-doc-template.md`): Defines markup language for variable substitution and AI processing directives from yaml templates
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction to transform yaml spec to final markdown output
 3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
 
-**Template Features**:
-
-- **Self-contained**: Templates embed both output structure and processing instructions
-- **Variable Substitution**: `{{placeholders}}` for dynamic content
-- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
-- **Interactive Refinement**: Built-in elicitation processes for quality improvement
-
 ### Technical Preferences Integration
 
 The `technical-preferences.md` file serves as a persistent technical profile that:
@@ -2054,7 +2042,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -2124,8 +2112,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines
@@ -2268,228 +2256,6 @@ Use the **expansion-creator** pack to build your own:
 - Prepare to continue without additional elicitation
 ==================== END: .bmad-core/data/elicitation-methods.md ====================
 
-==================== START: .bmad-core/utils/plan-management.md ====================
-# Plan Management Utility
-
-## Purpose
-
-Provides utilities for agents and tasks to interact with workflow plans, check progress, update status, and ensure workflow steps are executed in the appropriate sequence.
-
-## Core Functions
-
-### 1. Check Plan Existence
-
-Check for workflow plan:
-
-1. Look for docs/workflow-plan.md (default location)
-2. Return plan status to user (exists/not exists) - if not exists then HALT.
-
-### 2. Parse Plan Status
-
-[[LLM: Extract current progress from the plan document]]
-
-**Plan Parsing Logic:**
-
-1. **Identify Step Structure**:
-   - Look for checkbox lines: `- [ ]` or `- [x]`
-   - Extract step IDs from comments: `<!-- step-id: X.Y -->`
-   - Identify agent assignments: `<!-- agent: pm -->`
-
-2. **Determine Current State**:
-   - Last completed step (highest numbered `[x]`)
-   - Next expected step (first `[ ]` after completed steps)
-   - Overall progress percentage
-
-3. **Extract Metadata**:
-   - Workflow type from plan header
-   - Decision points and their status
-   - Any deviation notes
-
-### 3. Sequence Validation
-
-[[LLM: Check if requested action aligns with plan sequence]]
-
-**Validation Rules:**
-
-1. **Strict Mode** (enforceSequence: true):
-   - Must complete steps in exact order
-   - Warn and block if out of sequence
-   - Require explicit override justification
-
-2. **Flexible Mode** (enforceSequence: false):
-   - Warn about sequence deviation
-   - Allow with confirmation
-   - Log deviation reason
-
-**Warning Templates:**
-
-```text
-SEQUENCE WARNING: 
-The workflow plan shows you should complete "{expected_step}" next.
-You're attempting to: "{requested_action}"
-
-In strict mode: Block and require plan update
-In flexible mode: Allow with confirmation
-```
-
-### 4. Plan Update Operations
-
-[[LLM: Provide consistent way to update plan progress]]
-
-**Update Actions:**
-
-1. **Mark Step Complete**:
-   - Change `- [ ]` to `- [x]`
-   - Add completion timestamp comment
-   - Update any status metadata
-
-2. **Add Deviation Note**:
-   - Insert note explaining why sequence changed
-   - Reference the deviation in plan
-
-3. **Update Current Step Pointer**:
-   - Add/move `<!-- current-step -->` marker
-   - Update last-modified timestamp
-
-### 5. Integration Instructions
-
-[[LLM: How agents and tasks should use this utility]]
-
-**For Agents (startup sequence)**:
-
-```text
-1. Check if plan exists using this utility
-2. If exists:
-   - Parse current status
-   - Show user: "Active workflow plan detected. Current step: {X}"
-   - Suggest: "Next recommended action: {next_step}"
-3. Continue with normal startup
-```
-
-**For Tasks (pre-execution)**:
-
-```text
-1. Check if plan exists
-2. If exists:
-   - Verify this task aligns with plan
-   - If not aligned:
-     - In strict mode: Show warning and stop
-     - In flexible mode: Show warning and ask for confirmation
-3. After task completion:
-   - Update plan if task was a planned step
-   - Add note if task was unplanned
-```
-
-### 6. Plan Status Report Format
-
-[[LLM: Standard format for showing plan status]]
-
-```text
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Progress: {X}% complete ({completed}/{total} steps)
-
-✅ Completed:
-- {completed_step_1}
-- {completed_step_2}
-
-🔄 Current Step:
-- {current_step_description}
-
-📌 Upcoming:
-- {next_step_1}
-- {next_step_2}
-
-⚠️ Notes:
-- {any_deviations_or_notes}
-```
-
-### 7. Decision Point Handling
-
-[[LLM: Special handling for workflow decision points]]
-
-When encountering a decision point in the plan:
-
-1. **Identify Decision Marker**: `<!-- decision: {decision_id} -->`
-2. **Check Decision Status**: Made/Pending
-3. **If Pending**: 
-   - Block progress until decision made
-   - Show options to user
-   - Record decision when made
-4. **If Made**: 
-   - Verify current path aligns with decision
-   - Warn if attempting alternate path
-
-### 8. Plan Abandonment
-
-[[LLM: Graceful handling when user wants to stop following plan]]
-
-If user wants to abandon plan:
-
-1. Confirm abandonment intent
-2. Add abandonment note to plan
-3. Mark plan as "Abandoned" in header
-4. Stop plan checking for remainder of session
-5. Suggest creating new plan if needed
-
-## Usage Examples
-
-### Example 1: Agent Startup Check
-
-```text
-BMad Master starting...
-
-[Check for plan]
-Found active workflow plan: brownfield-fullstack
-Progress: 40% complete (4/10 steps)
-Current step: Create PRD (pm agent)
-
-Suggestion: Based on your plan, you should work with the PM agent next.
-Use *agent pm to switch, or *plan-status to see full progress.
-```
-
-### Example 2: Task Sequence Warning
-
-```text
-User: *task create-next-story
-
-[Plan check triggered]
-⚠️ SEQUENCE WARNING: 
-Your workflow plan indicates the PRD hasn't been created yet.
-Creating stories before the PRD may lead to incomplete requirements.
-
-Would you like to:
-1. Continue anyway (will note deviation in plan)
-2. Switch to creating PRD first (*agent pm)
-3. View plan status (*plan-status)
-```
-
-### Example 3: Automatic Plan Update
-
-```text
-[After completing create-doc task for PRD]
-
-✅ Plan Updated: Marked "Create PRD" as complete
-📍 Next step: Create Architecture Document (architect agent)
-```
-
-## Implementation Notes
-
-- This utility should be lightweight and fast
-- Plan parsing should be resilient to format variations
-- Always preserve user agency - warnings not blocks (unless strict mode)
-- Plan updates should be atomic to prevent corruption
-- Consider plan versioning for rollback capability
-
-## Error Handling
-
-- Missing plan: Return null, don't error
-- Malformed plan: Warn but continue, treat as no plan
-- Update failures: Log but don't block task completion
-- Parse errors: Fallback to basic text search
-==================== END: .bmad-core/utils/plan-management.md ====================
-
 ==================== START: .bmad-core/utils/workflow-management.md ====================
 # Workflow Management
 
@@ -2562,35 +2328,6 @@ Handle conditional paths by asking clarifying questions when needed.
 Agents should be workflow-aware: know active workflow, their role, access artifacts, understand expected outputs.
 ==================== END: .bmad-core/utils/workflow-management.md ====================
 
-==================== START: .bmad-core/utils/template-format.md ====================
-# Template Format Conventions
-
-Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
-
-## Template Markup Elements
-
-- **{{placeholders}}**: Variables to be replaced with actual content
-- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
-- **REPEAT** sections: Content blocks that may be repeated as needed
-- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
-- **@{examples}**: Example content for guidance (never output to users)
-
-## Processing Rules
-
-- Replace all {{placeholders}} with project-specific content
-- Execute all [[LLM: instructions]] internally without showing users
-- Process conditional and repeat blocks as specified
-- Use examples for guidance but never include them in final output
-- Present only clean, formatted content to users
-
-## Critical Guidelines
-
-- **NEVER display template markup, LLM instructions, or examples to users**
-- Template elements are for AI processing only
-- Focus on faithful template execution and clean output
-- All template-specific instructions are embedded within templates
-==================== END: .bmad-core/utils/template-format.md ====================
-
 ==================== START: .bmad-core/tasks/facilitate-brainstorming-session.md ====================
 ---
 docOutputLocation: docs/brainstorming-session-results.md
@@ -5203,9 +4940,9 @@ sections:
   - id: next-steps
     title: Next Steps
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
-        instruction: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.
+      - id: ux-expert-prompt
+        title: UX Expert Prompt
+        instruction: This section will contain the prompt for the UX Expert, keep it short and to the point to initiate create architecture mode using this document as input.
       - id: architect-prompt
         title: Architect Prompt
         instruction: This section will contain the prompt for the Architect, keep it short and to the point to initiate create architecture mode using this document as input.
@@ -7101,7 +6838,6 @@ sections:
       After completing the architecture:
       
       1. If project has UI components:
-      - Recommend engaging Design Architect agent
       - Use "Frontend Architecture Mode"
       - Provide this document as input
       
@@ -7112,22 +6848,15 @@ sections:
       
       3. Include specific prompts for next agents if needed
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
+      - id: architect-prompt
+        title: Architect Prompt
         condition: Project has UI components
         instruction: |
-          Create a brief prompt to hand off to Design Architect for Frontend Architecture creation. Include:
+          Create a brief prompt to hand off to Architect for Frontend Architecture creation. Include:
           - Reference to this architecture document
           - Key UI requirements from PRD
           - Any frontend-specific decisions made here
           - Request for detailed frontend architecture
-      - id: developer-handoff
-        title: Developer Handoff
-        instruction: |
-          Create a brief prompt for developers starting implementation. Include:
-          - Reference to this architecture and coding standards
-          - First epic/story to implement
-          - Key technical decisions to follow
 ==================== END: .bmad-core/templates/architecture-tmpl.yaml ====================
 
 ==================== START: .bmad-core/templates/front-end-architecture-tmpl.yaml ====================
@@ -9083,7 +8812,7 @@ To comprehensively validate a story draft before implementation begins, ensuring
 
 ### 0. Load Core Configuration and Inputs
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `.bmad-core/core-config.yaml`
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story validation."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`
 - Identify and load the following inputs:
@@ -9978,7 +9707,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid
@@ -10224,7 +9953,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid
@@ -10421,7 +10150,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid
@@ -10646,7 +10375,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid
@@ -11093,7 +10822,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

dist/teams/team-ide-minimal.txt

@@ -60,9 +60,6 @@ CRITICAL: Read the full YAML, start activation to alter your state of being, fol
 ```yaml
 activation-instructions:
   - Mention *help shows all available commands and options
-  - Check for active workflow plan using .bmad-core/utils/plan-management.md
-  - 'If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details.'
-  - 'If plan exists: Suggest next action based on plan progress'
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -184,9 +181,7 @@ dependencies:
     - bmad-kb.md
     - elicitation-methods.md
   utils:
-    - plan-management.md
     - workflow-management.md
-    - template-format.md
 ```
 ==================== END: .bmad-core/agents/bmad-orchestrator.md ====================
 
@@ -1623,17 +1618,10 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 
 BMad employs a sophisticated template system with three key components:
 
-1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
-2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+1. **Template Format** (`utils/bmad-doc-template.md`): Defines markup language for variable substitution and AI processing directives from yaml templates
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction to transform yaml spec to final markdown output
 3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
 
-**Template Features**:
-
-- **Self-contained**: Templates embed both output structure and processing instructions
-- **Variable Substitution**: `{{placeholders}}` for dynamic content
-- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
-- **Interactive Refinement**: Built-in elicitation processes for quality improvement
-
 ### Technical Preferences Integration
 
 The `technical-preferences.md` file serves as a persistent technical profile that:
@@ -1953,7 +1941,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -2023,8 +2011,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines
@@ -2167,228 +2155,6 @@ Use the **expansion-creator** pack to build your own:
 - Prepare to continue without additional elicitation
 ==================== END: .bmad-core/data/elicitation-methods.md ====================
 
-==================== START: .bmad-core/utils/plan-management.md ====================
-# Plan Management Utility
-
-## Purpose
-
-Provides utilities for agents and tasks to interact with workflow plans, check progress, update status, and ensure workflow steps are executed in the appropriate sequence.
-
-## Core Functions
-
-### 1. Check Plan Existence
-
-Check for workflow plan:
-
-1. Look for docs/workflow-plan.md (default location)
-2. Return plan status to user (exists/not exists) - if not exists then HALT.
-
-### 2. Parse Plan Status
-
-[[LLM: Extract current progress from the plan document]]
-
-**Plan Parsing Logic:**
-
-1. **Identify Step Structure**:
-   - Look for checkbox lines: `- [ ]` or `- [x]`
-   - Extract step IDs from comments: `<!-- step-id: X.Y -->`
-   - Identify agent assignments: `<!-- agent: pm -->`
-
-2. **Determine Current State**:
-   - Last completed step (highest numbered `[x]`)
-   - Next expected step (first `[ ]` after completed steps)
-   - Overall progress percentage
-
-3. **Extract Metadata**:
-   - Workflow type from plan header
-   - Decision points and their status
-   - Any deviation notes
-
-### 3. Sequence Validation
-
-[[LLM: Check if requested action aligns with plan sequence]]
-
-**Validation Rules:**
-
-1. **Strict Mode** (enforceSequence: true):
-   - Must complete steps in exact order
-   - Warn and block if out of sequence
-   - Require explicit override justification
-
-2. **Flexible Mode** (enforceSequence: false):
-   - Warn about sequence deviation
-   - Allow with confirmation
-   - Log deviation reason
-
-**Warning Templates:**
-
-```text
-SEQUENCE WARNING: 
-The workflow plan shows you should complete "{expected_step}" next.
-You're attempting to: "{requested_action}"
-
-In strict mode: Block and require plan update
-In flexible mode: Allow with confirmation
-```
-
-### 4. Plan Update Operations
-
-[[LLM: Provide consistent way to update plan progress]]
-
-**Update Actions:**
-
-1. **Mark Step Complete**:
-   - Change `- [ ]` to `- [x]`
-   - Add completion timestamp comment
-   - Update any status metadata
-
-2. **Add Deviation Note**:
-   - Insert note explaining why sequence changed
-   - Reference the deviation in plan
-
-3. **Update Current Step Pointer**:
-   - Add/move `<!-- current-step -->` marker
-   - Update last-modified timestamp
-
-### 5. Integration Instructions
-
-[[LLM: How agents and tasks should use this utility]]
-
-**For Agents (startup sequence)**:
-
-```text
-1. Check if plan exists using this utility
-2. If exists:
-   - Parse current status
-   - Show user: "Active workflow plan detected. Current step: {X}"
-   - Suggest: "Next recommended action: {next_step}"
-3. Continue with normal startup
-```
-
-**For Tasks (pre-execution)**:
-
-```text
-1. Check if plan exists
-2. If exists:
-   - Verify this task aligns with plan
-   - If not aligned:
-     - In strict mode: Show warning and stop
-     - In flexible mode: Show warning and ask for confirmation
-3. After task completion:
-   - Update plan if task was a planned step
-   - Add note if task was unplanned
-```
-
-### 6. Plan Status Report Format
-
-[[LLM: Standard format for showing plan status]]
-
-```text
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Progress: {X}% complete ({completed}/{total} steps)
-
-✅ Completed:
-- {completed_step_1}
-- {completed_step_2}
-
-🔄 Current Step:
-- {current_step_description}
-
-📌 Upcoming:
-- {next_step_1}
-- {next_step_2}
-
-⚠️ Notes:
-- {any_deviations_or_notes}
-```
-
-### 7. Decision Point Handling
-
-[[LLM: Special handling for workflow decision points]]
-
-When encountering a decision point in the plan:
-
-1. **Identify Decision Marker**: `<!-- decision: {decision_id} -->`
-2. **Check Decision Status**: Made/Pending
-3. **If Pending**: 
-   - Block progress until decision made
-   - Show options to user
-   - Record decision when made
-4. **If Made**: 
-   - Verify current path aligns with decision
-   - Warn if attempting alternate path
-
-### 8. Plan Abandonment
-
-[[LLM: Graceful handling when user wants to stop following plan]]
-
-If user wants to abandon plan:
-
-1. Confirm abandonment intent
-2. Add abandonment note to plan
-3. Mark plan as "Abandoned" in header
-4. Stop plan checking for remainder of session
-5. Suggest creating new plan if needed
-
-## Usage Examples
-
-### Example 1: Agent Startup Check
-
-```text
-BMad Master starting...
-
-[Check for plan]
-Found active workflow plan: brownfield-fullstack
-Progress: 40% complete (4/10 steps)
-Current step: Create PRD (pm agent)
-
-Suggestion: Based on your plan, you should work with the PM agent next.
-Use *agent pm to switch, or *plan-status to see full progress.
-```
-
-### Example 2: Task Sequence Warning
-
-```text
-User: *task create-next-story
-
-[Plan check triggered]
-⚠️ SEQUENCE WARNING: 
-Your workflow plan indicates the PRD hasn't been created yet.
-Creating stories before the PRD may lead to incomplete requirements.
-
-Would you like to:
-1. Continue anyway (will note deviation in plan)
-2. Switch to creating PRD first (*agent pm)
-3. View plan status (*plan-status)
-```
-
-### Example 3: Automatic Plan Update
-
-```text
-[After completing create-doc task for PRD]
-
-✅ Plan Updated: Marked "Create PRD" as complete
-📍 Next step: Create Architecture Document (architect agent)
-```
-
-## Implementation Notes
-
-- This utility should be lightweight and fast
-- Plan parsing should be resilient to format variations
-- Always preserve user agency - warnings not blocks (unless strict mode)
-- Plan updates should be atomic to prevent corruption
-- Consider plan versioning for rollback capability
-
-## Error Handling
-
-- Missing plan: Return null, don't error
-- Malformed plan: Warn but continue, treat as no plan
-- Update failures: Log but don't block task completion
-- Parse errors: Fallback to basic text search
-==================== END: .bmad-core/utils/plan-management.md ====================
-
 ==================== START: .bmad-core/utils/workflow-management.md ====================
 # Workflow Management
 
@@ -2461,35 +2227,6 @@ Handle conditional paths by asking clarifying questions when needed.
 Agents should be workflow-aware: know active workflow, their role, access artifacts, understand expected outputs.
 ==================== END: .bmad-core/utils/workflow-management.md ====================
 
-==================== START: .bmad-core/utils/template-format.md ====================
-# Template Format Conventions
-
-Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
-
-## Template Markup Elements
-
-- **{{placeholders}}**: Variables to be replaced with actual content
-- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
-- **REPEAT** sections: Content blocks that may be repeated as needed
-- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
-- **@{examples}**: Example content for guidance (never output to users)
-
-## Processing Rules
-
-- Replace all {{placeholders}} with project-specific content
-- Execute all [[LLM: instructions]] internally without showing users
-- Process conditional and repeat blocks as specified
-- Use examples for guidance but never include them in final output
-- Present only clean, formatted content to users
-
-## Critical Guidelines
-
-- **NEVER display template markup, LLM instructions, or examples to users**
-- Template elements are for AI processing only
-- Focus on faithful template execution and clean output
-- All template-specific instructions are embedded within templates
-==================== END: .bmad-core/utils/template-format.md ====================
-
 ==================== START: .bmad-core/tasks/execute-checklist.md ====================
 # Checklist Validation Task
 
@@ -3180,7 +2917,7 @@ To comprehensively validate a story draft before implementation begins, ensuring
 
 ### 0. Load Core Configuration and Inputs
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `.bmad-core/core-config.yaml`
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story validation."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`
 - Identify and load the following inputs:
@@ -4089,7 +3826,6 @@ To identify the next logical story based on project progress and epic definition
 - Load `.bmad-core/core-config.yaml` from the project root
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can either: 1) Copy it from GITHUB bmad-core/core-config.yaml and configure it for your project OR 2) Run the BMad installer against your project to upgrade and add the file automatically. Please add and configure core-config.yaml before proceeding."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`, `workflow.*`
-- If `workflow.trackProgress: true`, use `utils/plan-management.md` to check plan sequence and warn if out of order
 
 ### 1. Identify Next Story for Preparation
 

dist/teams/team-no-ui.txt

@@ -63,9 +63,6 @@ CRITICAL: Read the full YAML, start activation to alter your state of being, fol
 ```yaml
 activation-instructions:
   - Mention *help shows all available commands and options
-  - Check for active workflow plan using .bmad-core/utils/plan-management.md
-  - 'If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details.'
-  - 'If plan exists: Suggest next action based on plan progress'
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -187,9 +184,7 @@ dependencies:
     - bmad-kb.md
     - elicitation-methods.md
   utils:
-    - plan-management.md
     - workflow-management.md
-    - template-format.md
 ```
 ==================== END: .bmad-core/agents/bmad-orchestrator.md ====================
 
@@ -1666,17 +1661,10 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 
 BMad employs a sophisticated template system with three key components:
 
-1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
-2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+1. **Template Format** (`utils/bmad-doc-template.md`): Defines markup language for variable substitution and AI processing directives from yaml templates
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction to transform yaml spec to final markdown output
 3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
 
-**Template Features**:
-
-- **Self-contained**: Templates embed both output structure and processing instructions
-- **Variable Substitution**: `{{placeholders}}` for dynamic content
-- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
-- **Interactive Refinement**: Built-in elicitation processes for quality improvement
-
 ### Technical Preferences Integration
 
 The `technical-preferences.md` file serves as a persistent technical profile that:
@@ -1996,7 +1984,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -2066,8 +2054,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines
@@ -2210,228 +2198,6 @@ Use the **expansion-creator** pack to build your own:
 - Prepare to continue without additional elicitation
 ==================== END: .bmad-core/data/elicitation-methods.md ====================
 
-==================== START: .bmad-core/utils/plan-management.md ====================
-# Plan Management Utility
-
-## Purpose
-
-Provides utilities for agents and tasks to interact with workflow plans, check progress, update status, and ensure workflow steps are executed in the appropriate sequence.
-
-## Core Functions
-
-### 1. Check Plan Existence
-
-Check for workflow plan:
-
-1. Look for docs/workflow-plan.md (default location)
-2. Return plan status to user (exists/not exists) - if not exists then HALT.
-
-### 2. Parse Plan Status
-
-[[LLM: Extract current progress from the plan document]]
-
-**Plan Parsing Logic:**
-
-1. **Identify Step Structure**:
-   - Look for checkbox lines: `- [ ]` or `- [x]`
-   - Extract step IDs from comments: `<!-- step-id: X.Y -->`
-   - Identify agent assignments: `<!-- agent: pm -->`
-
-2. **Determine Current State**:
-   - Last completed step (highest numbered `[x]`)
-   - Next expected step (first `[ ]` after completed steps)
-   - Overall progress percentage
-
-3. **Extract Metadata**:
-   - Workflow type from plan header
-   - Decision points and their status
-   - Any deviation notes
-
-### 3. Sequence Validation
-
-[[LLM: Check if requested action aligns with plan sequence]]
-
-**Validation Rules:**
-
-1. **Strict Mode** (enforceSequence: true):
-   - Must complete steps in exact order
-   - Warn and block if out of sequence
-   - Require explicit override justification
-
-2. **Flexible Mode** (enforceSequence: false):
-   - Warn about sequence deviation
-   - Allow with confirmation
-   - Log deviation reason
-
-**Warning Templates:**
-
-```text
-SEQUENCE WARNING: 
-The workflow plan shows you should complete "{expected_step}" next.
-You're attempting to: "{requested_action}"
-
-In strict mode: Block and require plan update
-In flexible mode: Allow with confirmation
-```
-
-### 4. Plan Update Operations
-
-[[LLM: Provide consistent way to update plan progress]]
-
-**Update Actions:**
-
-1. **Mark Step Complete**:
-   - Change `- [ ]` to `- [x]`
-   - Add completion timestamp comment
-   - Update any status metadata
-
-2. **Add Deviation Note**:
-   - Insert note explaining why sequence changed
-   - Reference the deviation in plan
-
-3. **Update Current Step Pointer**:
-   - Add/move `<!-- current-step -->` marker
-   - Update last-modified timestamp
-
-### 5. Integration Instructions
-
-[[LLM: How agents and tasks should use this utility]]
-
-**For Agents (startup sequence)**:
-
-```text
-1. Check if plan exists using this utility
-2. If exists:
-   - Parse current status
-   - Show user: "Active workflow plan detected. Current step: {X}"
-   - Suggest: "Next recommended action: {next_step}"
-3. Continue with normal startup
-```
-
-**For Tasks (pre-execution)**:
-
-```text
-1. Check if plan exists
-2. If exists:
-   - Verify this task aligns with plan
-   - If not aligned:
-     - In strict mode: Show warning and stop
-     - In flexible mode: Show warning and ask for confirmation
-3. After task completion:
-   - Update plan if task was a planned step
-   - Add note if task was unplanned
-```
-
-### 6. Plan Status Report Format
-
-[[LLM: Standard format for showing plan status]]
-
-```text
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Progress: {X}% complete ({completed}/{total} steps)
-
-✅ Completed:
-- {completed_step_1}
-- {completed_step_2}
-
-🔄 Current Step:
-- {current_step_description}
-
-📌 Upcoming:
-- {next_step_1}
-- {next_step_2}
-
-⚠️ Notes:
-- {any_deviations_or_notes}
-```
-
-### 7. Decision Point Handling
-
-[[LLM: Special handling for workflow decision points]]
-
-When encountering a decision point in the plan:
-
-1. **Identify Decision Marker**: `<!-- decision: {decision_id} -->`
-2. **Check Decision Status**: Made/Pending
-3. **If Pending**: 
-   - Block progress until decision made
-   - Show options to user
-   - Record decision when made
-4. **If Made**: 
-   - Verify current path aligns with decision
-   - Warn if attempting alternate path
-
-### 8. Plan Abandonment
-
-[[LLM: Graceful handling when user wants to stop following plan]]
-
-If user wants to abandon plan:
-
-1. Confirm abandonment intent
-2. Add abandonment note to plan
-3. Mark plan as "Abandoned" in header
-4. Stop plan checking for remainder of session
-5. Suggest creating new plan if needed
-
-## Usage Examples
-
-### Example 1: Agent Startup Check
-
-```text
-BMad Master starting...
-
-[Check for plan]
-Found active workflow plan: brownfield-fullstack
-Progress: 40% complete (4/10 steps)
-Current step: Create PRD (pm agent)
-
-Suggestion: Based on your plan, you should work with the PM agent next.
-Use *agent pm to switch, or *plan-status to see full progress.
-```
-
-### Example 2: Task Sequence Warning
-
-```text
-User: *task create-next-story
-
-[Plan check triggered]
-⚠️ SEQUENCE WARNING: 
-Your workflow plan indicates the PRD hasn't been created yet.
-Creating stories before the PRD may lead to incomplete requirements.
-
-Would you like to:
-1. Continue anyway (will note deviation in plan)
-2. Switch to creating PRD first (*agent pm)
-3. View plan status (*plan-status)
-```
-
-### Example 3: Automatic Plan Update
-
-```text
-[After completing create-doc task for PRD]
-
-✅ Plan Updated: Marked "Create PRD" as complete
-📍 Next step: Create Architecture Document (architect agent)
-```
-
-## Implementation Notes
-
-- This utility should be lightweight and fast
-- Plan parsing should be resilient to format variations
-- Always preserve user agency - warnings not blocks (unless strict mode)
-- Plan updates should be atomic to prevent corruption
-- Consider plan versioning for rollback capability
-
-## Error Handling
-
-- Missing plan: Return null, don't error
-- Malformed plan: Warn but continue, treat as no plan
-- Update failures: Log but don't block task completion
-- Parse errors: Fallback to basic text search
-==================== END: .bmad-core/utils/plan-management.md ====================
-
 ==================== START: .bmad-core/utils/workflow-management.md ====================
 # Workflow Management
 
@@ -2504,35 +2270,6 @@ Handle conditional paths by asking clarifying questions when needed.
 Agents should be workflow-aware: know active workflow, their role, access artifacts, understand expected outputs.
 ==================== END: .bmad-core/utils/workflow-management.md ====================
 
-==================== START: .bmad-core/utils/template-format.md ====================
-# Template Format Conventions
-
-Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
-
-## Template Markup Elements
-
-- **{{placeholders}}**: Variables to be replaced with actual content
-- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
-- **REPEAT** sections: Content blocks that may be repeated as needed
-- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
-- **@{examples}**: Example content for guidance (never output to users)
-
-## Processing Rules
-
-- Replace all {{placeholders}} with project-specific content
-- Execute all [[LLM: instructions]] internally without showing users
-- Process conditional and repeat blocks as specified
-- Use examples for guidance but never include them in final output
-- Present only clean, formatted content to users
-
-## Critical Guidelines
-
-- **NEVER display template markup, LLM instructions, or examples to users**
-- Template elements are for AI processing only
-- Focus on faithful template execution and clean output
-- All template-specific instructions are embedded within templates
-==================== END: .bmad-core/utils/template-format.md ====================
-
 ==================== START: .bmad-core/tasks/facilitate-brainstorming-session.md ====================
 ---
 docOutputLocation: docs/brainstorming-session-results.md
@@ -5145,9 +4882,9 @@ sections:
   - id: next-steps
     title: Next Steps
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
-        instruction: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.
+      - id: ux-expert-prompt
+        title: UX Expert Prompt
+        instruction: This section will contain the prompt for the UX Expert, keep it short and to the point to initiate create architecture mode using this document as input.
       - id: architect-prompt
         title: Architect Prompt
         instruction: This section will contain the prompt for the Architect, keep it short and to the point to initiate create architecture mode using this document as input.
@@ -6637,7 +6374,6 @@ sections:
       After completing the architecture:
       
       1. If project has UI components:
-      - Recommend engaging Design Architect agent
       - Use "Frontend Architecture Mode"
       - Provide this document as input
       
@@ -6648,22 +6384,15 @@ sections:
       
       3. Include specific prompts for next agents if needed
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
+      - id: architect-prompt
+        title: Architect Prompt
         condition: Project has UI components
         instruction: |
-          Create a brief prompt to hand off to Design Architect for Frontend Architecture creation. Include:
+          Create a brief prompt to hand off to Architect for Frontend Architecture creation. Include:
           - Reference to this architecture document
           - Key UI requirements from PRD
           - Any frontend-specific decisions made here
           - Request for detailed frontend architecture
-      - id: developer-handoff
-        title: Developer Handoff
-        instruction: |
-          Create a brief prompt for developers starting implementation. Include:
-          - Reference to this architecture and coding standards
-          - First epic/story to implement
-          - Key technical decisions to follow
 ==================== END: .bmad-core/templates/architecture-tmpl.yaml ====================
 
 ==================== START: .bmad-core/templates/front-end-architecture-tmpl.yaml ====================
@@ -8619,7 +8348,7 @@ To comprehensively validate a story draft before implementation begins, ensuring
 
 ### 0. Load Core Configuration and Inputs
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `.bmad-core/core-config.yaml`
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story validation."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`
 - Identify and load the following inputs:
@@ -9669,7 +9398,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: .bmad-core/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

docs/GUIDING-PRINCIPLES.md

@@ -15,7 +15,7 @@ The BMad Method is a natural language framework for AI-assisted software develop
 
 - **Everything is markdown**: Agents, tasks, templates - all written in plain English
 - **No code in core**: The framework itself contains no programming code, only natural language instructions
-- **Self-contained templates**: Templates include their own generation instructions using `[[LLM: ...]]` markup
+- **Self-contained templates**: Templates are defined as YAML files with structured sections that include metadata, workflow configuration, and detailed instructions for content generation
 
 ### 3. Agent and Task Design
 
@@ -60,22 +60,28 @@ See [Expansion Packs Guide](../docs/expansion-packs.md) for detailed examples an
    - This keeps context overhead minimal
 6. **Reuse common tasks** - Don't create new document creation tasks
    - Use the existing `create-doc` task
-   - Pass the appropriate template with embedded LLM instructions
+   - Pass the appropriate YAML template with structured sections
    - This maintains consistency and reduces duplication
 
 ### Template Rules
 
-1. Include generation instructions with `[[LLM: ...]]` markup
-2. Provide clear structure for output
-3. Make templates reusable across agents
-4. Use standardized markup elements:
-   - `{{placeholders}}` for variables to be replaced
-   - `[[LLM: instructions]]` for AI-only processing (never shown to users)
-   - `REPEAT` sections for repeatable content blocks
-   - `^^CONDITION^^` blocks for conditional content
-   - `@{examples}` for guidance examples (never output to users)
-5. NEVER display template markup or LLM instructions to users
-6. Focus on clean output - all processing instructions stay internal
+Templates follow the [BMad Document Template](common/utils/bmad-doc-template.md) specification using YAML format:
+
+1. **Structure**: Templates are defined in YAML with clear metadata, workflow configuration, and section hierarchy
+2. **Separation of Concerns**: Instructions for LLMs are in `instruction` fields, separate from content
+3. **Reusability**: Templates are agent-agnostic and can be used across different agents
+4. **Key Components**:
+   - `template` block for metadata (id, name, version, output settings)
+   - `workflow` block for interaction mode configuration
+   - `sections` array defining document structure with nested subsections
+   - Each section has `id`, `title`, and `instruction` fields
+5. **Advanced Features**:
+   - Variable substitution using `{{variable_name}}` syntax
+   - Conditional sections with `condition` field
+   - Repeatable sections with `repeatable: true`
+   - Agent permissions with `owner` and `editors` fields
+   - Examples arrays for guidance (never included in output)
+6. **Clean Output**: YAML structure ensures all processing logic stays separate from generated content
 
 ## Remember
 

docs/template-markup-references.md

@@ -0,0 +1,86 @@
+# Old Template Markup System References
+
+This document catalogs all references to the old template markup system found in the BMAD-METHOD documentation and codebase.
+
+## Summary of Old Markup Patterns
+
+The old template markup system used the following patterns:
+
+- `[[LLM: ...]]` - LLM-only processing directives
+- `{{placeholders}}` - Variable substitution
+- `<<REPEAT section="name">>` - Repeatable sections
+- `^^CONDITION: condition_name^^` - Conditional blocks
+- `@{examples}` - Example content markers
+
+## Files Containing References
+
+### 1. Primary Documentation Files
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/docs/user-guide.md`
+
+- **Lines 149-155**: Describes template structure with placeholders and LLM instructions
+- **Lines 229-230**: References advanced elicitation with embedded LLM instructions
+- **Lines 527-549**: Shows custom template creation with LLM instructions and placeholders
+- **Lines 590-632**: Detailed template patterns including variables, AI processing, and conditionals
+- **Lines 619-623**: References to `@{example}` patterns and `[[LLM:]]` instructions
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/docs/core-architecture.md`
+
+- **Lines 93-104**: Describes templates as self-contained with embedded LLM instructions
+- **Lines 97-104**: Mentions template-format.md specification with placeholders and LLM directives
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/CLAUDE.md`
+
+- **Lines 37, 262**: References to template instructions using `[[LLM: ...]]` markup
+- **Line 38**: Mentions templates with embedded LLM instructions
+
+### 2. Common Utilities
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/common/utils/bmad-doc-template.md`
+
+- **Lines 296-324**: Migration section describes converting from legacy markdown+frontmatter templates
+- **Lines 319-323**: Specific conversion instructions for old markup patterns
+
+### 3. Task Files
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/bmad-core/tasks/shard-doc.md`
+
+- **Lines 11-30**: Contains LLM instructions embedded in the task
+- **Line 160**: References preserving template markup including `{{placeholders}}` and `[[LLM instructions]]`
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/expansion-packs/bmad-creator-tools/tasks/generate-expansion-pack.md`
+
+- **Lines 10-14**: Describes template systems with LLM instruction embedding
+- **Lines 107-118**: Template section planning with LLM instructions
+- **Lines 229-245**: Detailed LLM instruction patterns for templates
+- **Lines 569-593**: Advanced template design patterns
+- **Lines 229, 573**: Specific examples of `[[LLM:]]` usage
+- **Line 574**: References conditional content with `^^CONDITION:^^`
+- **Line 576**: Mentions iteration controls with `<<REPEAT>>`
+
+### 4. Agent and Template Files
+
+Multiple agent and task files contain actual usage of the old markup system (22 files found with `[[LLM:]]` patterns), including:
+
+- Story templates
+- Checklists
+- Task definitions
+- Workflow plans
+
+## Key Observations
+
+1. **Documentation vs Implementation**: The documentation heavily references the old markup system, while the new YAML-based template system (`bmad-doc-template.md`) is already defined but not yet reflected in the main documentation.
+
+2. **Migration Path**: The `bmad-doc-template.md` file includes a migration section (lines 316-324) that explicitly maps old patterns to new YAML structures.
+
+3. **Active Usage**: Many core tasks and templates still actively use the old markup patterns, particularly `[[LLM:]]` instructions embedded within markdown files.
+
+4. **Inconsistency**: Some files reference a `template-format.md` file that doesn't exist in the expected locations, suggesting incomplete migration or documentation updates.
+
+## Recommendations
+
+1. **Update User Guide**: The user guide needs significant updates to reflect the new YAML-based template system
+2. **Update Core Architecture Docs**: Remove references to embedded LLM instructions in templates
+3. **Create Template Migration Guide**: A comprehensive guide for converting existing templates
+4. **Update Extension Pack Documentation**: The bmad-creator-tools expansion pack documentation needs updates
+5. **Audit Active Templates**: Review and migrate templates that still use the old markup system

expansion-packs/bmad-2d-phaser-game-dev/agents/game-designer.md

@@ -3,9 +3,8 @@
 CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

expansion-packs/bmad-2d-phaser-game-dev/agents/game-developer.md

@@ -3,9 +3,8 @@
 CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

expansion-packs/bmad-2d-phaser-game-dev/agents/game-sm.md

@@ -3,9 +3,8 @@
 CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

expansion-packs/bmad-creator-tools/agents/bmad-the-creator.md

@@ -3,9 +3,8 @@
 CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-creator-tools
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

expansion-packs/bmad-infrastructure-devops/agents/infra-devops-platform.md

@@ -3,9 +3,8 @@
 CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-infrastructure-devops
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

expansion-packs/bmad-infrastructure-devops/data/bmad-kb.md

@@ -1,3 +1,308 @@
-# Usage Information
+# BMad Infrastructure DevOps Expansion Pack Knowledge Base
 
-TODO
+## Overview
+
+The BMad Infrastructure DevOps expansion pack extends the BMad Method framework with comprehensive infrastructure and DevOps capabilities. It enables teams to design, implement, validate, and maintain modern cloud-native infrastructure alongside their application development efforts.
+
+**Version**: 1.7.0  
+**BMad Compatibility**: v4+  
+**Author**: Brian (BMad)
+
+## Core Purpose
+
+This expansion pack addresses the critical need for systematic infrastructure planning and implementation in modern software projects. It provides:
+
+- Structured approach to infrastructure architecture design
+- Platform engineering implementation guidance
+- Comprehensive validation and review processes
+- Integration with core BMad development workflows
+- Support for cloud-native and traditional infrastructure patterns
+
+## When to Use This Expansion Pack
+
+Use the BMad Infrastructure DevOps expansion pack when your project involves:
+
+- **Cloud Infrastructure Design**: AWS, Azure, GCP, or multi-cloud architectures
+- **Kubernetes and Container Orchestration**: Container platform design and implementation
+- **Infrastructure as Code**: Terraform, CloudFormation, Pulumi implementations
+- **GitOps Workflows**: ArgoCD, Flux, or similar continuous deployment patterns
+- **Platform Engineering**: Building internal developer platforms and self-service capabilities
+- **Service Mesh Implementation**: Istio, Linkerd, or similar service mesh architectures
+- **DevOps Transformation**: Establishing or improving DevOps practices and culture
+
+## Key Components
+
+### 1. DevOps Agent: Alex
+
+**Role**: DevOps Infrastructure Specialist  
+**Experience**: 15+ years in infrastructure and platform engineering
+
+**Core Principles**:
+
+- Infrastructure as Code (IaC) First
+- Automation and Repeatability
+- Reliability and Scalability
+- Security by Design
+- Cost Optimization
+- Developer Experience Focus
+
+**Commands**:
+
+- `*help` - Display available commands and capabilities
+- `*chat-mode` - Interactive conversation mode for infrastructure discussions
+- `*create-doc` - Generate infrastructure documentation from templates
+- `*review-infrastructure` - Conduct systematic infrastructure review
+- `*validate-infrastructure` - Validate infrastructure against comprehensive checklist
+- `*checklist` - Access the 16-section infrastructure validation checklist
+- `*exit` - Return to normal context
+
+### 2. Infrastructure Templates
+
+#### Infrastructure Architecture Template
+
+**Purpose**: Design comprehensive infrastructure architecture  
+**Key Sections**:
+
+- Infrastructure Overview (providers, regions, environments)
+- Infrastructure as Code approach and tooling
+- Network Architecture with visual diagrams
+- Compute Resources planning
+- Security Architecture design
+- Monitoring and Observability strategy
+- CI/CD Pipeline architecture
+- Disaster Recovery planning
+- BMad Integration points
+
+#### Platform Implementation Template
+
+**Purpose**: Implement platform infrastructure based on approved architecture  
+**Key Sections**:
+
+- Foundation Infrastructure Layer
+- Container Platform (Kubernetes) setup
+- GitOps Workflow implementation
+- Service Mesh configuration
+- Developer Experience Platform
+- Security hardening procedures
+- Platform validation and testing
+
+### 3. Tasks
+
+#### Review Infrastructure Task
+
+**Purpose**: Systematic infrastructure review process  
+**Features**:
+
+- Incremental or rapid assessment modes
+- Architectural escalation for complex issues
+- Advanced elicitation for deep analysis
+- Prioritized findings and recommendations
+- Integration with BMad Architecture phase
+
+#### Validate Infrastructure Task
+
+**Purpose**: Comprehensive infrastructure validation  
+**Features**:
+
+- 16-section validation checklist
+- Architecture Design Review Gate
+- Compliance percentage tracking
+- Remediation planning
+- BMad integration assessment
+
+### 4. Infrastructure Validation Checklist
+
+A comprehensive 16-section checklist covering:
+
+**Foundation Infrastructure (Sections 1-12)**:
+
+1. Security Foundation - IAM, encryption, compliance
+2. Infrastructure as Code - Version control, testing, documentation
+3. Resilience & High Availability - Multi-AZ, failover, SLAs
+4. Backup & Disaster Recovery - Strategies, testing, RTO/RPO
+5. Monitoring & Observability - Metrics, logging, alerting
+6. Performance & Scalability - Auto-scaling, load testing
+7. Infrastructure Operations - Patching, maintenance, runbooks
+8. CI/CD Infrastructure - Pipelines, environments, deployments
+9. Networking & Connectivity - Architecture, security, DNS
+10. Compliance & Governance - Standards, auditing, policies
+11. BMad Integration - Agent support, workflow alignment
+12. Architecture Documentation - Diagrams, decisions, maintenance
+
+**Platform Engineering (Sections 13-16)**: 13. Container Platform - Kubernetes setup, RBAC, networking 14. GitOps Workflows - Repository structure, deployment patterns 15. Service Mesh - Traffic management, security, observability 16. Developer Experience - Self-service, documentation, tooling
+
+## Integration with BMad Flow
+
+### Workflow Integration Points
+
+1. **After Architecture Phase**: Infrastructure design begins after application architecture is defined
+2. **Parallel to Development**: Infrastructure implementation runs alongside application development
+3. **Before Production**: Infrastructure validation gates before production deployment
+4. **Continuous Operation**: Ongoing infrastructure reviews and improvements
+
+### Agent Collaboration
+
+- **With Architect (Sage)**: Joint planning sessions, design reviews, architectural alignment
+- **With Developer (Blake)**: Platform capabilities, development environment setup
+- **With Product Manager (Finley)**: Infrastructure requirements, cost considerations
+- **With Creator Agents**: Infrastructure for creative workflows and asset management
+
+## Best Practices
+
+### Infrastructure Design
+
+1. **Start with Requirements**: Understand application needs before designing infrastructure
+2. **Design for Scale**: Plan for 10x growth from day one
+3. **Security First**: Implement defense in depth at every layer
+4. **Cost Awareness**: Balance performance with budget constraints
+5. **Document Everything**: Maintain comprehensive documentation
+
+### Implementation Approach
+
+1. **Incremental Rollout**: Deploy infrastructure in stages with validation gates
+2. **Automation Focus**: Automate repetitive tasks and deployments
+3. **Testing Strategy**: Include infrastructure testing in CI/CD pipelines
+4. **Monitoring Setup**: Implement observability before production
+5. **Team Training**: Ensure team understanding of infrastructure
+
+### Validation Process
+
+1. **Regular Reviews**: Schedule periodic infrastructure assessments
+2. **Checklist Compliance**: Maintain high compliance with validation checklist
+3. **Performance Baselines**: Establish and monitor performance metrics
+4. **Security Audits**: Regular security assessments and penetration testing
+5. **Cost Optimization**: Monthly cost reviews and optimization
+
+## Common Use Cases
+
+### 1. New Project Infrastructure
+
+**Scenario**: Starting a new cloud-native application  
+**Process**:
+
+1. Use Infrastructure Architecture template for design
+2. Review with Architect agent
+3. Implement using Platform Implementation template
+4. Validate with comprehensive checklist
+5. Deploy incrementally with monitoring
+
+### 2. Infrastructure Modernization
+
+**Scenario**: Migrating legacy infrastructure to cloud  
+**Process**:
+
+1. Review existing infrastructure
+2. Design target architecture
+3. Plan migration phases
+4. Implement with validation gates
+5. Monitor and optimize
+
+### 3. Platform Engineering Initiative
+
+**Scenario**: Building internal developer platform  
+**Process**:
+
+1. Assess developer needs
+2. Design platform architecture
+3. Implement Kubernetes/GitOps foundation
+4. Build self-service capabilities
+5. Enable developer adoption
+
+### 4. Multi-Cloud Strategy
+
+**Scenario**: Implementing multi-cloud architecture  
+**Process**:
+
+1. Define cloud strategy and requirements
+2. Design cloud-agnostic architecture
+3. Implement with IaC abstraction
+4. Validate cross-cloud functionality
+5. Establish unified monitoring
+
+## Advanced Features
+
+### GitOps Workflows
+
+- **Repository Structure**: Organized by environment and application
+- **Deployment Patterns**: Progressive delivery, canary deployments
+- **Secret Management**: External secrets operator integration
+- **Policy Enforcement**: OPA/Gatekeeper for compliance
+
+### Service Mesh Capabilities
+
+- **Traffic Management**: Load balancing, circuit breaking, retries
+- **Security**: mTLS, authorization policies
+- **Observability**: Distributed tracing, service maps
+- **Multi-Cluster**: Cross-cluster communication
+
+### Developer Self-Service
+
+- **Portal Features**: Resource provisioning, environment management
+- **API Gateway**: Centralized API management
+- **Documentation**: Automated API docs, runbooks
+- **Tooling**: CLI tools, IDE integrations
+
+## Troubleshooting Guide
+
+### Common Issues
+
+1. **Infrastructure Drift**
+
+   - Solution: Implement drift detection in IaC pipelines
+   - Prevention: Restrict manual changes, enforce GitOps
+
+2. **Cost Overruns**
+
+   - Solution: Implement cost monitoring and alerts
+   - Prevention: Resource tagging, budget limits
+
+3. **Performance Problems**
+
+   - Solution: Review monitoring data, scale resources
+   - Prevention: Load testing, capacity planning
+
+4. **Security Vulnerabilities**
+   - Solution: Immediate patching, security reviews
+   - Prevention: Automated scanning, compliance checks
+
+## Metrics and KPIs
+
+### Infrastructure Metrics
+
+- **Availability**: Target 99.9%+ uptime
+- **Performance**: Response time < 100ms
+- **Cost Efficiency**: Cost per transaction trending down
+- **Security**: Zero critical vulnerabilities
+- **Automation**: 90%+ automated deployments
+
+### Platform Metrics
+
+- **Developer Satisfaction**: NPS > 50
+- **Self-Service Adoption**: 80%+ platform usage
+- **Deployment Frequency**: Multiple per day
+- **Lead Time**: < 1 hour from commit to production
+- **MTTR**: < 30 minutes for incidents
+
+## Future Enhancements
+
+### Planned Features
+
+1. **AI-Driven Optimization**: Automated infrastructure tuning
+2. **Enhanced Security**: Zero-trust architecture templates
+3. **Edge Computing**: Support for edge infrastructure patterns
+4. **Sustainability**: Carbon footprint optimization
+5. **Advanced Compliance**: Industry-specific compliance templates
+
+### Integration Roadmap
+
+1. **Cloud Provider APIs**: Direct integration with AWS, Azure, GCP
+2. **IaC Tools**: Native support for Terraform, Pulumi
+3. **Monitoring Platforms**: Integration with Datadog, New Relic
+4. **Security Tools**: SIEM and vulnerability scanner integration
+5. **Cost Management**: FinOps platform integration
+
+## Conclusion
+
+The BMad Infrastructure DevOps expansion pack provides a comprehensive framework for modern infrastructure and platform engineering. By following its structured approach and leveraging the provided tools and templates, teams can build reliable, scalable, and secure infrastructure that accelerates application delivery while maintaining operational excellence.
+
+For support and updates, refer to the main BMad Method documentation or contact the BMad community.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "4.27.2",
+  "version": "4.27.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "4.27.2",
+      "version": "4.27.6",
       "license": "MIT",
       "dependencies": {
         "@kayvan/markdown-tree-parser": "^1.5.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.27.2",
+  "version": "4.27.6",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "main": "tools/cli.js",
   "bin": {

tools/installer/bin/bmad.js

@@ -224,6 +224,58 @@ async function promptInstallation() {
   answers.installType = selectedItems.includes('bmad-core') ? 'full' : 'expansion-only';
   answers.expansionPacks = selectedItems.filter(item => item !== 'bmad-core');
 
+  // Ask sharding questions if installing BMad core
+  if (selectedItems.includes('bmad-core')) {
+    console.log(chalk.cyan('\n📋 Document Organization Settings'));
+    console.log(chalk.dim('Configure how your project documentation should be organized.\n'));
+    
+    // Ask about PRD sharding
+    const { prdSharded } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'prdSharded',
+        message: 'Will the PRD (Product Requirements Document) be sharded into multiple files?',
+        default: true
+      }
+    ]);
+    answers.prdSharded = prdSharded;
+    
+    // Ask about architecture sharding
+    const { architectureSharded } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'architectureSharded',
+        message: 'Will the architecture documentation be sharded into multiple files?',
+        default: true
+      }
+    ]);
+    answers.architectureSharded = architectureSharded;
+    
+    // Show warning if architecture sharding is disabled
+    if (!architectureSharded) {
+      console.log(chalk.yellow.bold('\n⚠️  IMPORTANT: Architecture Sharding Disabled'));
+      console.log(chalk.yellow('With architecture sharding disabled, you should still create the files listed'));
+      console.log(chalk.yellow('in devLoadAlwaysFiles (like coding-standards.md, tech-stack.md, source-tree.md)'));
+      console.log(chalk.yellow('as these are used by the dev agent at runtime.'));
+      console.log(chalk.yellow('\nAlternatively, you can remove these files from the devLoadAlwaysFiles list'));
+      console.log(chalk.yellow('in your core-config.yaml after installation.'));
+      
+      const { acknowledge } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'acknowledge',
+          message: 'Do you acknowledge this requirement and want to proceed?',
+          default: false
+        }
+      ]);
+      
+      if (!acknowledge) {
+        console.log(chalk.red('Installation cancelled.'));
+        process.exit(0);
+      }
+    }
+  }
+
   // Ask for IDE configuration
   const { ides } = await inquirer.prompt([
     {
@@ -246,6 +298,37 @@ async function promptInstallation() {
   // Use selected IDEs directly
   answers.ides = ides;
 
+  // Configure GitHub Copilot immediately if selected
+  if (ides.includes('github-copilot')) {
+    console.log(chalk.cyan('\n🔧 GitHub Copilot Configuration'));
+    console.log(chalk.dim('BMad works best with specific VS Code settings for optimal agent experience.\n'));
+    
+    const { configChoice } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'configChoice',
+        message: chalk.yellow('How would you like to configure GitHub Copilot settings?'),
+        choices: [
+          {
+            name: 'Use recommended defaults (fastest setup)',
+            value: 'defaults'
+          },
+          {
+            name: 'Configure each setting manually (customize to your preferences)',
+            value: 'manual'
+          },
+          {
+            name: 'Skip settings configuration (I\'ll configure manually later)',
+            value: 'skip'
+          }
+        ],
+        default: 'defaults'
+      }
+    ]);
+    
+    answers.githubCopilotConfig = { configChoice };
+  }
+
   // Ask for web bundles installation
   const { includeWebBundles } = await inquirer.prompt([
     {

tools/installer/lib/file-manager.js

@@ -47,7 +47,7 @@ class FileManager {
     }
   }
 
-  async copyGlobPattern(pattern, sourceDir, destDir) {
+  async copyGlobPattern(pattern, sourceDir, destDir, rootValue = null) {
     const files = glob.sync(pattern, { cwd: sourceDir });
     const copied = [];
 
@@ -55,7 +55,17 @@ class FileManager {
       const sourcePath = path.join(sourceDir, file);
       const destPath = path.join(destDir, file);
 
-      if (await this.copyFile(sourcePath, destPath)) {
+      // Use root replacement if rootValue is provided and file needs it
+      const needsRootReplacement = rootValue && (file.endsWith('.md') || file.endsWith('.yaml') || file.endsWith('.yml'));
+      
+      let success = false;
+      if (needsRootReplacement) {
+        success = await this.copyFileWithRootReplacement(sourcePath, destPath, rootValue);
+      } else {
+        success = await this.copyFile(sourcePath, destPath);
+      }
+
+      if (success) {
         copied.push(file);
       }
     }
@@ -271,6 +281,99 @@ class FileManager {
 
     return manifest;
   }
+
+  async modifyCoreConfig(installDir, config) {
+    const coreConfigPath = path.join(installDir, '.bmad-core', 'core-config.yaml');
+    
+    try {
+      // Read the existing core-config.yaml
+      const coreConfigContent = await fs.readFile(coreConfigPath, 'utf8');
+      const coreConfig = yaml.load(coreConfigContent);
+      
+      // Modify sharding settings if provided
+      if (config.prdSharded !== undefined) {
+        coreConfig.prd.prdSharded = config.prdSharded;
+      }
+      
+      if (config.architectureSharded !== undefined) {
+        coreConfig.architecture.architectureSharded = config.architectureSharded;
+      }
+      
+      // Write back the modified config
+      await fs.writeFile(coreConfigPath, yaml.dump(coreConfig, { indent: 2 }));
+      
+      return true;
+    } catch (error) {
+      await initializeModules();
+      console.error(chalk.red(`Failed to modify core-config.yaml:`), error.message);
+      return false;
+    }
+  }
+
+  async copyFileWithRootReplacement(source, destination, rootValue) {
+    try {
+      // Read the source file content
+      const fs = require('fs').promises;
+      const content = await fs.readFile(source, 'utf8');
+      
+      // Replace {root} with the specified root value
+      const updatedContent = content.replace(/\{root\}/g, rootValue);
+      
+      // Ensure directory exists
+      await this.ensureDirectory(path.dirname(destination));
+      
+      // Write the updated content
+      await fs.writeFile(destination, updatedContent, 'utf8');
+      
+      return true;
+    } catch (error) {
+      await initializeModules();
+      console.error(chalk.red(`Failed to copy ${source} with root replacement:`), error.message);
+      return false;
+    }
+  }
+
+  async copyDirectoryWithRootReplacement(source, destination, rootValue, fileExtensions = ['.md', '.yaml', '.yml']) {
+    try {
+      await initializeModules(); // Ensure chalk is initialized
+      await this.ensureDirectory(destination);
+      
+      // Get all files in source directory
+      const files = glob.sync('**/*', { 
+        cwd: source, 
+        nodir: true 
+      });
+      
+      let replacedCount = 0;
+      
+      for (const file of files) {
+        const sourcePath = path.join(source, file);
+        const destPath = path.join(destination, file);
+        
+        // Check if this file type should have {root} replacement
+        const shouldReplace = fileExtensions.some(ext => file.endsWith(ext));
+        
+        if (shouldReplace) {
+          if (await this.copyFileWithRootReplacement(sourcePath, destPath, rootValue)) {
+            replacedCount++;
+          }
+        } else {
+          // Regular copy for files that don't need replacement
+          await this.copyFile(sourcePath, destPath);
+        }
+      }
+      
+      if (replacedCount > 0) {
+        console.log(chalk.dim(`  Processed ${replacedCount} files with {root} replacement`));
+      }
+      
+      return true;
+    } catch (error) {
+      await initializeModules();
+      console.error(chalk.red(`Failed to copy directory ${source} with root replacement:`), error.message);
+      return false;
+    }
+  }
 }
 
 module.exports = new FileManager();

tools/installer/lib/ide-setup.js

@@ -41,7 +41,7 @@ class IdeSetup {
     }
   }
 
-  async setup(ide, installDir, selectedAgent = null, spinner = null) {
+  async setup(ide, installDir, selectedAgent = null, spinner = null, preConfiguredSettings = null) {
     await initializeModules();
     const ideConfig = await configLoader.getIdeConfiguration(ide);
 
@@ -66,7 +66,7 @@ class IdeSetup {
       case "gemini":
         return this.setupGeminiCli(installDir, selectedAgent);
       case "github-copilot":
-        return this.setupGitHubCopilot(installDir, selectedAgent, spinner);
+        return this.setupGitHubCopilot(installDir, selectedAgent, spinner, preConfiguredSettings);
       default:
         console.log(chalk.yellow(`\nIDE ${ide} not yet supported`));
         return false;
@@ -566,11 +566,11 @@ class IdeSetup {
     return true;
   }
 
-  async setupGitHubCopilot(installDir, selectedAgent, spinner = null) {
+  async setupGitHubCopilot(installDir, selectedAgent, spinner = null, preConfiguredSettings = null) {
     await initializeModules();
     
     // Configure VS Code workspace settings first to avoid UI conflicts with loading spinners
-    await this.configureVsCodeSettings(installDir, spinner);
+    await this.configureVsCodeSettings(installDir, spinner, preConfiguredSettings);
     
     const chatmodesDir = path.join(installDir, ".github", "chatmodes");
     const agents = selectedAgent ? [selectedAgent] : await this.getAllAgentIds(installDir);
@@ -616,7 +616,7 @@ tools: ['changes', 'codebase', 'fetch', 'findTestFiles', 'githubRepo', 'problems
     return true;
   }
 
-  async configureVsCodeSettings(installDir, spinner) {
+  async configureVsCodeSettings(installDir, spinner, preConfiguredSettings = null) {
     await initializeModules(); // Ensure inquirer is loaded
     const vscodeDir = path.join(installDir, ".vscode");
     const settingsPath = path.join(vscodeDir, "settings.json");
@@ -636,34 +636,42 @@ tools: ['changes', 'codebase', 'fetch', 'findTestFiles', 'githubRepo', 'problems
       }
     }
     
-    // Clear any previous output and add spacing to avoid conflicts with loaders
-    console.log('\n'.repeat(2));
-    console.log(chalk.blue("🔧 Github Copilot Agent Settings Configuration"));
-    console.log(chalk.dim("BMad works best with specific VS Code settings for optimal agent experience."));
-    console.log(''); // Add extra spacing
-    
-    const { configChoice } = await inquirer.prompt([
-      {
-        type: 'list',
-        name: 'configChoice',
-        message: 'How would you like to configure Github Copilot settings?',
-        choices: [
-          {
-            name: 'Use recommended defaults (fastest setup)',
-            value: 'defaults'
-          },
-          {
-            name: 'Configure each setting manually (customize to your preferences)',
-            value: 'manual'
-          },
-          {
-            name: 'Skip settings configuration (I\'ll configure manually later)\n',
-            value: 'skip'
-          }
-        ],
-        default: 'defaults'
-      }
-    ]);
+    // Use pre-configured settings if provided, otherwise prompt
+    let configChoice;
+    if (preConfiguredSettings && preConfiguredSettings.configChoice) {
+      configChoice = preConfiguredSettings.configChoice;
+      console.log(chalk.dim(`Using pre-configured GitHub Copilot settings: ${configChoice}`));
+    } else {
+      // Clear any previous output and add spacing to avoid conflicts with loaders
+      console.log('\n'.repeat(2));
+      console.log(chalk.blue("🔧 Github Copilot Agent Settings Configuration"));
+      console.log(chalk.dim("BMad works best with specific VS Code settings for optimal agent experience."));
+      console.log(''); // Add extra spacing
+      
+      const response = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'configChoice',
+          message: chalk.yellow('How would you like to configure GitHub Copilot settings?'),
+          choices: [
+            {
+              name: 'Use recommended defaults (fastest setup)',
+              value: 'defaults'
+            },
+            {
+              name: 'Configure each setting manually (customize to your preferences)',
+              value: 'manual'
+            },
+            {
+              name: 'Skip settings configuration (I\'ll configure manually later)',
+              value: 'skip'
+            }
+          ],
+          default: 'defaults'
+        }
+      ]);
+      configChoice = response.configChoice;
+    }
     
     let bmadSettings = {};
     

tools/installer/lib/installer.js

@@ -244,7 +244,7 @@ class Installer {
       spinner.text = "Copying complete .bmad-core folder...";
       const sourceDir = configLoader.getBmadCorePath();
       const bmadCoreDestDir = path.join(installDir, ".bmad-core");
-      await fileManager.copyDirectory(sourceDir, bmadCoreDestDir);
+      await fileManager.copyDirectoryWithRootReplacement(sourceDir, bmadCoreDestDir, ".bmad-core");
       
       // Copy common/ items to .bmad-core
       spinner.text = "Copying common utilities...";
@@ -263,7 +263,7 @@ class Installer {
       // Single agent installation
       spinner.text = `Installing ${config.agent} agent...`;
 
-      // Copy agent file
+      // Copy agent file with {root} replacement
       const agentPath = configLoader.getAgentPath(config.agent);
       const destAgentPath = path.join(
         installDir,
@@ -271,7 +271,7 @@ class Installer {
         "agents",
         `${config.agent}.md`
       );
-      await fileManager.copyFile(agentPath, destAgentPath);
+      await fileManager.copyFileWithRootReplacement(agentPath, destAgentPath, ".bmad-core");
       files.push(`.bmad-core/agents/${config.agent}.md`);
 
       // Copy dependencies
@@ -284,15 +284,16 @@ class Installer {
         spinner.text = `Copying dependency: ${dep}`;
 
         if (dep.includes("*")) {
-          // Handle glob patterns
+          // Handle glob patterns with {root} replacement
           const copiedFiles = await fileManager.copyGlobPattern(
             dep.replace(".bmad-core/", ""),
             sourceBase,
-            path.join(installDir, ".bmad-core")
+            path.join(installDir, ".bmad-core"),
+            ".bmad-core"
           );
           files.push(...copiedFiles.map(f => `.bmad-core/${f}`));
         } else {
-          // Handle single files
+          // Handle single files with {root} replacement if needed
           const sourcePath = path.join(
             sourceBase,
             dep.replace(".bmad-core/", "")
@@ -302,7 +303,16 @@ class Installer {
             dep
           );
 
-          if (await fileManager.copyFile(sourcePath, destPath)) {
+          const needsRootReplacement = dep.endsWith('.md') || dep.endsWith('.yaml') || dep.endsWith('.yml');
+          let success = false;
+          
+          if (needsRootReplacement) {
+            success = await fileManager.copyFileWithRootReplacement(sourcePath, destPath, ".bmad-core");
+          } else {
+            success = await fileManager.copyFile(sourcePath, destPath);
+          }
+
+          if (success) {
             files.push(dep);
           }
         }
@@ -325,19 +335,29 @@ class Installer {
         spinner.text = `Copying team dependency: ${dep}`;
         
         if (dep.includes("*")) {
-          // Handle glob patterns
+          // Handle glob patterns with {root} replacement
           const copiedFiles = await fileManager.copyGlobPattern(
             dep.replace(".bmad-core/", ""),
             sourceBase,
-            path.join(installDir, ".bmad-core")
+            path.join(installDir, ".bmad-core"),
+            ".bmad-core"
           );
           files.push(...copiedFiles.map(f => `.bmad-core/${f}`));
         } else {
-          // Handle single files
+          // Handle single files with {root} replacement if needed
           const sourcePath = path.join(sourceBase, dep.replace(".bmad-core/", ""));
           const destPath = path.join(installDir, dep);
           
-          if (await fileManager.copyFile(sourcePath, destPath)) {
+          const needsRootReplacement = dep.endsWith('.md') || dep.endsWith('.yaml') || dep.endsWith('.yml');
+          let success = false;
+          
+          if (needsRootReplacement) {
+            success = await fileManager.copyFileWithRootReplacement(sourcePath, destPath, ".bmad-core");
+          } else {
+            success = await fileManager.copyFile(sourcePath, destPath);
+          }
+
+          if (success) {
             files.push(dep);
           }
         }
@@ -373,10 +393,17 @@ class Installer {
     if (ides.length > 0) {
       for (const ide of ides) {
         spinner.text = `Setting up ${ide} integration...`;
-        await ideSetup.setup(ide, installDir, config.agent, spinner);
+        const preConfiguredSettings = ide === 'github-copilot' ? config.githubCopilotConfig : null;
+        await ideSetup.setup(ide, installDir, config.agent, spinner, preConfiguredSettings);
       }
     }
 
+    // Modify core-config.yaml if sharding preferences were provided
+    if (config.installType !== "expansion-only" && (config.prdSharded !== undefined || config.architectureSharded !== undefined)) {
+      spinner.text = "Configuring document sharding settings...";
+      await fileManager.modifyCoreConfig(installDir, config);
+    }
+
     // Create manifest (skip for expansion-only installations)
     if (config.installType !== "expansion-only") {
       spinner.text = "Creating installation manifest...";
@@ -1165,32 +1192,41 @@ class Installer {
               nodir: true
             });
 
-            // Copy each file to the expansion pack's dot folder
+            // Copy each file to the expansion pack's dot folder with {root} replacement
             for (const file of files) {
               const sourcePath = path.join(sourceFolder, file);
               const destPath = path.join(expansionDotFolder, folder, file);
               
-              if (await fileManager.copyFile(sourcePath, destPath)) {
+              const needsRootReplacement = file.endsWith('.md') || file.endsWith('.yaml') || file.endsWith('.yml');
+              let success = false;
+              
+              if (needsRootReplacement) {
+                success = await fileManager.copyFileWithRootReplacement(sourcePath, destPath, `.${packId}`);
+              } else {
+                success = await fileManager.copyFile(sourcePath, destPath);
+              }
+              
+              if (success) {
                 installedFiles.push(path.join(`.${packId}`, folder, file));
               }
             }
           }
         }
 
-        // Copy config.yaml
+        // Copy config.yaml with {root} replacement
         const configPath = path.join(expansionPackDir, 'config.yaml');
         if (await fileManager.pathExists(configPath)) {
           const configDestPath = path.join(expansionDotFolder, 'config.yaml');
-          if (await fileManager.copyFile(configPath, configDestPath)) {
+          if (await fileManager.copyFileWithRootReplacement(configPath, configDestPath, `.${packId}`)) {
             installedFiles.push(path.join(`.${packId}`, 'config.yaml'));
           }
         }
         
-        // Copy README if it exists
+        // Copy README if it exists with {root} replacement
         const readmePath = path.join(expansionPackDir, 'README.md');
         if (await fileManager.pathExists(readmePath)) {
           const readmeDestPath = path.join(expansionDotFolder, 'README.md');
-          if (await fileManager.copyFile(readmePath, readmeDestPath)) {
+          if (await fileManager.copyFileWithRootReplacement(readmePath, readmeDestPath, `.${packId}`)) {
             installedFiles.push(path.join(`.${packId}`, 'README.md'));
           }
         }
@@ -1251,7 +1287,7 @@ class Installer {
       const yamlContent = extractYamlFromAgent(agentContent);
       if (yamlContent) {
         try {
-          const agentConfig = yaml.parse(yamlContent);
+          const agentConfig = yaml.load(yamlContent);
           const dependencies = agentConfig.dependencies || {};
           
           // Check for core dependencies (those that don't exist in the expansion pack)
@@ -1270,9 +1306,9 @@ class Installer {
                 if (await fileManager.pathExists(coreDepPath)) {
                   spinner.text = `Copying core dependency ${dep} for ${packId}...`;
                   
-                  // Copy from core to expansion pack dot folder
+                  // Copy from core to expansion pack dot folder with {root} replacement
                   const destPath = path.join(expansionDotFolder, depType, depFileName);
-                  await fileManager.copyFile(coreDepPath, destPath);
+                  await fileManager.copyFileWithRootReplacement(coreDepPath, destPath, `.${packId}`);
                   
                   console.log(chalk.dim(`  Added core dependency: ${depType}/${depFileName}`));
                 } else {
@@ -1314,7 +1350,7 @@ class Installer {
       const teamContent = await fs.readFile(teamPath, 'utf8');
       
       try {
-        const teamConfig = yaml.parse(teamContent);
+        const teamConfig = yaml.load(teamContent);
         const agents = teamConfig.agents || [];
         
         // Add bmad-orchestrator if not present (required for all teams)
@@ -1331,9 +1367,9 @@ class Installer {
             if (await fileManager.pathExists(coreAgentPath)) {
               spinner.text = `Copying core agent ${agentId} for ${packId}...`;
               
-              // Copy agent file
+              // Copy agent file with {root} replacement
               const destPath = path.join(expansionDotFolder, 'agents', `${agentId}.md`);
-              await fileManager.copyFile(coreAgentPath, destPath);
+              await fileManager.copyFileWithRootReplacement(coreAgentPath, destPath, `.${packId}`);
               existingAgents.add(agentId);
               
               console.log(chalk.dim(`  Added core agent: ${agentId}`));
@@ -1345,7 +1381,7 @@ class Installer {
               if (yamlContent) {
                 try {
                   
-                  const agentConfig = yaml.parse(yamlContent);
+                  const agentConfig = yaml.load(yamlContent);
                   const dependencies = agentConfig.dependencies || {};
                   
                   // Copy all dependencies for this agent
@@ -1363,7 +1399,7 @@ class Installer {
                         
                         if (await fileManager.pathExists(coreDepPath)) {
                           const destDepPath = path.join(expansionDotFolder, depType, depFileName);
-                          await fileManager.copyFile(coreDepPath, destDepPath);
+                          await fileManager.copyFileWithRootReplacement(coreDepPath, destDepPath, `.${packId}`);
                           console.log(chalk.dim(`    Added agent dependency: ${depType}/${depFileName}`));
                         } else {
                           // Try common folder

tools/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.27.2",
+  "version": "4.27.6",
   "description": "BMad Method installer - AI-powered Agile development framework",
   "main": "lib/installer.js",
   "bin": {

zoo/docs/architecture.md

@@ -1,812 +0,0 @@
-# TermTodo Architecture Document
-
-## Introduction
-
-This document outlines the overall project architecture for TermTodo, including backend systems, shared services, and non-UI specific concerns. Its primary goal is to serve as the guiding architectural blueprint for AI-driven development, ensuring consistency and adherence to chosen patterns and technologies.
-
-**Relationship to Frontend Architecture:**
-If the project includes a significant user interface, a separate Frontend Architecture Document will detail the frontend-specific design and MUST be used in conjunction with this document. Core technology stack choices documented herein (see "Tech Stack") are definitive for the entire project, including any frontend components.
-
-### Starter Template or Existing Project
-
-N/A - This is a greenfield Rust CLI project with no starter template.
-
-### Change Log
-
-| Date       | Version | Description                                | Author              |
-| ---------- | ------- | ------------------------------------------ | ------------------- |
-| 2025-07-07 | 1.0     | Initial architecture based on TermTodo PRD | Winston (Architect) |
-
-## High Level Architecture
-
-### Technical Summary
-
-TermTodo is a monolithic, single-binary CLI application built with Rust, utilizing embedded SQLite for ACID-compliant local storage. The architecture employs clean architecture principles with clear separation between CLI parsing, business logic, and data persistence layers. Performance-critical design choices including synchronous execution, prepared statement caching, and minimal dependencies ensure sub-100ms command execution. The system implements repository and command patterns to maintain testability while delivering a zero-configuration tool that integrates seamlessly into developer workflows.
-
-### High Level Overview
-
-**Architectural Style:** Monolithic Single Binary
-
-- All functionality compiled into one executable for instant startup
-- No network dependencies or service discovery overhead
-- Embedded SQLite database with local file storage
-
-**Repository Structure:** Monorepo
-
-- Single repository containing all code, tests, and documentation
-- Simplified dependency management and atomic commits
-- Unified CI/CD pipeline for all components
-
-**Service Architecture:** Monolith
-
-- Single process handling all operations
-- Synchronous execution model (no async runtime needed)
-- Direct database access without network layers
-
-**Primary Data Flow:**
-
-1. User invokes `todo` command with arguments
-2. CLI parser validates and routes to appropriate command handler
-3. Command handler orchestrates business logic operations
-4. Repository layer manages SQLite transactions
-5. Formatted output returned to terminal
-
-**Key Architectural Decisions:**
-
-- **Synchronous Model**: Eliminates async runtime overhead for faster cold starts
-- **Embedded Database**: Zero configuration, portable data storage
-- **Static Linking**: Single binary distribution with no runtime dependencies
-- **Clean Architecture**: Testable layers despite monolithic structure
-
-### High Level Project Diagram
-
-```mermaid
-graph TB
-    User[Terminal User]
-
-    subgraph "TermTodo Binary"
-        CLI[CLI Parser<br/>clap v4]
-        CMD[Command Handlers]
-        BL[Business Logic]
-        REPO[Repository Layer]
-        DB[(SQLite DB)]
-        CONFIG[Config Manager<br/>TOML]
-    end
-
-    subgraph "File System"
-        DBFILE[todo.db]
-        CFGFILE[config.toml]
-    end
-
-    User -->|todo add/list/etc| CLI
-    CLI -->|Parsed Commands| CMD
-    CMD -->|Operations| BL
-    BL -->|Data Access| REPO
-    REPO -->|SQL| DB
-    DB -.->|File I/O| DBFILE
-    CONFIG -.->|Read/Write| CFGFILE
-
-    style User fill:#e1f5fe
-    style CLI fill:#fff3e0
-    style CMD fill:#fff3e0
-    style BL fill:#f3e5f5
-    style REPO fill:#e8f5e9
-    style DB fill:#e8f5e9
-```
-
-### Architectural and Design Patterns
-
-- **Clean Architecture:** Separation of concerns with CLI, Application, Domain, and Infrastructure layers - _Rationale:_ Enables 80%+ test coverage requirement by isolating business logic from I/O operations
-
-- **Repository Pattern:** Abstract SQLite operations behind trait-based interfaces - _Rationale:_ Allows in-memory repositories for unit tests and potential future database migrations
-
-- **Command Pattern:** Each CLI subcommand as a discrete handler with execute method - _Rationale:_ Simplifies testing and follows clap's natural structure for maintainable command routing
-
-- **Builder Pattern:** Fluent interfaces for constructing complex queries and task filters - _Rationale:_ Provides readable API for combining multiple filter criteria while maintaining performance
-
-- **Result/Option Monads:** Explicit error handling using Rust's type system - _Rationale:_ Prevents runtime panics and enables graceful error messages as required by NFR13
-
-## Tech Stack
-
-This is the DEFINITIVE technology selection for TermTodo. All implementation must use these exact versions and technologies.
-
-### Cloud Infrastructure
-
-- **Provider:** Local-only (No cloud requirements)
-- **Key Services:** N/A
-- **Deployment Regions:** N/A
-
-### Technology Stack Table
-
-| Category               | Technology     | Version | Purpose                       | Rationale                                                                 |
-| ---------------------- | -------------- | ------- | ----------------------------- | ------------------------------------------------------------------------- |
-| **Language**           | Rust           | 1.78.0  | Primary development language  | Zero-cost abstractions, memory safety, single binary output               |
-| **Database**           | SQLite         | 3.45.0  | Embedded database             | ACID compliance, zero configuration, excellent performance                |
-| **CLI Framework**      | clap           | 4.5.4   | Command-line argument parsing | Automatic help generation, shell completion, strong typing                |
-| **ORM/Query Builder**  | sqlx           | 0.7.4   | Database operations           | Compile-time checked queries, async support (if needed later), migrations |
-| **Date Parsing**       | chrono         | 0.4.38  | Date/time handling            | Comprehensive timezone support, widely adopted                            |
-| **Human Date Parsing** | chrono-english | 0.1.7   | Natural language dates        | Parses "tomorrow", "next friday" as required                              |
-| **Serialization**      | serde          | 1.0.197 | JSON/CSV export               | De facto standard, excellent performance                                  |
-| **Configuration**      | toml           | 0.8.12  | Config file parsing           | Human-readable, simple for users                                          |
-| **Terminal Colors**    | termcolor      | 1.4.1   | Colored output                | Respects NO_COLOR, cross-platform                                         |
-| **Error Handling**     | anyhow         | 1.0.82  | Application errors            | Simplified error handling with context                                    |
-| **Error Types**        | thiserror      | 1.0.58  | Custom error types            | Derive macro for error enums                                              |
-| **Testing**            | built-in       | std     | Unit/integration tests        | Rust's excellent built-in test framework                                  |
-| **Benchmarking**       | criterion      | 0.5.1   | Performance testing           | Statistical benchmarking for CI regression detection                      |
-| **Logging**            | env_logger     | 0.11.3  | Debug logging                 | Simple, runtime-configurable via RUST_LOG                                 |
-
-## Data Models
-
-### Task
-
-**Purpose:** Core entity representing a single todo item with all associated metadata
-
-**Key Attributes:**
-
-- `id`: i64 - Unique identifier (SQLite ROWID)
-- `description`: String - Task description (up to 1000 chars)
-- `status`: TaskStatus - Enum (Incomplete/Complete)
-- `project`: Option<String> - Optional project grouping
-- `priority`: Priority - Enum (High/Medium/Low), defaults to Medium
-- `due_date`: Option<DateTime> - Optional due date with timezone
-- `created_at`: DateTime - Creation timestamp
-- `updated_at`: DateTime - Last modification timestamp
-- `completed_at`: Option<DateTime> - Completion timestamp
-
-**Relationships:**
-
-- Has many Tags (many-to-many via task_tags table)
-- Belongs to one Project (denormalized for performance)
-
-### Tag
-
-**Purpose:** Flexible categorization system for tasks
-
-**Key Attributes:**
-
-- `id`: i64 - Unique identifier
-- `name`: String - Tag name (alphanumeric + dash/underscore)
-- `created_at`: DateTime - First use timestamp
-
-**Relationships:**
-
-- Has many Tasks (many-to-many via task_tags table)
-- Cascade delete orphaned tags
-
-### TaskTag
-
-**Purpose:** Junction table for many-to-many task-tag relationship
-
-**Key Attributes:**
-
-- `task_id`: i64 - Foreign key to tasks
-- `tag_id`: i64 - Foreign key to tags
-
-**Relationships:**
-
-- Composite primary key (task_id, tag_id)
-- ON DELETE CASCADE for both foreign keys
-
-## Components
-
-### CLI Parser
-
-**Responsibility:** Parse command-line arguments, validate inputs, and route to appropriate command handlers
-
-**Key Interfaces:**
-
-- `parse_args()` - Main entry point parsing std::env::args()
-- `generate_completions()` - Shell completion script generation
-- Subcommand routing to handlers
-
-**Dependencies:** clap v4 for parsing, command handlers for execution
-
-**Technology Stack:** Pure Rust with clap derive macros for type-safe parsing
-
-### Command Handlers
-
-**Responsibility:** Orchestrate business logic for each CLI subcommand (add, list, complete, etc.)
-
-**Key Interfaces:**
-
-- `execute(&self, app: &Application) -> Result<()>` - Common trait for all commands
-- Command-specific structs with validated parameters
-- Output formatting for terminal display
-
-**Dependencies:** Application service layer, terminal output formatters
-
-**Technology Stack:** Rust structs implementing Command trait, termcolor for output
-
-### Application Service
-
-**Responsibility:** Core business logic and workflow orchestration independent of I/O concerns
-
-**Key Interfaces:**
-
-- `add_task(desc: &str, opts: AddOptions) -> Result<Task>`
-- `list_tasks(filters: FilterOptions) -> Result<Vec<Task>>`
-- `complete_tasks(ids: &[i64]) -> Result<usize>`
-- `search_tasks(query: &str) -> Result<Vec<Task>>`
-
-**Dependencies:** Repository interfaces (traits), domain models
-
-**Technology Stack:** Pure Rust business logic with Result-based error handling
-
-### Repository Layer
-
-**Responsibility:** Abstract data persistence operations with SQLite implementation
-
-**Key Interfaces:**
-
-- `TaskRepository` trait with CRUD operations
-- `TagRepository` trait for tag management
-- `Transaction` support for atomic operations
-- Migration runner for schema updates
-
-**Dependencies:** sqlx for database access, domain models
-
-**Technology Stack:** sqlx with compile-time checked queries, connection pooling
-
-### Configuration Manager
-
-**Responsibility:** Load, validate, and provide access to user configuration
-
-**Key Interfaces:**
-
-- `load_config() -> Result<Config>` - Load from XDG directory
-- `save_config(&Config) -> Result<()>` - Persist changes
-- `get_default_project()` - Typed config access
-
-**Dependencies:** toml for parsing, serde for serialization
-
-**Technology Stack:** TOML files with serde deserialization
-
-### Database Manager
-
-**Responsibility:** SQLite connection lifecycle, migrations, and performance optimization
-
-**Key Interfaces:**
-
-- `connect() -> Result<SqlitePool>` - Initialize connection pool
-- `run_migrations() -> Result<()>` - Apply schema updates
-- Prepared statement caching
-- PRAGMA optimizations
-
-**Dependencies:** sqlx SQLite driver, migration files
-
-**Technology Stack:** SQLite with WAL mode, connection pool size of 1
-
-### Component Diagram
-
-```mermaid
-graph LR
-    subgraph "Presentation Layer"
-        CLI[CLI Parser]
-        FMT[Output Formatter]
-    end
-
-    subgraph "Application Layer"
-        CMD[Command Handlers]
-        APP[Application Service]
-    end
-
-    subgraph "Domain Layer"
-        MODELS[Domain Models]
-        TRAITS[Repository Traits]
-    end
-
-    subgraph "Infrastructure Layer"
-        REPO[SQLite Repository]
-        CONFIG[Config Manager]
-        DB[Database Manager]
-    end
-
-    CLI --> CMD
-    CMD --> APP
-    CMD --> FMT
-    APP --> TRAITS
-    TRAITS --> REPO
-    REPO --> DB
-    APP --> MODELS
-    CONFIG --> APP
-
-    style CLI fill:#fff3e0
-    style CMD fill:#fff3e0
-    style APP fill:#f3e5f5
-    style REPO fill:#e8f5e9
-    style DB fill:#e8f5e9
-```
-
-## External APIs
-
-This project does not require any external API integrations. All operations are performed locally with no network dependencies.
-
-## Core Workflows
-
-### Add Task Workflow
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant CLI
-    participant CMD as AddCommand
-    participant APP as Application
-    participant REPO as Repository
-    participant DB as SQLite
-
-    User->>CLI: todo add "Review PR" -p work -P high +review
-    CLI->>CMD: parse_add_command()
-    CMD->>CMD: validate_description_length()
-    CMD->>APP: add_task(desc, options)
-    APP->>APP: parse_tags_from_description()
-    APP->>REPO: begin_transaction()
-    REPO->>DB: BEGIN TRANSACTION
-    APP->>REPO: insert_task(task)
-    REPO->>DB: INSERT INTO tasks...
-    DB-->>REPO: task_id = 42
-    APP->>REPO: insert_tags(task_id, tags)
-    REPO->>DB: INSERT INTO tags...
-    REPO->>DB: INSERT INTO task_tags...
-    APP->>REPO: commit()
-    REPO->>DB: COMMIT
-    APP-->>CMD: Task { id: 42, ... }
-    CMD->>User: ✓ Added task #42
-```
-
-### List Tasks with Filters Workflow
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant CLI
-    participant CMD as ListCommand
-    participant APP as Application
-    participant REPO as Repository
-    participant DB as SQLite
-    participant FMT as Formatter
-
-    User->>CLI: todo list -p work -P high --due
-    CLI->>CMD: parse_list_command()
-    CMD->>APP: list_tasks(filters)
-    APP->>REPO: find_tasks_with_filters(filters)
-    REPO->>REPO: build_query_with_filters()
-    REPO->>DB: SELECT ... WHERE project=? AND priority=? AND due_date IS NOT NULL
-    DB-->>REPO: Vec<TaskRow>
-    REPO->>REPO: load_tags_for_tasks(task_ids)
-    REPO->>DB: SELECT ... FROM task_tags WHERE task_id IN (...)
-    DB-->>REPO: Vec<TagRow>
-    REPO-->>APP: Vec<Task>
-    APP-->>CMD: Vec<Task>
-    CMD->>FMT: format_task_list(tasks)
-    FMT->>User: ID  Description           Project  Priority  Due        Tags<br/>42  Review PR            work     !!!       tomorrow   #review
-```
-
-### Complete Task with Toggle Workflow
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant CLI
-    participant CMD as CompleteCommand
-    participant APP as Application
-    participant REPO as Repository
-    participant DB as SQLite
-
-    User->>CLI: todo complete 42 43
-    CLI->>CMD: parse_complete_command()
-    CMD->>APP: complete_tasks([42, 43])
-
-    loop For each task_id
-        APP->>REPO: find_task_by_id(task_id)
-        REPO->>DB: SELECT ... WHERE id = ?
-        DB-->>REPO: Task
-
-        alt Task exists
-            APP->>APP: toggle_status(task)
-            APP->>REPO: update_task_status(id, new_status)
-            REPO->>DB: UPDATE tasks SET status=?, completed_at=?
-            DB-->>REPO: 1 row affected
-        else Task not found
-            APP->>APP: record_error(task_id)
-        end
-    end
-
-    APP-->>CMD: CompletionResult { success: 2, failed: 0 }
-    CMD->>User: ✓ Completed tasks: #42, #43
-```
-
-## Database Schema
-
-```sql
--- Enable foreign key constraints
-PRAGMA foreign_keys = ON;
-
--- Enable Write-Ahead Logging for better concurrency
-PRAGMA journal_mode = WAL;
-
--- Optimize for fast reads
-PRAGMA synchronous = NORMAL;
-PRAGMA temp_store = MEMORY;
-PRAGMA mmap_size = 30000000000;
-
--- Tasks table: Core entity
-CREATE TABLE tasks (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    description TEXT NOT NULL CHECK(length(description) <= 1000),
-    status TEXT NOT NULL DEFAULT 'incomplete' CHECK(status IN ('incomplete', 'complete')),
-    project TEXT,
-    priority TEXT NOT NULL DEFAULT 'medium' CHECK(priority IN ('high', 'medium', 'low')),
-    due_date DATETIME,
-    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    completed_at DATETIME
-);
-
--- Indexes for common query patterns
-CREATE INDEX idx_tasks_status ON tasks(status);
-CREATE INDEX idx_tasks_project ON tasks(project) WHERE project IS NOT NULL;
-CREATE INDEX idx_tasks_priority ON tasks(priority);
-CREATE INDEX idx_tasks_due_date ON tasks(due_date) WHERE due_date IS NOT NULL;
-CREATE INDEX idx_tasks_created_at ON tasks(created_at);
-
--- Composite index for common filter combinations
-CREATE INDEX idx_tasks_filters ON tasks(status, project, priority);
-
--- Tags table
-CREATE TABLE tags (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL UNIQUE CHECK(name REGEXP '^[a-zA-Z0-9][a-zA-Z0-9_-]*$'),
-    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-
--- Junction table for many-to-many relationship
-CREATE TABLE task_tags (
-    task_id INTEGER NOT NULL,
-    tag_id INTEGER NOT NULL,
-    PRIMARY KEY (task_id, tag_id),
-    FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE CASCADE,
-    FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE
-);
-
--- Index for tag lookups
-CREATE INDEX idx_task_tags_tag_id ON task_tags(tag_id);
-
--- Full-text search virtual table
-CREATE VIRTUAL TABLE tasks_fts USING fts5(
-    description,
-    project,
-    content=tasks,
-    content_rowid=id
-);
-
--- Triggers to keep FTS index in sync
-CREATE TRIGGER tasks_fts_insert AFTER INSERT ON tasks
-BEGIN
-    INSERT INTO tasks_fts(rowid, description, project)
-    VALUES (new.id, new.description, new.project);
-END;
-
-CREATE TRIGGER tasks_fts_update AFTER UPDATE ON tasks
-BEGIN
-    UPDATE tasks_fts
-    SET description = new.description, project = new.project
-    WHERE rowid = old.id;
-END;
-
-CREATE TRIGGER tasks_fts_delete AFTER DELETE ON tasks
-BEGIN
-    DELETE FROM tasks_fts WHERE rowid = old.id;
-END;
-
--- Update trigger for updated_at timestamp
-CREATE TRIGGER tasks_update_timestamp AFTER UPDATE ON tasks
-BEGIN
-    UPDATE tasks SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
-END;
-
--- Migration tracking table
-CREATE TABLE IF NOT EXISTS schema_migrations (
-    version INTEGER PRIMARY KEY,
-    applied_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-```
-
-## Source Tree
-
-```plaintext
-termtodo/
-├── Cargo.toml                 # Project manifest with dependencies
-├── Cargo.lock                # Locked dependency versions
-├── build.rs                   # Build script for embedding resources
-├── .github/
-│   └── workflows/
-│       ├── ci.yml            # Test, lint, build on all platforms
-│       └── release.yml       # Build and publish binaries on tag
-├── src/
-│   ├── main.rs              # Entry point, CLI setup
-│   ├── cli/
-│   │   ├── mod.rs           # CLI module exports
-│   │   ├── parser.rs        # Clap command definitions
-│   │   ├── commands/        # Command handlers
-│   │   │   ├── mod.rs
-│   │   │   ├── add.rs       # Add command implementation
-│   │   │   ├── list.rs      # List command with formatting
-│   │   │   ├── complete.rs  # Complete/uncomplete logic
-│   │   │   ├── delete.rs    # Delete command
-│   │   │   ├── search.rs    # Full-text search
-│   │   │   └── config.rs    # Config management commands
-│   │   └── output.rs        # Terminal output formatting
-│   ├── app/
-│   │   ├── mod.rs           # Application layer exports
-│   │   ├── service.rs       # Main application service
-│   │   ├── filters.rs       # Filter builder and logic
-│   │   └── errors.rs        # Application error types
-│   ├── domain/
-│   │   ├── mod.rs           # Domain model exports
-│   │   ├── task.rs          # Task entity and value objects
-│   │   ├── tag.rs           # Tag entity
-│   │   └── types.rs         # Enums (Status, Priority)
-│   ├── infra/
-│   │   ├── mod.rs           # Infrastructure exports
-│   │   ├── db/
-│   │   │   ├── mod.rs       # Database module
-│   │   │   ├── connection.rs # Connection pool setup
-│   │   │   ├── migrations.rs # Migration runner
-│   │   │   └── queries.rs   # SQL query constants
-│   │   ├── repos/
-│   │   │   ├── mod.rs       # Repository traits
-│   │   │   ├── task_repo.rs # Task repository impl
-│   │   │   └── tag_repo.rs  # Tag repository impl
-│   │   └── config/
-│   │       ├── mod.rs       # Config module
-│   │       └── manager.rs   # Config file handling
-│   └── utils/
-│       ├── mod.rs           # Utility exports
-│       ├── dates.rs         # Date parsing helpers
-│       └── result.rs        # Result extensions
-├── tests/
-│   ├── integration/         # Integration tests
-│   │   ├── cli_tests.rs     # End-to-end CLI tests
-│   │   ├── db_tests.rs      # Database integration
-│   │   └── helpers/         # Test utilities
-│   └── fixtures/            # Test data files
-├── benches/
-│   └── performance.rs       # Criterion benchmarks
-├── migrations/              # SQL migration files
-│   ├── 001_initial.sql
-│   └── 002_add_fts.sql
-└── docs/
-    ├── architecture.md      # This document
-    ├── prd.md              # Product requirements
-    └── README.md           # User documentation
-```
-
-## Infrastructure and Deployment
-
-### Infrastructure as Code
-
-- **Tool:** Not applicable (local application)
-- **Location:** N/A
-- **Approach:** Single binary deployment
-
-### Deployment Strategy
-
-- **Strategy:** Direct binary distribution
-- **CI/CD Platform:** GitHub Actions
-- **Pipeline Configuration:** `.github/workflows/release.yml`
-
-### Environments
-
-- **Development:** Local developer machine with debug builds
-- **Testing:** CI environment with all platforms (Linux, macOS, Windows)
-- **Production:** User's local machine with release binary
-
-### Environment Promotion Flow
-
-```text
-Development (local) -> CI Testing -> GitHub Release -> User Installation
-                         ↓
-                    Failed tests
-                         ↓
-                    Fix & retry
-```
-
-### Rollback Strategy
-
-- **Primary Method:** Previous version binary installation
-- **Trigger Conditions:** User-reported critical bugs, data corruption
-- **Recovery Time Objective:** < 5 minutes (download previous release)
-
-## Error Handling Strategy
-
-### General Approach
-
-- **Error Model:** Result<T, Error> for all fallible operations
-- **Exception Hierarchy:** anyhow::Error for applications, custom types for libraries
-- **Error Propagation:** ? operator with context via .context()
-
-### Logging Standards
-
-- **Library:** env_logger 0.11.3
-- **Format:** `[TIMESTAMP] [LEVEL] [MODULE] Message`
-- **Levels:** ERROR, WARN, INFO, DEBUG, TRACE
-- **Required Context:**
-  - Correlation ID: Not needed (single-user CLI)
-  - Service Context: Module path automatically included
-  - User Context: Never log user data or task content
-
-### Error Handling Patterns
-
-#### External API Errors
-
-- **Retry Policy:** No external APIs
-- **Circuit Breaker:** Not applicable
-- **Timeout Configuration:** Not applicable
-- **Error Translation:** Not applicable
-
-#### Business Logic Errors
-
-- **Custom Exceptions:**
-  - `TaskNotFound(id)`
-  - `InvalidTaskDescription(reason)`
-  - `DuplicateTag(name)`
-  - `ConfigError(path, reason)`
-- **User-Facing Errors:** Clear, actionable messages via Display trait
-- **Error Codes:** Not used - descriptive messages preferred
-
-#### Data Consistency
-
-- **Transaction Strategy:** Explicit transactions for multi-table operations
-- **Compensation Logic:** Not needed with ACID SQLite
-- **Idempotency:** Complete/uncomplete operations are naturally idempotent
-
-## Coding Standards
-
-These standards are MANDATORY for AI agents and define project-specific conventions.
-
-### Core Standards
-
-- **Languages & Runtimes:** Rust 1.78.0 (edition 2021)
-- **Style & Linting:** rustfmt with default config, clippy with pedantic lints
-- **Test Organization:** Unit tests in `#[cfg(test)]` modules, integration tests in tests/
-
-### Naming Conventions
-
-| Element   | Convention      | Example               |
-| --------- | --------------- | --------------------- |
-| Structs   | PascalCase      | `TaskFilter`          |
-| Functions | snake_case      | `parse_due_date`      |
-| Constants | SCREAMING_SNAKE | `MAX_DESCRIPTION_LEN` |
-| Modules   | snake_case      | `task_repo`           |
-
-### Critical Rules
-
-- **No unwrap() in production code:** Use expect() with clear message or proper error handling
-- **All public functions must have doc comments:** Include examples for complex APIs
-- **SQL queries must use parameterized statements:** Never concatenate user input
-- **Benchmark new features:** Add criterion benchmarks for any performance-critical code
-- **Check Task description length:** Enforce 1000 character limit at CLI parsing layer
-
-## Test Strategy and Standards
-
-### Testing Philosophy
-
-- **Approach:** Test-after development with comprehensive coverage
-- **Coverage Goals:** 80% overall, 90% for business logic
-- **Test Pyramid:** 70% unit, 25% integration, 5% e2e
-
-### Test Types and Organization
-
-#### Unit Tests
-
-- **Framework:** Rust built-in testing
-- **File Convention:** Tests in same file as code under `#[cfg(test)]` module
-- **Location:** Bottom of each source file
-- **Mocking Library:** Manual test doubles (traits make this easy)
-- **Coverage Requirement:** 90% for domain and app layers
-
-**AI Agent Requirements:**
-
-- Generate tests for all public methods
-- Cover edge cases and error conditions
-- Follow AAA pattern (Arrange, Act, Assert)
-- Mock all external dependencies
-
-#### Integration Tests
-
-- **Scope:** Database operations, CLI parsing, file I/O
-- **Location:** `tests/integration/`
-- **Test Infrastructure:**
-  - **Database:** In-memory SQLite for speed
-  - **File System:** tempfile crate for isolated testing
-  - **CLI:** assert_cmd for command execution tests
-
-#### End-to-End Tests
-
-- **Framework:** assert_cmd 2.0.14
-- **Scope:** Full command execution with real database
-- **Environment:** Isolated temp directory per test
-- **Test Data:** Fixtures in tests/fixtures/
-
-### Test Data Management
-
-- **Strategy:** Builder pattern for test objects
-- **Fixtures:** `tests/fixtures/` for import/export tests
-- **Factories:** TaskBuilder, TagBuilder in test modules
-- **Cleanup:** Automatic via tempfile cleanup
-
-### Continuous Testing
-
-- **CI Integration:** Run on every push (test, clippy, fmt)
-- **Performance Tests:** Criterion benchmarks with 5% regression threshold
-- **Security Tests:** cargo audit in CI pipeline
-
-## Security
-
-### Input Validation
-
-- **Validation Library:** Built-in Rust type system + manual checks
-- **Validation Location:** CLI parsing layer before any processing
-- **Required Rules:**
-  - All external inputs MUST be validated
-  - Validation at API boundary before processing
-  - Whitelist approach preferred over blacklist
-
-### Authentication & Authorization
-
-- **Auth Method:** Not applicable (local single-user application)
-- **Session Management:** Not applicable
-- **Required Patterns:**
-  - File permissions rely on OS user permissions
-  - XDG directory compliance for proper isolation
-
-### Secrets Management
-
-- **Development:** No secrets required
-- **Production:** No secrets required
-- **Code Requirements:**
-  - NEVER hardcode secrets
-  - Access via configuration service only
-  - No secrets in logs or error messages
-
-### API Security
-
-Not applicable - no network APIs exposed
-
-### Data Protection
-
-- **Encryption at Rest:** Relies on OS disk encryption
-- **Encryption in Transit:** Not applicable (local only)
-- **PII Handling:** Task descriptions may contain PII - never log
-- **Logging Restrictions:** Never log task content, only IDs and metadata
-
-### Dependency Security
-
-- **Scanning Tool:** cargo audit
-- **Update Policy:** Monthly dependency updates
-- **Approval Process:** Review changelog for breaking changes
-
-### Security Testing
-
-- **SAST Tool:** cargo clippy with security lints
-- **DAST Tool:** Not applicable
-- **Penetration Testing:** Not required for local CLI
-
-## Checklist Results Report
-
-To be completed after architecture review.
-
-## Next Steps
-
-### Developer Handoff
-
-Begin implementation with the following:
-
-- Reference this architecture document and coding standards throughout development
-- Start with Epic 1, Story 1.1: Project Setup and Infrastructure
-- Key technical decisions to follow:
-  - Use Rust 1.78.0 with 2021 edition
-  - Implement clean architecture layers as specified
-  - All commands must complete in < 100ms
-  - Use synchronous code (no async/await)
-  - Follow the defined error handling patterns

zoo/docs/brief.md

@@ -1,253 +0,0 @@
-# Project Brief: Terminal Todo App
-
-## Project Overview
-
-**Project Name:** TermTodo  
-**Version:** 1.0  
-**Date:** 2025-07-07  
-**Status:** Planning Phase
-
-### Executive Summary
-
-TermTodo is a lightweight, fast, and efficient terminal-based todo application designed for developers and power users who live in the command line. The application prioritizes speed, simplicity, and seamless integration with existing terminal workflows while providing robust task management capabilities.
-
-### Vision Statement
-
-To create the most efficient terminal todo app that enhances developer productivity by eliminating context switching between GUI applications and the command line environment.
-
-## Problem Statement
-
-### Current Pain Points
-
-- **Context Switching:** Developers lose focus switching between terminal and GUI todo apps
-- **Bloated Solutions:** Existing todo apps are feature-heavy and slow to load
-- **Poor CLI Integration:** Most todo apps don't integrate well with terminal workflows
-- **Sync Overhead:** Cloud-based solutions add unnecessary complexity for local task management
-
-### Target Opportunity
-
-Create a fast, local-first todo application that feels native to terminal users while providing essential productivity features without bloat.
-
-## Objectives & Success Metrics
-
-### Primary Objectives
-
-1. **Speed:** App launches and executes commands in <100ms
-2. **Simplicity:** Core functionality accessible through intuitive commands
-3. **Integration:** Seamless workflow integration with git, editors, and shell scripts
-4. **Reliability:** Zero data loss with robust local storage
-
-### Success Metrics
-
-- **Performance:** Sub-100ms command execution time
-- **Adoption:** 1000+ GitHub stars within 6 months
-- **Usage:** Daily active usage by 100+ developers
-- **Satisfaction:** 90%+ positive feedback on usability
-
-## Target Audience
-
-### Primary Users
-
-**Developer Power Users**
-
-- Daily terminal users
-- Prefer keyboard-driven workflows
-- Value speed and efficiency over visual polish
-- Work with multiple projects simultaneously
-
-**System Administrators**
-
-- Manage multiple servers and tasks
-- Need quick task tracking between systems
-- Prefer scriptable/automatable solutions
-
-### User Personas
-
-**"Terminal Tom" - Senior Developer**
-
-- 8+ years experience
-- Uses vim/emacs, tmux, custom shell setups
-- Manages 3-5 projects simultaneously
-- Values minimalism and efficiency
-
-**"DevOps Dana" - Infrastructure Engineer**
-
-- Manages CI/CD pipelines
-- Juggles multiple environments
-- Needs quick task capture during incidents
-- Prefers automation-friendly tools
-
-## Scope & Features
-
-### Core Features (MVP)
-
-1. **Basic Task Management**
-
-   - Add, edit, delete tasks
-   - Mark tasks as complete
-   - List tasks with filtering
-
-2. **Organization**
-
-   - Project-based task grouping
-   - Priority levels (high, medium, low)
-   - Due date support
-
-3. **Search & Filter**
-   - Text search across tasks
-   - Filter by status, priority, project
-   - Tag-based organization
-
-### Advanced Features (v2.0+)
-
-1. **Workflow Integration**
-
-   - Git branch integration
-   - Editor plugin support
-   - Shell completion
-
-2. **Automation**
-
-   - Recurring tasks
-   - Template tasks
-   - Bulk operations
-
-3. **Reporting**
-   - Productivity metrics
-   - Time tracking
-   - Export capabilities
-
-### Out of Scope
-
-- Web interface
-- Mobile applications
-- Cloud synchronization
-- Collaborative features
-- Complex project management
-
-## Technical Requirements
-
-### Technology Stack
-
-- **Language:** Rust (performance, single binary distribution)
-- **CLI Framework:** Clap (argument parsing)
-- **Storage:** SQLite (local, reliable, queryable)
-- **Configuration:** TOML files
-
-### Performance Requirements
-
-- **Startup Time:** <50ms cold start
-- **Command Execution:** <100ms for all operations
-- **Memory Usage:** <10MB resident memory
-- **Storage:** Efficient SQLite schema design
-
-### Platform Support
-
-- **Primary:** Linux, macOS
-- **Secondary:** Windows (WSL)
-- **Distribution:** Single binary, package managers
-
-## Implementation Strategy
-
-### Development Phases
-
-**Phase 1: Core MVP (4 weeks)**
-
-- Basic CRUD operations
-- SQLite storage layer
-- Command-line interface
-- Unit test coverage
-
-**Phase 2: Organization (3 weeks)**
-
-- Project grouping
-- Priority and due dates
-- Search and filtering
-- Integration testing
-
-**Phase 3: Polish (2 weeks)**
-
-- Shell completion
-- Configuration management
-- Documentation
-- Performance optimization
-
-### Risk Mitigation
-
-- **Technical Risk:** Rust learning curve → Start with simple CLI, iterate
-- **Market Risk:** Existing solutions → Focus on speed and terminal integration
-- **Adoption Risk:** Discoverability → Leverage dev community, GitHub
-
-## Timeline & Milestones
-
-### Key Milestones
-
-| Phase | Deliverable      | Timeline | Success Criteria               |
-| ----- | ---------------- | -------- | ------------------------------ |
-| 1     | MVP Release      | Week 4   | Core features functional       |
-| 2     | Beta Release     | Week 7   | Organization features complete |
-| 3     | v1.0 Release     | Week 9   | Production ready               |
-| 4     | Community Growth | Week 20  | 1000+ GitHub stars             |
-
-### Critical Path
-
-1. SQLite schema design
-2. Core command structure
-3. Performance optimization
-4. Documentation and examples
-
-## Team & Stakeholders
-
-### Core Team
-
-**Solo Developer** (Primary)
-
-- Full-stack development
-- Design and architecture
-- Testing and documentation
-
-### Advisory Stakeholders
-
-- **Developer Community:** Feedback and feature requests
-- **Beta Users:** Early testing and validation
-- **Open Source Community:** Contributions and maintenance
-
-## Budget & Resources
-
-### Development Resources
-
-- **Time Investment:** 20 hours/week for 9 weeks
-- **Infrastructure:** GitHub (free), domain name ($15/year)
-- **Tools:** Development environment, testing tools
-
-### Total Investment
-
-- **Development Time:** ~180 hours
-- **Direct Costs:** <$50
-- **Opportunity Cost:** Personal projects, learning time
-
-## Success Factors
-
-### Critical Success Factors
-
-1. **Performance First:** Every feature decision evaluated for speed impact
-2. **Developer Experience:** Intuitive commands that feel natural
-3. **Terminal Native:** Feels like a built-in shell command
-4. **Community Building:** Engage early adopters for feedback
-
-### Potential Risks
-
-- **Over-engineering:** Feature creep beyond core use cases
-- **Performance Degradation:** Complex features slowing core operations
-- **Adoption Challenges:** Difficulty reaching target developers
-
-## Next Steps
-
-1. **Technical Spike:** Rust CLI framework evaluation (Week 1)
-2. **Database Design:** SQLite schema and migration strategy
-3. **Core Architecture:** Command structure and data flow
-4. **MVP Development:** Begin core feature implementation
-
----
-
-_This project brief will be reviewed and updated at each milestone to ensure alignment with objectives and market feedback._

zoo/docs/prd.md

@@ -1,500 +0,0 @@
-# TermTodo Product Requirements Document (PRD)
-
-## Goals and Background Context
-
-### Goals
-
-- Deliver a terminal todo app that executes all commands in under 100ms
-- Eliminate context switching for developers who live in the command line
-- Provide intuitive task management through simple, memorable commands
-- Enable seamless integration with existing terminal workflows (git, editors, scripts)
-- Achieve zero data loss with robust local SQLite storage
-- Build a tool that feels native to terminal power users
-- Create a maintainable single-binary distribution for easy installation
-
-### Background Context
-
-TermTodo addresses a critical gap in developer productivity tools. While numerous todo applications exist, they force developers to break their flow by switching between terminal and GUI applications. Current solutions are either bloated web applications with unnecessary features or simplistic command-line tools that lack essential task management capabilities. TermTodo strikes the balance by providing a fast, local-first solution that integrates naturally into terminal-based workflows.
-
-The application targets developers and system administrators who value speed and efficiency over visual polish. By focusing on sub-100ms execution times and keyboard-driven interactions, TermTodo eliminates the friction that prevents consistent task tracking in fast-paced development environments. The choice of Rust ensures performance goals are met while providing a single binary that's easy to distribute and install across Linux, macOS, and Windows (WSL) platforms.
-
-### Change Log
-
-| Date       | Version | Description                                 | Author   |
-| ---------- | ------- | ------------------------------------------- | -------- |
-| 2025-07-07 | 1.0     | Initial PRD creation based on Project Brief | PM Agent |
-
-## Requirements
-
-### Functional
-
-- FR1: The application must support adding tasks with a single command (e.g., `todo add "Complete code review"`)
-- FR2: Users must be able to mark tasks as complete/incomplete with toggle functionality
-- FR3: The application must support editing existing task descriptions
-- FR4: Users must be able to delete individual tasks or bulk delete completed tasks
-- FR5: The application must list tasks with configurable filtering by status, priority, project, and tags
-- FR6: Task organization must support project-based grouping with easy project switching
-- FR7: Each task must support priority levels (high, medium, low) with visual indicators in listings
-- FR8: Tasks must support optional due dates with human-readable input (e.g., "tomorrow", "next friday")
-- FR9: The application must provide full-text search across all task fields
-- FR10: Users must be able to add and remove tags from tasks for flexible categorization
-- FR11: The application must support task templates for recurring task patterns
-- FR12: Shell completion must be available for all commands and common parameters
-- FR13: The application must provide export functionality to common formats (JSON, CSV, Markdown)
-- FR14: Configuration must be manageable through TOML files with sensible defaults
-
-### Non Functional
-
-- NFR1: All commands must execute in under 100ms from invocation to completion
-- NFR2: Cold start time must be under 50ms on standard developer hardware
-- NFR3: Memory usage must not exceed 10MB during normal operation
-- NFR4: The application must be distributed as a single static binary with no runtime dependencies
-- NFR5: Data storage must use SQLite with ACID compliance for zero data loss
-- NFR6: The CLI must follow Unix conventions (stdin/stdout, exit codes, composability)
-- NFR7: All user-facing messages must be clear, concise, and actionable
-- NFR8: The application must support Linux and macOS as primary platforms, Windows via WSL
-- NFR9: Installation must be possible through major package managers (brew, apt, cargo)
-- NFR10: The codebase must maintain 80%+ test coverage for reliability
-- NFR11: All commands must be documented with man pages and --help output
-- NFR12: The application must handle 10,000+ tasks without performance degradation
-- NFR13: Error messages must provide clear guidance for resolution
-- NFR14: The application must support UTF-8 for international task descriptions
-
-## Technical Assumptions
-
-### Repository Structure: Monorepo
-
-Single repository containing all TermTodo code, tests, documentation, and build configurations. This simplifies development, testing, and distribution for a focused CLI tool.
-
-### Service Architecture
-
-**Monolith** - TermTodo will be built as a single, self-contained binary with all functionality compiled in. This architecture aligns with our performance goals (sub-50ms startup) and distribution requirements (single binary). The SQLite database will be embedded, and all operations will run in-process without network dependencies.
-
-### Testing Requirements
-
-**Full Testing Pyramid** - Given the critical nature of data integrity and performance requirements:
-
-- **Unit Tests**: Core business logic, data models, command parsing
-- **Integration Tests**: SQLite operations, file I/O, command execution flows
-- **E2E Tests**: Full command-line scenarios using the actual binary
-- **Performance Tests**: Automated benchmarks ensuring sub-100ms execution
-- **Manual Testing Helpers**: Debug commands and verbose modes for troubleshooting
-
-### Additional Technical Assumptions and Requests
-
-- **Language**: Rust (as specified in Project Brief) for performance and memory safety
-- **CLI Framework**: Clap v4+ for robust argument parsing and automatic help generation
-- **Database**: SQLite with schema migrations support (using sqlx or diesel)
-- **Error Handling**: Comprehensive error types with user-friendly messages using anyhow/thiserror
-- **Configuration**: TOML for human-readable config files, with XDG base directory compliance
-- **Build System**: Cargo with cross-compilation support for Linux/macOS/Windows targets
-- **Serialization**: Serde for JSON/CSV export functionality
-- **Date Parsing**: Chrono with chrono-english for human-readable date input
-- **Terminal Output**: Colored output using termcolor, respecting NO_COLOR environment variable
-- **Shell Completion**: Built-in completion generation for bash, zsh, fish, and PowerShell
-- **Packaging**: Release binaries via GitHub releases, plus cargo, brew tap, and AUR support
-- **Documentation**: Embedded man pages generated from clap, README with examples
-- **Logging**: Optional debug logging to file (not stdout) for troubleshooting
-- **Benchmarking**: Criterion.rs for performance regression testing in CI
-
-## Epic List
-
-- **Epic 1: Foundation & Core Task Management**: Establish project infrastructure, CI/CD, and implement basic CRUD operations for tasks with SQLite storage
-- **Epic 2: Organization & Filtering**: Implement project-based task grouping, priority levels, tags, and comprehensive filtering capabilities
-- **Epic 3: Advanced Features & Integration**: Add due dates, search functionality, shell completion, templates, and import/export capabilities
-
-## Epic 1: Foundation & Core Task Management
-
-Establish the foundational infrastructure for TermTodo including project setup, continuous integration, and core task CRUD operations. This epic delivers a functional but minimal todo application that can add, list, complete, and delete tasks with persistent SQLite storage, while meeting our aggressive performance requirements.
-
-### Story 1.1: Project Setup and Infrastructure
-
-As a developer,
-I want a properly structured Rust project with CI/CD pipelines,
-so that I can ensure code quality and automated releases from the start.
-
-#### Acceptance Criteria
-
-1: Repository initialized with Rust project structure and .gitignore
-2: Cargo.toml configured with project metadata and initial dependencies (clap, sqlx, tokio)
-3: GitHub Actions workflow for CI (test, lint, build) on all platforms
-4: GitHub Actions workflow for CD (release binaries) on tag push
-5: Basic README with project description and development setup instructions
-6: Pre-commit hooks configured for formatting (rustfmt) and linting (clippy)
-7: MIT License file added
-8: Makefile with common development commands (test, build, release)
-
-### Story 1.2: CLI Framework and Command Structure
-
-As a user,
-I want a well-structured command-line interface with help documentation,
-so that I can easily discover and use all available commands.
-
-#### Acceptance Criteria
-
-1: Main CLI entry point implemented with clap v4
-2: Subcommand structure established (add, list, complete, delete, etc.)
-3: Global flags implemented (--version, --help, --config)
-4: Auto-generated help text for all commands and subcommands
-5: Version information properly displayed from Cargo.toml
-6: Exit codes follow Unix conventions (0 for success, non-zero for errors)
-7: Basic error handling structure with user-friendly messages
-
-### Story 1.3: SQLite Database Layer
-
-As a developer,
-I want a robust database layer with schema management,
-so that I can reliably store and retrieve tasks with ACID compliance.
-
-#### Acceptance Criteria
-
-1: SQLite connection pool initialized with proper settings
-2: Initial schema migration creating tasks table (id, description, status, created_at, updated_at)
-3: Migration system implemented for future schema changes
-4: Database file created in XDG-compliant data directory
-5: Connection timeout and busy handling configured for concurrent access
-6: Basic database error handling with rollback support
-7: Database layer abstraction with trait for testability
-
-### Story 1.4: Add Task Functionality
-
-As a user,
-I want to quickly add new tasks from the command line,
-so that I can capture todo items without breaking my workflow.
-
-#### Acceptance Criteria
-
-1: "todo add <description>" command creates new task in database
-2: Task description supports UTF-8 and quotes/special characters
-3: Newly created task ID displayed on successful addition
-4: Task creation timestamp automatically recorded
-5: Performance requirement met: command completes in <100ms
-6: Error shown if description is empty or too long (>1000 chars)
-7: Success message confirms task was added
-
-### Story 1.5: List Tasks Functionality
-
-As a user,
-I want to see my current tasks in a clear format,
-so that I can review what needs to be done.
-
-#### Acceptance Criteria
-
-1: "todo list" command displays all incomplete tasks
-2: Output shows task ID, description, and age (e.g., "2 days ago")
-3: Tasks sorted by creation date (oldest first) by default
-4: Completed tasks hidden by default
-5: "--all" flag shows both complete and incomplete tasks
-6: Empty state message when no tasks exist
-7: Output formatted for terminal width with proper truncation
-
-### Story 1.6: Complete Task Functionality
-
-As a user,
-I want to mark tasks as complete,
-so that I can track my progress.
-
-#### Acceptance Criteria
-
-1: "todo complete <id>" marks specified task as complete
-2: Multiple IDs can be provided to complete multiple tasks
-3: Completion timestamp recorded in database
-4: Success message confirms which task(s) were completed
-5: Error shown for non-existent task IDs
-6: Already-completed tasks can be marked complete again (idempotent)
-7: Performance requirement met: command completes in <100ms
-
-### Story 1.7: Delete Task Functionality
-
-As a user,
-I want to delete tasks I no longer need,
-so that I can keep my task list clean and relevant.
-
-#### Acceptance Criteria
-
-1: "todo delete <id>" removes specified task from database
-2: Multiple IDs can be provided to delete multiple tasks
-3: Confirmation required by default (bypass with --force flag)
-4: Success message confirms which task(s) were deleted
-5: Error shown for non-existent task IDs
-6: "todo delete --completed" removes all completed tasks
-7: Deleted tasks cannot be recovered (documented in help)
-
-## Epic 2: Organization & Filtering
-
-Implement comprehensive task organization features including projects, priorities, tags, and filtering capabilities. This epic transforms the basic todo app into a powerful task management system that can handle complex workflows while maintaining simplicity and performance.
-
-### Story 2.1: Project-Based Task Grouping
-
-As a developer working on multiple projects,
-I want to organize tasks by project,
-so that I can focus on relevant tasks for my current context.
-
-#### Acceptance Criteria
-
-1: Tasks table schema updated to include optional project field
-2: "todo add -p <project> <description>" assigns task to project
-3: "todo list -p <project>" filters tasks by project
-4: "todo projects" lists all unique projects with task counts
-5: Default project configurable in TOML config file
-6: Project names validated (alphanumeric + dash/underscore)
-7: Tasks without project show under "default" in listings
-
-### Story 2.2: Priority Levels
-
-As a user,
-I want to assign priority levels to tasks,
-so that I can focus on what's most important.
-
-#### Acceptance Criteria
-
-1: Tasks table schema updated to include priority field (high/medium/low)
-2: "todo add -P high <description>" sets task priority
-3: Default priority is "medium" if not specified
-4: Priority shown in task listings with visual indicators (!, !!, !!!)
-5: "todo list --priority high" filters by priority level
-6: Tasks sorted by priority within date sorting
-7: Priority can be updated with "todo priority <id> <level>"
-
-### Story 2.3: Tag System
-
-As a user,
-I want to add tags to tasks for flexible categorization,
-so that I can create custom organizational schemes.
-
-#### Acceptance Criteria
-
-1: Tags table created with many-to-many relationship to tasks
-2: "todo add <description> +tag1 +tag2" adds tags during creation
-3: Tags parsed from description (+ prefix) and stored separately
-4: "todo tag <id> +tag" adds tags to existing tasks
-5: "todo tag <id> -tag" removes tags from tasks
-6: "todo list +tag" filters tasks by tag
-7: "todo tags" lists all tags with usage counts
-
-### Story 2.4: Advanced Filtering
-
-As a power user,
-I want to combine multiple filters when listing tasks,
-so that I can create precise views of my work.
-
-#### Acceptance Criteria
-
-1: Multiple filters can be combined (project AND priority AND tags)
-2: "todo list -p work -P high +urgent" shows filtered results
-3: Date range filtering with --since and --until flags
-4: Status filtering with --status (incomplete/complete/all)
-5: Inverse filters supported with --not-project, --not-tag
-6: Filter combinations can be saved as named views in config
-7: Performance maintained under 100ms even with complex filters
-
-### Story 2.5: Configuration Management
-
-As a user,
-I want to customize default behaviors and preferences,
-so that the tool works the way I prefer.
-
-#### Acceptance Criteria
-
-1: TOML config file created at XDG config location on first run
-2: Config supports: default project, default priority, date format
-3: Config supports: color preferences, list sort order
-4: "todo config" opens config file in $EDITOR
-5: "todo config --list" shows current configuration
-6: Invalid config shows clear error without crashing
-7: Config changes take effect immediately (no restart needed)
-
-## Epic 3: Advanced Features & Integration
-
-Add power-user features including due dates, full-text search, shell completion, templates, and data portability. This epic completes the feature set needed for TermTodo to become an indispensable part of a developer's workflow.
-
-### Story 3.1: Due Date Support
-
-As a user,
-I want to set due dates on tasks,
-so that I can manage time-sensitive work effectively.
-
-#### Acceptance Criteria
-
-1: Tasks table schema updated to include optional due_date field
-2: "todo add <description> due:tomorrow" sets due date with natural language
-3: Supported formats: "due:2024-12-31", "due:friday", "due:3d" (3 days)
-4: Due dates shown in task listings with urgency indicators
-5: "todo list --due" shows only tasks with due dates
-6: "todo list --overdue" shows past-due tasks highlighted
-7: Due date can be updated with "todo due <id> <date>"
-
-### Story 3.2: Full-Text Search
-
-As a user with many tasks,
-I want to search across all task fields,
-so that I can quickly find specific items.
-
-#### Acceptance Criteria
-
-1: "todo search <query>" searches description, project, and tags
-2: Search uses SQLite FTS5 for performance and features
-3: Results show matched tasks with search terms highlighted
-4: Search supports quoted phrases for exact matching
-5: Boolean operators AND/OR supported in queries
-6: Search results include context around matches
-7: Performance requirement met: search completes in <100ms
-
-### Story 3.3: Shell Completion
-
-As a command-line power user,
-I want shell completion for all commands and parameters,
-so that I can work more efficiently.
-
-#### Acceptance Criteria
-
-1: Completion scripts generated for bash, zsh, fish, PowerShell
-2: Command completion includes all subcommands and flags
-3: Project names completed for -p flag from existing projects
-4: Tag names completed after + prefix from existing tags
-5: Task IDs completed for complete/delete/update commands
-6: Installation instructions included in README
-7: Completion scripts included in distribution packages
-
-### Story 3.4: Task Templates
-
-As a user with recurring task patterns,
-I want to create templates for common tasks,
-so that I can quickly add similar tasks.
-
-#### Acceptance Criteria
-
-1: Templates stored in TOML config file with name and pattern
-2: "todo template create <name>" interactively creates template
-3: "todo template list" shows available templates
-4: "todo add --template <name>" creates task from template
-5: Templates support placeholders like {date}, {project}
-6: Templates can include default project, priority, tags
-7: "todo template delete <name>" removes unused templates
-
-### Story 3.5: Import/Export Functionality
-
-As a user,
-I want to export and import my tasks in common formats,
-so that I can backup data or integrate with other tools.
-
-#### Acceptance Criteria
-
-1: "todo export --format json" exports all tasks to JSON
-2: "todo export --format csv" exports tasks to CSV format
-3: "todo export --format markdown" creates Markdown task list
-4: Export supports filtering (only export filtered tasks)
-5: "todo import <file>" imports tasks from JSON format
-6: Import validates data and reports errors without corruption
-7: Export includes all fields: description, project, priority, tags, dates
-
-### Story 3.6: Performance Optimization
-
-As a developer using the tool hundreds of times per day,
-I want consistent sub-100ms performance,
-so that the tool never slows down my workflow.
-
-#### Acceptance Criteria
-
-1: Benchmark suite implemented using criterion.rs
-2: All commands benchmarked in CI to prevent regression
-3: Database indexes optimized for common query patterns
-4: Prepared statements cached for repeated queries
-5: Binary size optimized with release flags and LTO
-6: Cold start optimized to meet <50ms requirement
-7: Performance guide documented with optimization tips
-
-## Checklist Results Report
-
-### Executive Summary
-
-- **Overall PRD Completeness**: 95%
-- **MVP Scope Appropriateness**: Just Right
-- **Readiness for Architecture Phase**: Ready
-- **Most Critical Gaps**: None - PRD is comprehensive and well-structured
-
-### Category Analysis Table
-
-| Category                         | Status | Critical Issues          |
-| -------------------------------- | ------ | ------------------------ |
-| 1. Problem Definition & Context  | PASS   | None                     |
-| 2. MVP Scope Definition          | PASS   | None                     |
-| 3. User Experience Requirements  | PASS   | CLI-focused, appropriate |
-| 4. Functional Requirements       | PASS   | None                     |
-| 5. Non-Functional Requirements   | PASS   | None                     |
-| 6. Epic & Story Structure        | PASS   | None                     |
-| 7. Technical Guidance            | PASS   | None                     |
-| 8. Cross-Functional Requirements | PASS   | None                     |
-| 9. Clarity & Communication       | PASS   | None                     |
-
-### Top Issues by Priority
-
-**BLOCKERS**: None identified
-
-**HIGH**: None identified
-
-**MEDIUM**:
-
-- Consider adding explicit data migration strategy for future schema changes
-- May want to specify exact Rust version requirements
-
-**LOW**:
-
-- Could add more specific examples of shell script integration possibilities
-- Might benefit from explicit CI/CD tool preferences (GitHub Actions assumed)
-
-### MVP Scope Assessment
-
-**Scope Analysis**:
-
-- The MVP scope is appropriately minimal while delivering core value
-- Epic 1 provides a working todo app with essential CRUD operations
-- Epic 2 and 3 can be delivered incrementally based on user feedback
-- No features appear superfluous for the target audience
-
-**Timeline Realism**:
-
-- 9-week timeline is aggressive but achievable for a solo developer
-- Story sizing is appropriate for AI-assisted development
-- Performance requirements may require iteration but are well-defined
-
-### Technical Readiness
-
-**Clarity of Technical Constraints**:
-
-- Technology stack clearly defined (Rust, SQLite, Clap)
-- Performance requirements explicit and measurable
-- Distribution strategy well-planned
-
-**Identified Technical Risks**:
-
-- SQLite cold-start performance for <50ms requirement
-- Cross-platform shell completion complexity
-- Natural language date parsing edge cases
-
-**Areas Needing Architect Investigation**:
-
-- Optimal SQLite configuration for performance
-- Schema design for efficient filtering and search
-- Binary size optimization strategies
-
-### Recommendations
-
-1. **Proceed to Architecture Phase**: The PRD is comprehensive and ready
-2. **Early Performance Validation**: Create a spike to validate SQLite startup times
-3. **Schema Evolution Strategy**: Document migration approach early in development
-4. **User Testing Plan**: Consider early beta program for developer feedback
-
-### Final Decision
-
-**READY FOR ARCHITECT**: The PRD and epics are comprehensive, properly structured, and ready for architectural design. The document provides clear requirements, appropriate technical constraints, and a well-sequenced implementation plan suitable for the target developer audience.
-
-## Next Steps
-
-### Design Architect Prompt
-
-Review the TermTodo PRD and create a comprehensive UI/UX design specification for this CLI application, focusing on terminal-based interaction patterns, command syntax design, output formatting, and the overall developer experience.
-
-### Architect Prompt
-
-Analyze the TermTodo PRD and create a detailed technical architecture document including: database schema design, Rust module structure, performance optimization strategies, error handling patterns, and a concrete implementation plan for achieving sub-100ms execution times.

zoo/docs/stories/1.1.story.md

@@ -1,278 +0,0 @@
-# Story 1.1: Project Setup and Infrastructure
-
-## Status
-
-Draft
-
-## Story
-
-**As a** developer,
-**I want** a properly structured Rust project with CI/CD pipelines,
-**so that** I can ensure code quality and automated releases from the start.
-
-## Acceptance Criteria
-
-1. Repository initialized with Rust project structure and .gitignore
-2. Cargo.toml configured with project metadata and all required dependencies from tech stack
-3. GitHub Actions workflow for CI (test, lint, build) on all platforms
-4. GitHub Actions workflow for CD (release binaries) on tag push
-5. Basic README with project description and development setup instructions
-6. Pre-commit hooks configured for formatting (rustfmt) and linting (clippy)
-7. MIT License file added
-8. Makefile with common development commands (test, build, release)
-
-## Tasks / Subtasks
-
-- [ ] Task 1: Initialize Rust project structure (AC: 1)
-  - [ ] Create Cargo.toml with project metadata
-  - [ ] Set up proper .gitignore for Rust projects
-  - [ ] Initialize git repository if needed
-  - [ ] Create basic src/main.rs entry point
-- [ ] Task 2: Configure dependencies in Cargo.toml (AC: 2)
-  - [ ] Add clap v4.5.4 for CLI framework
-  - [ ] Add sqlx v0.7.4 for database operations
-  - [ ] Add anyhow v1.0.82 for error handling
-  - [ ] Add thiserror v1.0.58 for custom error types
-  - [ ] Add toml v0.8.12 for config file parsing
-  - [ ] Add termcolor v1.4.1 for colored output
-  - [ ] Add criterion v0.5.1 for benchmarking
-  - [ ] Add env_logger v0.11.3 for debug logging
-  - [ ] Add chrono v0.4.38 and chrono-english v0.1.7 for date parsing
-  - [ ] Add serde v1.0.197 for serialization
-- [ ] Task 3: Set up GitHub Actions CI workflow (AC: 3)
-  - [ ] Create .github/workflows/ci.yml
-  - [ ] Configure test, lint, and build jobs
-  - [ ] Set up matrix builds for Linux and macOS
-  - [ ] Add rustfmt and clippy checks
-  - [ ] Add security audit using cargo audit
-  - [ ] Add performance benchmarks with 5% regression threshold
-- [ ] Task 4: Set up GitHub Actions CD workflow (AC: 4)
-  - [ ] Create .github/workflows/release.yml
-  - [ ] Configure binary builds for release
-  - [ ] Set up artifact uploads for releases
-  - [ ] Configure triggering on tag push
-- [ ] Task 5: Create project documentation (AC: 5)
-  - [ ] Write README.md with project description
-  - [ ] Add development setup instructions
-  - [ ] Document build and test commands
-  - [ ] Include installation instructions
-- [ ] Task 6: Configure pre-commit hooks (AC: 6)
-  - [ ] Set up rustfmt pre-commit hook
-  - [ ] Set up clippy pre-commit hook
-  - [ ] Document hook setup in README
-- [ ] Task 7: Add MIT License (AC: 7)
-  - [ ] Create LICENSE file with MIT license text
-  - [ ] Add license field to Cargo.toml
-- [ ] Task 8: Create Makefile for development (AC: 8)
-  - [ ] Add test target
-  - [ ] Add build target (debug and release)
-  - [ ] Add lint target (rustfmt + clippy)
-  - [ ] Add clean target
-
-## Dev Notes
-
-### Previous Story Insights
-
-No previous story exists - this is the first story in the project.
-
-### Technical Architecture Context
-
-**Project Structure Requirements** [Source: architecture.md#source-tree]:
-
-- Follow the defined monorepo structure with clear separation of concerns
-- Implement clean architecture layers: CLI, Application, Domain, Infrastructure
-- Use the exact directory structure specified in the architecture document
-
-**Technology Stack Requirements** [Source: architecture.md#tech-stack]:
-
-- **Language**: Rust 1.78.0 (2021 edition)
-- **CLI Framework**: clap v4.5.4 for command-line parsing
-- **Database**: sqlx v0.7.4 for SQLite operations
-- **Error Handling**: anyhow v1.0.82 for application errors, thiserror v1.0.58 for custom types
-- **Configuration**: toml v0.8.12 for config file parsing
-- **Terminal Output**: termcolor v1.4.1 for colored output
-- **Testing**: criterion v0.5.1 for benchmarking
-- **Logging**: env_logger v0.11.3 for debug logging
-- **Date Parsing**: chrono v0.4.38, chrono-english v0.1.7
-- **Serialization**: serde v1.0.197 for JSON/CSV export
-
-**Performance Requirements** [Source: architecture.md#high-level-architecture]:
-
-- Sub-100ms command execution requirement
-- Cold start application startup < 50ms
-- Memory usage must not exceed 10MB during normal operation
-- Single binary distribution with no runtime dependencies
-- Synchronous execution model (no async runtime overhead)
-- Static linking required for zero runtime dependencies
-
-**Build and CI Requirements** [Source: architecture.md#infrastructure-and-deployment]:
-
-- GitHub Actions for CI/CD pipeline
-- Matrix builds for Linux and macOS platforms
-- Automated binary releases on tag push
-- Integration with cargo, rustfmt, and clippy
-- Security audit using cargo audit in CI pipeline
-- Performance benchmarks with 5% regression threshold
-- LTO enabled for release builds
-- Binary size optimization for releases
-
-### File Locations
-
-Based on the architecture document, the complete project structure should be:
-
-```
-termtodo/
-├── Cargo.toml                 # Project manifest with dependencies
-├── Cargo.lock                # Locked dependency versions
-├── build.rs                   # Build script for embedding resources
-├── .github/
-│   └── workflows/
-│       ├── ci.yml            # Test, lint, build on all platforms
-│       └── release.yml       # Build and publish binaries on tag
-├── src/
-│   ├── main.rs              # Entry point, CLI setup
-│   ├── cli/
-│   │   ├── mod.rs           # CLI module exports
-│   │   ├── parser.rs        # Clap command definitions
-│   │   └── commands/        # Command handlers
-│   ├── app/
-│   │   ├── mod.rs           # Application layer exports
-│   │   ├── service.rs       # Main application service
-│   │   └── errors.rs        # Application error types
-│   ├── domain/
-│   │   ├── mod.rs           # Domain model exports
-│   │   ├── task.rs          # Task entity
-│   │   └── types.rs         # Enums (Status, Priority)
-│   ├── infra/
-│   │   ├── mod.rs           # Infrastructure exports
-│   │   ├── db/             # Database module
-│   │   ├── repos/          # Repository implementations
-│   │   └── config/         # Config file handling
-│   └── utils/
-│       ├── mod.rs           # Utility exports
-│       ├── dates.rs         # Date parsing helpers
-│       └── result.rs        # Result extensions
-├── tests/
-│   ├── integration/         # Integration tests
-│   └── fixtures/            # Test data files
-├── benches/
-│   └── performance.rs       # Criterion benchmarks
-├── migrations/              # SQL migration files
-├── LICENSE                  # MIT license file
-├── Makefile                 # Development commands
-└── README.md               # Project documentation
-```
-
-### Testing Requirements
-
-**Testing Standards** [Source: architecture.md#test-strategy-and-standards]:
-
-- Use Rust built-in testing framework
-- Target 80% overall coverage, 90% for business logic
-- Unit tests in `#[cfg(test)]` modules within source files
-- Integration tests in `tests/integration/` directory
-- Performance tests using criterion benchmarks
-- Pre-commit hooks for formatting and linting validation
-
-### Technical Constraints
-
-**Coding Standards** [Source: architecture.md#coding-standards]:
-
-- Rust 1.78.0 with 2021 edition
-- rustfmt with default configuration
-- clippy with pedantic lints enabled
-- No unwrap() in production code
-- All public functions must have doc comments
-- Parameterized SQL statements only
-
-**Error Handling** [Source: architecture.md#error-handling-strategy]:
-
-- Result<T, Error> for all fallible operations
-- anyhow::Error for applications, custom types for libraries
-- Error propagation using ? operator with context
-
-### Database Configuration Requirements
-
-**SQLite PRAGMA Settings** [Source: architecture.md#database-requirements]:
-
-- foreign_keys=ON for referential integrity
-- journal_mode=WAL for performance
-- synchronous=NORMAL for balanced safety/performance
-- Connection pooling and prepared statement caching
-- Schema migration system with version tracking
-- Optimized indexes for common query patterns
-
-### Clean Architecture Layer Requirements
-
-**Layer Separation** [Source: architecture.md#clean-architecture]:
-
-- **CLI Layer**: Command parsing and output formatting only
-- **Application Layer**: Business logic orchestration
-- **Domain Layer**: Core entities and business rules
-- **Infrastructure Layer**: Database, config, external concerns
-- Repository pattern for data access abstraction
-- Command pattern for CLI subcommand handlers
-
-### Testing
-
-**Testing Standards** [Source: architecture.md#test-strategy-and-standards]:
-
-**Framework**: Rust built-in testing framework
-**Coverage Goals**:
-
-- 80% overall coverage minimum
-- 90% for business logic coverage minimum
-- Test pyramid: 70% unit, 25% integration, 5% e2e
-
-**Test Organization**:
-
-- Unit tests in `#[cfg(test)]` modules within source files
-- Integration tests in `tests/integration/` directory
-- End-to-end tests using assert_cmd for CLI testing
-- Performance tests using criterion benchmarks
-
-**Testing Infrastructure**:
-
-- Use tempfile crate for isolated file system testing
-- In-memory SQLite for database integration tests
-- Criterion benchmarks for performance regression testing
-- assert_cmd for CLI end-to-end testing
-
-**CI Requirements**:
-
-- Run tests on every push and pull request
-- Include rustfmt and clippy checks in CI pipeline
-- Performance benchmarks with 5% regression threshold
-- Security audit using cargo audit
-- Cross-platform testing (Linux and macOS)
-
-## Change Log
-
-| Date       | Version | Description                                                                                                          | Author                |
-| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------- | --------------------- |
-| 2025-07-07 | 1.0     | Initial story creation                                                                                               | Bob (Scrum Master)    |
-| 2025-07-07 | 1.1     | Fixed validation issues: complete dependency list, template structure, performance requirements, source tree details | Sarah (Product Owner) |
-
-## Dev Agent Record
-
-_This section will be populated by the development agent during implementation_
-
-### Agent Model Used
-
-_To be filled by dev agent_
-
-### Debug Log References
-
-_To be filled by dev agent_
-
-### Completion Notes List
-
-_To be filled by dev agent_
-
-### File List
-
-_To be filled by dev agent_
-
-## QA Results
-
-_Results from QA Agent review will be populated here_