bmad-method 5.1.3 → 6.0.0-alpha.1

package/src/modules/bmb/workflows/redoc/README.md

@@ -0,0 +1,87 @@
+# ReDoc - Reverse-Tree Documentation Engine
+
+**Type:** Autonomous Action Workflow
+**Module:** BMad Builder (bmb)
+
+## Purpose
+
+ReDoc is an intelligent documentation maintenance system for BMAD modules, workflows, and agents. It uses a reverse-tree approach (leaf folders first, then parent folders) to systematically generate and update README.md files with technical writer quality output.
+
+The workflow understands BMAD conventions deeply and focuses documentation on distinctive features rather than explaining standard patterns, resulting in succinct, precise technical documentation.
+
+## Key Features
+
+- **Reverse-Tree Processing**: Documents from deepest folders up to module root, allowing child documentation to inform parent summaries
+- **Convention-Aware**: Loads BMAD architecture patterns and only documents unique/distinctive aspects
+- **Scalability**: Automatically creates catalog documents (WORKFLOWS-CATALOG.md, AGENTS-CATALOG.md) for massive folders (>10 items)
+- **Diff-Aware**: Tracks `last-redoc-date` frontmatter to enable change detection since last run
+- **Autonomous**: Runs without user checkpoints unless clarification is genuinely required
+- **Comprehensive**: Reads ALL files completely before generating documentation (no partial reads)
+
+## Usage
+
+Invoke with a target path:
+
+```
+workflow redoc
+```
+
+When prompted, provide one of:
+
+- **Module path**: `bmad/bmm` (documents entire module: root, workflows, agents)
+- **Workflows folder**: `bmad/bmm/workflows` (documents all workflows)
+- **Agents folder**: `bmad/bmm/agents` (documents all agents)
+- **Single workflow**: `bmad/bmm/workflows/product-brief` (documents one workflow)
+- **Single agent**: `bmad/bmm/agents/prd-agent.md` (documents one agent)
+
+## Inputs
+
+### Required
+
+- **target_path**: Path to module, folder, or specific component to document
+
+### Knowledge Base (Auto-loaded)
+
+- agent-architecture.md
+- agent-command-patterns.md
+- agent-types.md
+- module-structure.md
+- workflow-creation-guide.md
+
+## Outputs
+
+### Created/Updated Files
+
+- **README.md**: At each documented level (workflow folders, agent folders, module root)
+- **Catalog files**: WORKFLOWS-CATALOG.md, AGENTS-CATALOG.md (for massive folders)
+- **Frontmatter**: All READMEs include `last-redoc-date: <timestamp>`
+
+### Summary Report
+
+- Documentation coverage statistics
+- List of files created/updated
+- Any items requiring manual review
+
+## Workflow Steps
+
+1. **Initialize**: Load BMAD conventions and validate target
+2. **Analyze Structure**: Build reverse-tree execution plan
+3. **Process Leaves**: Document individual workflows/agents (deepest first)
+4. **Process Folders**: Document workflow/agent collections with categorization
+5. **Process Root**: Document module overview with links and highlights
+6. **Validate**: Verify completeness and generate report
+7. **Diff Analysis** (optional): Show changes since last redoc
+8. **Complete**: Report success and suggest next steps
+
+## Technical Details
+
+- **Execution**: Autonomous with minimal user interaction
+- **Quality**: Technical writer standards - succinct, precise, professional
+- **Context-Aware**: Uses BMAD convention knowledge to highlight only distinctive features
+- **Scalable**: Handles folders of any size with intelligent catalog creation
+
+## Next Steps After Running
+
+1. Review generated documentation for accuracy
+2. If documenting a subfolder, run redoc on parent module to update references
+3. Commit documentation updates with meaningful message

package/src/modules/bmb/workflows/redoc/checklist.md

