From 5babf43b90e6684505ac257a576f9910c78274b4 Mon Sep 17 00:00:00 2001
From: Basit Mustafa <basit.mustafa@gmail.com>
Date: Thu, 24 Jul 2025 19:29:19 -0700
Subject: [PATCH] chore(integrations): claude integration docs/gh templates

---
 .github/ISSUE_TEMPLATE/agent_improvement.md | 211 ++++++++++++++++++++
 .github/ISSUE_TEMPLATE/bug_report.md        | 134 ++++++++++---
 .github/ISSUE_TEMPLATE/config.yml           |  14 ++
 .github/ISSUE_TEMPLATE/documentation.md     | 184 +++++++++++++++++
 .github/ISSUE_TEMPLATE/feature_request.md   | 186 +++++++++++++++--
 .github/ISSUE_TEMPLATE/question.md          | 108 ++++++++++
 .github/pull_request_template.md            | 123 ++++++++++++
 README.md                                   |   2 +
 8 files changed, 926 insertions(+), 36 deletions(-)
 create mode 100644 .github/ISSUE_TEMPLATE/agent_improvement.md
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/ISSUE_TEMPLATE/documentation.md
 create mode 100644 .github/ISSUE_TEMPLATE/question.md
 create mode 100644 .github/pull_request_template.md

