From e3b6029496ba4f1f1127ad7afcffc5962372c130 Mon Sep 17 00:00:00 2001 From: Jonah Schulte Date: Thu, 8 Jan 2026 20:45:25 -0500 Subject: [PATCH] docs: add Claude Desktop + GitHub MCP integration guide Enable BMAD usage directly in Claude Desktop without local installation: - docs/how-to/installation/claude-desktop-github.md: Full setup guide - resources/prompts/claude-desktop-po-bootstrap.md: Copy-paste bootstrap prompts The key insight: with GitHub MCP, Claude Desktop can fetch agent definitions directly from the repo and embody them dynamically. Also enhanced PO agent setup-github prompt to cover both Claude Desktop and Claude Code workflows. --- .../installation/claude-desktop-github.md | 212 ++++++++++++++++++ .../prompts/claude-desktop-po-bootstrap.md | 98 ++++++++ src/modules/bmm/agents/po.agent.yaml | 36 ++- 3 files changed, 337 insertions(+), 9 deletions(-) create mode 100644 docs/how-to/installation/claude-desktop-github.md create mode 100644 resources/prompts/claude-desktop-po-bootstrap.md diff --git a/docs/how-to/installation/claude-desktop-github.md b/docs/how-to/installation/claude-desktop-github.md new file mode 100644 index 00000000..dbf5f4b0 --- /dev/null +++ b/docs/how-to/installation/claude-desktop-github.md @@ -0,0 +1,212 @@ +--- +title: "Using BMAD with Claude Desktop + GitHub" +description: Use BMAD agents in Claude Desktop without local installation +--- + +Use BMAD agents directly in Claude Desktop by reading agent files from GitHub. Perfect for Product Owners, stakeholders, and team members who don't need a full local development setup. + +## Prerequisites + +- **Claude Desktop** with GitHub MCP configured +- **GitHub repository** with BMAD installed (has `_bmad/` folder) +- **GitHub Personal Access Token** with `repo` and `issues` scopes + +## Step 1: Configure GitHub MCP + +Open Claude Desktop settings and add the GitHub MCP server: + +1. Go to **Settings** → **Developer** → **Model Context Protocol** +2. Add this configuration: + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here" + } + } + } +} +``` + +3. Create a token at: https://github.com/settings/tokens + - Required scopes: `repo`, `issues`, `read:org` +4. Restart Claude Desktop + +## Step 2: Load a BMAD Agent + +In a new Claude Desktop conversation, ask Claude to load an agent from your repo: + +``` +Please read and embody the Product Owner agent from my repository. +Fetch the file from: github.com/YOUR-ORG/YOUR-REPO at path +src/modules/bmm/agents/po.agent.yaml + +After reading it, introduce yourself and show me the available commands. +``` + +Claude will: +1. Use `mcp__github__get_file_contents` to fetch the agent definition +2. Parse the persona, menu, and prompts +3. Embody the agent and present the menu + +## Step 3: Start Using Team Features + +Once the agent is loaded, you can use all the team collaboration features: + +### Check Your Tasks +``` +What needs my attention? +``` +or just type `MT` + +### Create a PRD +``` +Create a new PRD for user authentication +``` +or type `CP` + +### View PRD Dashboard +``` +Show me all PRDs +``` +or type `PD` + +## Available Agents + +| Agent | Path | Purpose | +|-------|------|---------| +| **Product Owner** | `src/modules/bmm/agents/po.agent.yaml` | PRD management, stories, stakeholder coordination | +| **Analyst** | `src/modules/bmm/agents/analyst.agent.yaml` | Project initialization, workflow guidance | +| **PM** | `src/modules/bmm/agents/pm.agent.yaml` | Requirements, epics, story creation | +| **Architect** | `src/modules/bmm/agents/architect.agent.yaml` | Architecture decisions, technical design | + +## How It Works + +``` +┌─────────────────────────────────────────────────────────────┐ +│ CLAUDE DESKTOP │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ User: "Load the PO agent from my repo" │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────┐ │ +│ │ GitHub MCP │ │ +│ │ mcp__github__get_file_contents │ │ +│ │ → Fetches po.agent.yaml │ │ +│ └─────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ Claude embodies the agent persona │ +│ │ │ +│ ▼ │ +│ User: "MT" (my tasks) │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────┐ │ +│ │ GitHub MCP │ │ +│ │ mcp__github__search_issues │ │ +│ │ → Finds PRDs needing attention │ │ +│ └─────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Tips for Best Results + +### Start Each Session Fresh +Load the agent at the beginning of each conversation: +``` +Load the PO agent from github.com/myorg/myrepo +``` + +### Use Natural Language +The agent understands natural language, not just commands: +- "What PRDs are waiting for feedback?" +- "Create a story for the login epic" +- "Who's working on authentication?" + +### Combine with Project Knowledge +For even better context, you can also upload the `llms-full.txt` file to your Claude Project: +``` +curl https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt +``` + +This gives Claude the full BMAD methodology documentation. + +## Comparison: Local Install vs GitHub MCP + +| Feature | Local Install | GitHub MCP Only | +|---------|--------------|-----------------| +| Requires Node.js | ✅ Yes | ❌ No | +| `/agent-name` commands | ✅ Yes | ❌ Manual load | +| Agent files | Local in `_bmad/` | Fetched from GitHub | +| GitHub Issues | ✅ Works | ✅ Works | +| PRD Crowdsourcing | ✅ Works | ✅ Works | +| Story Locking | ✅ Works | ✅ Works | +| Best for | Developers | POs, Stakeholders | + +## Troubleshooting + +### "Agent file not found" +- Verify the repository has BMAD installed +- Check the file path is correct +- Ensure your token has `repo` access + +### "GitHub API errors" +- Check your token hasn't expired +- Verify the token has required scopes +- Try: "Can you call mcp__github__get_me?" + +### "Agent doesn't understand commands" +- Make sure Claude fully read and embodied the agent +- Try asking Claude to "show the menu" to verify +- Start a fresh conversation and reload the agent + +## Quick Start - Bootstrap Prompts + +Copy and paste this into Claude Desktop to get started immediately: + +### Minimal Version +``` +Load the Product Owner agent from github.com/YOUR-ORG/YOUR-REPO +(path: src/modules/bmm/agents/po.agent.yaml) and enter PO mode. +Show me what needs my attention. +``` + +### Full Version +``` +Fetch and embody the BMAD Product Owner agent. + +1. Read the agent definition from GitHub: + - Repository: YOUR-ORG/YOUR-REPO + - Path: src/modules/bmm/agents/po.agent.yaml + +2. After reading, fully embody this agent: + - Adopt the persona (name, role, communication style) + - Internalize all principles + - Make the menu commands available + +3. Introduce yourself and show the available commands. + +4. Then check: what PRDs or stories need my attention? + +Use GitHub MCP tools (mcp__github__*) for all GitHub operations. +``` + +Replace `YOUR-ORG` and `YOUR-REPO` with your actual repository details. + +For more bootstrap prompts (including stakeholder-specific versions), see: +`resources/prompts/claude-desktop-po-bootstrap.md` + +--- + +## Related + +- [Install BMAD Locally](./install-bmad.md) - Full local installation +- [Team Collaboration Features](../../../docs/TEAM-COLLABORATION-FEATURES.md) - PRD crowdsourcing overview +- [Getting Started](../../tutorials/getting-started/getting-started-bmadv6.md) - Full tutorial diff --git a/resources/prompts/claude-desktop-po-bootstrap.md b/resources/prompts/claude-desktop-po-bootstrap.md new file mode 100644 index 00000000..9e96a760 --- /dev/null +++ b/resources/prompts/claude-desktop-po-bootstrap.md @@ -0,0 +1,98 @@ +# BMAD Product Owner - Claude Desktop Bootstrap + +Copy and paste this entire prompt into Claude Desktop to activate the Product Owner agent. + +--- + +## Quick Start (Replace YOUR-ORG/YOUR-REPO) + +``` +Fetch and embody the BMAD Product Owner agent. + +1. Read the agent definition from GitHub: + - Repository: YOUR-ORG/YOUR-REPO + - Path: src/modules/bmm/agents/po.agent.yaml + +2. After reading, fully embody this agent: + - Adopt the persona (name, role, communication style) + - Internalize all principles + - Make the menu commands available + - Load any prompts defined in the file + +3. Introduce yourself and show the available commands. + +4. Then check: what PRDs or stories need my attention? + +Use GitHub MCP tools (mcp__github__*) for all GitHub operations. +``` + +--- + +## Example with Real Repository + +``` +Fetch and embody the BMAD Product Owner agent. + +1. Read the agent definition from GitHub: + - Repository: acme-corp/acme-platform + - Path: src/modules/bmm/agents/po.agent.yaml + +2. After reading, fully embody this agent: + - Adopt the persona (name, role, communication style) + - Internalize all principles + - Make the menu commands available + - Load any prompts defined in the file + +3. Introduce yourself and show the available commands. + +4. Then check: what PRDs or stories need my attention? + +Use GitHub MCP tools (mcp__github__*) for all GitHub operations. +``` + +--- + +## Minimal Version + +If you just want the shortest possible bootstrap: + +``` +Load the Product Owner agent from github.com/YOUR-ORG/YOUR-REPO +(path: src/modules/bmm/agents/po.agent.yaml) and enter PO mode. +Show me what needs my attention. +``` + +--- + +## For Stakeholders (Non-PO Team Members) + +Stakeholders who just need to give feedback on PRDs can use a lighter prompt: + +``` +I'm a stakeholder who needs to review PRDs and give feedback. + +Load the Product Owner agent from github.com/YOUR-ORG/YOUR-REPO +(path: src/modules/bmm/agents/po.agent.yaml) + +Then show me: +1. What PRDs need my feedback +2. What PRDs need my sign-off + +I'll mainly use these commands: +- MT (my tasks) +- SF (submit feedback) +- SO (sign off) +- VF (view feedback) +``` + +--- + +## Prerequisites + +Before using these prompts, ensure: + +1. **GitHub MCP is configured** in Claude Desktop settings +2. **Your repo has BMAD installed** (has `src/modules/bmm/agents/` folder) +3. **Your GitHub token** has `repo` and `issues` scopes + +See the full setup guide: `docs/how-to/installation/claude-desktop-github.md` diff --git a/src/modules/bmm/agents/po.agent.yaml b/src/modules/bmm/agents/po.agent.yaml index ea160d42..31206250 100644 --- a/src/modules/bmm/agents/po.agent.yaml +++ b/src/modules/bmm/agents/po.agent.yaml @@ -193,15 +193,23 @@ agent: This guide helps you enable team collaboration features. - ## Step 1: Verify GitHub MCP + ## Are You Using Claude Desktop or Claude Code? - Claude Desktop needs the GitHub MCP server to interact with GitHub Issues. + **Claude Desktop (chat app):** + - You only need GitHub MCP configured + - I can read agent files directly from your GitHub repo + - No local BMAD installation required! - **Check if configured:** - I'll try to call the GitHub API. If this fails, you need to set up GitHub MCP. + **Claude Code (CLI tool):** + - Run `npx bmad-method install` in your project + - Then configure GitHub MCP for team features + + ## Step 1: Configure GitHub MCP + + Both Claude Desktop and Claude Code need GitHub MCP for team features. **To add GitHub MCP:** - 1. Open Claude Desktop Settings (Cmd/Ctrl + ,) + 1. Open Settings (Cmd/Ctrl + ,) 2. Go to "Developer" → "Model Context Protocol" 3. Add the GitHub MCP server: ```json @@ -219,9 +227,19 @@ agent: ``` 4. Create a GitHub token at: https://github.com/settings/tokens - Required scopes: `repo`, `issues`, `read:org` - 5. Restart Claude Desktop + 5. Restart Claude - ## Step 2: Enable GitHub Integration in BMAD + ## Step 2: For Claude Desktop Users (No Local Install) + + I can load myself directly from your GitHub repo! Just tell me: + ``` + Load the PO agent from github.com/YOUR-ORG/YOUR-REPO + at path: src/modules/bmm/agents/po.agent.yaml + ``` + + Then I'll fetch my full definition and embody the agent persona. + + ## Step 3: For Claude Code Users (Local Install) Edit `_bmad/bmm/config.yaml`: @@ -232,7 +250,7 @@ agent: repo: "your-repo-name" ``` - ## Step 3: Configure Notifications (Optional) + ## Step 4: Configure Notifications (Optional) For Slack notifications, add to config.yaml: ```yaml @@ -243,7 +261,7 @@ agent: channel: "#prd-updates" ``` - ## Step 4: Verify Setup + ## Step 5: Verify Setup Say "my tasks" or `MT` to verify everything works.