@@ -0,0 +1,99 @@
+# ReDoc Workflow Validation Checklist
+
+## Initialization and Setup
+
+- [ ] All BMAD convention documents loaded and understood
+- [ ] Target path validated and exists
+- [ ] Target type correctly identified (module/workflow/agent/folder)
+- [ ] Documentation execution plan created with reverse-tree order
+
+## File Analysis
+
+- [ ] All files in target scope read completely (no offset/limit usage)
+- [ ] Existing README.md files detected and last-redoc-date parsed
+- [ ] Massive folders (>10 items) identified for catalog document creation
+- [ ] Documentation depth levels calculated correctly
+
+## Leaf-Level Documentation (Workflows)
+
+- [ ] Each workflow's ALL files read: workflow.yaml, instructions.md, template.md, checklist.md
+- [ ] README.md includes frontmatter with current last-redoc-date
+- [ ] Description is 2-4 paragraphs of technical writer quality
+- [ ] Focuses on DISTINCTIVE features, not BMAD boilerplate conventions
+- [ ] Includes "Usage" section with invocation command
+- [ ] Includes "Inputs" and "Outputs" sections where applicable
+- [ ] Succinct and precise language used throughout
+
+## Leaf-Level Documentation (Agents)
+
+- [ ] Each agent file read completely including XML structure, commands, persona
+- [ ] README.md includes frontmatter with current last-redoc-date
+- [ ] Description is 1-3 paragraphs of technical writer quality
+- [ ] Lists all available commands clearly
+- [ ] Explains when to use this agent
+- [ ] Highlights unique capabilities vs standard agent patterns
+
+## Mid-Level Documentation (Folders)
+
+- [ ] All child README.md files read before generating folder README
+- [ ] Workflows categorized logically if massive folder (>10 items)
+- [ ] Agents categorized by type if massive folder (>10 items)
+- [ ] Catalog documents (WORKFLOWS-CATALOG.md, AGENTS-CATALOG.md) created for massive folders
+- [ ] Catalog documents include frontmatter with last-redoc-date
+- [ ] Folder README.md references catalog if one exists
+- [ ] Folder README.md is succinct (1-2 paragraphs + listings/links)
+- [ ] Notable/commonly-used items highlighted
+
+## Root Module Documentation
+
+- [ ] Module config.yaml read and understood
+- [ ] Workflows and agents folder READMEs read before creating root README
+- [ ] Root README includes frontmatter with current last-redoc-date
+- [ ] Module purpose clearly stated in 2-3 sentences
+- [ ] Links to /workflows/README.md and /agents/README.md included
+- [ ] 2-3 key workflows mentioned with context
+- [ ] 2-3 key agents mentioned with context
+- [ ] Configuration section highlights UNIQUE settings only
+- [ ] Usage section explains invocation patterns
+- [ ] BMAD convention knowledge applied (describes only distinctive aspects)
+
+## Quality Standards
+
+- [ ] All documentation uses proper BMAD terminology
+- [ ] Technical writer quality: clear, concise, professional
+- [ ] No placeholder text or generic descriptions remain
+- [ ] All links are valid and correctly formatted
+- [ ] Frontmatter syntax is correct and dates are current
+- [ ] No redundant explanation of standard BMAD patterns
+
+## Validation and Reporting
+
+- [ ] All planned documentation items created/updated
+- [ ] Frontmatter dates verified as current across all files
+- [ ] File paths and internal links validated
+- [ ] Summary report generated with counts and coverage
+- [ ] Files skipped (if any) documented with reasons
+
+## Git Diff Analysis (Optional Step)
+
+- [ ] last-redoc-date timestamps extracted correctly
+- [ ] Git log queried for changes since last redoc
+- [ ] Modified files identified and reported
+- [ ] Findings presented clearly to user
+
+## Final Validation
+
+- [ ] Documentation Coverage
+  - All README.md files in scope created/updated
+  - Catalog documents created where needed
+  - No documentation gaps identified
+
+- [ ] Execution Quality
+  - Reverse-tree order followed (leaf → root)
+  - Autonomous execution (minimal user prompts)
+  - Only clarification questions asked when truly necessary
+
+- [ ] Output Quality
+  - Technical precision maintained throughout
+  - Succinct descriptions (no verbose explanations)
+  - Professional documentation standards met

package/src/modules/bmb/workflows/redoc/instructions.md