diff --git a/.github/ISSUE_TEMPLATE/agent_improvement.md b/.github/ISSUE_TEMPLATE/agent_improvement.md
new file mode 100644
index 00000000..f35c0173
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/agent_improvement.md
@@ -0,0 +1,211 @@
+---
+name: 🎭 Agent Improvement
+about: Suggest improvements to specific BMAD Claude agents
+title: '[AGENT] [Agent Name] - '
+labels: ['agent-improvement', 'enhancement']
+assignees: ''
+---
+
+# 🎭 Agent Improvement
+
+## 📊 Target Agent
+<!-- Select the agent(s) this improvement targets -->
+- [ ] 📊 **Analyst (Mary)** - Market research, competitive analysis, project briefing
+- [ ] 🏗️ **Architect (Winston)** - System design, technical architecture
+- [ ] 👨‍💻 **Dev (James)** - Implementation, coding, technical development
+- [ ] 📋 **PM (John)** - Project management, planning, coordination
+- [ ] 🔍 **QA (Quinn)** - Quality assurance, testing, validation
+- [ ] 🎯 **Scrum Master (Bob)** - Agile process management, team facilitation
+- [ ] 🔄 **Cross-Agent** - Multi-agent workflows and collaboration
+
+## 🎯 Improvement Type
+<!-- Check the type of improvement -->
+- [ ] 🧠 **Persona Enhancement** - Improve agent character/personality
+- [ ] 📝 **Prompt Optimization** - Better system prompts and instructions  
+- [ ] 🛠️ **New Capabilities** - Add new commands or skills
+- [ ] 📚 **BMAD Integration** - Better methodology adherence
+- [ ] 🤝 **Collaboration** - Improve cross-agent workflows
+- [ ] 💾 **Memory/Context** - Better context management
+- [ ] 📊 **Output Quality** - Improve response quality
+- [ ] 🎨 **User Experience** - Better interaction patterns
+
+## 📋 Current Behavior
+<!-- Describe how the agent currently behaves -->
+**What does the agent do now?**
+
+### Current Strengths
+<!-- What works well currently? -->
+
+### Current Limitations
+<!-- What could be improved? -->
+
+### Example Current Response
+```
+<!-- Paste an example of current agent behavior -->
+```
+
+## ✨ Proposed Improvement
+<!-- Describe the specific improvement -->
+**What should the agent do differently?**
+
+### Detailed Description
+<!-- Explain the improvement in detail -->
+
+### Expected Benefits
+<!-- How would this make the agent better? -->
+
+### Example Improved Response
+```
+<!-- Show what the improved response would look like -->
+```
+
+## 🧪 Testing Scenario
+<!-- How would you test this improvement? -->
+
+### Test Prompt
+```
+<!-- Provide a specific prompt to test the improvement -->
+```
+
+### Success Criteria
+<!-- How would you know the improvement worked? -->
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+### Evaluation Method
+- [ ] Manual testing in Claude Code
+- [ ] Comparison with previous responses
+- [ ] User feedback collection
+- [ ] Automated scoring (if applicable)
+
+## 🎭 BMAD Methodology Alignment
+<!-- How does this align with BMAD principles? -->
+
+### BMAD Integration
+- [ ] Enhances existing BMAD workflow adherence
+- [ ] Adds new BMAD artifact usage
+- [ ] Improves BMAD template integration
+- [ ] Better cross-agent BMAD coordination
+- [ ] Maintains BMAD methodology integrity
+
+### Agent Role Consistency
+<!-- Does this maintain the agent's core BMAD role? -->
+- [ ] Stays true to agent's primary BMAD function
+- [ ] Enhances domain expertise appropriately
+- [ ] Maintains professional persona
+- [ ] Supports BMAD workflow patterns
+
+## 📈 Impact Assessment
+
+### User Experience Impact
+- [ ] 🟢 Significantly improves user experience
+- [ ] 🟡 Moderately improves user experience  
+- [ ] 🟠 Minor improvement
+- [ ] 🔴 Minimal impact
+
+### Agent Performance Impact
+- [ ] 🟢 Major improvement in agent capability
+- [ ] 🟡 Moderate improvement
+- [ ] 🟠 Small improvement
+- [ ] 🔴 Minimal improvement
+
+### Implementation Complexity
+- [ ] 🟢 Simple - Prompt/template changes only
+- [ ] 🟡 Medium - Some code changes required
+- [ ] 🟠 Complex - Significant changes needed
+- [ ] 🔴 Major - Architectural changes required
+
+## 🔧 Implementation Details
+
+### Prompt Changes Required
+<!-- What specific prompt modifications are needed? -->
+
+### New Dependencies
+<!-- Any new templates, tasks, or data files needed? -->
+- [ ] New task files in bmad-core/tasks/
+- [ ] New templates in bmad-core/templates/
+- [ ] New data files in bmad-core/data/
+- [ ] Agent template modifications
+- [ ] Build system changes
+
+### Tool/Command Changes
+- [ ] New BMAD commands needed
+- [ ] Existing command modifications
+- [ ] New tool permissions required
+- [ ] Memory/persistence changes
+
+## 📊 Comparison Analysis
+<!-- How does this compare to other agents or systems? -->
+
+### Similar Functionality
+<!-- Do other agents have similar capabilities? -->
+
+### Best Practices
+<!-- What best practices does this follow? -->
+
+### Differentiation
+<!-- How does this make the agent unique/better? -->
+
+## 🔗 Related Work
+<!-- Link to related issues, discussions, or examples -->
+- Related to #(issue number)
+- Inspired by #(issue number)
+- Builds on #(issue number)
+
+### External References
+<!-- Relevant external resources -->
+- BMAD methodology documentation
+- Claude Code best practices
+- Agent prompt engineering guides
+
+## 📋 Additional Context
+
+### User Feedback
+<!-- Any user feedback that inspired this improvement? -->
+
+### Research/Evidence
+<!-- Any research supporting this improvement? -->
+
+### Examples from Other Domains
+<!-- Similar improvements in other AI systems? -->
+
+## 🤝 Implementation Plan
+<!-- How could this be implemented? -->
+
+### Phase 1: Planning
+- [ ] Finalize improvement specification
+- [ ] Design prompt modifications
+- [ ] Plan testing approach
+
+### Phase 2: Implementation  
+- [ ] Modify agent templates/prompts
+- [ ] Add any new dependencies
+- [ ] Update build system if needed
+
+### Phase 3: Testing
+- [ ] Test with sample scenarios
+- [ ] Validate BMAD integration
+- [ ] Collect feedback
+
+### Phase 4: Refinement
+- [ ] Iterate based on testing
+- [ ] Document changes
+- [ ] Update examples
+
+## 🤝 Contribution
+<!-- How can you help with this improvement? -->
+- [ ] I can implement the prompt changes
+- [ ] I can help with testing and validation
+- [ ] I can provide additional use cases
+- [ ] I can help with documentation
+- [ ] I need guidance but want to contribute
+
+---
+
+**Please ensure you've:**
+- [ ] Clearly identified the target agent(s)
+- [ ] Provided specific examples of current vs. improved behavior
+- [ ] Considered BMAD methodology alignment
+- [ ] Thought through implementation complexity
+- [ ] Included testing criteria
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 979457ee..dc2fe60c 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,32 +1,120 @@
 ---
-name: Bug report
-about: Create a report to help us improve
-title: ""
-labels: ""
-assignees: ""
+name: 🐛 Bug Report
+about: Report a bug in the BMAD Claude integration
+title: '[BUG] '
+labels: ['bug', 'needs-triage']
+assignees: ''
 ---
 
