docs: add onboarding guides and enhance PO agent prompts
Add comprehensive documentation for team collaboration features: - docs/TEAM-COLLABORATION-FEATURES.md: Overview for sharing with team - src/modules/bmm/workflows/po/README.md: PO Quick Start Guide - src/modules/bmm/workflows/1-requirements/crowdsource/README.md: Stakeholder Guide Enhance PO agent with interactive prompts: - getting-started: First-time orientation with prerequisites check - setup-github: Step-by-step GitHub MCP and integration setup - help: Comprehensive command reference - troubleshoot: Common issues and solutions These prompts guide Claude Desktop users through the complete setup process for team collaboration features.
This commit is contained in:
Jonah Schulte
parent
1adf1ce195
commit
4522c8928d
|
|
@ -0,0 +1,248 @@
|
||||||
|
# BMAD Team Collaboration Features
|
||||||
|
|
||||||
|
This document explains the new collaboration features added to our version of BMAD that enable multi-developer workflows and asynchronous stakeholder collaboration.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Start: What's New?
|
||||||
|
|
||||||
|
We've added three major capabilities:
|
||||||
|
|
||||||
|
1. **PRD/Epic Crowdsourcing** - Async collaboration on requirements with feedback synthesis
|
||||||
|
2. **Story Locking** - Prevent two developers from working on the same story
|
||||||
|
3. **Multi-Channel Notifications** - Get notified via GitHub, Slack, or Email
|
||||||
|
|
||||||
|
**Important:** These features are **optional**. If you're working solo or on a local project, BMAD works exactly as before. Enable GitHub integration when your project reaches a point where team coordination is needed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feature 1: PRD/Epic Crowdsourcing
|
||||||
|
|
||||||
|
### The Problem This Solves
|
||||||
|
|
||||||
|
Before:
|
||||||
|
- Synchronous meetings to collect feedback
|
||||||
|
- Feedback scattered across email, Slack, docs
|
||||||
|
- No structured way to track who has reviewed
|
||||||
|
- Conflicting feedback hard to reconcile
|
||||||
|
- No audit trail of how requirements evolved
|
||||||
|
|
||||||
|
After:
|
||||||
|
- Stakeholders give feedback asynchronously on their own schedule
|
||||||
|
- All feedback tracked in GitHub Issues with structured labels
|
||||||
|
- LLM synthesizes conflicting feedback with rationale
|
||||||
|
- Clear sign-off tracking (who approved, who hasn't, who blocked)
|
||||||
|
- Full version history in the PRD document
|
||||||
|
|
||||||
|
### Workflow Overview
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────┐
|
||||||
|
│ PRD LIFECYCLE │
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ 📝 Draft → 💬 Feedback → 🔄 Synthesis │
|
||||||
|
│ ↑ ↓ │
|
||||||
|
│ └──(iterate)──┘ │
|
||||||
|
│ ↓ │
|
||||||
|
│ ✍️ Sign-off → ✅ Approved │
|
||||||
|
└─────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Commands
|
||||||
|
|
||||||
|
| Command | Who | What It Does |
|
||||||
|
|---------|-----|--------------|
|
||||||
|
| `/my-tasks` | Everyone | See what PRDs/Epics need your input |
|
||||||
|
| `/prd-dashboard` | PO | See status of all PRDs |
|
||||||
|
| `/create-prd-draft` | PO | Start a new PRD |
|
||||||
|
| `/open-feedback-round` | PO | Request feedback from stakeholders |
|
||||||
|
| `/submit-feedback` | Stakeholder | Provide feedback on a PRD section |
|
||||||
|
| `/synthesize-feedback` | PO | Use LLM to process feedback |
|
||||||
|
| `/request-signoff` | PO | Move to approval phase |
|
||||||
|
| `/submit-signoff` | Stakeholder | Approve or block the PRD |
|
||||||
|
|
||||||
|
### Feedback Types
|
||||||
|
|
||||||
|
When submitting feedback, you categorize it:
|
||||||
|
- **Clarification**: Something is unclear
|
||||||
|
- **Concern**: Potential issue or risk
|
||||||
|
- **Suggestion**: Improvement idea
|
||||||
|
- **Addition**: Missing requirement
|
||||||
|
- **Priority**: Disagree with prioritization
|
||||||
|
|
||||||
|
### Sign-off Configuration
|
||||||
|
|
||||||
|
PRDs can have different approval requirements:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# Example: Require 3 approvals from anyone
|
||||||
|
signoff_config:
|
||||||
|
threshold_type: count
|
||||||
|
minimum_approvals: 3
|
||||||
|
|
||||||
|
# Example: Require specific people
|
||||||
|
signoff_config:
|
||||||
|
threshold_type: required_approvers
|
||||||
|
required: ["@po", "@tech-lead", "@security"]
|
||||||
|
optional: ["@ux", "@qa"]
|
||||||
|
minimum_optional: 1 # At least 1 optional must approve
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feature 2: Story Locking
|
||||||
|
|
||||||
|
### The Problem This Solves
|
||||||
|
|
||||||
|
When multiple developers work from the same backlog:
|
||||||
|
- Two developers might accidentally work on the same story
|
||||||
|
- No visibility into who is working on what
|
||||||
|
- Story updates might conflict
|
||||||
|
|
||||||
|
### How Story Locking Works
|
||||||
|
|
||||||
|
```
|
||||||
|
Developer A: /checkout-story 2-5-auth-login
|
||||||
|
→ Story locked to @alice for 8 hours
|
||||||
|
→ Story file copied to local cache
|
||||||
|
→ Developer starts working
|
||||||
|
|
||||||
|
Developer B: /checkout-story 2-5-auth-login
|
||||||
|
→ ⚠️ Story is locked by @alice (expires in 7h)
|
||||||
|
→ Developer picks a different story
|
||||||
|
|
||||||
|
Developer A finishes and completes story
|
||||||
|
→ Lock automatically released
|
||||||
|
→ Story pushed back to GitHub
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Commands
|
||||||
|
|
||||||
|
| Command | What It Does |
|
||||||
|
|---------|--------------|
|
||||||
|
| `/available-stories` | See stories ready for development (with lock status) |
|
||||||
|
| `/checkout-story` | Lock a story and start working on it |
|
||||||
|
| `/lock-status` | See all currently locked stories |
|
||||||
|
| `/unlock-story` | Release a lock (if you're done or abandoning) |
|
||||||
|
|
||||||
|
### Lock Expiration
|
||||||
|
|
||||||
|
- Default lock duration: 8 hours
|
||||||
|
- Locks auto-expire (prevents abandoned locks)
|
||||||
|
- PO can force-unlock stories if needed
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feature 3: Multi-Channel Notifications
|
||||||
|
|
||||||
|
### Notification Channels
|
||||||
|
|
||||||
|
1. **GitHub @mentions** (always on)
|
||||||
|
- Comments on PRD/Epic issues when feedback needed
|
||||||
|
- @mentions for specific stakeholders
|
||||||
|
|
||||||
|
2. **Slack** (optional)
|
||||||
|
- Webhook integration to a team channel
|
||||||
|
- Rich formatted messages with actions
|
||||||
|
|
||||||
|
3. **Email** (optional)
|
||||||
|
- Supports SMTP, SendGrid, or Amazon SES
|
||||||
|
- For stakeholders who don't check GitHub/Slack
|
||||||
|
|
||||||
|
### Notification Events
|
||||||
|
|
||||||
|
| Event | Notification |
|
||||||
|
|-------|--------------|
|
||||||
|
| Feedback round opened | "📣 PRD 'User Auth' is open for feedback until Jan 15" |
|
||||||
|
| Feedback submitted | "💬 New feedback on 'User Auth' from @mike: Concern" |
|
||||||
|
| Synthesis complete | "🔄 PRD 'User Auth' v2 synthesized with 8 feedback items" |
|
||||||
|
| Sign-off requested | "✍️ Sign-off requested for 'User Auth' - deadline: Jan 20" |
|
||||||
|
| PRD approved | "✅ PRD 'User Auth' approved! All sign-offs received." |
|
||||||
|
| PRD blocked | "🚫 PRD 'User Auth' blocked by @security: Missing compliance section" |
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
Notifications are configured in `module.yaml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
notifications:
|
||||||
|
github_mentions:
|
||||||
|
enabled: true # Always on
|
||||||
|
|
||||||
|
slack:
|
||||||
|
enabled: true
|
||||||
|
webhook_url: "https://hooks.slack.com/..."
|
||||||
|
channel: "#prd-updates"
|
||||||
|
|
||||||
|
email:
|
||||||
|
enabled: false # Enable when needed
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
### For Existing Local Projects
|
||||||
|
|
||||||
|
Nothing changes! Continue using BMAD as before. GitHub integration is disabled by default.
|
||||||
|
|
||||||
|
### Enabling GitHub Integration
|
||||||
|
|
||||||
|
When your project needs team coordination:
|
||||||
|
|
||||||
|
1. Set `github_integration_enabled: true` in `module.yaml`
|
||||||
|
2. Configure your GitHub repo details
|
||||||
|
3. Optionally configure Slack/Email notifications
|
||||||
|
4. Start using the collaboration commands
|
||||||
|
|
||||||
|
### Day-to-Day Usage
|
||||||
|
|
||||||
|
**As a Developer:**
|
||||||
|
```
|
||||||
|
1. Check in: /my-tasks
|
||||||
|
2. Pick a story: /available-stories
|
||||||
|
3. Lock it: /checkout-story 2-5-auth
|
||||||
|
4. Work on it...
|
||||||
|
5. Complete it: (story syncs to GitHub)
|
||||||
|
```
|
||||||
|
|
||||||
|
**As a Product Owner:**
|
||||||
|
```
|
||||||
|
1. Create PRD: /create-prd-draft
|
||||||
|
2. Request feedback: /open-feedback-round
|
||||||
|
3. Wait for stakeholders...
|
||||||
|
4. Synthesize: /synthesize-feedback
|
||||||
|
5. Request approval: /request-signoff
|
||||||
|
6. Track progress: /prd-dashboard
|
||||||
|
```
|
||||||
|
|
||||||
|
**As a Stakeholder:**
|
||||||
|
```
|
||||||
|
1. Check tasks: /my-tasks
|
||||||
|
2. View PRD and give feedback: /submit-feedback
|
||||||
|
3. Later, sign off: /submit-signoff
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture: Where Data Lives
|
||||||
|
|
||||||
|
| Data Type | Location | Why |
|
||||||
|
|-----------|----------|-----|
|
||||||
|
| PRD/Epic Documents | `docs/prd/*.md`, `docs/epics/*.md` | Living documents, version controlled |
|
||||||
|
| Review Rounds | GitHub Issues | Closeable coordination (round complete = close) |
|
||||||
|
| Feedback Items | GitHub Issues (linked) | Closeable (incorporated = close) |
|
||||||
|
| Story Lock Status | Issue labels + local cache | Real-time coordination |
|
||||||
|
| Local Cache | `.bmad-cache/` | Fast <100ms access for LLM tools |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Questions?
|
||||||
|
|
||||||
|
- Review the detailed config guide: `src/modules/bmm/data/github-integration-config.md`
|
||||||
|
- Check available workflows in the PO or Stakeholder agent menus
|
||||||
|
- All 673 tests pass - the feature is thoroughly tested
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Last updated: January 2026*
|
||||||
|
|
@ -119,3 +119,239 @@ agent:
|
||||||
- trigger: EDD or fuzzy match on epic-crowdsource-dashboard
|
- trigger: EDD or fuzzy match on epic-crowdsource-dashboard
|
||||||
workflow: "{project-root}/_bmad/bmm/workflows/1-requirements/crowdsource/epic-dashboard/workflow.yaml"
|
workflow: "{project-root}/_bmad/bmm/workflows/1-requirements/crowdsource/epic-dashboard/workflow.yaml"
|
||||||
description: "[EDD] Epic Dashboard - view all epics with PRD lineage"
|
description: "[EDD] Epic Dashboard - view all epics with PRD lineage"
|
||||||
|
|
||||||
|
prompts:
|
||||||
|
- id: getting-started
|
||||||
|
description: "First-time setup and orientation for Product Owners"
|
||||||
|
content: |
|
||||||
|
# 🎯 Welcome, Product Owner!
|
||||||
|
|
||||||
|
I'm Sarah, your PO assistant. I help you manage PRDs, epics, stories, and stakeholder collaboration—all through GitHub Issues.
|
||||||
|
|
||||||
|
## Prerequisites Check
|
||||||
|
|
||||||
|
Before we start, let's verify you're set up:
|
||||||
|
|
||||||
|
**1. BMAD Installed?**
|
||||||
|
- You should have a `_bmad/` folder in your project
|
||||||
|
- If not, run: `npx bmad-method install`
|
||||||
|
|
||||||
|
**2. GitHub MCP Configured?**
|
||||||
|
- This enables me to read/write GitHub Issues
|
||||||
|
- If not set up, say "setup github" for instructions
|
||||||
|
|
||||||
|
**3. GitHub Integration Enabled?**
|
||||||
|
- Check `_bmad/bmm/config.yaml` for `github_integration_enabled: true`
|
||||||
|
- Without this, PRDs and stories stay local only
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
**First, let's see what you have:**
|
||||||
|
- Say `/my-tasks` or `MT` to see what needs your attention
|
||||||
|
- Say `/prd-dashboard` or `PD` to see all PRDs
|
||||||
|
|
||||||
|
## What I Can Help You Do
|
||||||
|
|
||||||
|
### 📝 Requirements Management (PRD Crowdsourcing)
|
||||||
|
| Say This | I'll Do This |
|
||||||
|
|----------|--------------|
|
||||||
|
| "Create a new PRD" | Start a PRD draft with guided prompts |
|
||||||
|
| "Open feedback on auth PRD" | Notify stakeholders to review |
|
||||||
|
| "Synthesize feedback" | Use AI to merge all feedback |
|
||||||
|
| "Request sign-off" | Move to approval phase |
|
||||||
|
|
||||||
|
### 📦 Story Management
|
||||||
|
| Say This | I'll Do This |
|
||||||
|
|----------|--------------|
|
||||||
|
| "Create a story for epic 2" | Generate story with ACs |
|
||||||
|
| "Show sprint dashboard" | See progress and blockers |
|
||||||
|
| "Who's working on what?" | Show story locks |
|
||||||
|
|
||||||
|
## Team Collaboration Features
|
||||||
|
|
||||||
|
These features require GitHub integration:
|
||||||
|
|
||||||
|
- **PRD Crowdsourcing** - Async feedback from stakeholders
|
||||||
|
- **Epic Crowdsourcing** - Collaborative story breakdown
|
||||||
|
- **Story Locking** - Prevents two devs on same story
|
||||||
|
- **Multi-Channel Notifications** - GitHub, Slack, Email
|
||||||
|
|
||||||
|
## Your First PRD
|
||||||
|
|
||||||
|
Ready to create your first PRD? Just say:
|
||||||
|
> "Create a new PRD for [your feature]"
|
||||||
|
|
||||||
|
Or type `CP` for the quick command.
|
||||||
|
|
||||||
|
---
|
||||||
|
*I understand natural language. Just describe what you need!*
|
||||||
|
|
||||||
|
- id: setup-github
|
||||||
|
description: "Configure GitHub integration for team collaboration"
|
||||||
|
content: |
|
||||||
|
# 🔧 GitHub Integration Setup
|
||||||
|
|
||||||
|
This guide helps you enable team collaboration features.
|
||||||
|
|
||||||
|
## Step 1: Verify GitHub MCP
|
||||||
|
|
||||||
|
Claude Desktop needs the GitHub MCP server to interact with GitHub Issues.
|
||||||
|
|
||||||
|
**Check if configured:**
|
||||||
|
I'll try to call the GitHub API. If this fails, you need to set up GitHub MCP.
|
||||||
|
|
||||||
|
**To add GitHub MCP:**
|
||||||
|
1. Open Claude Desktop Settings (Cmd/Ctrl + ,)
|
||||||
|
2. Go to "Developer" → "Model Context Protocol"
|
||||||
|
3. Add the GitHub MCP server:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"github": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": ["-y", "@modelcontextprotocol/server-github"],
|
||||||
|
"env": {
|
||||||
|
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
4. Create a GitHub token at: https://github.com/settings/tokens
|
||||||
|
- Required scopes: `repo`, `issues`, `read:org`
|
||||||
|
5. Restart Claude Desktop
|
||||||
|
|
||||||
|
## Step 2: Enable GitHub Integration in BMAD
|
||||||
|
|
||||||
|
Edit `_bmad/bmm/config.yaml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
github_integration_enabled: true
|
||||||
|
github:
|
||||||
|
owner: "your-org-or-username"
|
||||||
|
repo: "your-repo-name"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 3: Configure Notifications (Optional)
|
||||||
|
|
||||||
|
For Slack notifications, add to config.yaml:
|
||||||
|
```yaml
|
||||||
|
notifications:
|
||||||
|
slack:
|
||||||
|
enabled: true
|
||||||
|
webhook_url: "https://hooks.slack.com/..."
|
||||||
|
channel: "#prd-updates"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 4: Verify Setup
|
||||||
|
|
||||||
|
Say "my tasks" or `MT` to verify everything works.
|
||||||
|
|
||||||
|
If you see your GitHub data, you're all set!
|
||||||
|
|
||||||
|
---
|
||||||
|
*Need help? Ask me to troubleshoot any step.*
|
||||||
|
|
||||||
|
- id: help
|
||||||
|
description: "Show available commands"
|
||||||
|
content: |
|
||||||
|
# 🎯 Product Owner Commands
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| "getting started" | First-time orientation |
|
||||||
|
| "setup github" | Configure GitHub integration |
|
||||||
|
| "help" | Show this command list |
|
||||||
|
|
||||||
|
## Requirements & PRDs
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `MT` `/my-tasks` | What needs my attention |
|
||||||
|
| `CP` `/create-prd` | Create new PRD draft |
|
||||||
|
| `PD` `/prd-dashboard` | View all PRDs |
|
||||||
|
| `OF` `/open-feedback` | Request stakeholder feedback |
|
||||||
|
| `VF` `/view-feedback` | See all feedback |
|
||||||
|
| `SZ` `/synthesize` | Process feedback with AI |
|
||||||
|
| `RS` `/request-signoff` | Move to approval phase |
|
||||||
|
| `SO` `/signoff` | Submit sign-off decision |
|
||||||
|
|
||||||
|
## Epics
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `CE` `/create-epic` | Create epic from approved PRD |
|
||||||
|
| `OE` `/open-epic-feedback` | Request epic feedback |
|
||||||
|
| `SE` `/synthesize-epic` | Process epic feedback |
|
||||||
|
| `EDD` `/epic-dashboard` | View all epics |
|
||||||
|
|
||||||
|
## Stories & Sprint
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `NS` `/new-story` | Create new story |
|
||||||
|
| `US` `/update-story` | Update story details |
|
||||||
|
| `DS` `/dashboard` | Sprint progress |
|
||||||
|
| `AP` `/approve-story` | Approve completed story |
|
||||||
|
| `AS` `/available-stories` | Stories ready for dev |
|
||||||
|
| `LS` `/lock-status` | Who's working on what |
|
||||||
|
| `MG` `/migrate` | Migrate local stories to GitHub |
|
||||||
|
|
||||||
|
## Sync
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `SY` `/sync` | Sync changes from GitHub |
|
||||||
|
|
||||||
|
---
|
||||||
|
*All commands work with natural language too!*
|
||||||
|
|
||||||
|
- id: troubleshoot
|
||||||
|
description: "Troubleshoot common issues"
|
||||||
|
content: |
|
||||||
|
# 🔧 Troubleshooting
|
||||||
|
|
||||||
|
## "GitHub API calls fail"
|
||||||
|
|
||||||
|
**Symptoms:** Commands like `MT` or `PD` show errors
|
||||||
|
|
||||||
|
**Solutions:**
|
||||||
|
1. Verify GitHub MCP is configured in Claude Desktop
|
||||||
|
2. Check your GitHub token hasn't expired
|
||||||
|
3. Ensure token has `repo` and `issues` scopes
|
||||||
|
4. Try: "Can you call mcp__github__get_me?"
|
||||||
|
|
||||||
|
## "No PRDs or stories found"
|
||||||
|
|
||||||
|
**Possible causes:**
|
||||||
|
- GitHub integration not enabled in config.yaml
|
||||||
|
- Wrong owner/repo in config
|
||||||
|
- No issues with BMAD labels exist yet
|
||||||
|
|
||||||
|
**Check:** Look at `_bmad/bmm/config.yaml` for correct settings
|
||||||
|
|
||||||
|
## "Stakeholders not getting notifications"
|
||||||
|
|
||||||
|
**Check:**
|
||||||
|
1. GitHub @mentions: Are usernames correct?
|
||||||
|
2. Slack: Is webhook URL valid?
|
||||||
|
3. Email: Is SMTP configured?
|
||||||
|
|
||||||
|
**Test:** Create a test PRD and open feedback
|
||||||
|
|
||||||
|
## "Story locks not working"
|
||||||
|
|
||||||
|
**Possible causes:**
|
||||||
|
- GitHub integration disabled
|
||||||
|
- Issue labels not set correctly
|
||||||
|
- Cache out of sync
|
||||||
|
|
||||||
|
**Fix:** Run `SY` (sync) to refresh from GitHub
|
||||||
|
|
||||||
|
## "Can't find BMAD commands"
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Verify BMAD is installed: check for `_bmad/` folder
|
||||||
|
2. If missing, run: `npx bmad-method install`
|
||||||
|
3. Choose your IDE during installation
|
||||||
|
4. Start a fresh chat after installation
|
||||||
|
|
||||||
|
---
|
||||||
|
*Still stuck? Describe your issue and I'll help debug.*
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,145 @@
|
||||||
|
# Stakeholder Quick Start Guide
|
||||||
|
|
||||||
|
Welcome! This guide helps team members (developers, designers, tech leads, etc.) participate in PRD and Epic reviews using Claude Desktop.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What Can You Do?
|
||||||
|
|
||||||
|
As a stakeholder, you can:
|
||||||
|
|
||||||
|
| Task | Command | What It Does |
|
||||||
|
|------|---------|--------------|
|
||||||
|
| **See your inbox** | `/my-tasks` or `MT` | What PRDs/Epics need your input |
|
||||||
|
| **Give feedback** | `/submit-feedback` or `SF` | Add feedback to a PRD or Epic |
|
||||||
|
| **Sign off** | `/signoff` or `SO` | Approve or block a PRD/Epic |
|
||||||
|
| **View feedback** | `/view-feedback` or `VF` | See what others have said |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Your Typical Workflow
|
||||||
|
|
||||||
|
### 1. Check What Needs Your Input
|
||||||
|
|
||||||
|
```
|
||||||
|
You: What needs my attention?
|
||||||
|
```
|
||||||
|
|
||||||
|
Claude shows:
|
||||||
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
📋 MY TASKS - @yourname
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
|
||||||
|
🔴 URGENT (Deadline Soon)
|
||||||
|
• prd:payments-v2 → Sign-off needed (Tomorrow!)
|
||||||
|
• prd:user-auth → Feedback needed (2 days)
|
||||||
|
|
||||||
|
📋 PENDING
|
||||||
|
• epic:3-mobile → Feedback needed (5 days)
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Give Feedback
|
||||||
|
|
||||||
|
```
|
||||||
|
You: I want to give feedback on the auth PRD
|
||||||
|
```
|
||||||
|
|
||||||
|
Claude will:
|
||||||
|
1. Show you the current PRD
|
||||||
|
2. Ask which section you're commenting on
|
||||||
|
3. Ask your feedback type (concern, suggestion, etc.)
|
||||||
|
4. Help you write clear feedback
|
||||||
|
5. Submit it to the PO
|
||||||
|
|
||||||
|
### 3. Sign Off When Ready
|
||||||
|
|
||||||
|
After feedback is synthesized:
|
||||||
|
|
||||||
|
```
|
||||||
|
You: Sign off on auth PRD
|
||||||
|
```
|
||||||
|
|
||||||
|
Options:
|
||||||
|
- ✅ **Approve** - Looks good!
|
||||||
|
- ✅📝 **Approve with note** - Minor comment, still approving
|
||||||
|
- 🚫 **Block** - Can't approve until X is fixed
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feedback Types
|
||||||
|
|
||||||
|
When giving feedback, pick the type that fits:
|
||||||
|
|
||||||
|
| Type | When to Use | Example |
|
||||||
|
|------|-------------|---------|
|
||||||
|
| 🔍 **Clarification** | Something is unclear | "What happens if the user closes mid-flow?" |
|
||||||
|
| ⚠️ **Concern** | You see a potential problem | "This conflicts with our API rate limits" |
|
||||||
|
| 💡 **Suggestion** | You have an improvement idea | "Could we add a 'remember me' checkbox?" |
|
||||||
|
| ➕ **Addition** | Something is missing | "Need to specify error messages" |
|
||||||
|
| ⚖️ **Priority** | You disagree with priority/scope | "OAuth should be phase 1, not phase 2" |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Good Feedback Examples
|
||||||
|
|
||||||
|
### ❌ Vague
|
||||||
|
> "The login section needs work"
|
||||||
|
|
||||||
|
### ✅ Specific
|
||||||
|
> "FR-3 (Session Management): Unclear what happens when session expires during a payment. Should we save cart and redirect to login?"
|
||||||
|
|
||||||
|
### ❌ Just a complaint
|
||||||
|
> "This is too complicated"
|
||||||
|
|
||||||
|
### ✅ Actionable
|
||||||
|
> "US-4 (Password Reset): Consider splitting into two stories - (1) basic reset via email, (2) phone/SMS reset. Current scope may be too large for one sprint."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Blocking vs Concerns
|
||||||
|
|
||||||
|
**Block** when:
|
||||||
|
- Security vulnerability would ship
|
||||||
|
- Legal/compliance requirement is missing
|
||||||
|
- Technical impossibility that must be resolved
|
||||||
|
|
||||||
|
**Concern** (but still approve) when:
|
||||||
|
- "Nice to have" improvement
|
||||||
|
- Minor clarification needed
|
||||||
|
- Stylistic preference
|
||||||
|
|
||||||
|
The PO can't proceed to implementation while blocks exist.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## FAQs
|
||||||
|
|
||||||
|
**Q: Do I have to respond to every PRD?**
|
||||||
|
A: Only if you're listed as a stakeholder. Check `/my-tasks` to see what needs you.
|
||||||
|
|
||||||
|
**Q: What if I miss the deadline?**
|
||||||
|
A: The PO can still proceed, but late feedback may require a new revision cycle.
|
||||||
|
|
||||||
|
**Q: Can I see what others said?**
|
||||||
|
A: Yes! Use `/view-feedback` to see all feedback and identify conflicts.
|
||||||
|
|
||||||
|
**Q: What if I agree with someone else's feedback?**
|
||||||
|
A: You can add supporting feedback, but don't duplicate. The synthesis step will group similar feedback.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Say This... | To Do This... |
|
||||||
|
|-------------|---------------|
|
||||||
|
| "What needs my attention?" | Check your inbox |
|
||||||
|
| "Give feedback on auth PRD" | Add feedback |
|
||||||
|
| "What did others say about auth?" | View all feedback |
|
||||||
|
| "Sign off on payments PRD" | Submit approval |
|
||||||
|
| "Block auth PRD" | Submit with blocker |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*For PO-specific tasks (creating PRDs, synthesizing feedback), see the PO Quick Start Guide.*
|
||||||
|
|
@ -0,0 +1,176 @@
|
||||||
|
# Product Owner Quick Start Guide
|
||||||
|
|
||||||
|
Welcome! This guide helps you get started with BMAD's Product Owner tools in Claude Desktop.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What Can You Do?
|
||||||
|
|
||||||
|
As a PO, you can:
|
||||||
|
|
||||||
|
| Task | Command | What It Does |
|
||||||
|
|------|---------|--------------|
|
||||||
|
| **See your inbox** | `/my-tasks` or `MT` | What PRDs/Epics need your attention |
|
||||||
|
| **Create a PRD** | `/create-prd` or `CP` | Start a new Product Requirements Document |
|
||||||
|
| **View all PRDs** | `/prd-dashboard` or `PD` | See status of all PRDs |
|
||||||
|
| **Get feedback** | `/open-feedback` or `OF` | Request stakeholder feedback on a PRD |
|
||||||
|
| **Process feedback** | `/synthesize` or `SZ` | Use AI to merge feedback into new version |
|
||||||
|
| **Get approval** | `/request-signoff` or `RS` | Move PRD to approval phase |
|
||||||
|
| **Create stories** | `/new-story` or `NS` | Create a new user story |
|
||||||
|
| **View sprint** | `/dashboard` or `DS` | See sprint progress |
|
||||||
|
|
||||||
|
Just type any command (like `MT` or `/my-tasks`) and Claude will guide you through it.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Your First PRD: A 5-Step Walkthrough
|
||||||
|
|
||||||
|
### Step 1: Create a PRD Draft
|
||||||
|
|
||||||
|
```
|
||||||
|
You: Create a new PRD for user authentication
|
||||||
|
Claude: [Walks you through creating the PRD with sections for vision, goals, requirements, etc.]
|
||||||
|
```
|
||||||
|
|
||||||
|
Or use the command: `/create-prd`
|
||||||
|
|
||||||
|
### Step 2: Request Feedback
|
||||||
|
|
||||||
|
Once your draft is ready:
|
||||||
|
|
||||||
|
```
|
||||||
|
You: Open feedback on the auth PRD
|
||||||
|
Claude: [Sets deadline, notifies stakeholders, opens feedback round]
|
||||||
|
```
|
||||||
|
|
||||||
|
Stakeholders will get notified (via GitHub @mention, Slack, or email depending on your setup).
|
||||||
|
|
||||||
|
### Step 3: Check Feedback Status
|
||||||
|
|
||||||
|
After a day or two:
|
||||||
|
|
||||||
|
```
|
||||||
|
You: Show me feedback on the auth PRD
|
||||||
|
Claude: [Shows all feedback organized by section and type, highlights conflicts]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Synthesize Feedback
|
||||||
|
|
||||||
|
When you have enough feedback:
|
||||||
|
|
||||||
|
```
|
||||||
|
You: Synthesize feedback for auth PRD
|
||||||
|
Claude: [AI processes all feedback, proposes changes with rationale, you accept/reject each]
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates version 2 of your PRD with all accepted changes.
|
||||||
|
|
||||||
|
### Step 5: Get Sign-off
|
||||||
|
|
||||||
|
When the PRD is ready for approval:
|
||||||
|
|
||||||
|
```
|
||||||
|
You: Request sign-off on auth PRD
|
||||||
|
Claude: [Notifies stakeholders, tracks who approved/blocked]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Everyday Commands
|
||||||
|
|
||||||
|
### Morning Check-in
|
||||||
|
|
||||||
|
```
|
||||||
|
You: What needs my attention?
|
||||||
|
```
|
||||||
|
|
||||||
|
This shows you:
|
||||||
|
- PRDs waiting for your review
|
||||||
|
- Epics needing feedback synthesis
|
||||||
|
- Stories ready for approval
|
||||||
|
- Any blocked items
|
||||||
|
|
||||||
|
### Quick Status Check
|
||||||
|
|
||||||
|
```
|
||||||
|
You: Show PRD dashboard
|
||||||
|
```
|
||||||
|
|
||||||
|
See all PRDs at a glance:
|
||||||
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
📊 PRD PORTFOLIO
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
📝 Draft: 2 PRDs
|
||||||
|
💬 Feedback: 3 PRDs (collecting input)
|
||||||
|
✍️ Sign-off: 2 PRDs (awaiting approval)
|
||||||
|
✅ Approved: 8 PRDs (this quarter)
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sprint Management
|
||||||
|
|
||||||
|
```
|
||||||
|
You: Show sprint dashboard
|
||||||
|
You: Create a new story for epic 2
|
||||||
|
You: Approve story 2-5-auth
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Understanding Feedback Types
|
||||||
|
|
||||||
|
When stakeholders give feedback, they categorize it:
|
||||||
|
|
||||||
|
| Type | Meaning | Example |
|
||||||
|
|------|---------|---------|
|
||||||
|
| 🔍 **Clarification** | Something is unclear | "What happens if session expires?" |
|
||||||
|
| ⚠️ **Concern** | Potential problem | "This might conflict with GDPR" |
|
||||||
|
| 💡 **Suggestion** | Improvement idea | "Consider adding biometric auth" |
|
||||||
|
| ➕ **Addition** | Missing requirement | "Need audit logging" |
|
||||||
|
| ⚖️ **Priority** | Order disagreement | "MFA should be MVP, not phase 2" |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Sign-off Options
|
||||||
|
|
||||||
|
Stakeholders can:
|
||||||
|
- ✅ **Approve** - No concerns
|
||||||
|
- ✅📝 **Approve with Note** - Minor comment, still approves
|
||||||
|
- 🚫 **Block** - Cannot approve, has blocker (returns to feedback)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tips for Success
|
||||||
|
|
||||||
|
1. **Start small** - Try `/my-tasks` first to see what's in flight
|
||||||
|
2. **Natural language works** - Just describe what you want; you don't need exact commands
|
||||||
|
3. **Check feedback before synthesizing** - Use `/view-feedback` to see what came in
|
||||||
|
4. **Iterate** - You can do multiple feedback rounds before sign-off
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Getting Help
|
||||||
|
|
||||||
|
| Command | What It Does |
|
||||||
|
|---------|--------------|
|
||||||
|
| `help` | Show available commands |
|
||||||
|
| `show me the auth PRD` | Read a specific PRD |
|
||||||
|
| `what's the status of payments PRD?` | Quick status check |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Optional: GitHub Integration
|
||||||
|
|
||||||
|
If your team uses GitHub Issues for coordination:
|
||||||
|
|
||||||
|
1. Ask your admin to enable `github_integration_enabled: true` in module.yaml
|
||||||
|
2. PRD feedback will be tracked in GitHub Issues
|
||||||
|
3. You'll get @mentions when stakeholders submit feedback
|
||||||
|
4. Story locks prevent two developers working on the same thing
|
||||||
|
|
||||||
|
Without GitHub, everything still works - it just stays local.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*For technical details, see: `src/modules/bmm/data/github-integration-config.md`*
|
||||||
Loading…
Reference in New Issue