@@ -0,0 +1,265 @@
+# ReDoc Workflow Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/src/modules/bmb/workflows/redoc/workflow.yaml</critical>
+<critical>Communicate in {communication_language} throughout the documentation process</critical>
+<critical>This is an AUTONOMOUS workflow - minimize user interaction unless clarification is absolutely required</critical>
+<critical>IMPORTANT: Process ONE document at a time to avoid token limits. Each README should be created individually, not batched.</critical>
+<critical>When using Task tool with sub-agents: Only request ONE workflow or agent documentation per invocation to prevent token overflow.</critical>
+
+<workflow>
+
+<step n="1" goal="Load BMAD conventions and initialize">
+<action>Load ALL BMAD convention documents from {bmad_conventions}:
+- agent_architecture.md - Understand agent XML structure and patterns
+- agent_command_patterns.md - Command syntax and activation patterns
+- agent_types.md - Standard agent categories and purposes
+- module_structure.md - Module organization and folder conventions
+- workflow_guide.md - Workflow structure and best practices
+</action>
+
+<action>Internalize these conventions so you can:
+
+- Recognize standard patterns vs unique implementations
+- Describe only what's distinctive about each component
+- Use proper terminology consistently
+- Write with technical precision
+  </action>
+
+<action>Get target path from user:
+
+- Ask: "What do you want to document? (module path, workflow path, agent path, or folder path)"
+- Store as {{target_path}}
+  </action>
+
+<action>Validate target path exists and determine target type:
+
+- Module root (contains config.yaml, /workflows, /agents folders)
+- Workflows folder (contains multiple workflow folders)
+- Agents folder (contains multiple agent .md files)
+- Single workflow folder (contains workflow.yaml)
+- Single agent file (.md)
+  </action>
+
+<action>Store target type as {{target_type}} for conditional processing</action>
+</step>
+
+<step n="2" goal="Analyze directory structure and existing documentation">
+<action>Build complete tree structure of {{target_path}} using Glob and file system tools</action>
+
+<action>Identify all documentation points:
+
+- List all folders requiring README.md files
+- Detect existing README.md files
+- Parse frontmatter from existing READMEs to extract last-redoc-date
+- Calculate documentation depth (how many levels deep)
+  </action>
+
+<action>Create documentation map with execution order (deepest → shallowest):
+
+- Level 0 (deepest): Individual workflow folders, individual agent files
+- Level 1: /workflows folder, /agents folder
+- Level 2 (root): Module root README.md
+  </action>
+
+<action>Detect "massive folders" requiring child catalog documents:
+
+- Threshold: >10 items or complex categorization needed
+- Mark folders for catalog document creation (e.g., WORKFLOWS-CATALOG.md, AGENTS-CATALOG.md)
+  </action>
+
+<critical>Store execution order as {{doc_execution_plan}} - this ensures reverse-tree processing</critical>
+</step>
+
+<step n="3" goal="Process leaf-level documentation" repeat="for-each-leaf-item">
+<critical>TOKEN LIMIT WARNING: Process ONE item at a time to prevent token overflow issues.</critical>
+<critical>If using Task tool with sub-agents: NEVER batch multiple workflows/agents in a single invocation.</critical>
+<critical>Each README creation should be a separate operation with its own file save.</critical>
+<critical>Sequential processing is MANDATORY - do not attempt parallel documentation generation.</critical>
+<action>For each individual workflow folder in execution plan (PROCESS ONE AT A TIME):
+1. Read ALL files completely:
+   - workflow.yaml (metadata, purpose, configuration)
+   - instructions.md (step structure, goals)
+   - template.md (output structure) if exists
+   - checklist.md (validation criteria) if exists
+   - Any supporting data files
+
+2. Synthesize understanding:
+   - Core purpose and use case
+   - Input requirements
+   - Output produced
+   - Unique characteristics (vs standard BMAD workflow patterns)
+   - Key steps or special features
+
+3. Generate/update README.md:
+   - Add frontmatter: `---\nlast-redoc-date: {{date}}\n---\n`
+   - Write 2-4 paragraph technical description
+   - Include "Usage" section with invocation command
+   - Include "Inputs" section if applicable
+   - Include "Outputs" section
+   - Be succinct and precise - technical writer quality
+   - Focus on DISTINCTIVE features, not boilerplate
+
+4. Save README.md to workflow folder
+
+<critical>If multiple workflows need documentation, process them SEQUENTIALLY not in parallel. Each workflow gets its own complete processing cycle.</critical>
+</action>
+
+<action>For each individual agent file in execution plan (PROCESS ONE AT A TIME):
+
+1. Read agent definition file completely:
+   - XML structure and metadata
+   - Commands and their purposes
+   - Activation patterns
+   - Persona and communication style
+   - Critical actions and workflows invoked
+
+2. Synthesize understanding:
+   - Agent purpose and role
+   - Available commands
+   - When to use this agent
+   - Unique capabilities
+
+3. Generate/update README.md (or agent-name-README.md if in shared folder):
+   - Add frontmatter: `---\nlast-redoc-date: {{date}}\n---\n`
+   - Write 1-3 paragraph technical description
+   - Include "Commands" section listing available commands
+   - Include "Usage" section
+   - Focus on distinctive features
+
+4. Save README.md
+   </action>
+
+<action if="clarification needed about purpose or unique features">Ask user briefly, then continue</action>
+</step>
+
+<step n="4" goal="Process mid-level folder documentation" if="target_type requires folder docs">
+<action>For /workflows folder:
+1. Read ALL workflow README.md files created in Step 3
+2. Categorize workflows by purpose/type if folder is massive (>10 workflows):
+   - Document generation workflows
+   - Action workflows
+   - Meta-workflows
+   - Interactive workflows
+
+3. If massive folder detected:
+   - Create WORKFLOWS-CATALOG.md with categorized listings
+   - Each entry: workflow name, 1-sentence description, link to folder
+   - Add frontmatter with last-redoc-date
+
+4. Generate/update /workflows/README.md:
+   - Add frontmatter: `---\nlast-redoc-date: {{date}}\n---\n`
+   - High-level summary of workflow collection
+   - If catalog exists: reference it
+   - If not massive: list all workflows with brief descriptions and links
+   - Highlight notable or commonly-used workflows
+   - Keep succinct (1-2 paragraphs + list)
+
+5. Save README.md
+   </action>
+
+<action>For /agents folder:
+
+1. Read ALL agent README.md files
+2. Categorize agents by type if massive folder (>10 agents):
+   - Task agents
+   - Meta agents
+   - Specialized agents
+   - Utility agents
+
+3. If massive folder detected:
+   - Create AGENTS-CATALOG.md with categorized listings
+   - Each entry: agent name, 1-sentence description, link
+   - Add frontmatter with last-redoc-date
+
+4. Generate/update /agents/README.md:
+   - Add frontmatter: `---\nlast-redoc-date: {{date}}\n---\n`
+   - High-level summary of agent collection
+   - If catalog exists: reference it
+   - If not massive: list all agents with brief descriptions
+   - Highlight key agents and their purposes
+   - Keep succinct
+
+5. Save README.md
+   </action>
+   </step>
+
+<step n="5" goal="Process root module documentation" if="target_type is module root">
+<action>For module root README.md:
+1. Read module config.yaml for metadata and configuration
+2. Read /workflows/README.md and /agents/README.md created in Step 4
+3. Identify module's unique purpose within BMAD ecosystem
+
+4. Generate/update module README.md:
+   - Add frontmatter: `---\nlast-redoc-date: {{date}}\n---\n`
+
+   Structure:
+   - # Module Name
+   - **Purpose**: 2-3 sentence high-level module purpose
+   - **Overview**: 1-2 paragraphs describing what this module provides
+
+   - ## Workflows
+     - Link to /workflows/README.md with 1-sentence summary
+     - Mention count and highlight 2-3 key workflows
+
+   - ## Agents
+     - Link to /agents/README.md with 1-sentence summary
+     - Mention count and highlight 2-3 key agents
+
+   - ## Configuration
+     - Notable config.yaml settings if unique/important
+     - Reference paths and conventions
+
+   - ## Usage
+     - How to invoke workflows or agents from this module
+     - Prerequisites if any
+
+   Focus on UNIQUE aspects using BMAD convention knowledge:
+   - Don't explain standard BMAD patterns
+   - Highlight what makes THIS module distinctive
+   - Use proper BMAD terminology
+
+5. Save README.md to module root
+   </action>
+   </step>
+
+<step n="6" goal="Validation and summary report">
+<action>Verify all planned documentation was created/updated:
+- Check each item in {{doc_execution_plan}}
+- Confirm frontmatter dates are current
+- Validate file paths and links
+</action>
+
+<action>Generate summary report showing:
+
+- Target documented: {{target_path}}
+- Target type: {{target_type}}
+- Documentation files created/updated (count and list)
+- Any catalog files created
+- Files skipped or requiring manual review (if any)
+- Coverage: X% of items documented
+- Processing notes: Confirm sequential processing was used to avoid token limits
+  </action>
+
+<action>Display summary to user</action>
+</step>
+
+<step n="7" goal="Optional git diff analysis" optional="true">
+<ask>Would you like to see what changed since the last redoc run? [y/n]</ask>
+
+<action if="user_response == 'y'">
+For each README with last-redoc-date frontmatter:
+1. Extract last-redoc-date timestamp
+2. Use git log to find files modified since that date in the documented folder
+3. Highlight files that changed but may need documentation updates
+4. Report findings to user
+</action>
+</step>
+
+<step n="8" goal="Completion">
+<action>Confirm to {user_name} in {communication_language} that autonomous workflow execution is complete</action>
+<action>Provide path to all updated documentation</action>
+<action>Suggest next steps if needed</action>
+</step>
+
+</workflow>