-**Describe the bug**
-A clear and concise description of what the bug is.
+# 🐛 Bug Report
 
-**Steps to Reproduce**
-What lead to the bug and can it be reliable recreated - if so with what steps.
+## 📋 Summary
+<!-- A clear and concise description of what the bug is -->
 
-**PR**
-If you have an idea to fix and would like to contribute, please indicate here you are working on a fix, or link to a proposed PR to fix the issue. Please review the contribution.md - contributions are always welcome!
+## 🎭 Affected Component
+<!-- Check all that apply -->
+- [ ] 📊 Analyst Agent (Mary)
+- [ ] 🏗️ Architect Agent (Winston)
+- [ ] 👨‍💻 Dev Agent (James)
+- [ ] 📋 PM Agent (John)
+- [ ] 🔍 QA Agent (Quinn)
+- [ ] 🎯 Scrum Master Agent (Bob)
+- [ ] 🛠️ Build System (`npm run build:claude`)
+- [ ] 🧪 Testing Framework
+- [ ] 📚 Documentation
+- [ ] 🔄 Cross-agent workflows
+- [ ] 💾 Memory/persistence
+- [ ] 📁 BMAD integration
 
-**Expected behavior**
-A clear and concise description of what you expected to happen.
+## 🔄 Steps to Reproduce
+<!-- Steps to reproduce the behavior -->
+1. Run `npm run build:claude`
+2. Start Claude Code with `claude`
+3. Execute command: '...'
+4. See error
 
-**Please be Specific if relevant**
-Model(s) Used:
-Agentic IDE Used:
-WebSite Used:
-Project Language:
-BMad Method version:
+## ✅ Expected Behavior
+<!-- A clear and concise description of what you expected to happen -->
 
-**Screenshots or Links**
-If applicable, add screenshots or links (if web sharable record) to help explain your problem.
+## ❌ Actual Behavior
+<!-- A clear and concise description of what actually happened -->
 
