fix: installer for github copilot asks follow up questions right away now so it does not seem to hang, and some minor doc improvements

docs/GUIDING-PRINCIPLES.md

@@ -0,0 +1,91 @@
+# BMad Method Guiding Principles
+
+The BMad Method is a natural language framework for AI-assisted software development. These principles ensure contributions maintain the method's effectiveness.
+
+## Core Principles
+
+### 1. Dev Agents Must Be Lean
+
+- **Minimize dev agent dependencies**: Development agents that work in IDEs must have minimal context overhead
+- **Save context for code**: Every line counts - dev agents should focus on coding, not documentation
+- **Web agents can be larger**: Planning agents (PRD Writer, Architect) used in web UI can have more complex tasks and dependencies
+- **Small files, loaded on demand**: Multiple small, focused files are better than large files with many branches
+
+### 2. Natural Language First
+
+- **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 are defined as YAML files with structured sections that include metadata, workflow configuration, and detailed instructions for content generation
+
+### 3. Agent and Task Design
+
+- **Agents define roles**: Each agent is a persona with specific expertise (e.g., Frontend Developer, API Developer)
+- **Tasks are procedures**: Step-by-step instructions an agent follows to complete work
+- **Templates are outputs**: Structured documents with embedded instructions for generation
+- **Dependencies matter**: Explicitly declare only what's needed
+
+## Practical Guidelines
+
+### When to Add to Core
+
+- Universal software development needs only
+- Doesn't bloat dev agent contexts
+- Follows existing agent/task/template patterns
+
+### When to Create Expansion Packs
+
+- Domain-specific needs beyond software development
+- Non-technical domains (business, wellness, education, creative)
+- Specialized technical domains (games, infrastructure, mobile)
+- Heavy documentation or knowledge bases
+- Anything that would bloat core agents
+
+See [Expansion Packs Guide](../docs/expansion-packs.md) for detailed examples and ideas.
+
+### Agent Design Rules
+
+1. **Web/Planning Agents**: Can have richer context, multiple tasks, extensive templates
+2. **Dev Agents**: Minimal dependencies, focused on code generation, lean task sets
+3. **All Agents**: Clear persona, specific expertise, well-defined capabilities
+
+### Task Writing Rules
+
+1. Write clear step-by-step procedures
+2. Use markdown formatting for readability
+3. Keep dev agent tasks focused and concise
+4. Planning tasks can be more elaborate
+5. **Prefer multiple small tasks over one large branching task**
+   - Instead of one task with many conditional paths
+   - Create multiple focused tasks the agent can choose from
+   - 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 YAML template with structured sections
+   - This maintains consistency and reduces duplication
+
+### Template Rules
+
+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
+
+- The power is in natural language orchestration, not code
+- Dev agents code, planning agents plan
+- Keep dev agents lean for maximum coding efficiency
+- Expansion packs handle specialized domains

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