package/src/modules/bmb/workflows/redoc/workflow.yaml

@@ -0,0 +1,34 @@
+# ReDoc - Reverse-Tree Documentation Engine
+name: "redoc"
+description: "Autonomous documentation system that maintains module, workflow, and agent documentation using a reverse-tree approach (leaf folders first, then parents). Understands BMAD conventions and produces technical writer quality output."
+author: "BMad"
+
+# Critical variables
+config_source: "{project-root}/bmad/bmb/config.yaml"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+
+# Required knowledge base - BMAD conventions and patterns
+bmad_conventions:
+  agent_architecture: "{project-root}/src/modules/bmb/workflows/create-agent/agent-architecture.md"
+  agent_command_patterns: "{project-root}/src/modules/bmb/workflows/create-agent/agent-command-patterns.md"
+  agent_types: "{project-root}/src/modules/bmb/workflows/create-agent/agent-types.md"
+  module_structure: "{project-root}/src/modules/bmb/workflows/create-module/module-structure.md"
+  workflow_guide: "{project-root}/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md"
+
+# Runtime inputs
+target_path: "" # User specifies: module path, workflow path, agent path, or folder path
+
+# Module path and component files
+installed_path: "{project-root}/src/modules/bmb/workflows/redoc"
+template: false # Action workflow - updates files in place
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Configuration
+autonomous: true # Runs without user checkpoints unless clarification needed
+
+standalone: true
+
+# Web bundle configuration
+web_bundle: false # BMB workflows run locally in BMAD-METHOD project

