bmad-stella 2.0.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/bmad-core/agents/planner.md +1 -1
- package/docs/atlassian-token-guide.md +44 -0
- package/docs/bmad-memory.md +38 -0
- package/docs/stella-user-guide.md +87 -50
- package/package.json +117 -117
- package/tools/installer/lib/claude-permissions-manager.js +4 -5
- package/tools/installer/lib/dependency-manager.js +145 -511
- package/bmad-core/utils/github-mcp-auth.js +0 -81
- package/docs/github-pat-guide.md +0 -65
package/README.md
CHANGED
|
@@ -36,7 +36,6 @@ Planner → Dev → QA → Reviewer
|
|
|
36
36
|
- [Claude Code CLI](https://docs.anthropic.com/claude/docs/claude-code) installed and configured
|
|
37
37
|
- JIRA account with access to your organization's instance
|
|
38
38
|
- Confluence page URL for architecture documentation (recommended)
|
|
39
|
-
- GitHub fine-grained token for PR review (optional) — see [Create a GitHub Token for BMad](docs/github-pat-guide.md)
|
|
40
39
|
|
|
41
40
|
### Installation (5 minutes)
|
|
42
41
|
|
|
@@ -68,6 +67,9 @@ npx bmad-stella install
|
|
|
68
67
|
- 🔧 **[Command Reference](docs/stella-user-guide.md#command-reference)** - All agent commands with detailed usage
|
|
69
68
|
- 💡 **[Best Practices](docs/stella-user-guide.md#best-practices)** - Tips for success with each agent
|
|
70
69
|
- 🐛 **[Troubleshooting](docs/stella-user-guide.md#troubleshooting)** - Common issues and solutions
|
|
70
|
+
- 🔑 **[Atlassian Token Guide](docs/atlassian-token-guide.md)** - Create the JIRA/Confluence API token
|
|
71
|
+
- 🧠 **[BMad Memory](docs/bmad-memory.md)** - How agents remember your project across sessions
|
|
72
|
+
- 📋 **[Semantic Logger](docs/semantic-logger.md)** - Automatic friction reports per plan
|
|
71
73
|
|
|
72
74
|
### Understanding BMad-Stella
|
|
73
75
|
|
|
@@ -85,7 +85,7 @@ commands:
|
|
|
85
85
|
- For each attachment entry where mimeType starts with `image/`, invoke the Read tool on its `localPath` so the image enters context
|
|
86
86
|
- For each entry where mimeType is `application/pdf`, use Read with `pages:"1-5"` by default; expand range only if needed
|
|
87
87
|
- 'On failure (non-zero exit), the helper prints a clear error line on stderr — relay it in one concise line: "⚠️ Attachment retrieval failed — {that stderr message}." Then fall back to attachment-manual-fallback (never block the workflow).'
|
|
88
|
-
- 'If the error is credentials/auth ("Missing credentials" / "Authentication failed"), append: "Check JIRA_BASE_URL / JIRA_EMAIL / JIRA_API_TOKEN in
|
|
88
|
+
- 'If the error is credentials/auth ("Missing credentials" / "Authentication failed"), append: "Check JIRA_BASE_URL / JIRA_EMAIL / JIRA_API_TOKEN in bmad-docs/.bmad-tokens/.env; regenerate token: https://id.atlassian.com/manage-profile/security/api-tokens". If the ticket was not found, ask the user to verify the ticket key instead of pasting.'
|
|
89
89
|
- Skipped attachments (video, archives, oversized) are listed in the manifest `skipped` array — mention them to the user so they know what is not loaded
|
|
90
90
|
- attachment-manual-fallback: Request user to provide attachments via copy/paste (alt+v) or file path if downloaded. Use this only when the auto-fetch helper cannot run (missing credentials, auth failure, or fallback path)
|
|
91
91
|
- output-format: Display ticket title, description, comments, attachment summary (counts of downloaded/skipped/failed from the manifest), and Acceptance Criteria status (present in ticket / missing — will be derived in §6) with clear validation prompt
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Create an Atlassian API Token for BMad
|
|
2
|
+
|
|
3
|
+
BMad uses your Atlassian API token to download JIRA ticket attachments and fetch architecture / domain docs from Confluence.
|
|
4
|
+
|
|
5
|
+
**⏱️ ~1 minute.**
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Open the token page
|
|
10
|
+
|
|
11
|
+
1. Go to → **https://id.atlassian.com/manage-profile/security/api-tokens**
|
|
12
|
+
2. Click **Create API token**
|
|
13
|
+
|
|
14
|
+
## 2. Name + expiry
|
|
15
|
+
|
|
16
|
+
- **Name:** anything (e.g. `bmad-jira`)
|
|
17
|
+
- **Expires:** pick what you like (max 1 year)
|
|
18
|
+
|
|
19
|
+
## 3. Create + copy
|
|
20
|
+
|
|
21
|
+
Click **Create** → **copy it now** (Atlassian shows it only once).
|
|
22
|
+
|
|
23
|
+
## 4. Give it to BMad
|
|
24
|
+
|
|
25
|
+
- **During install:** paste it when the installer asks for the **Atlassian API token**, along with:
|
|
26
|
+
- **Site URL:** `https://stellaint.atlassian.net`
|
|
27
|
+
- **Email:** your Stella account email
|
|
28
|
+
- **Already installed, or changing the token later:** open `bmad-docs/.bmad-tokens/.env` in your project and update:
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
JIRA_BASE_URL=https://stellaint.atlassian.net
|
|
32
|
+
JIRA_EMAIL=you@stellainternational.com
|
|
33
|
+
JIRA_API_TOKEN=your-token-here
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## ✅ Done
|
|
37
|
+
|
|
38
|
+
Verify: `node .bmad-core/utils/jira-attachments --self-test`
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
**Note:** this token is separate from the Atlassian **MCP server** login — that one authenticates via browser OAuth (`/mcp` → Atlassian), no token needed.
|
|
43
|
+
|
|
44
|
+
**Security note:** the token is stored in a git-ignored file (`bmad-docs/.bmad-tokens/.env`, mode 0600). Rotate it by editing that file.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# BMad Memory
|
|
2
|
+
|
|
3
|
+
## What it does
|
|
4
|
+
|
|
5
|
+
Agents remember your project across sessions — what was built, what failed, which utilities to reuse, and how you like to work. Fully automatic, no commands.
|
|
6
|
+
|
|
7
|
+
## How it works
|
|
8
|
+
|
|
9
|
+
Once a day, your first prompt spawns a silent background job that scans recently completed plan files and updates memory:
|
|
10
|
+
|
|
11
|
+
| Memory | What it holds | Who reads it |
|
|
12
|
+
| --------------- | ----------------------------------------------------------- | ---------------------------------------- |
|
|
13
|
+
| **Domain map** | Business context, core entities, invariants | All agents, injected at activation |
|
|
14
|
+
| **Patterns** | Verified reusable base classes / utilities, ranked by usage | All agents, injected at activation |
|
|
15
|
+
| **Episodes** | Compressed history of past plans, per module area | Planner, for the relevant module |
|
|
16
|
+
| **Semantic** | Distilled current-state knowledge, per domain | Planner, for the relevant domain |
|
|
17
|
+
| **Lessons** | Rules learned from past agent failures, per module | Planner, for the relevant module |
|
|
18
|
+
| **Constraints** | Active temporary constraints (e.g. "migration in progress") | All agents, until the constraint expires |
|
|
19
|
+
|
|
20
|
+
Separately, a user-wide hook watches for your corrections ("don't do X", "I said before…") and updates your developer profile at `~/.claude/personalization.md` — applied in every session, in every project.
|
|
21
|
+
|
|
22
|
+
**You are never interrupted.** Everything runs detached in the background — nothing waits, nothing prints into your chat.
|
|
23
|
+
|
|
24
|
+
## Where it lives
|
|
25
|
+
|
|
26
|
+
- `bmad-docs/memory/` — project memory, git-ignored, **per developer** (yours only)
|
|
27
|
+
- `bmad-docs/memory/MEMORY.md` — the index; open it to see what the agents know
|
|
28
|
+
- `~/.claude/personalization.md` — your cross-project developer profile
|
|
29
|
+
|
|
30
|
+
**Moving to a new PC?** Copy `bmad-docs/memory/` and `~/.claude/personalization.md` to the same paths.
|
|
31
|
+
|
|
32
|
+
## Troubleshooting
|
|
33
|
+
|
|
34
|
+
Every action and skip reason is logged to:
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
~/.claude/bmad-hooks/bmad_hooks_debug.log
|
|
38
|
+
```
|
|
@@ -12,8 +12,7 @@ Stella is an AI-powered development workflow system that guides you through the
|
|
|
12
12
|
|
|
13
13
|
- **Node.js 20+** — [nodejs.org](https://nodejs.org)
|
|
14
14
|
- **Claude Code CLI** — [setup guide](https://docs.anthropic.com/claude/docs/claude-code)
|
|
15
|
-
- **Atlassian account** — JIRA access + API token ([create
|
|
16
|
-
- **GitHub personal access token** _(optional)_ — fine-grained, for PR review integration ([create token](https://github.com/settings/personal-access-tokens))
|
|
15
|
+
- **Atlassian account** — JIRA access + API token ([how to create](atlassian-token-guide.md))
|
|
17
16
|
- **Confluence architecture page** _(optional)_ — for auto-loading coding standards, tech stack, project structure
|
|
18
17
|
|
|
19
18
|
### Install
|
|
@@ -93,24 +92,19 @@ Enter **y**. To be notified upon Claude events like when your permission is requ
|
|
|
93
92
|
|
|
94
93
|
```
|
|
95
94
|
? Which MCP servers do you want to configure:
|
|
96
|
-
(*) Atlassian (for JIRA integration)
|
|
97
|
-
(*) GitHub (for repository, issue, and PR integration)
|
|
95
|
+
(*) Atlassian (for JIRA & Confluence integration)
|
|
98
96
|
( ) Other (custom MCP server)
|
|
99
97
|
```
|
|
100
98
|
|
|
101
|
-
|
|
99
|
+
Atlassian is pre-selected. Press **ENTER**.
|
|
102
100
|
|
|
103
101
|
- **Atlassian:**
|
|
104
102
|
- **If not configured:** asks for your JIRA instance URL. Example: `https://stellaint.atlassian.net`
|
|
105
103
|
- **If already configured:** skips the prompt and shows authentication status.
|
|
106
104
|
|
|
107
|
-
- **GitHub:**
|
|
108
|
-
- **First-time setup:** asks for a fine-grained Personal Access Token ([create token](https://github.com/settings/personal-access-tokens)). Verified against GitHub, then stored in a git-ignored `.env` (mode 0600).
|
|
109
|
-
- **If a token already exists:** press **ENTER** to reuse it, or **n** to enter a fresh one.
|
|
110
|
-
|
|
111
105
|
**8. Jira API credentials**
|
|
112
106
|
|
|
113
|
-
Used by the Jira attachment helper to download ticket images and PDFs. Stored in
|
|
107
|
+
Used by the Jira attachment helper to download ticket images and PDFs. Stored in git-ignored `bmad-docs/.bmad-tokens/.env` (mode 0600).
|
|
114
108
|
|
|
115
109
|
- **First-time setup:**
|
|
116
110
|
|
|
@@ -128,7 +122,7 @@ Used by the Jira attachment helper to download ticket images and PDFs. Stored in
|
|
|
128
122
|
|
|
129
123
|
[Create a token here](https://id.atlassian.com/manage-profile/security/api-tokens).
|
|
130
124
|
|
|
131
|
-
- **If credentials already exist in
|
|
125
|
+
- **If credentials already exist in `bmad-docs/.bmad-tokens/.env`:**
|
|
132
126
|
|
|
133
127
|
```
|
|
134
128
|
✓ Detected existing credentials (you@stellainternational.com → https://stellaint.atlassian.net).
|
|
@@ -143,15 +137,15 @@ Installation completes with a summary of installed components.
|
|
|
143
137
|
|
|
144
138
|
### What Gets Installed Where
|
|
145
139
|
|
|
146
|
-
| Location | What
|
|
147
|
-
| ------------------------------ |
|
|
148
|
-
| `.bmad-core/` | Agents, tasks, templates, `core-config.yaml`
|
|
149
|
-
| `bmad-docs/` | Plans, QA reports,
|
|
150
|
-
| `bmad-docs/.bmad-tokens/.env` | JIRA
|
|
151
|
-
| `.claude/settings.local.json` | BMad permissions allowlist + project hooks
|
|
152
|
-
| `.claude/bmad-hooks/` | Friction logger (BMAD-LOGS) + prompt hooks (project-level)
|
|
153
|
-
| `~/.claude/bmad-hooks/` | Notification + personalization hooks (user-wide)
|
|
154
|
-
| `~/.claude/personalization.md` | Your developer profile, seeded from git config
|
|
140
|
+
| Location | What |
|
|
141
|
+
| ------------------------------ | ------------------------------------------------------------ |
|
|
142
|
+
| `.bmad-core/` | Agents, tasks, templates, `core-config.yaml` |
|
|
143
|
+
| `bmad-docs/` | Plans, QA reports, logs, memory — git-ignored, per developer |
|
|
144
|
+
| `bmad-docs/.bmad-tokens/.env` | JIRA API credentials (git-ignored, mode 0600) |
|
|
145
|
+
| `.claude/settings.local.json` | BMad permissions allowlist + project hooks |
|
|
146
|
+
| `.claude/bmad-hooks/` | Friction logger (BMAD-LOGS) + prompt hooks (project-level) |
|
|
147
|
+
| `~/.claude/bmad-hooks/` | Notification + personalization hooks (user-wide) |
|
|
148
|
+
| `~/.claude/personalization.md` | Your developer profile, seeded from git config |
|
|
155
149
|
|
|
156
150
|
### Post-Installation
|
|
157
151
|
|
|
@@ -162,9 +156,7 @@ Required before using the planner agent.
|
|
|
162
156
|
1. Open Claude Code in your project directory
|
|
163
157
|
2. Run `/mcp`
|
|
164
158
|
3. Select **Atlassian** → follow the OAuth redirect → grant JIRA + Confluence access
|
|
165
|
-
4. Verify **Atlassian**
|
|
166
|
-
|
|
167
|
-
GitHub needs no OAuth — it authenticates with the token stored during installation. If it shows disconnected, the token is missing or expired — re-run `npx bmad-stella install` to set a fresh one.
|
|
159
|
+
4. Verify **Atlassian** shows **Connected**
|
|
168
160
|
|
|
169
161
|
### Troubleshooting
|
|
170
162
|
|
|
@@ -176,7 +168,6 @@ GitHub needs no OAuth — it authenticates with the token stored during installa
|
|
|
176
168
|
| Architecture docs not loading | Re-authenticate: `/mcp` → Atlassian → Re-authenticate |
|
|
177
169
|
| Agent files not found | Re-run `npx bmad-stella install` |
|
|
178
170
|
| Jira attachments not loading | Check all credentials in `bmad-docs/.bmad-tokens/.env` (`JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`). If the token expired, [create a new one](https://id.atlassian.com/manage-profile/security/api-tokens) and update the file. |
|
|
179
|
-
| GitHub MCP disconnected | Token expired or revoked — regenerate ([create token](https://github.com/settings/personal-access-tokens)) and update `GITHUB_PERSONAL_ACCESS_TOKEN` in `bmad-docs/.bmad-tokens/.env`, or re-run `npx bmad-stella install` |
|
|
180
171
|
| No desktop notifications | Re-run `npx bmad-stella install` and accept the notification prompt |
|
|
181
172
|
|
|
182
173
|
---
|
|
@@ -208,7 +199,7 @@ Planner → Dev → QA → Security → Reviewer
|
|
|
208
199
|
|
|
209
200
|
**Must-Use Commands:**
|
|
210
201
|
|
|
211
|
-
- `*retrieve-ticket-
|
|
202
|
+
- `*retrieve-ticket-information` - Fetch JIRA ticket details (JIRA path)
|
|
212
203
|
- `*capture-requirements` - Capture requirements from non-JIRA sources (.md, .txt, direct instruction)
|
|
213
204
|
- `*draft-plan` - Create implementation plan
|
|
214
205
|
- `*implement-task` - Execute planned tasks
|
|
@@ -229,6 +220,8 @@ Planner → Dev → QA → Security → Reviewer
|
|
|
229
220
|
- `*risk-profile` - Assess risks for complex stories
|
|
230
221
|
- `*pr-review` - Review a GitHub PR against its requirements (reviewer, read-only)
|
|
231
222
|
- `*ask` / `*explain` / `*decide` - Query project knowledge (domain expert)
|
|
223
|
+
- `*search` / `*status` - Search loaded docs / show which docs are loaded (domain expert)
|
|
224
|
+
- `*decompose-task` - Break a complex task into detailed subtasks (planner)
|
|
232
225
|
- `*onboard` - Guided project onboarding for new developers (domain expert)
|
|
233
226
|
- `*reload` - Refresh domain knowledge from Confluence (domain expert)
|
|
234
227
|
- `*quick-flow` - Run full dev cycle in one session (quick-dev)
|
|
@@ -245,7 +238,7 @@ Planner → Dev → QA → Security → Reviewer
|
|
|
245
238
|
```mermaid
|
|
246
239
|
graph TD
|
|
247
240
|
A["Start Development"] --> A1{"Source?"}
|
|
248
|
-
A1 -->|JIRA Ticket| B["Planner: *retrieve-ticket-
|
|
241
|
+
A1 -->|JIRA Ticket| B["Planner: *retrieve-ticket-information"]
|
|
249
242
|
A1 -->|Non-JIRA<br/>(.md / .txt / direct)| B2["Planner: *capture-requirements"]
|
|
250
243
|
B --> C["Planner: *draft-plan"]
|
|
251
244
|
B2 --> C
|
|
@@ -345,7 +338,7 @@ graph TD
|
|
|
345
338
|
```bash
|
|
346
339
|
# 1. Planning Phase (in Claude Code CLI)
|
|
347
340
|
/planner
|
|
348
|
-
*retrieve-ticket-
|
|
341
|
+
*retrieve-ticket-information PROJ-123
|
|
349
342
|
*draft-plan {task-file}
|
|
350
343
|
# For complex/high-risk stories, add risk assessment:
|
|
351
344
|
# *risk-profile bmad-docs/impl-plan/PROJ-123-plan.md
|
|
@@ -403,7 +396,7 @@ graph TD
|
|
|
403
396
|
```bash
|
|
404
397
|
# 1. Planning (in Claude Code CLI)
|
|
405
398
|
/planner
|
|
406
|
-
*retrieve-ticket-
|
|
399
|
+
*retrieve-ticket-information BUG-789
|
|
407
400
|
*draft-plan {task-file}
|
|
408
401
|
*validate-plan bmad-docs/impl-plan/BUG-789-plan.md
|
|
409
402
|
|
|
@@ -588,7 +581,7 @@ Use for small, well-scoped work where switching between four agents adds unneces
|
|
|
588
581
|
| **Attachments not auto-loaded into plan** | Jira API credentials missing, invalid, or `bmad-docs/.bmad-tokens/.env` not present | Run `npx bmad-stella install` to refresh credentials, or create `bmad-docs/.bmad-tokens/.env` with `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`. Verify with `node .bmad-core/utils/jira-attachments --self-test` |
|
|
589
582
|
| **`Authentication failed (401)` from helper** | Expired or revoked Atlassian API token | Regenerate token at https://id.atlassian.com/manage-profile/security/api-tokens → Update `JIRA_API_TOKEN` in `bmad-docs/.bmad-tokens/.env` → Retry |
|
|
590
583
|
| **Agent cannot find plan file** | Plan file path incorrect or not created | Ensure plan exists in `bmad-docs/impl-plan/{PLAN-ID}-plan.md` → Provide full path |
|
|
591
|
-
| **Tests failing during validation** | Implementation mismatch or incorrect test scenarios | Review test failure messages → Verify implementation matches requirements → Use `/dev` then `*review-qa` → Use `/qa` then `*run-tests` to verify fixes
|
|
584
|
+
| **Tests failing during validation** | Implementation mismatch or incorrect test scenarios | Review test failure messages → Verify implementation matches requirements → Use `/dev` then `*review-qa-security` → Use `/qa` then `*run-tests` to verify fixes |
|
|
592
585
|
| **Dev agent HALTs** | Unapproved dependency, ambiguous requirements, 3+ failures, missing config, or failing regression | Address blocking issue (approve dependency, clarify requirements, provide config, fix tests) → Resume |
|
|
593
586
|
| **`*run-tests` shows no tests** | Test design or implementation not completed | Run `/qa` → `*test-design` → `*implement-test` → Then `*run-tests` |
|
|
594
587
|
| **Architecture docs not loading** | Install-time prefetch skipped (no Atlassian credentials) and Atlassian MCP not authenticated, or incorrect Confluence URL | `/mcp` → Atlassian → Re-authenticate → Verify Confluence URL in core-config.yaml → Re-run `/planner` activation (or delete `bmad-docs/architecture/` and re-run `npx bmad-stella install`) |
|
|
@@ -606,17 +599,18 @@ Use for small, well-scoped work where switching between four agents adds unneces
|
|
|
606
599
|
**Agent:** Alex - Senior Implementation Planner
|
|
607
600
|
**Icon:** 🎯
|
|
608
601
|
|
|
609
|
-
| Command
|
|
610
|
-
|
|
|
611
|
-
| `*help`
|
|
612
|
-
| `*retrieve-ticket-
|
|
613
|
-
| `*capture-requirements`
|
|
614
|
-
| `*identify-dependencies`
|
|
615
|
-
| `*draft-plan`
|
|
616
|
-
| `*
|
|
617
|
-
| `*
|
|
618
|
-
| `*
|
|
619
|
-
| `*
|
|
602
|
+
| Command | Purpose | When to Use | Files Created/Modified | Parameters |
|
|
603
|
+
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
|
|
604
|
+
| `*help` | Display all available commands | When starting planner agent or need command list | None | None |
|
|
605
|
+
| `*retrieve-ticket-information` | Fetch JIRA ticket details via Atlassian MCP | **First step (JIRA path)** in planning workflow. Use when you have a JIRA ticket number or URL and need to gather requirements, acceptance criteria, and attachments before planning | None (displays ticket info for validation) | `{ticket-number-or-url}` - JIRA ticket ID (e.g., PROJ-123) or full URL |
|
|
606
|
+
| `*capture-requirements` | Capture requirements from non-JIRA sources (direct text, .md, or .txt) and prepare for planning | **First step (non-JIRA path)** in planning workflow. Use when work originates from a brief, internal doc, or direct ask. Asks for screenshots, Plan ID, and confirms type (Bug/Feature/Migration) before handoff to `*draft-plan` | None (displays prepared summary for validation) | `{input}` - Direct text (quoted) OR path to a `.md`/`.txt` file |
|
|
607
|
+
| `*identify-dependencies` | Find related past tickets, analyze code files modified in past work, and assess code modification requirements for the current ticket | After retrieving ticket info. Use before drafting a plan for complex tasks to understand what past work is related, which files are likely impacted, and what risks or blockers exist early | **Creates:** `bmad-docs/temporary/{TICKET-ID}-dependency-tmp.md` | `{ticket-number-or-url}` - JIRA ticket ID (e.g., PROJ-123) or full URL |
|
|
608
|
+
| `*draft-plan` | Create detailed implementation plan with tasks, technical approach, and dependencies | After retrieving ticket info and validating requirements. Transforms task into actionable plan with step-by-step tasks that junior developers can follow | **Creates:** `bmad-docs/impl-plan/{PLAN-ID}-plan.md` | `{task-file-or-description}` - Task file path or description with Acceptance Criteria |
|
|
609
|
+
| `*decompose-task` | Break down a complex task into detailed subtasks | When a task is too large or vague to plan directly. Produces a detailed subtask breakdown before or during plan drafting | None (displays decomposition for validation) | `{task-file-or-description}` - Task file path or description |
|
|
610
|
+
| `*refine-plan` | Iterate and improve existing implementation plan | When initial plan needs more technical detail, user provides feedback, requirements change, or approach needs adjustment. Supports iterative refinement before dev handoff | **Modifies:** Existing plan file | `{plan-file}` - Path to implementation plan |
|
|
611
|
+
| `*validate-plan` | Run validation checklist on plan completeness | Before handing off to dev agent. Ensures plan has all required sections, clear acceptance criteria, detailed tasks, identified dependencies, and technical decisions documented | None (displays validation results) | `{plan-file}` - Path to implementation plan |
|
|
612
|
+
| `*risk-profile` | Generate risk assessment matrix with mitigation strategies | For complex/high-risk stories: database migrations, schema changes, breaking API changes, multi-integration features, security-sensitive implementations, or stories affecting critical business flows | **Creates:** Risk assessment section in plan or separate assessment file | `{story}` - Story/plan reference |
|
|
613
|
+
| `*exit` | Exit planner agent mode | When planning phase is complete and plan is validated | None | None |
|
|
620
614
|
|
|
621
615
|
---
|
|
622
616
|
|
|
@@ -626,14 +620,14 @@ Use for small, well-scoped work where switching between four agents adds unneces
|
|
|
626
620
|
**Agent:** Bob - Full Stack Developer
|
|
627
621
|
**Icon:** 💻
|
|
628
622
|
|
|
629
|
-
| Command
|
|
630
|
-
|
|
|
631
|
-
| `*help`
|
|
632
|
-
| `*implement-task`
|
|
633
|
-
| `*comment-plan`
|
|
634
|
-
| `*review-qa`
|
|
635
|
-
| `*explain`
|
|
636
|
-
| `*exit`
|
|
623
|
+
| Command | Purpose | When to Use | Files Created/Modified | Parameters |
|
|
624
|
+
| --------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
|
|
625
|
+
| `*help` | Display all available commands | When starting dev agent or need command list | None | None |
|
|
626
|
+
| `*implement-task` | Execute implementation plan tasks sequentially | **Primary development command.** Use when you have an approved implementation plan and are ready to code. Implements one task at a time, writes tests, runs validations, and HALTs between tasks for user approval | **Modifies:** Implementation plan (checkboxes, Dev Agent Record, Change Log, Status). **Creates/Modifies:** Source code files, test files as specified in plan | None (reads from current implementation plan) |
|
|
627
|
+
| `*comment-plan` | Post implementation summary to JIRA ticket | **ONLY after ticket implementation is FULLY done** - all tasks completed with [x], all validations pass, code complete. Posts formatted comment with completed tasks, technical summary, and acceptance criteria (if not in ticket) to update JIRA stakeholders | None (posts comment to JIRA) | `{plan-file}` - Path to implementation plan |
|
|
628
|
+
| `*review-qa-security` | Apply fixes based on QA and security feedback | When QA identifies bugs, test failures, or coverage gaps, or security audit records violations in the plan. Systematically addresses the feedback. After fixes, must run `/qa` then `*run-tests` to verify corrections | **Modifies:** Source code files, test files, implementation plan Debug Log | None (reads QA/security feedback from plan) |
|
|
629
|
+
| `*explain` | Provide detailed explanation of implementation | When you want to learn and understand what was implemented, why certain decisions were made, and how code works. Educational tool for knowledge transfer | None | None |
|
|
630
|
+
| `*exit` | Exit dev agent mode | When development phase is complete or switching agents | None | None |
|
|
637
631
|
|
|
638
632
|
**CRITICAL Dev Rules:**
|
|
639
633
|
|
|
@@ -726,6 +720,43 @@ Use for small, well-scoped work where switching between four agents adds unneces
|
|
|
726
720
|
|
|
727
721
|
---
|
|
728
722
|
|
|
723
|
+
### Security Agent Commands
|
|
724
|
+
|
|
725
|
+
**Activation (in Claude Code CLI):** `/security`
|
|
726
|
+
**Agent:** Sam - Security Auditor
|
|
727
|
+
**Icon:** 🔒
|
|
728
|
+
|
|
729
|
+
| Command | Purpose | When to Use | Files Created/Modified | Parameters |
|
|
730
|
+
| ----------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------- |
|
|
731
|
+
| `*help` | Display all available commands | When starting security agent or need command list | None | None |
|
|
732
|
+
| `*check-frontend` | Audit frontend security against the plan | After QA approval. Runs the frontend security checklist on files changed during implementation | **Modifies:** plan's Security Violations section (findings only — never edits source) | `{implementation-plan}` - Path to plan file |
|
|
733
|
+
| `*check-backend` | Audit backend security against the plan | After QA approval. Checks authorization coverage, role/permission correctness, auth pipeline and context integrity, audit completeness | **Modifies:** plan's Security Violations section (findings only — never edits source) | `{implementation-plan}` - Path to plan file |
|
|
734
|
+
| `*exit` | Exit security agent mode | When security phase is complete or switching agents | None | None |
|
|
735
|
+
|
|
736
|
+
**Important:** Security never modifies code. Violations land in the plan — fix them with `/dev` then `*review-qa-security`, and re-run both checks until clean.
|
|
737
|
+
|
|
738
|
+
---
|
|
739
|
+
|
|
740
|
+
### Domain Expert Agent Commands
|
|
741
|
+
|
|
742
|
+
**Activation (in Claude Code CLI):** `/domain-expert`
|
|
743
|
+
**Agent:** Sage - Project Knowledge Oracle
|
|
744
|
+
**Icon:** 🧠
|
|
745
|
+
|
|
746
|
+
| Command | Purpose | When to Use | Files Created/Modified | Parameters |
|
|
747
|
+
| ---------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------ |
|
|
748
|
+
| `*help` | Display all available commands | When starting domain expert agent or need command list | None | None |
|
|
749
|
+
| `*ask` | Answer a question from loaded domain-knowledge and architecture docs | Anytime, during any workflow. Answers cite the source document; knowledge gaps are stated instead of guessed | None | `{question}` - Question in quotes |
|
|
750
|
+
| `*explain` | Thorough explanation of a topic, component, API, workflow, or concept | When you need depth on one area. Answers only from loaded docs; offers codebase scan only with permission | None | `{topic}` - Topic in quotes |
|
|
751
|
+
| `*decide` | Recommend a technical/architectural decision based on project patterns | When choosing between approaches. Analyzes the scenario against documented conventions and recommends with reasoning | None | `{scenario}` - Decision scenario in quotes |
|
|
752
|
+
| `*onboard` | Guided project onboarding for new developers | When a new developer joins. Walks through overview, tech stack, architecture, structure, workflow, coding standards, Q&A | None | None |
|
|
753
|
+
| `*search` | Search all loaded documentation for a term or concept | When you need every mention of a keyword across the loaded docs, with context | None | `{term}` - Search term |
|
|
754
|
+
| `*status` | Show which documentation files are currently loaded | To verify what knowledge Sage is answering from, and the configured architecture URL | None | None |
|
|
755
|
+
| `*reload` | Re-fetch all domain knowledge pages fresh from Confluence | After Confluence documentation updates. **WARNING:** deletes and replaces `bmad-docs/domain-knowledge/` | **Replaces:** `bmad-docs/domain-knowledge/` | None |
|
|
756
|
+
| `*exit` | Exit domain expert agent mode | When done querying project knowledge | None | None |
|
|
757
|
+
|
|
758
|
+
---
|
|
759
|
+
|
|
729
760
|
### User-Level Commands
|
|
730
761
|
|
|
731
762
|
These commands are not tied to any agent — run them anytime in Claude Code CLI.
|
|
@@ -743,6 +774,12 @@ When a plan reaches **Ready for Review** or **Ready for Done**, a background hoo
|
|
|
743
774
|
|
|
744
775
|
---
|
|
745
776
|
|
|
777
|
+
### Architecture Conflict Detection
|
|
778
|
+
|
|
779
|
+
During planning, the planner (and quick-dev's planning phase) checks the proposed direction against the architecture docs in `bmad-docs/architecture/` — tech stack, coding standards, project structure. If a conflict is found, you're asked whether it's a **deliberate architecture change** (Confluence is updated first, then local docs re-synced) or the plan should **align with current docs** (planning halts until the direction is revised). Fully automatic, no commands.
|
|
780
|
+
|
|
781
|
+
---
|
|
782
|
+
|
|
746
783
|
### File Creation Summary
|
|
747
784
|
|
|
748
785
|
Everything lands under `bmad-docs/` (git-ignored, per developer):
|
|
@@ -758,7 +795,7 @@ bmad-docs/
|
|
|
758
795
|
├── bmad-logs/ # Friction reports per plan (automatic)
|
|
759
796
|
├── memory/ # Session memory (hooks)
|
|
760
797
|
├── cache/jira/ # Downloaded ticket attachments
|
|
761
|
-
└── .bmad-tokens/.env # JIRA
|
|
798
|
+
└── .bmad-tokens/.env # JIRA API credentials
|
|
762
799
|
```
|
|
763
800
|
|
|
764
801
|
Dev modifies the plan (checkboxes, Dev Agent Record, Change Log) and project source/test files. Reviewer `*review` modifies source directly. QA also writes test files into the project's test directories.
|
|
@@ -774,7 +811,7 @@ Dev modifies the plan (checkboxes, Dev Agent Record, Change Log) and project sou
|
|
|
774
811
|
3. **Don't skip validation** - Catching issues early saves time
|
|
775
812
|
4. **Keep JIRA updated** - Use `*comment-plan` ONCE when ticket is fully complete
|
|
776
813
|
5. **Ask for help** - Every agent has a `*help` command
|
|
777
|
-
6. **Iterate when needed** - Use refine-plan, review-qa as needed
|
|
814
|
+
6. **Iterate when needed** - Use refine-plan, review-qa-security as needed
|
|
778
815
|
7. **Run all tests** - Including regression before marking done
|
|
779
816
|
8. **Document changes** - File List and Change Log matter
|
|
780
817
|
9. **Review before completion** - Final review catches optimizations
|