-**Additional context**
-Add any other context about the problem here. The more information you can provide, the easier it will be to suggest a fix or resolve
+## 📸 Screenshots/Output
+<!-- If applicable, add screenshots or command output to help explain your problem -->
+```
+<!-- Paste error output or logs here -->
+```
+
+## 🖥️ Environment
+<!-- Please complete the following information -->
+
+### System Information
+- **OS**: [e.g. macOS 14.6, Windows 11, Ubuntu 22.04]
+- **Node.js Version**: [e.g. v20.5.0]
+- **npm Version**: [e.g. 9.8.0]
+- **Claude Code Version**: [run `claude --version`]
+
+### BMAD Integration Version
+- **BMAD Method Version**: [check package.json version]
+- **Integration Build**: [when did you last run `npm run build:claude`?]
+- **Git Commit**: [run `git rev-parse HEAD`]
+
+### File State
+- [ ] `.claude/agents/` directory exists
+- [ ] All 6 agent files present (analyst, architect, dev, pm, qa, sm)
+- [ ] `npm run validate` passes in integration/claude
+
+## 🔧 Configuration
+<!-- Any relevant configuration details -->
+
+### Agent Configuration
+- **Custom modifications**: [Yes/No - describe any changes made]
+- **Tool permissions**: [any custom tool configurations]
+- **Memory settings**: [any custom memory configurations]
+
+### Build Configuration
+- **Custom templates**: [any modifications to agent.mustache]
+- **Custom BMAD data**: [any additions to bmad-core/data/]
+- **Environment variables**: [any relevant env vars]
+
+## 🧪 Attempted Solutions
+<!-- What have you tried to fix this issue? -->
+- [ ] Rebuilt agents with `npm run build:claude`
+- [ ] Cleared `.claude` directory and rebuilt
+- [ ] Restarted Claude Code
+- [ ] Checked for Claude Code updates
+- [ ] Verified Node.js version compatibility
+- [ ] Reviewed error logs
+
+## 📋 Additional Context
+<!-- Add any other context about the problem here -->
+
+### Error Frequency
+- [ ] Happens every time
+- [ ] Happens sometimes
+- [ ] Happened once
+- [ ] Only in specific scenarios
+
+### Impact Level
+- [ ] 🔥 Critical - Blocks all functionality
+- [ ] 🟠 High - Blocks major functionality  
+- [ ] 🟡 Medium - Workaround available
+- [ ] 🟢 Low - Minor inconvenience
+
+### Workarounds
+<!-- Any workarounds you've discovered -->
+
+## 🤝 Contribution
+<!-- Would you like to help fix this? -->
+- [ ] I'd like to work on fixing this issue
+- [ ] I can provide additional testing
+- [ ] I have ideas for the solution
+- [ ] I need guidance on how to help
+
+---
+
+**Please ensure you've:**
+- [ ] Searched existing issues to avoid duplicates
+- [ ] Provided all requested information
+- [ ] Used a descriptive title
+- [ ] Included steps to reproduce the issue
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 00000000..4ca7238c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,14 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 💬 Community Discussion
+    url: https://discord.gg/gk8jAdXWmj
+    about: Join our Discord community for general questions, ideas, and collaboration
+  - name: 📖 BMAD Method Documentation
+    url: https://github.com/bmadcode/bmad-method
+    about: Original BMAD-Method documentation and core methodology
+  - name: 🔧 Claude Code Documentation  
+    url: https://docs.anthropic.com/en/docs/claude-code/overview
+    about: Official Claude Code documentation and subagent guides
+  - name: 🚀 Claude Code Download
+    url: https://claude.ai/code
+    about: Download and install Claude Code for your platform
diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md
new file mode 100644
index 00000000..bb6bfac9
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/documentation.md
@@ -0,0 +1,184 @@
+---
+name: 📚 Documentation
+about: Request documentation improvements or report documentation issues
+title: '[DOCS] '
+labels: ['documentation', 'good first issue']
+assignees: ''
+---
+
+# 📚 Documentation Issue
+
+## 📋 Documentation Type
+<!-- What kind of documentation needs attention? -->
+- [ ] 📖 **User Guide** - How to use the BMAD Claude integration
+- [ ] 🔧 **Setup/Installation** - Getting started instructions
+- [ ] 🎭 **Agent Usage** - How to use specific agents effectively
+- [ ] 🧪 **Testing Guide** - How to test and validate the integration
+- [ ] 🛠️ **Developer Docs** - Technical implementation details
+- [ ] 📝 **API Reference** - Command and configuration reference
+- [ ] 🔄 **Workflow Examples** - Real-world usage examples
+- [ ] 🐛 **Troubleshooting** - Common issues and solutions
+- [ ] 📋 **Contributing** - How to contribute to the project
+- [ ] 🏗️ **Architecture** - Technical architecture documentation
+
+## 🎯 Issue Type
+<!-- What kind of documentation issue is this? -->
+- [ ] ❌ **Missing Documentation** - Something that should be documented isn't
+- [ ] 📝 **Unclear Documentation** - Existing docs are confusing or incomplete
+- [ ] 🔄 **Outdated Documentation** - Docs don't match current functionality
+- [ ] 🐛 **Incorrect Documentation** - Docs contain errors or wrong information
+- [ ] ✨ **Enhancement Request** - Suggestion for better documentation
+- [ ] 🔗 **Broken Links** - Links that don't work or go to wrong places
+- [ ] 📱 **Format/Structure** - Improve organization or presentation
+
+## 📍 Location
+<!-- Where is the documentation issue? -->
+**File(s) affected:**
+- [ ] README.md (main)
+- [ ] integration/claude/README.md
+- [ ] integration/claude/TESTING.md
+- [ ] integration/claude/complete-test-framework.md
+- [ ] integration/claude/manual-test-guide.md
+- [ ] docs/claude-integration.md
+- [ ] CONTRIBUTING.md
+- [ ] Other: _______________
+
+**Section/area:**
+<!-- Specific section, heading, or line numbers -->
+
+## 📋 Current State
+<!-- What exists now (if anything)? -->
+**Current documentation:**
+<!-- Quote or describe the current documentation -->
+
+**What's wrong/missing:**
+<!-- Specific description of the issue -->
+
+## ✨ Requested Improvement
+<!-- What should the documentation say/include? -->
+**Proposed content:**
+<!-- Describe what the documentation should include -->
+
+### Specific Additions/Changes
+<!-- Detailed description of needed changes -->
+
+### Target Audience
+<!-- Who is this documentation for? -->
+- [ ] New users trying to get started
+- [ ] Experienced users looking for advanced features
+- [ ] Developers wanting to contribute
+- [ ] Troubleshooting specific issues
+- [ ] Integration with existing BMAD workflows
+
+## 🎯 Use Case
+<!-- Why is this documentation needed? -->
+**User scenario:**
+<!-- Describe when someone would need this documentation -->
+
+**Current pain points:**
+<!-- What problems does the missing/poor documentation cause? -->
+
+## 📝 Content Suggestions
+<!-- Specific content ideas -->
+
+### Structure
+<!-- How should this be organized? -->
+
+### Examples
+<!-- What examples would be helpful? -->
+
+### Code Samples
+```bash
+# Example commands that should be documented
+```
+
+### Screenshots/Diagrams
+<!-- Would visual aids help? -->
+
+## 🔗 Related Documentation
+<!-- Link to related docs or issues -->
+- Similar documentation in: [link]
+- Related to issue: #(number)
+- Referenced in: [location]
+
+### External References
+<!-- Helpful external resources -->
+- Claude Code official docs
+- BMAD methodology guides
+- Similar project documentation
+
+## 📊 Priority/Impact
+<!-- Help us understand the importance -->
+
+### Impact Level
+- [ ] 🔥 **Critical** - Blocks users from basic functionality
+- [ ] 🟠 **High** - Significantly impacts user experience
+- [ ] 🟡 **Medium** - Moderately helpful improvement
+- [ ] 🟢 **Low** - Nice to have enhancement
+
+### User Frequency
+- [ ] Daily use - core functionality
+- [ ] Weekly use - common workflows  
+- [ ] Monthly use - occasional needs
+- [ ] Rare use - edge cases
+
+### Complexity
+- [ ] Simple addition/fix (minutes)
+- [ ] Medium effort (hours)
+- [ ] Complex documentation (days)
+- [ ] Major restructuring needed
+
+## 🎭 Agent-Specific Context
+<!-- If this relates to specific agents -->
+**Relevant agents:**
+- [ ] 📊 Analyst documentation
+- [ ] 🏗️ Architect documentation
+- [ ] 👨‍💻 Dev documentation
+- [ ] 📋 PM documentation
+- [ ] 🔍 QA documentation
+- [ ] 🎯 Scrum Master documentation
+- [ ] 🔄 Cross-agent workflows
+
+**BMAD methodology context:**
+<!-- How does this relate to BMAD workflows? -->
+
+## ✅ Acceptance Criteria
+<!-- How would you know this is done well? -->
+- [ ] Information is accurate and up-to-date
+- [ ] Examples work when followed step-by-step
+- [ ] Language is clear and accessible
+- [ ] Structure is logical and easy to navigate
+- [ ] Covers all necessary use cases
+- [ ] Includes troubleshooting for common issues
+
+## 🤝 Contribution
+<!-- Can you help with this documentation? -->
+- [ ] I can write the documentation
+- [ ] I can provide content/examples
+- [ ] I can review drafts
+- [ ] I can test the documented procedures
+- [ ] I need help but want to contribute
+
+### Draft Content
+<!-- If you have content ideas, include them here -->
+
+## 📋 Additional Context
+<!-- Anything else that would be helpful -->
+
+### User Feedback
+<!-- Any user feedback about documentation gaps? -->
+
+### Common Questions
+<!-- Questions that this documentation should answer -->
+
+### Success Stories
+<!-- Examples of when good documentation helped -->
+
+---
+
+**Please ensure you've:**
+- [ ] Checked existing documentation to avoid duplicates
+- [ ] Provided specific location information
+- [ ] Included concrete suggestions for improvement
+- [ ] Considered the target audience
+- [ ] Specified the impact and priority level
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index 9453b837..a43c682c 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,22 +1,182 @@
 ---