package/src/modules/bmm/README.md

@@ -0,0 +1,141 @@
+# BMM - BMad Method Module
+
+The BMM (BMad Method Module) is the core orchestration system for the BMad Method, providing comprehensive software development lifecycle management through specialized agents, workflows, teams, and tasks.
+
+## 📚 Essential Reading
+
+**Before using BMM, you MUST read the [BMM v6 Workflows Guide](./workflows/README.md).** This document explains the revolutionary v6a workflow system and how all components work together.
+
+## Module Structure
+
+### 🤖 `/agents`
+
+Specialized AI agents for different development roles:
+
+- **PM** (Product Manager) - Product planning and requirements
+- **Analyst** - Business analysis and research
+- **Architect** - Technical architecture and design
+- **SM** (Scrum Master) - Sprint and story management
+- **DEV** (Developer) - Code implementation
+- **TEA** (Test Architect) - Test Architect
+- **UX** - User experience design
+- And more specialized roles
+
+**Game Development Agents** (Optional):
+During installation, you can optionally include game development specialists:
+
+- **Game Designer** - Creative vision and game design documents (GDD)
+- **Game Developer** - Game-specific implementation
+- **Game Architect** - Game systems and technical infrastructure
+
+These agents come with specialized workflows (`brainstorm-game`, `game-brief`, `gdd`) and are only installed if you select "Include Game Planning Agents and Workflows" during BMM installation.
+
+### 📋 `/workflows`
+
+The heart of BMM - structured workflows for the four development phases:
+
+1. **Analysis Phase** (Optional)
+   - `brainstorm-project` - Project ideation
+   - `research` - Market/technical research
+   - `product-brief` - Product strategy
+
+2. **Planning Phase** (Required)
+   - `prd` - Scale-adaptive project planning
+   - Routes to appropriate documentation based on project complexity
+
+3. **Solutioning Phase** (Level 3-4 projects)
+   - `3-solutioning` - Architecture design
+   - `tech-spec` - Epic-specific technical specifications
+
+4. **Implementation Phase** (Iterative)
+   - `create-story` - Story drafting (SM agent)
+   - `story-ready` - Approve story for development (SM agent)
+   - `story-context` - Expertise injection (SM agent)
+   - `dev-story` - Implementation (DEV agent)
+   - `story-done` - Mark story done (DEV agent)
+   - `code-review` - Quality validation (DEV/SR agent)
+   - `correct-course` - Issue resolution
+   - `retrospective` - Continuous improvement
+
+### 👥 `/teams`
+
+Pre-configured agent teams for different project types and phases. Teams coordinate multiple agents working together on complex tasks.
+
+### 📝 `/tasks`
+
+Reusable task definitions that agents execute within workflows. These are the atomic units of work that compose into larger workflows.
+
+### 🔧 `/sub-modules`
+
+Extension modules that add specialized capabilities to BMM.
+
+### 🏗️ `/testarch`
+
+Test architecture and quality assurance components. The **[Test Architect (TEA) Guide](./testarch/README.md)** provides comprehensive testing strategy across 9 workflows: framework setup, CI/CD, test design, ATDD, automation, traceability, NFR assessment, quality gates, and test review.
+
+## Quick Start
+
+```bash
+# Load the PM agent - either via slash command or drag and drop or @ the agent file.
+# Once loaded, the agent should greet you and offer a menu of options. You can enter:
+`*prd`
+```
+
+## Key Concepts
+
+### Scale Levels
+
+BMM automatically adapts to project complexity:
+
+- **Level 0**: Single atomic change
+- **Level 1**: 1-10 stories, minimal documentation
+- **Level 2**: 5-15 stories, focused PRD
+- **Level 3**: 12-40 stories, full architecture
+- **Level 4**: 40+ stories, enterprise scale
+
+### Just-In-Time Design
+
+Technical specifications are created one epic at a time during implementation, not all upfront, allowing for learning and adaptation.
+
+### Story State Machine
+
+Stories flow through a 4-state lifecycle tracked in the status file:
+
+```
+BACKLOG → TODO → IN PROGRESS → DONE
+```
+
+- **BACKLOG**: Ordered list of stories to be drafted (populated at phase transition)
+- **TODO**: Single story ready for SM to draft (or drafted, awaiting approval)
+- **IN PROGRESS**: Single story approved for DEV to implement
+- **DONE**: Completed stories with dates and points
+
+Agents never search for "next story" - they always read the exact story from the status file. Simple workflows (`story-ready`, `story-done`) advance the queue automatically.
+
+### Context Injection
+
+Story-specific technical guidance is generated dynamically, providing developers with exactly the expertise needed for each task.
+
+## Integration with BMad Core
+
+BMM integrates seamlessly with the BMad Core framework, leveraging:
+
+- The agent execution engine
+- Workflow orchestration
+- Task management
+- Team coordination
+
+## Related Documentation
+
+- [BMM Workflows Guide](./workflows/README.md) - **Start here!**
+- [Test Architect (TEA) Guide](./testarch/README.md) - Quality assurance and testing strategy
+
+## Best Practices
+
+1. **Always start with the workflows** - Let workflows guide your process
+2. **Respect the scale** - Don't over-document small projects
+3. **Trust the process** - The methodology has been carefully designed
+
+---
+
+For detailed information about the complete BMad Method workflow system, see the [BMM Workflows README](./workflows/README.md).

package/src/modules/bmm/_module-installer/assets/bmm-kb.md

@@ -0,0 +1 @@
+# BMad Method Master Knowledge Base Index

package/src/modules/bmm/_module-installer/assets/technical-decisions.md

@@ -0,0 +1,30 @@
+# Technical Decisions Log
+
+_Auto-updated during discovery and planning sessions - you can also add information here yourself_
+
+## Purpose
+
+This document captures technical decisions, preferences, and constraints discovered during project discussions. It serves as input for architecture.md and solution design documents.
+
+## Confirmed Decisions
+
+<!-- Technical choices explicitly confirmed by the team/user -->
+
+## Preferences
+
+<!-- Non-binding preferences mentioned during discussions -->
+
+## Constraints
+
+<!-- Hard requirements from infrastructure, compliance, or integration needs -->
+
+## To Investigate
+
+<!-- Technical questions that need research or architect input -->
+
+## Notes
+
+- This file is automatically updated when technical information is mentioned
+- Decisions here are inputs, not final architecture
+- Final technical decisions belong in architecture.md
+- Implementation details belong in solutions/\*.md and story context or dev notes.