-name: Feature request
-about: Suggest an idea for this project
-title: ""
-labels: ""
-assignees: ""
+name: ✨ Feature Request
+about: Suggest an improvement or new feature for the BMAD Claude integration
+title: '[FEATURE] '
+labels: ['enhancement', 'needs-discussion']
+assignees: ''
 ---
 
-**Did you discuss the idea first in Discord Server (#general-dev)**
-Yes/No - Link to thread. If no, please after posting request also share the link in the channel so it can be easily discussed.
+# ✨ Feature Request
 
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+## 📋 Summary
+<!-- A clear and concise description of the feature you'd like to see -->
 
-**Describe the solution you'd like**
+## 🎯 Component Area
+<!-- Check all that apply -->
+- [ ] 📊 Analyst Agent capabilities
+- [ ] 🏗️ Architect Agent capabilities  
+- [ ] 👨‍💻 Dev Agent capabilities
+- [ ] 📋 PM Agent capabilities
+- [ ] 🔍 QA Agent capabilities
+- [ ] 🎯 Scrum Master Agent capabilities
+- [ ] 🔄 Cross-agent collaboration
+- [ ] 🛠️ Build system improvements
+- [ ] 🧪 Testing framework
+- [ ] 📚 Documentation
+- [ ] 💾 Memory/persistence
+- [ ] 🎭 Agent personas/prompts
+- [ ] 📁 BMAD methodology integration
+- [ ] 🔧 Developer experience
+- [ ] 🚀 Performance optimization
+
+## 💡 Problem Statement
+<!-- What problem does this feature solve? -->
+**Is your feature request related to a problem?**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when...
+
+## 🎯 Proposed Solution
+<!-- Describe the solution you'd like -->
+**Describe the solution you'd like:**
 A clear and concise description of what you want to happen.
 
-**Describe alternatives you've considered**
+### Detailed Description
+<!-- More detailed explanation of the feature -->
+
+### User Experience
+<!-- How would users interact with this feature? -->
+
+### Example Usage
+```bash
+# Example commands or usage
+```
+
+## 🤔 Alternatives Considered
+<!-- Describe alternatives you've considered -->
+**Describe alternatives you've considered:**
 A clear and concise description of any alternative solutions or features you've considered.
 
-**Additional context**
-Add any other context or screenshots about the feature request here.
+## 🎭 Agent Behavior Impact
+<!-- How would this affect agent behavior? -->
+
+### Prompt Changes
+- [ ] Requires agent prompt modifications
+- [ ] New commands or capabilities needed
+- [ ] Changes to existing command behavior
+- [ ] No prompt changes needed
+
+### BMAD Integration
+- [ ] Enhances BMAD methodology adherence
+- [ ] Adds new BMAD artifacts/templates
+- [ ] Improves cross-BMAD-agent workflows
+- [ ] Maintains existing BMAD compatibility
+
+### Expected Agent Improvements
+<!-- How would this make agents better? -->
+
+## 🔧 Technical Considerations
+
+### Implementation Complexity
+- [ ] 🟢 Simple - Template/config changes
+- [ ] 🟡 Medium - Some code changes required
+- [ ] 🟠 Complex - Significant code changes
+- [ ] 🔴 Major - Architectural changes needed
+
+### Dependencies
+<!-- What would this feature depend on? -->
+- [ ] Claude Code platform updates
+- [ ] New npm dependencies
+- [ ] External API integrations
+- [ ] BMAD core changes
+- [ ] No new dependencies
+
+### Compatibility
+- [ ] Backwards compatible
+- [ ] Requires migration
+- [ ] Breaking change
+- [ ] Optional feature
+
+## 📊 Use Cases
+<!-- Provide specific use cases -->
+
+### Primary Use Case
+<!-- The main scenario where this would be used -->
+
+### Secondary Use Cases
+<!-- Additional scenarios -->
+
+### User Stories
+```
+As a [user type], I want [feature] so that [benefit].
+```
+
+## 🎯 Success Criteria
+<!-- How would we know this feature is successful? -->
+- [ ] Measurable improvement in agent performance
+- [ ] Positive user feedback
+- [ ] Increased adoption of specific workflows
+- [ ] Better BMAD methodology integration
+- [ ] Enhanced developer experience
+
+## 📈 Priority/Impact
+<!-- Help us understand the importance -->
+
+### Impact Level
+- [ ] 🔥 High - Significantly improves core functionality
+- [ ] 🟠 Medium - Notable improvement to user experience
+- [ ] 🟡 Low - Nice to have enhancement
+
+### User Demand
+- [ ] Many users have requested this
+- [ ] Few users have requested this
+- [ ] I personally need this
+- [ ] Identified gap during development
+
+### Effort Estimate
+- [ ] Low effort (hours)
+- [ ] Medium effort (days)
+- [ ] High effort (weeks)
+- [ ] Unknown effort
+
+## 🔗 Related
+<!-- Link related issues, discussions, or resources -->
+- Related to #(issue number)
+- Depends on #(issue number)
+- Blocks #(issue number)
+
+### External References
+<!-- Any relevant external resources -->
+- Claude Code documentation: [link]
+- BMAD methodology reference: [link]
+- Similar implementations: [link]
+
+## 📋 Additional Context
+<!-- Add any other context, mockups, or examples -->
+
+### Mockups/Examples
+<!-- Screenshots, diagrams, or code examples -->
+
+### Research
+<!-- Any research you've done on this feature -->
+
+### Community Input
+<!-- Feedback from other users or community -->
+
+## 🤝 Contribution
+<!-- How can you help implement this? -->
+- [ ] I can implement this feature
+- [ ] I can help with design/planning
+- [ ] I can provide testing
+- [ ] I can contribute documentation
+- [ ] I need help but want to contribute
+
+### Implementation Ideas
+<!-- Any technical ideas for how to implement this -->
+
+---
+
+**Please ensure you've:**
+- [ ] Searched existing issues and discussions
+- [ ] Provided clear use cases and benefits
+- [ ] Considered impact on existing functionality
+- [ ] Thought about implementation complexity
+- [ ] Used a descriptive title
diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md
new file mode 100644
index 00000000..743f2d9e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/question.md
@@ -0,0 +1,108 @@
+---
+name: ❓ Question
+about: Ask a question about the BMAD Claude integration
+title: '[QUESTION] '
+labels: ['question', 'needs-triage']
+assignees: ''
+---
+
+# ❓ Question
+
+## 📋 Question Summary
+<!-- Briefly describe your question -->
+
+## 🎯 Category
+<!-- What area is your question about? -->
+- [ ] 🚀 **Getting Started** - Installation, setup, first steps
+- [ ] 🎭 **Agent Usage** - How to use specific agents effectively
+- [ ] 🔄 **Workflows** - BMAD methodology and cross-agent processes
+- [ ] 🛠️ **Technical** - Implementation details, troubleshooting
+- [ ] 🧪 **Testing** - How to validate and test the integration
+- [ ] 📚 **Documentation** - Where to find information
+- [ ] 🤝 **Contributing** - How to help improve the project
+- [ ] 🔗 **Integration** - Using with existing BMAD workflows
+- [ ] 🎯 **Best Practices** - Optimal usage patterns
+- [ ] 🐛 **Troubleshooting** - Solving specific issues
+
+## 🔍 Detailed Question
+<!-- Ask your question in detail -->
+
+### Context
+<!-- Provide background information that helps answer your question -->
+
+### What I'm Trying to Do
+<!-- Describe your goal or use case -->
+
+### What I've Tried
+<!-- What have you attempted so far? -->
+- [ ] Read the README.md files
+- [ ] Checked the documentation in docs/
+- [ ] Ran `npm run test:claude`
+- [ ] Searched existing issues
+- [ ] Asked in Discord community
+- [ ] Consulted Claude Code documentation
+
+### Specific Examples
+<!-- Include specific examples, commands, or scenarios -->
+```bash
+# Commands you've run
+```
+
+```
+# Output or responses you've seen
+```
+
+## 🖥️ Environment (if relevant)
+<!-- Include if this might be environment-specific -->
+- **OS**: [e.g. macOS, Windows, Linux]
+- **Node.js Version**: [e.g. v20.5.0]
+- **Claude Code Version**: [run `claude --version`]
+- **BMAD Integration**: [when did you last build?]
+
+## 🎭 Agent Context (if relevant)
+<!-- If your question is about specific agents -->
+**Relevant agents:**
+- [ ] 📊 Analyst (Mary)
+- [ ] 🏗️ Architect (Winston)
+- [ ] 👨‍💻 Dev (James)
+- [ ] 📋 PM (John)
+- [ ] 🔍 QA (Quinn)
+- [ ] 🎯 Scrum Master (Bob)
+
+**BMAD workflow context:**
+<!-- What BMAD process are you working on? -->
+
+## 📚 Additional Context
+<!-- Any other information that might be helpful -->
+
+### Related Resources
+<!-- Link to any relevant documentation or issues -->
+
+### Expected Outcome
+<!-- What kind of answer are you looking for? -->
+- [ ] Step-by-step instructions
+- [ ] Conceptual explanation
+- [ ] Code examples
+- [ ] Best practice recommendations
+- [ ] Troubleshooting guidance
+- [ ] Resource/documentation pointers
+
+### Urgency
+- [ ] 🔥 Urgent - Blocking critical work
+- [ ] 🟠 Soon - Needed within days
+- [ ] 🟡 Normal - Needed within weeks
+- [ ] 🟢 Low - Just curious/exploring
+
+## 🤝 Community Help
+<!-- Can you help others with similar questions? -->
+- [ ] I'd be willing to help others with similar questions
+- [ ] I can contribute to documentation based on the answer
+- [ ] I'm interested in improving this area of the project
+
+---
+
+**Before posting, please:**
+- [ ] Search existing issues for similar questions
+- [ ] Check the Discord community for recent discussions
+- [ ] Review the documentation in the repository
+- [ ] Provide enough context for others to help you
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 00000000..785f8675
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,123 @@
+# BMAD Claude Integration - Pull Request
+
+## 📋 Summary
+<!-- Provide a brief description of the changes in this PR -->
+
+## 🎯 Type of Change
+<!-- Check all that apply -->
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📚 Documentation only changes
+- [ ] 🔧 Refactoring (no functional changes, no api changes)
+- [ ] ⚡ Performance improvements
+- [ ] 🧪 Test improvements
+- [ ] 🎭 Agent improvements (prompts, personas, capabilities)
+- [ ] 🏗️ Build system changes
+- [ ] 🔄 CI/CD changes
+
+## 🎭 Agent Impact
+<!-- If this affects Claude subagents, specify which ones -->
+- [ ] 📊 Analyst (Mary)
+- [ ] 🏗️ Architect (Winston)  
+- [ ] 👨‍💻 Dev (James)
+- [ ] 📋 PM (John)
+- [ ] 🔍 QA (Quinn)
+- [ ] 🎯 Scrum Master (Bob)
+- [ ] 🛠️ Build system / templates
+- [ ] 📁 BMAD core integration
+
+## 🧪 Testing
+<!-- Describe the tests you ran to verify your changes -->
+
+### Automated Testing
+- [ ] `npm run build:claude` passes
+- [ ] `npm run test:claude` passes
+- [ ] `npm run validate` passes (in integration/claude)
+- [ ] All agent files generate without errors
+
+### Manual Testing
+- [ ] Tested affected agents in Claude Code
+- [ ] Verified agent behavior matches expectations
+- [ ] Tested cross-agent workflows (if applicable)
+- [ ] Validated BMAD methodology integration
+
+### Test Commands Used
+```bash
+# List the specific test commands you ran
+```
+
+### Test Results
+<!-- Describe the results of your testing -->
+
+## 📝 Checklist
+<!-- Check all completed items -->
+
+### Code Quality
+- [ ] My code follows the project's style guidelines
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] My changes generate no new warnings or errors
+
+### Documentation
+- [ ] I have made corresponding changes to the documentation
+- [ ] I have updated README.md if needed
+- [ ] I have updated integration/claude/README.md if needed
+- [ ] Any new features are documented
+
+### BMAD Integration
+- [ ] Changes maintain BMAD methodology integrity
+- [ ] Agent personas remain consistent with BMAD roles
+- [ ] Template and task integrations work correctly
+- [ ] Cross-agent collaboration still functions
+
+### Compatibility
+- [ ] Changes are compatible with existing Claude Code installations
+- [ ] Original BMAD structure remains unmodified (clean separation)
+- [ ] No breaking changes to existing agent configurations
+
+## 🔗 Related Issues
+<!-- Link any related issues -->
+Fixes #(issue number)
+Closes #(issue number)
+Related to #(issue number)
+
+## 📸 Screenshots
+<!-- If applicable, add screenshots to help explain your changes -->
+
+## 🤔 Additional Context
+<!-- Add any other context about the pull request here -->
+
+### Breaking Changes
+<!-- If this is a breaking change, describe what breaks and why -->
+
+### Migration Guide
+<!-- If this requires migration steps, document them here -->
+
+### Performance Impact
+<!-- Describe any performance implications -->
+
+## 📋 Reviewer Guidelines
+<!-- Help reviewers focus on important aspects -->
+
+### Focus Areas
+- [ ] Agent prompt quality and BMAD integration
+- [ ] Code architecture and maintainability
+- [ ] Documentation completeness
+- [ ] Test coverage and validation
+- [ ] Compatibility and backwards compatibility
+
+### Testing Instructions
+<!-- Specific instructions for reviewers to test your changes -->
+
+1. Build the agents: `npm run build:claude`
+2. Run validation: `npm run test:claude`
+3. Test specific agents: [provide specific test scenarios]
+4. Verify [specific functionality]
+
+---
+
+**By submitting this PR, I confirm that:**
+- [ ] I have read and agree to the [Contributing Guidelines](CONTRIBUTING.md)
+- [ ] This contribution is my own work or properly attributed
+- [ ] I understand this will be released under the MIT license
diff --git a/README.md b/README.md
index 2f116983..d4b06606 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,8 @@ There are a few enhancements I have attempted to make to make the flow/DX of usi
 - Memory priming
 - Data sourcing helper
 
+See [Claude Code Subagents Integration](docs/claude-integration.md) for more details.
+
 ```bash
 # Generate Claude Code subagents
 npm run build:claude