Compare commits
9 Commits
13408a9325
...
e75f57e73d
| Author | SHA1 | Date |
|---|---|---|
shindo107
|
e75f57e73d | |
Murat K Ozcan
|
eeebf152af | |
Alex Verkhovsky
|
d419ac8a70 | |
Darren Podolak
|
49d284179a | |
|
Darren Podolak
|
594d9854eb | |
|
Darren Podolak
|
9565bef286 | |
|
Darren Podolak
|
54ab3f13d3 | |
|
Darren Podolak
|
c3cf0c1fc6 | |
|
Darren Podolak
|
5247468d98 |
|
|
@ -79,3 +79,6 @@ bmad-custom-src/
|
|||
website/.astro/
|
||||
website/dist/
|
||||
build/
|
||||
|
||||
# Fork-specific documentation (not committed)
|
||||
BUG-TRACKING.md
|
||||
|
|
|
|||
|
|
@ -0,0 +1,536 @@
|
|||
# Bug Tracking Workflow Wireframe
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```
|
||||
COMMANDS:
|
||||
/triage - Triage new bugs from bugs.md
|
||||
/implement bug-NNN - Implement a bug fix
|
||||
/implement feature-N - Implement a feature
|
||||
/verify - List pending verification
|
||||
/verify bug-NNN - Verify and close specific bug
|
||||
/verify all - Batch verify all
|
||||
|
||||
FILES:
|
||||
docs/bugs.md - Human-readable bug tracking
|
||||
docs/bugs.yaml - Agent-readable metadata
|
||||
|
||||
SEVERITY → COMPLEXITY → WORKFLOW ROUTING:
|
||||
┌──────────┬─────────┬─────────┬─────────┬─────────┐
|
||||
│ │ TRIVIAL │ SMALL │ MEDIUM │ COMPLEX │
|
||||
├──────────┼─────────┼─────────┼─────────┼─────────┤
|
||||
│ CRITICAL │ correct-course (any complexity) │
|
||||
├──────────┼─────────┼─────────┼─────────┼─────────┤
|
||||
│ HIGH │direct-fx│tech-spec│corr-crs │corr-crs │
|
||||
├──────────┼─────────┼─────────┼─────────┼─────────┤
|
||||
│ MEDIUM │direct-fx│tech-spec│corr-crs │corr-crs │
|
||||
├──────────┼─────────┼─────────┼─────────┼─────────┤
|
||||
│ LOW │direct-fx│ backlog │ backlog │ backlog │
|
||||
└──────────┴─────────┴─────────┴─────────┴─────────┘
|
||||
|
||||
SEVERITY:
|
||||
critical - Core broken, crashes, data loss
|
||||
high - Major feature blocked, workaround exists
|
||||
medium - Partial breakage, minor impact
|
||||
low - Cosmetic, edge case
|
||||
|
||||
COMPLEXITY:
|
||||
trivial - One-liner, minimal change
|
||||
small - Single file change
|
||||
medium - Multi-file change
|
||||
complex - Architectural change
|
||||
|
||||
STATUS FLOW:
|
||||
reported → triaged → [routed] → in-progress → fixed/implemented → verified → closed
|
||||
|
||||
STATUS VALUES:
|
||||
triaged - Analyzed, routed, awaiting implementation
|
||||
routed - Sent to tech-spec or correct-course workflow
|
||||
in-progress - Developer actively working
|
||||
fixed - Code complete, awaiting verification (bugs)
|
||||
implemented - Code complete, awaiting verification (features)
|
||||
closed - Verified and closed
|
||||
backlog - Deferred to future sprint
|
||||
blocked - Cannot proceed until issue resolved
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part 1: System Architecture
|
||||
|
||||
### System Overview
|
||||
|
||||
```
|
||||
INPUT SOURCES
|
||||
+-------------------+ +-------------------+ +-------------------+
|
||||
| IN-APP MODAL | | MANUAL ENTRY | | EXTERNAL ISSUE |
|
||||
| (Optional API) | | (bugs.md) | | TRACKER IMPORT |
|
||||
+--------+----------+ +--------+----------+ +--------+----------+
|
||||
| | |
|
||||
+------------+------------+-------------------------+
|
||||
|
|
||||
v
|
||||
+============================+
|
||||
| /triage (WORKFLOW) |
|
||||
+============================+
|
||||
|
|
||||
+---------------+---------------+---------------+
|
||||
| | | |
|
||||
v v v v
|
||||
direct-fix tech-spec correct-course backlog
|
||||
| | | |
|
||||
v v v v
|
||||
/implement /tech-spec /correct-course (deferred)
|
||||
| | |
|
||||
+---------------+---------------+
|
||||
|
|
||||
v
|
||||
/verify → CLOSED
|
||||
```
|
||||
|
||||
### File Architecture
|
||||
|
||||
```
|
||||
{project-root}/
|
||||
docs/
|
||||
bugs.md <-- User-facing: informal bug reports & tracking
|
||||
bugs.yaml <-- Agent-facing: structured metadata database
|
||||
epics.md <-- Context: for mapping bugs to stories
|
||||
_bmad/bmm/
|
||||
config.yaml <-- Project configuration
|
||||
workflows/
|
||||
bug-tracking/ <-- Triage workflow files
|
||||
implement/ <-- Implementation workflow
|
||||
verify/ <-- Verification workflow
|
||||
```
|
||||
|
||||
### bugs.md Structure
|
||||
|
||||
```markdown
|
||||
# Bug Tracking - {project_name}
|
||||
|
||||
# manual input
|
||||
## Bug: Login fails on iOS Safari
|
||||
Description of the bug...
|
||||
Reported by: User Name
|
||||
Date: 2025-01-15
|
||||
|
||||
- **Crash on startup (Android)**: App crashes immediately. CRITICAL.
|
||||
|
||||
1. Form validation missing - No validation on email field
|
||||
|
||||
---
|
||||
|
||||
# Tracked Bugs
|
||||
### bug-001: Login fails on iOS Safari
|
||||
Brief description...
|
||||
- **Severity:** high
|
||||
- **Complexity:** small
|
||||
- **Workflow:** tech-spec
|
||||
- **Related:** story-2-3
|
||||
**Notes:** Triage reasoning...
|
||||
|
||||
---
|
||||
|
||||
# Tracked Feature Requests
|
||||
### feature-001: Dark mode toggle
|
||||
Brief description...
|
||||
- **Priority:** medium
|
||||
- **Complexity:** medium
|
||||
- **Workflow:** tech-spec
|
||||
|
||||
---
|
||||
|
||||
# Fixed Bugs
|
||||
[IMPLEMENTED] bug-003: Header alignment [Sev: low, Fixed: 2025-01-18, Verified: pending]
|
||||
- Fix: Adjusted flexbox styling
|
||||
- File(s): src/components/Header.tsx
|
||||
|
||||
bug-002: Form submission error [Sev: medium, Fixed: 2025-01-15, Verified: 2025-01-16, CLOSED]
|
||||
- Fix: Added error boundary
|
||||
|
||||
---
|
||||
|
||||
# Implemented Features
|
||||
[IMPLEMENTED] feature-002: Export to CSV [Impl: 2025-01-20, Verified: pending]
|
||||
- Files: src/export.ts, src/utils/csv.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part 2: Workflow Operations
|
||||
|
||||
### Slash Command Reference
|
||||
|
||||
| Command | Description | When to Use |
|
||||
|---------|-------------|-------------|
|
||||
| `/triage` | Main workflow - triage user-reported bugs | When new bugs are in bugs.md |
|
||||
| `/implement bug-NNN` | Implement a specific bug fix | After triage, routed for direct-fix |
|
||||
| `/implement feature-NNN` | Implement a feature request | After feature is triaged |
|
||||
| `/verify` | List all pending verification | After implementation, before closing |
|
||||
| `/verify bug-NNN` | Verify and close specific bug | After testing confirms fix works |
|
||||
| `/verify all` | Batch verify all pending items | Bulk close multiple fixes |
|
||||
|
||||
### /triage Workflow
|
||||
|
||||
```
|
||||
USER INVOKES: /triage
|
||||
|
|
||||
v
|
||||
+---------------------------+
|
||||
| STEP 1: INITIALIZATION |
|
||||
+---------------------------+
|
||||
| - Load config.yaml |
|
||||
| - Check for bugs.yaml |
|
||||
| - Detect existing session |
|
||||
+------------+--------------+
|
||||
|
|
||||
+--------+--------+
|
||||
| |
|
||||
v v
|
||||
+-------------+ +-------------+
|
||||
| Has pending | | Fresh start |
|
||||
| triaged work| +------+------+
|
||||
+------+------+ |
|
||||
| v
|
||||
v +-------------+
|
||||
+-------------+ | Scan manual |
|
||||
| Show status | | input section|
|
||||
| [T/I/V/L/Q] | +------+------+
|
||||
+-------------+ |
|
||||
v
|
||||
+-------------+
|
||||
| [S/C/Q] |
|
||||
| Sync/Cont/Q |
|
||||
+------+------+
|
||||
|
|
||||
+---------------+---------------+
|
||||
v v v
|
||||
[S] API Sync [C] Continue [Q] Quit
|
||||
|
||||
+---------------------------+
|
||||
| STEP 2: API SYNC | (Optional - if [S] selected)
|
||||
+---------------------------+
|
||||
| GET /api/bug-reports/pending
|
||||
| - Fetch, format, insert to bugs.md
|
||||
| - POST /mark-synced
|
||||
+---------------------------+
|
||||
|
||||
+---------------------------+
|
||||
| STEP 3: PARSE |
|
||||
+---------------------------+
|
||||
| Read "# manual input" only
|
||||
| - Parse headers, bullets, numbered lists
|
||||
| - Extract: title, desc, reporter, platform
|
||||
| - Compare with bugs.yaml (NEW vs EXISTING)
|
||||
+------------+--------------+
|
||||
|
|
||||
+--------+--------+
|
||||
v v
|
||||
No new bugs {N} new bugs
|
||||
[HALT] [C] Continue
|
||||
|
|
||||
v
|
||||
+---------------------------+
|
||||
| STEP 4: TRIAGE (per bug) |
|
||||
+---------------------------+
|
||||
| FOR EACH NEW BUG:
|
||||
| 1. Generate bug-NNN ID
|
||||
| 2. Assess SEVERITY (critical|high|med|low)
|
||||
| 3. Assess COMPLEXITY (trivial|small|med|complex)
|
||||
| 4. Apply ROUTING MATRIX → workflow
|
||||
| 5. Map to story/epic if applicable
|
||||
| 6. Assess DOC IMPACT (prd|architecture|ux)
|
||||
| 7. Add triage notes
|
||||
| 8. Present: [A]ccept/[M]odify/[S]kip/[N]ext
|
||||
+---------------------------+
|
||||
|
|
||||
v (after all bugs)
|
||||
+---------------------------+
|
||||
| STEP 5: UPDATE FILES |
|
||||
+---------------------------+
|
||||
| bugs.yaml: Add entries, update stats
|
||||
| bugs.md: Remove from manual input,
|
||||
| Add to Tracked Bugs/Features
|
||||
+---------------------------+
|
||||
|
|
||||
v
|
||||
+---------------------------+
|
||||
| STEP 6: COMPLETE |
|
||||
+---------------------------+
|
||||
| Show summary + next steps:
|
||||
| /implement bug-NNN
|
||||
| /verify bug-NNN
|
||||
+---------------------------+
|
||||
```
|
||||
|
||||
### /implement Workflow
|
||||
|
||||
```
|
||||
USER INVOKES: /implement bug-NNN
|
||||
|
|
||||
v
|
||||
+-------------------------------+
|
||||
| STEP 1-2: Load Context |
|
||||
+-------------------------------+
|
||||
| - Parse ID (bug-NNN/feature-NNN)
|
||||
| - Load from bugs.yaml
|
||||
| - Check status (halt if backlog/blocked/deferred)
|
||||
+---------------+---------------+
|
||||
|
|
||||
v
|
||||
+-------------------------------+
|
||||
| STEP 3: Check Workflow Route |
|
||||
+-------------------------------+
|
||||
|
|
||||
+-----------+-----------+-----------+
|
||||
v v v v
|
||||
correct- tech-spec direct-fix ambiguous
|
||||
course |
|
||||
| | | Apply Matrix
|
||||
v v |
|
||||
[ROUTES TO [ROUTES TO |
|
||||
/correct- /tech-spec |
|
||||
course] workflow] |
|
||||
| | |
|
||||
v v v
|
||||
Creates Creates +--------+
|
||||
story spec | STEP 4:|
|
||||
| Confirm|
|
||||
+---+----+
|
||||
|
|
||||
v
|
||||
+---------------+
|
||||
| STEP 5: |
|
||||
| IMPLEMENT |
|
||||
+---------------+
|
||||
| Dev Agent: |
|
||||
| - Read files |
|
||||
| - Make changes|
|
||||
| - Minimal fix |
|
||||
+-------+-------+
|
||||
|
|
||||
v
|
||||
+---------------+
|
||||
| STEP 6: Check |
|
||||
| npm run check |
|
||||
+-------+-------+
|
||||
|
|
||||
v
|
||||
+---------------+
|
||||
| STEP 7-8: |
|
||||
| Update Files |
|
||||
+---------------+
|
||||
| bugs.yaml: |
|
||||
| status: fixed|
|
||||
| bugs.md: |
|
||||
| [IMPLEMENTED]|
|
||||
+-------+-------+
|
||||
|
|
||||
v
|
||||
+---------------+
|
||||
| STEP 9: |
|
||||
| "Run /verify" |
|
||||
+---------------+
|
||||
```
|
||||
|
||||
### /verify Workflow
|
||||
|
||||
```
|
||||
USER INVOKES: /verify [bug-NNN]
|
||||
|
|
||||
+-----------+-----------+
|
||||
v v
|
||||
+---------------+ +---------------+
|
||||
| No ID given | | ID provided |
|
||||
+-------+-------+ +-------+-------+
|
||||
| |
|
||||
v |
|
||||
+---------------+ |
|
||||
| List pending | |
|
||||
| [IMPLEMENTED] | |
|
||||
| items | |
|
||||
+-------+-------+ |
|
||||
| |
|
||||
+-------+---------------+
|
||||
|
|
||||
v
|
||||
+-------------------------------+
|
||||
| STEP 2: Load & Validate |
|
||||
+-------------------------------+
|
||||
| - Verify status: fixed/implemented
|
||||
| - Check file sync
|
||||
+---------------+---------------+
|
||||
|
|
||||
v
|
||||
+-------------------------------+
|
||||
| STEP 3: Confirm Verification |
|
||||
+-------------------------------+
|
||||
| Show: Title, type, date, files
|
||||
| "Has this been tested?"
|
||||
| [yes | no | skip]
|
||||
+---------------+---------------+
|
||||
|
|
||||
+-----------+-----------+
|
||||
v v v
|
||||
+-------+ +-------+ +-------+
|
||||
| YES | | NO | | SKIP |
|
||||
+---+---+ +---+---+ +---+---+
|
||||
| | |
|
||||
v v v
|
||||
Step 4 Add note Next item
|
||||
"rework"
|
||||
|
||||
+-------------------------------+
|
||||
| STEP 4-5: Update Files |
|
||||
+-------------------------------+
|
||||
| bugs.yaml: status: closed,
|
||||
| verified_date
|
||||
| bugs.md: Remove [IMPLEMENTED],
|
||||
| Add CLOSED tag
|
||||
+-------------------------------+
|
||||
|
|
||||
v
|
||||
+-------------------------------+
|
||||
| STEP 6: Summary |
|
||||
| "bug-NNN VERIFIED and CLOSED" |
|
||||
+-------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part 3: Routing & Agent Delegation
|
||||
|
||||
### Workflow Routing by Type
|
||||
|
||||
| Workflow | Trigger Conditions | Pre-Implement Phase | Implementation Phase |
|
||||
|----------|-------------------|---------------------|---------------------|
|
||||
| **direct-fix** | high/med + trivial | None | Dev Agent in /implement Step 5 |
|
||||
| **tech-spec** | high/med + small | Architect creates spec | /dev-story per spec |
|
||||
| **correct-course** | critical (any) OR med/complex+ OR doc_impact | PM→Architect→SM create story | /dev-story per story |
|
||||
| **backlog** | low + small+ | None (deferred) | Awaits sprint promotion |
|
||||
|
||||
### Agent Responsibilities
|
||||
|
||||
```
|
||||
/triage
|
||||
|
|
||||
v
|
||||
+------------------------+
|
||||
| SM AGENT (Scrum |
|
||||
| Master Facilitator) |
|
||||
+------------------------+
|
||||
| - Runs triage workflow |
|
||||
| - Assesses severity |
|
||||
| - Routes to workflows |
|
||||
+-----------+------------+
|
||||
|
|
||||
+-------------------+-------------------+
|
||||
v v v
|
||||
+------------+ +------------+ +------------+
|
||||
| Direct-Fix | | Tech-Spec | | Correct- |
|
||||
+-----+------+ +-----+------+ | Course |
|
||||
| | +-----+------+
|
||||
v v |
|
||||
+------------+ +------------+ v
|
||||
| DEV AGENT | | ARCHITECT | +------------+
|
||||
| /implement | | /tech-spec | | PM AGENT |
|
||||
| Step 5 | +-----+------+ | + ARCHITECT|
|
||||
+------------+ | | + SM |
|
||||
v +-----+------+
|
||||
+------------+ |
|
||||
| DEV AGENT | v
|
||||
| /dev-story | +------------+
|
||||
+------------+ | DEV AGENT |
|
||||
| /dev-story |
|
||||
+------------+
|
||||
```
|
||||
|
||||
### Doc Impact Routing
|
||||
|
||||
When `doc_impact` flags are detected during /implement:
|
||||
|
||||
| Flag | Agent | Action |
|
||||
|------|-------|--------|
|
||||
| PRD | PM Agent | Update PRD.md |
|
||||
| Architecture | Architect Agent | Update architecture.md |
|
||||
| UX | UX Designer Agent | Update UX specs |
|
||||
|
||||
User is prompted: `[update-docs-first | proceed-anyway | cancel]`
|
||||
|
||||
---
|
||||
|
||||
## Part 4: State & Lifecycle
|
||||
|
||||
### File State Transitions
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════════════════════════════════════
|
||||
DIRECT-FIX TECH-SPEC CORRECT-COURSE BACKLOG
|
||||
═══════════════════════════════════════════════════════════════════════════════
|
||||
|
||||
ENTRY # manual input # manual input # manual input # manual input
|
||||
(informal text) (informal text) (informal text) (informal text)
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
─────────────────────────────────────────────────────────────────────────────────
|
||||
TRIAGE # Tracked Bugs # Tracked Bugs # Tracked Bugs # Tracked Bugs
|
||||
bug-NNN bug-NNN bug-NNN bug-NNN
|
||||
wf: direct-fix wf: tech-spec wf: correct-crs wf: backlog
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ │
|
||||
─────────────────────────────────────────────────────────────────────────────────
|
||||
ROUTE (skip) /tech-spec /correct-course (waiting)
|
||||
creates spec creates story │
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ │
|
||||
─────────────────────────────────────────────────────────────────────────────────
|
||||
CODE /implement /dev-story /dev-story (waiting)
|
||||
Step 5 per spec per story │
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ │
|
||||
─────────────────────────────────────────────────────────────────────────────────
|
||||
IMPL # Fixed Bugs # Fixed Bugs # Fixed Bugs (unchanged)
|
||||
[IMPLEMENTED] [IMPLEMENTED] [IMPLEMENTED] │
|
||||
bug-NNN bug-NNN bug-NNN │
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ │
|
||||
─────────────────────────────────────────────────────────────────────────────────
|
||||
VERIFY /verify /verify /verify (waiting)
|
||||
bug-NNN bug-NNN bug-NNN │
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
─────────────────────────────────────────────────────────────────────────────────
|
||||
DONE CLOSED ✓ CLOSED ✓ CLOSED ✓ WAITING ◷
|
||||
═══════════════════════════════════════════════════════════════════════════════
|
||||
|
||||
FILE STATE SUMMARY:
|
||||
┌──────────┬─────────────────────────────┬──────────────────────────────────┐
|
||||
│ STAGE │ bugs.md │ bugs.yaml │
|
||||
├──────────┼─────────────────────────────┼──────────────────────────────────┤
|
||||
│ Entry │ # manual input │ (no entry) │
|
||||
├──────────┼─────────────────────────────┼──────────────────────────────────┤
|
||||
│ Triage │ → # Tracked Bugs/Features │ status: triaged + metadata │
|
||||
├──────────┼─────────────────────────────┼──────────────────────────────────┤
|
||||
│ Implement│ → # Fixed [IMPLEMENTED] │ status: fixed/implemented │
|
||||
├──────────┼─────────────────────────────┼──────────────────────────────────┤
|
||||
│ Verify │ [IMPLEMENTED] → CLOSED │ status: closed + verified_date │
|
||||
└──────────┴─────────────────────────────┴──────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Optional Extensions
|
||||
|
||||
### In-App Bug Reporting API
|
||||
|
||||
Optional integration for apps with built-in bug reporting UI:
|
||||
|
||||
1. **User submits** via in-app modal → `POST /api/bug-reports`
|
||||
2. **Database stores** with `status: 'new'`
|
||||
3. **During /triage Step 2** (if [S]ync selected):
|
||||
- `GET /api/bug-reports/pending` fetches new reports
|
||||
- Formats as markdown, inserts to `# manual input`
|
||||
- `POST /api/bug-reports/mark-synced` prevents re-fetch
|
||||
|
||||
This is optional - manual entry to bugs.md works without any API.
|
||||
|
|
@ -26,7 +26,7 @@ BMad does not mandate TEA. There are five valid ways to use it (or skip it). Pic
|
|||
2. **TEA-only (Standalone)**
|
||||
- Use TEA on a non-BMad project. Bring your own requirements, acceptance criteria, and environments.
|
||||
- Typical sequence: `*test-design` (system or epic) -> `*atdd` and/or `*automate` -> optional `*test-review` -> `*trace` for coverage and gate decisions.
|
||||
- Run `*framework` or `*ci` only if you want TEA to scaffold the harness or pipeline.
|
||||
- Run `*framework` or `*ci` only if you want TEA to scaffold the harness or pipeline; they work best after you decide the stack/architecture.
|
||||
|
||||
3. **Integrated: Greenfield - BMad Method (Simple/Standard Work)**
|
||||
- Phase 3: system-level `*test-design`, then `*framework` and `*ci`.
|
||||
|
|
@ -48,8 +48,29 @@ BMad does not mandate TEA. There are five valid ways to use it (or skip it). Pic
|
|||
|
||||
If you are unsure, default to the integrated path for your track and adjust later.
|
||||
|
||||
## TEA Command Catalog
|
||||
|
||||
| Command | Primary Outputs | Notes | With Playwright MCP Enhancements |
|
||||
| -------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| `*framework` | Playwright/Cypress scaffold, `.env.example`, `.nvmrc`, sample specs | Use when no production-ready harness exists | - |
|
||||
| `*ci` | CI workflow, selective test scripts, secrets checklist | Platform-aware (GitHub Actions default) | - |
|
||||
| `*test-design` | Combined risk assessment, mitigation plan, and coverage strategy | Risk scoring + optional exploratory mode | **+ Exploratory**: Interactive UI discovery with browser automation (uncover actual functionality) |
|
||||
| `*atdd` | Failing acceptance tests + implementation checklist | TDD red phase + optional recording mode | **+ Recording**: AI generation verified with live browser (accurate selectors from real DOM) |
|
||||
| `*automate` | Prioritized specs, fixtures, README/script updates, DoD summary | Optional healing/recording, avoid duplicate coverage | **+ Healing**: Pattern fixes enhanced with visual debugging + **+ Recording**: AI verified with live browser |
|
||||
| `*test-review` | Test quality review report with 0-100 score, violations, fixes | Reviews tests against knowledge base patterns | - |
|
||||
| `*nfr-assess` | NFR assessment report with actions | Focus on security/performance/reliability | - |
|
||||
| `*trace` | Phase 1: Coverage matrix, recommendations. Phase 2: Gate decision (PASS/CONCERNS/FAIL/WAIVED) | Two-phase workflow: traceability + gate decision | - |
|
||||
|
||||
## TEA Workflow Lifecycle
|
||||
|
||||
**Phase Numbering Note:** BMad uses a 4-phase methodology with optional Phase 1 and a documentation prerequisite:
|
||||
|
||||
- **Documentation** (Optional for brownfield): Prerequisite using `*document-project`
|
||||
- **Phase 1** (Optional): Discovery/Analysis (`*brainstorm`, `*research`, `*product-brief`)
|
||||
- **Phase 2** (Required): Planning (`*prd` creates PRD with FRs/NFRs)
|
||||
- **Phase 3** (Track-dependent): Solutioning (`*architecture` → `*test-design` (system-level) → `*create-epics-and-stories` → TEA: `*framework`, `*ci` → `*implementation-readiness`)
|
||||
- **Phase 4** (Required): Implementation (`*sprint-planning` → per-epic: `*test-design` → per-story: dev workflows)
|
||||
|
||||
TEA integrates into the BMad development lifecycle during Solutioning (Phase 3) and Implementation (Phase 4):
|
||||
|
||||
```mermaid
|
||||
|
|
@ -132,62 +153,25 @@ graph TB
|
|||
style Waived fill:#9c27b0,stroke:#4a148c,stroke-width:3px,color:#000
|
||||
```
|
||||
|
||||
**Phase Numbering Note:** BMad uses a 4-phase methodology with optional Phase 1 and documentation prerequisite:
|
||||
|
||||
- **Documentation** (Optional for brownfield): Prerequisite using `*document-project`
|
||||
- **Phase 1** (Optional): Discovery/Analysis (`*brainstorm`, `*research`, `*product-brief`)
|
||||
- **Phase 2** (Required): Planning (`*prd` creates PRD with FRs/NFRs)
|
||||
- **Phase 3** (Track-dependent): Solutioning (`*architecture` → `*test-design` (system-level) → `*create-epics-and-stories` → TEA: `*framework`, `*ci` → `*implementation-readiness`)
|
||||
- **Phase 4** (Required): Implementation (`*sprint-planning` → per-epic: `*test-design` → per-story: dev workflows)
|
||||
|
||||
**TEA workflows:** `*framework` and `*ci` run once in Phase 3 after architecture. `*test-design` is **dual-mode**:
|
||||
|
||||
- **System-level (Phase 3):** Run immediately after architecture/ADR drafting to produce `test-design-system.md` (testability review, ADR → test mapping, Architecturally Significant Requirements (ASRs), environment needs). Feeds the implementation-readiness gate.
|
||||
- **Epic-level (Phase 4):** Run per-epic to produce `test-design-epic-N.md` (risk, priorities, coverage plan).
|
||||
|
||||
Quick Flow track skips Phases 1 and 3.
|
||||
The Quick Flow track skips Phases 1 and 3.
|
||||
BMad Method and Enterprise use all phases based on project needs.
|
||||
When an ADR or architecture draft is produced, run `*test-design` in **system-level** mode before the implementation-readiness gate. This ensures the ADR has an attached testability review and ADR → test mapping. Keep the test-design updated if ADRs change.
|
||||
|
||||
## Why TEA is Different from Other BMM Agents
|
||||
## Why TEA Is Different from Other BMM Agents
|
||||
|
||||
TEA is the only BMM agent that operates in **multiple phases** (Phase 3 and Phase 4) and has its own **knowledge base architecture**.
|
||||
|
||||
### Phase-Specific Agents (Standard Pattern)
|
||||
|
||||
Most BMM agents work in a single phase:
|
||||
|
||||
- **Phase 1 (Analysis)**: Analyst agent
|
||||
- **Phase 2 (Planning)**: PM agent
|
||||
- **Phase 3 (Solutioning)**: Architect agent
|
||||
- **Phase 4 (Implementation)**: SM, DEV agents
|
||||
|
||||
### TEA: Multi-Phase Quality Agent (Unique Pattern)
|
||||
|
||||
TEA is **the only agent that operates in multiple phases**:
|
||||
|
||||
```
|
||||
Phase 1 (Analysis) → [TEA not typically used]
|
||||
↓
|
||||
Phase 2 (Planning) → [PM defines requirements - TEA not active]
|
||||
↓
|
||||
Phase 3 (Solutioning) → TEA: *framework, *ci (test infrastructure AFTER architecture)
|
||||
↓
|
||||
Phase 4 (Implementation) → TEA: *test-design (per epic: "how do I test THIS feature?")
|
||||
→ TEA: *atdd, *automate, *test-review, *trace (per story)
|
||||
↓
|
||||
Epic/Release Gate → TEA: *nfr-assess, *trace Phase 2 (release decision)
|
||||
```
|
||||
TEA spans multiple phases (Phase 3, Phase 4, and the release gate). Most BMM agents operate in a single phase. That multi-phase role is paired with a dedicated testing knowledge base so standards stay consistent across projects.
|
||||
|
||||
### TEA's 8 Workflows Across Phases
|
||||
|
||||
**Standard agents**: 1-3 workflows per phase
|
||||
**TEA**: 8 workflows across Phase 3, Phase 4, and Release Gate
|
||||
|
||||
| Phase | TEA Workflows | Frequency | Purpose |
|
||||
| ----------- | --------------------------------------------------------- | ---------------- | ---------------------------------------------- |
|
||||
| **Phase 2** | (none) | - | Planning phase - PM defines requirements |
|
||||
| **Phase 3** | \*framework, \*ci | Once per project | Setup test infrastructure AFTER architecture |
|
||||
| **Phase 3** | \*test-design (system-level), \*framework, \*ci | Once per project | System testability review and test infrastructure setup |
|
||||
| **Phase 4** | \*test-design, \*atdd, \*automate, \*test-review, \*trace | Per epic/story | Test planning per epic, then per-story testing |
|
||||
| **Release** | \*nfr-assess, \*trace (Phase 2: gate) | Per epic/release | Go/no-go decision |
|
||||
|
||||
|
|
@ -197,17 +181,17 @@ Epic/Release Gate → TEA: *nfr-assess, *trace Phase 2 (release decision)
|
|||
|
||||
TEA uniquely requires:
|
||||
|
||||
- **Extensive domain knowledge**: 30+ fragments covering test patterns, CI/CD, fixtures, quality practices, and optional playwright-utils integration
|
||||
- **Cross-cutting concerns**: Domain-specific testing patterns that apply across all BMad projects (vs project-specific artifacts like PRDs/stories)
|
||||
- **Optional integrations**: MCP capabilities (exploratory, verification) and playwright-utils support
|
||||
- **Extensive domain knowledge**: Test patterns, CI/CD, fixtures, and quality practices
|
||||
- **Cross-cutting concerns**: Standards that apply across all BMad projects (not just PRDs or stories)
|
||||
- **Optional integrations**: Playwright-utils and MCP enhancements
|
||||
|
||||
This architecture enables TEA to maintain consistent, production-ready testing patterns across all BMad projects while operating across multiple development phases.
|
||||
This architecture lets TEA maintain consistent, production-ready testing patterns while operating across multiple phases.
|
||||
|
||||
## High-Level Cheat Sheets
|
||||
## Track Cheat Sheets (Condensed)
|
||||
|
||||
These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks** across the **4-Phase Methodology** (Phase 1: Analysis, Phase 2: Planning, Phase 3: Solutioning, Phase 4: Implementation).
|
||||
|
||||
**Note:** Quick Flow projects typically don't require TEA (covered in Overview). These cheat sheets focus on BMad Method and Enterprise tracks where TEA adds value.
|
||||
**Note:** The Quick Flow track typically doesn't require TEA (covered in Overview). These cheat sheets focus on BMad Method and Enterprise tracks where TEA adds value.
|
||||
|
||||
**Legend for Track Deltas:**
|
||||
|
||||
|
|
@ -231,39 +215,15 @@ These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks*
|
|||
| **Phase 4**: Story Review | Execute `*test-review` (optional), re-run `*trace` | Address recommendations, update code/tests | Quality report, refreshed coverage matrix |
|
||||
| **Phase 4**: Release Gate | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Confirm Definition of Done, share release notes | Quality audit, Gate YAML + release summary |
|
||||
|
||||
<details>
|
||||
<summary>Execution Notes</summary>
|
||||
|
||||
- Run `*framework` only once per repo or when modern harness support is missing.
|
||||
- **Phase 3 (Solutioning)**: After architecture is complete, run `*framework` and `*ci` to setup test infrastructure based on architectural decisions.
|
||||
- **Phase 4 starts**: After solutioning is complete, sprint planning loads all epics.
|
||||
- **`*test-design` runs per-epic**: At the beginning of working on each epic, run `*test-design` to create a test plan for THAT specific epic/feature. Output: `test-design-epic-N.md`.
|
||||
- Use `*atdd` before coding when the team can adopt ATDD; share its checklist with the dev agent.
|
||||
- Post-implementation, keep `*trace` current, expand coverage with `*automate`, optionally review test quality with `*test-review`. For release gate, run `*trace` with Phase 2 enabled to get deployment decision.
|
||||
- Use `*test-review` after `*atdd` to validate generated tests, after `*automate` to ensure regression quality, or before gate for final audit.
|
||||
- Clarification: `*test-review` is optional and only audits existing tests; run it after `*atdd` or `*automate` when you want a quality review, not as a required step.
|
||||
- Clarification: `*atdd` outputs are not auto-consumed; share the ATDD doc/tests with the dev workflow. `*trace` does not run `*atdd`—it evaluates existing artifacts for coverage and gate readiness.
|
||||
- Clarification: `*ci` is a one-time setup; recommended early (Phase 3 or before feature work), but it can be done later if it was skipped.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Worked Example – “Nova CRM” Greenfield Feature</summary>
|
||||
|
||||
1. **Planning (Phase 2):** Analyst runs `*product-brief`; PM executes `*prd` to produce PRD with FRs/NFRs.
|
||||
2. **Solutioning (Phase 3):** Architect completes `*architecture` for the new module; `*create-epics-and-stories` generates epics/stories based on architecture; TEA sets up test infrastructure via `*framework` and `*ci` based on architectural decisions; gate check validates planning completeness.
|
||||
3. **Sprint Start (Phase 4):** Scrum Master runs `*sprint-planning` to load all epics into sprint status.
|
||||
4. **Epic 1 Planning (Phase 4):** TEA runs `*test-design` to create test plan for Epic 1, producing `test-design-epic-1.md` with risk assessment.
|
||||
5. **Story Implementation (Phase 4):** For each story in Epic 1, SM generates story via `*create-story`; TEA optionally runs `*atdd`; Dev implements with guidance from failing tests.
|
||||
6. **Post-Dev (Phase 4):** TEA runs `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` to refresh coverage.
|
||||
7. **Release Gate:** TEA runs `*trace` with Phase 2 enabled to generate gate decision.
|
||||
|
||||
</details>
|
||||
**Key notes:**
|
||||
- Run `*framework` and `*ci` once in Phase 3 after architecture.
|
||||
- Run `*test-design` per epic in Phase 4; use `*atdd` before dev when helpful.
|
||||
- Use `*trace` for gate decisions; `*test-review` is an optional audit.
|
||||
|
||||
### Brownfield - BMad Method or Enterprise (Simple or Complex)
|
||||
|
||||
**Planning Tracks:** BMad Method or Enterprise Method
|
||||
**Use Case:** Existing codebases - simple additions (BMad Method) or complex enterprise requirements (Enterprise Method)
|
||||
**Use Case:** Existing codebases: simple additions (BMad Method) or complex enterprise requirements (Enterprise Method)
|
||||
|
||||
**🔄 Brownfield Deltas from Greenfield:**
|
||||
|
||||
|
|
@ -284,31 +244,10 @@ These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks*
|
|||
| **Phase 4**: Story Review | Apply `*test-review` (optional), re-run `*trace`, ➕ `*nfr-assess` if needed | Resolve gaps, update docs/tests | Quality report, refreshed coverage matrix, NFR report |
|
||||
| **Phase 4**: Release Gate | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Capture sign-offs, share release notes | Quality audit, Gate YAML + release summary |
|
||||
|
||||
<details>
|
||||
<summary>Execution Notes</summary>
|
||||
|
||||
- Lead with `*trace` during Planning (Phase 2) to baseline existing test coverage before architecture work begins.
|
||||
- **Phase 3 (Solutioning)**: After architecture is complete, run `*framework` and `*ci` to modernize test infrastructure. For brownfield, framework may need to integrate with or replace existing test setup.
|
||||
- **Phase 4 starts**: After solutioning is complete and sprint planning loads all epics.
|
||||
- **`*test-design` runs per-epic**: At the beginning of working on each epic, run `*test-design` to identify regression hotspots, integration risks, and mitigation strategies for THAT specific epic/feature. Output: `test-design-epic-N.md`.
|
||||
- Use `*atdd` when stories benefit from ATDD; otherwise proceed to implementation and rely on post-dev automation.
|
||||
- After development, expand coverage with `*automate`, optionally review test quality with `*test-review`, re-run `*trace` (Phase 2 for gate decision). Run `*nfr-assess` now if non-functional risks weren't addressed earlier.
|
||||
- Use `*test-review` to validate existing brownfield tests or audit new tests before gate.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Worked Example – “Atlas Payments” Brownfield Story</summary>
|
||||
|
||||
1. **Planning (Phase 2):** PM executes `*prd` to create PRD with FRs/NFRs; TEA runs `*trace` to baseline existing coverage.
|
||||
2. **Solutioning (Phase 3):** Architect triggers `*architecture` capturing legacy payment flows and integration architecture; `*create-epics-and-stories` generates Epic 1 (Payment Processing) based on architecture; TEA sets up `*framework` and `*ci` based on architectural decisions; gate check validates planning.
|
||||
3. **Sprint Start (Phase 4):** Scrum Master runs `*sprint-planning` to load Epic 1 into sprint status.
|
||||
4. **Epic 1 Planning (Phase 4):** TEA runs `*test-design` for Epic 1 (Payment Processing), producing `test-design-epic-1.md` that flags settlement edge cases, regression hotspots, and mitigation plans.
|
||||
5. **Story Implementation (Phase 4):** For each story in Epic 1, SM generates story via `*create-story`; TEA runs `*atdd` producing failing Playwright specs; Dev implements with guidance from tests and checklist.
|
||||
6. **Post-Dev (Phase 4):** TEA applies `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` to refresh coverage.
|
||||
7. **Release Gate:** TEA performs `*nfr-assess` to validate SLAs, runs `*trace` with Phase 2 enabled to generate gate decision (PASS/CONCERNS/FAIL).
|
||||
|
||||
</details>
|
||||
**Key notes:**
|
||||
- Start with `*trace` in Phase 2 to baseline coverage.
|
||||
- Focus `*test-design` on regression hotspots and integration risk.
|
||||
- Run `*nfr-assess` before the gate if it wasn't done earlier.
|
||||
|
||||
### Greenfield - Enterprise Method (Enterprise/Compliance Work)
|
||||
|
||||
|
|
@ -332,105 +271,36 @@ These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks*
|
|||
| **Phase 4**: Story Dev | (Optional) `*atdd`, `*automate`, `*test-review`, `*trace` per story | SM `*create-story`, DEV implements | Tests, fixtures, quality reports, coverage matrices |
|
||||
| **Phase 4**: Release Gate | Final `*test-review` audit, Run `*trace` (Phase 2), 📦 archive artifacts | Capture sign-offs, 📦 compliance evidence | Quality audit, updated assessments, gate YAML, 📦 audit trail |
|
||||
|
||||
<details>
|
||||
<summary>Execution Notes</summary>
|
||||
**Key notes:**
|
||||
- Run `*nfr-assess` early in Phase 2.
|
||||
- `*test-design` emphasizes compliance, security, and performance alignment.
|
||||
- Archive artifacts at the release gate for audits.
|
||||
|
||||
- `*nfr-assess` runs early in Planning (Phase 2) to capture compliance, security, and performance requirements upfront.
|
||||
- **Phase 3 (Solutioning)**: After architecture is complete, run `*framework` and `*ci` with enterprise-grade configurations (selective testing, burn-in jobs, caching, notifications).
|
||||
- **Phase 4 starts**: After solutioning is complete and sprint planning loads all epics.
|
||||
- **`*test-design` runs per-epic**: At the beginning of working on each epic, run `*test-design` to create an enterprise-focused test plan for THAT specific epic, ensuring alignment with security architecture, performance targets, and compliance requirements. Output: `test-design-epic-N.md`.
|
||||
- Use `*atdd` for stories when feasible so acceptance tests can lead implementation.
|
||||
- Use `*test-review` per story or sprint to maintain quality standards and ensure compliance with testing best practices.
|
||||
- Prior to release, rerun coverage (`*trace`, `*automate`), perform final quality audit with `*test-review`, and formalize the decision with `*trace` Phase 2 (gate decision); archive artifacts for compliance audits.
|
||||
**Related how-to guides:**
|
||||
- [How to Run Test Design](/docs/how-to/workflows/run-test-design.md)
|
||||
- [How to Set Up a Test Framework](/docs/how-to/workflows/setup-test-framework.md)
|
||||
|
||||
</details>
|
||||
## Optional Integrations
|
||||
|
||||
<details>
|
||||
<summary>Worked Example – “Helios Ledger” Enterprise Release</summary>
|
||||
### Playwright Utils (`@seontechnologies/playwright-utils`)
|
||||
|
||||
1. **Planning (Phase 2):** Analyst runs `*research` and `*product-brief`; PM completes `*prd` creating PRD with FRs/NFRs; TEA runs `*nfr-assess` to establish NFR targets.
|
||||
2. **Solutioning (Phase 3):** Architect completes `*architecture` with enterprise considerations; `*create-epics-and-stories` generates epics/stories based on architecture; TEA sets up `*framework` and `*ci` with enterprise-grade configurations based on architectural decisions; gate check validates planning completeness.
|
||||
3. **Sprint Start (Phase 4):** Scrum Master runs `*sprint-planning` to load all epics into sprint status.
|
||||
4. **Per-Epic (Phase 4):** For each epic, TEA runs `*test-design` to create epic-specific test plan (e.g., `test-design-epic-1.md`, `test-design-epic-2.md`) with compliance-focused risk assessment.
|
||||
5. **Per-Story (Phase 4):** For each story, TEA uses `*atdd`, `*automate`, `*test-review`, and `*trace`; Dev teams iterate on the findings.
|
||||
6. **Release Gate:** TEA re-checks coverage, performs final quality audit with `*test-review`, and logs the final gate decision via `*trace` Phase 2, archiving artifacts for compliance.
|
||||
Production-ready fixtures and utilities that enhance TEA workflows.
|
||||
|
||||
</details>
|
||||
- Install: `npm install -D @seontechnologies/playwright-utils`
|
||||
> Note: Playwright Utils is enabled via the installer. Only set `tea_use_playwright_utils` in `_bmad/bmm/config.yaml` if you need to override the installer choice.
|
||||
- Impacts: `*framework`, `*atdd`, `*automate`, `*test-review`, `*ci`
|
||||
- Utilities include: api-request, auth-session, network-recorder, intercept-network-call, recurse, log, file-utils, burn-in, network-error-monitor, fixtures-composition
|
||||
|
||||
## TEA Command Catalog
|
||||
### Playwright MCP Enhancements
|
||||
|
||||
| Command | Primary Outputs | Notes | With Playwright MCP Enhancements |
|
||||
| -------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| `*framework` | Playwright/Cypress scaffold, `.env.example`, `.nvmrc`, sample specs | Use when no production-ready harness exists | - |
|
||||
| `*ci` | CI workflow, selective test scripts, secrets checklist | Platform-aware (GitHub Actions default) | - |
|
||||
| `*test-design` | Combined risk assessment, mitigation plan, and coverage strategy | Risk scoring + optional exploratory mode | **+ Exploratory**: Interactive UI discovery with browser automation (uncover actual functionality) |
|
||||
| `*atdd` | Failing acceptance tests + implementation checklist | TDD red phase + optional recording mode | **+ Recording**: AI generation verified with live browser (accurate selectors from real DOM) |
|
||||
| `*automate` | Prioritized specs, fixtures, README/script updates, DoD summary | Optional healing/recording, avoid duplicate coverage | **+ Healing**: Pattern fixes enhanced with visual debugging + **+ Recording**: AI verified with live browser |
|
||||
| `*test-review` | Test quality review report with 0-100 score, violations, fixes | Reviews tests against knowledge base patterns | - |
|
||||
| `*nfr-assess` | NFR assessment report with actions | Focus on security/performance/reliability | - |
|
||||
| `*trace` | Phase 1: Coverage matrix, recommendations. Phase 2: Gate decision (PASS/CONCERNS/FAIL/WAIVED) | Two-phase workflow: traceability + gate decision | - |
|
||||
|
||||
## Playwright Utils Integration
|
||||
|
||||
TEA optionally integrates with `@seontechnologies/playwright-utils`, an open-source library providing fixture-based utilities for Playwright tests. This integration enhances TEA's test generation and review workflows with production-ready patterns.
|
||||
|
||||
<details>
|
||||
<summary><strong>Installation & Configuration</strong></summary>
|
||||
|
||||
**Package**: `@seontechnologies/playwright-utils` ([npm](https://www.npmjs.com/package/@seontechnologies/playwright-utils) | [GitHub](https://github.com/seontechnologies/playwright-utils))
|
||||
|
||||
**Install**: `npm install -D @seontechnologies/playwright-utils`
|
||||
|
||||
**Enable during BMAD installation** by answering "Yes" when prompted, or manually set `tea_use_playwright_utils: true` in `_bmad/bmm/config.yaml`.
|
||||
|
||||
**To disable**: Set `tea_use_playwright_utils: false` in `_bmad/bmm/config.yaml`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>How Playwright Utils Enhances TEA Workflows</strong></summary>
|
||||
|
||||
1. `*framework`:
|
||||
- Default: Basic Playwright scaffold
|
||||
- **+ playwright-utils**: Scaffold with api-request, network-recorder, auth-session, burn-in, network-error-monitor fixtures pre-configured
|
||||
|
||||
Benefit: Production-ready patterns from day one
|
||||
|
||||
2. `*automate`, `*atdd`:
|
||||
- Default: Standard test patterns
|
||||
- **+ playwright-utils**: Tests using api-request (schema validation), intercept-network-call (mocking), recurse (polling), log (structured logging), file-utils (CSV/PDF)
|
||||
|
||||
Benefit: Advanced patterns without boilerplate
|
||||
|
||||
3. `*test-review`:
|
||||
- Default: Reviews against core knowledge base (22 fragments)
|
||||
- **+ playwright-utils**: Reviews against expanded knowledge base (33 fragments: 22 core + 11 playwright-utils)
|
||||
|
||||
Benefit: Reviews include fixture composition, auth patterns, network recording best practices
|
||||
|
||||
4. `*ci`:
|
||||
- Default: Standard CI workflow
|
||||
- **+ playwright-utils**: CI workflow with burn-in script (smart test selection) and network-error-monitor integration
|
||||
|
||||
Benefit: Faster CI feedback, HTTP error detection
|
||||
|
||||
**Utilities available** (10 total): api-request, network-recorder, auth-session, intercept-network-call, recurse, log, file-utils, burn-in, network-error-monitor, fixtures-composition
|
||||
|
||||
</details>
|
||||
|
||||
## Playwright MCP Enhancements
|
||||
|
||||
TEA can leverage Playwright MCP servers to enhance test generation with live browser verification. MCP provides interactive capabilities on top of TEA's default AI-based approach.
|
||||
|
||||
<details>
|
||||
<summary><strong>MCP Server Configuration</strong></summary>
|
||||
Live browser verification for test design and automation.
|
||||
|
||||
**Two Playwright MCP servers** (actively maintained, continuously updated):
|
||||
|
||||
- `playwright` - Browser automation (`npx @playwright/mcp@latest`)
|
||||
- `playwright-test` - Test runner with failure analysis (`npx playwright run-test-mcp-server`)
|
||||
|
||||
**Config example**:
|
||||
**Configuration example**:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -447,29 +317,8 @@ TEA can leverage Playwright MCP servers to enhance test generation with live bro
|
|||
}
|
||||
```
|
||||
|
||||
**To disable**: Set `tea_use_mcp_enhancements: false` in `_bmad/bmm/config.yaml` OR remove MCPs from IDE config.
|
||||
- Helps `*test-design` validate actual UI behavior.
|
||||
- Helps `*atdd` and `*automate` verify selectors against the live DOM.
|
||||
- Enhances healing with `browser_snapshot`, console, network, and locator tools.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>How MCP Enhances TEA Workflows</strong></summary>
|
||||
|
||||
1. `*test-design`:
|
||||
- Default: Analysis + documentation
|
||||
- **+ MCP**: Interactive UI discovery with `browser_navigate`, `browser_click`, `browser_snapshot`, behavior observation
|
||||
|
||||
Benefit: Discover actual functionality, edge cases, undocumented features
|
||||
|
||||
2. `*atdd`, `*automate`:
|
||||
- Default: Infers selectors and interactions from requirements and knowledge fragments
|
||||
- **+ MCP**: Generates tests **then** verifies with `generator_setup_page`, `browser_*` tools, validates against live app
|
||||
|
||||
Benefit: Accurate selectors from real DOM, verified behavior, refined test code
|
||||
|
||||
3. `*automate` (healing mode):
|
||||
- Default: Pattern-based fixes from error messages + knowledge fragments
|
||||
- **+ MCP**: Pattern fixes **enhanced with** `browser_snapshot`, `browser_console_messages`, `browser_network_requests`, `browser_generate_locator`
|
||||
|
||||
Benefit: Visual failure context, live DOM inspection, root cause discovery
|
||||
|
||||
</details>
|
||||
**To disable**: set `tea_use_mcp_enhancements: false` in `_bmad/bmm/config.yaml` or remove MCPs from IDE config.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,91 @@
|
|||
<task id="_bmad/core/tasks/editorial-review-prose.xml"
|
||||
name="Editorial Review - Prose"
|
||||
description="Clinical copy-editor that reviews text for communication issues"
|
||||
standalone="false">
|
||||
|
||||
<objective>Review text for communication issues that impede comprehension and output suggested fixes in a three-column table</objective>
|
||||
|
||||
<inputs>
|
||||
<input name="content" required="true" desc="Cohesive unit of text to review (markdown, plain text, or text-heavy XML)" />
|
||||
<input name="reader_type" required="false" default="humans" desc="'humans' (default) for standard editorial, 'llm' for precision focus" />
|
||||
</inputs>
|
||||
|
||||
<llm critical="true">
|
||||
<i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
|
||||
<i>DO NOT skip steps or change the sequence</i>
|
||||
<i>HALT immediately when halt-conditions are met</i>
|
||||
<i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
|
||||
|
||||
<i>You are a clinical copy-editor: precise, professional, neither warm nor cynical</i>
|
||||
<i>Apply Microsoft Writing Style Guide principles as your baseline</i>
|
||||
<i>Focus on communication issues that impede comprehension - not style preferences</i>
|
||||
<i>NEVER rewrite for preference - only fix genuine issues</i>
|
||||
|
||||
<i critical="true">CONTENT IS SACROSANCT: Never challenge ideas—only clarify how they're expressed.</i>
|
||||
|
||||
<principles>
|
||||
<i>Minimal intervention: Apply the smallest fix that achieves clarity</i>
|
||||
<i>Preserve structure: Fix prose within existing structure, never restructure</i>
|
||||
<i>Skip code/markup: Detect and skip code blocks, frontmatter, structural markup</i>
|
||||
<i>When uncertain: Flag with a query rather than suggesting a definitive change</i>
|
||||
<i>Deduplicate: Same issue in multiple places = one entry with locations listed</i>
|
||||
<i>No conflicts: Merge overlapping fixes into single entries</i>
|
||||
<i>Respect author voice: Preserve intentional stylistic choices</i>
|
||||
</principles>
|
||||
|
||||
</llm>
|
||||
|
||||
<flow>
|
||||
<step n="1" title="Validate Input">
|
||||
<action>Check if content is empty or contains fewer than 3 words</action>
|
||||
<action if="empty or fewer than 3 words">HALT with error: "Content too short for editorial review (minimum 3 words required)"</action>
|
||||
<action>Validate reader_type is "humans" or "llm" (or not provided, defaulting to "humans")</action>
|
||||
<action if="reader_type is invalid">HALT with error: "Invalid reader_type. Must be 'humans' or 'llm'"</action>
|
||||
<action>Identify content type (markdown, plain text, XML with text)</action>
|
||||
<action>Note any code blocks, frontmatter, or structural markup to skip</action>
|
||||
</step>
|
||||
|
||||
<step n="2" title="Analyze Style">
|
||||
<action>Analyze the style, tone, and voice of the input text</action>
|
||||
<action>Note any intentional stylistic choices to preserve (informal tone, technical jargon, rhetorical patterns)</action>
|
||||
<action>Calibrate review approach based on reader_type parameter</action>
|
||||
<action if="reader_type='llm'">Prioritize: unambiguous references, consistent terminology, explicit structure, no hedging</action>
|
||||
<action if="reader_type='humans'">Prioritize: clarity, flow, readability, natural progression</action>
|
||||
</step>
|
||||
|
||||
<step n="3" title="Editorial Review" critical="true">
|
||||
<action>Review all prose sections (skip code blocks, frontmatter, structural markup)</action>
|
||||
<action>Identify communication issues that impede comprehension</action>
|
||||
<action>For each issue, determine the minimal fix that achieves clarity</action>
|
||||
<action>Deduplicate: If same issue appears multiple times, create one entry listing all locations</action>
|
||||
<action>Merge overlapping issues into single entries (no conflicting suggestions)</action>
|
||||
<action>For uncertain fixes, phrase as query: "Consider: [suggestion]?" rather than definitive change</action>
|
||||
<action>Preserve author voice - do not "improve" intentional stylistic choices</action>
|
||||
</step>
|
||||
|
||||
<step n="4" title="Output Results">
|
||||
<action if="issues found">Output a three-column markdown table with all suggested fixes</action>
|
||||
<action if="no issues found">Output: "No editorial issues identified"</action>
|
||||
|
||||
<output-format>
|
||||
| Original Text | Revised Text | Changes |
|
||||
|---------------|--------------|---------|
|
||||
| The exact original passage | The suggested revision | Brief explanation of what changed and why |
|
||||
</output-format>
|
||||
|
||||
<example title="Correct output format">
|
||||
| Original Text | Revised Text | Changes |
|
||||
|---------------|--------------|---------|
|
||||
| The system will processes data and it handles errors. | The system processes data and handles errors. | Fixed subject-verb agreement ("will processes" to "processes"); removed redundant "it" |
|
||||
| Users can chose from options (lines 12, 45, 78) | Users can choose from options | Fixed spelling: "chose" to "choose" (appears in 3 locations) |
|
||||
</example>
|
||||
</step>
|
||||
</flow>
|
||||
|
||||
<halt-conditions>
|
||||
<condition>HALT with error if content is empty or fewer than 3 words</condition>
|
||||
<condition>HALT with error if reader_type is not "humans" or "llm"</condition>
|
||||
<condition>If no issues found after thorough review, output "No editorial issues identified" (this is valid completion, not an error)</condition>
|
||||
</halt-conditions>
|
||||
|
||||
</task>
|
||||
|
|
@ -0,0 +1,198 @@
|
|||
<?xml version="1.0"?>
|
||||
<!-- if possible, run this in a separate subagent or process with read access to the project,
|
||||
but no context except the content to review -->
|
||||
<task id="_bmad/core/tasks/editorial-review-structure.xml"
|
||||
name="Editorial Review - Structure"
|
||||
description="Structural editor that proposes cuts, reorganization,
|
||||
and simplification while preserving comprehension"
|
||||
standalone="false">
|
||||
<objective>Review document structure and propose substantive changes
|
||||
to improve clarity and flow-run this BEFORE copy editing</objective>
|
||||
<inputs>
|
||||
<input name="content" required="true"
|
||||
desc="Document to review (markdown, plain text, or structured content)"/>
|
||||
<input name="purpose" required="false"
|
||||
desc="Document's intended purpose (e.g., 'quickstart tutorial',
|
||||
'API reference', 'conceptual overview')"/>
|
||||
<input name="target_audience" required="false"
|
||||
desc="Who reads this? (e.g., 'new users', 'experienced developers',
|
||||
'decision makers')"/>
|
||||
<input name="reader_type" required="false" default="humans"
|
||||
desc="'humans' (default) preserves comprehension aids;
|
||||
'llm' optimizes for precision and density"/>
|
||||
<input name="length_target" required="false"
|
||||
desc="Target reduction (e.g., '30% shorter', 'half the length',
|
||||
'no limit')"/>
|
||||
</inputs>
|
||||
<llm critical="true">
|
||||
<i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
|
||||
<i>DO NOT skip steps or change the sequence</i>
|
||||
<i>HALT immediately when halt-conditions are met</i>
|
||||
<i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
|
||||
<i>You are a structural editor focused on HIGH-VALUE DENSITY</i>
|
||||
<i>Brevity IS clarity: Concise writing respects limited attention spans and enables effective scanning</i>
|
||||
<i>Every section must justify its existence-cut anything that delays understanding</i>
|
||||
<i>True redundancy is failure</i>
|
||||
<principles>
|
||||
<i>Comprehension through calibration: Optimize for the minimum words needed to maintain understanding</i>
|
||||
<i>Front-load value: Critical information comes first; nice-to-know comes last (or goes)</i>
|
||||
<i>One source of truth: If information appears identically twice, consolidate</i>
|
||||
<i>Scope discipline: Content that belongs in a different document should be cut or linked</i>
|
||||
<i>Propose, don't execute: Output recommendations-user decides what to accept</i>
|
||||
<i critical="true">CONTENT IS SACROSANCT: Never challenge ideas—only optimize how they're organized.</i>
|
||||
</principles>
|
||||
<human-reader-principles>
|
||||
<i>These elements serve human comprehension and engagement-preserve unless clearly wasteful:</i>
|
||||
<i>Visual aids: Diagrams, images, and flowcharts anchor understanding</i>
|
||||
<i>Expectation-setting: "What You'll Learn" helps readers confirm they're in the right place</i>
|
||||
<i>Reader's Journey: Organize content biologically (linear progression), not logically (database)</i>
|
||||
<i>Mental models: Overview before details prevents cognitive overload</i>
|
||||
<i>Warmth: Encouraging tone reduces anxiety for new users</i>
|
||||
<i>Whitespace: Admonitions and callouts provide visual breathing room</i>
|
||||
<i>Summaries: Recaps help retention; they're reinforcement, not redundancy</i>
|
||||
<i>Examples: Concrete illustrations make abstract concepts accessible</i>
|
||||
<i>Engagement: "Flow" techniques (transitions, variety) are functional, not "fluff"-they maintain attention</i>
|
||||
</human-reader-principles>
|
||||
<llm-reader-principles>
|
||||
<i>When reader_type='llm', optimize for PRECISION and UNAMBIGUITY:</i>
|
||||
<i>Dependency-first: Define concepts before usage to minimize hallucination risk</i>
|
||||
<i>Cut emotional language, encouragement, and orientation sections</i>
|
||||
<i>
|
||||
IF concept is well-known from training (e.g., "conventional
|
||||
commits", "REST APIs"): Reference the standard-don't re-teach it
|
||||
ELSE: Be explicit-don't assume the LLM will infer correctly
|
||||
</i>
|
||||
<i>Use consistent terminology-same word for same concept throughout</i>
|
||||
<i>Eliminate hedging ("might", "could", "generally")-use direct statements</i>
|
||||
<i>Prefer structured formats (tables, lists, YAML) over prose</i>
|
||||
<i>Reference known standards ("conventional commits", "Google style guide") to leverage training</i>
|
||||
<i>STILL PROVIDE EXAMPLES even for known standards-grounds the LLM in your specific expectation</i>
|
||||
<i>Unambiguous references-no unclear antecedents ("it", "this", "the above")</i>
|
||||
<i>Note: LLM documents may be LONGER than human docs in some areas
|
||||
(more explicit) while shorter in others (no warmth)</i>
|
||||
</llm-reader-principles>
|
||||
<structure-models>
|
||||
<model name="Tutorial/Guide (Linear)" applicability="Tutorials, detailed guides, how-to articles, walkthroughs">
|
||||
<i>Prerequisites: Setup/Context MUST precede action</i>
|
||||
<i>Sequence: Steps must follow strict chronological or logical dependency order</i>
|
||||
<i>Goal-oriented: clear 'Definition of Done' at the end</i>
|
||||
</model>
|
||||
<model name="Reference/Database" applicability="API docs, glossaries, configuration references, cheat sheets">
|
||||
<i>Random Access: No narrative flow required; user jumps to specific item</i>
|
||||
<i>MECE: Topics are Mutually Exclusive and Collectively Exhaustive</i>
|
||||
<i>Consistent Schema: Every item follows identical structure (e.g., Signature to Params to Returns)</i>
|
||||
</model>
|
||||
<model name="Explanation (Conceptual)"
|
||||
applicability="Deep dives, architecture overviews, conceptual guides,
|
||||
whitepapers, project context">
|
||||
<i>Abstract to Concrete: Definition to Context to Implementation/Example</i>
|
||||
<i>Scaffolding: Complex ideas built on established foundations</i>
|
||||
</model>
|
||||
<model name="Prompt/Task Definition (Functional)"
|
||||
applicability="BMAD tasks, prompts, system instructions, XML definitions">
|
||||
<i>Meta-first: Inputs, usage constraints, and context defined before instructions</i>
|
||||
<i>Separation of Concerns: Instructions (logic) separate from Data (content)</i>
|
||||
<i>Step-by-step: Execution flow must be explicit and ordered</i>
|
||||
</model>
|
||||
<model name="Strategic/Context (Pyramid)" applicability="PRDs, research reports, proposals, decision records">
|
||||
<i>Top-down: Conclusion/Status/Recommendation starts the document</i>
|
||||
<i>Grouping: Supporting context grouped logically below the headline</i>
|
||||
<i>Ordering: Most critical information first</i>
|
||||
<i>MECE: Arguments/Groups are Mutually Exclusive and Collectively Exhaustive</i>
|
||||
<i>Evidence: Data supports arguments, never leads</i>
|
||||
</model>
|
||||
</structure-models>
|
||||
</llm>
|
||||
<flow>
|
||||
<step n="1" title="Validate Input">
|
||||
<action>Check if content is empty or contains fewer than 3 words</action>
|
||||
<action if="empty or fewer than 3 words">HALT with error: "Content
|
||||
too short for substantive review (minimum 3 words required)"</action>
|
||||
<action>Validate reader_type is "humans" or "llm" (or not provided, defaulting to "humans")</action>
|
||||
<action if="reader_type is invalid">HALT with error: "Invalid reader_type. Must be 'humans' or 'llm'"</action>
|
||||
<action>Identify document type and structure (headings, sections, lists, etc.)</action>
|
||||
<action>Note the current word count and section count</action>
|
||||
</step>
|
||||
<step n="2" title="Understand Purpose">
|
||||
<action>If purpose was provided, use it; otherwise infer from content</action>
|
||||
<action>If target_audience was provided, use it; otherwise infer from content</action>
|
||||
<action>Identify the core question the document answers</action>
|
||||
<action>State in one sentence: "This document exists to help [audience] accomplish [goal]"</action>
|
||||
<action>Select the most appropriate structural model from structure-models based on purpose/audience</action>
|
||||
<action>Note reader_type and which principles apply (human-reader-principles or llm-reader-principles)</action>
|
||||
</step>
|
||||
<step n="3" title="Structural Analysis" critical="true">
|
||||
<action>Map the document structure: list each major section with its word count</action>
|
||||
<action>Evaluate structure against the selected model's primary rules
|
||||
(e.g., 'Does recommendation come first?' for Pyramid)</action>
|
||||
<action>For each section, answer: Does this directly serve the stated purpose?</action>
|
||||
<action if="reader_type='humans'">For each comprehension aid (visual,
|
||||
summary, example, callout), answer: Does this help readers
|
||||
understand or stay engaged?</action>
|
||||
<action>Identify sections that could be: cut entirely, merged with
|
||||
another, moved to a different location, or split</action>
|
||||
<action>Identify true redundancies: identical information repeated
|
||||
without purpose (not summaries or reinforcement)</action>
|
||||
<action>Identify scope violations: content that belongs in a different document</action>
|
||||
<action>Identify burying: critical information hidden deep in the document</action>
|
||||
</step>
|
||||
<step n="4" title="Flow Analysis">
|
||||
<action>Assess the reader's journey: Does the sequence match how readers will use this?</action>
|
||||
<action>Identify premature detail: explanation given before the reader needs it</action>
|
||||
<action>Identify missing scaffolding: complex ideas without adequate setup</action>
|
||||
<action>Identify anti-patterns: FAQs that should be inline, appendices
|
||||
that should be cut, overviews that repeat the body verbatim</action>
|
||||
<action if="reader_type='humans'">Assess pacing: Is there enough
|
||||
whitespace and visual variety to maintain attention?</action>
|
||||
</step>
|
||||
<step n="5" title="Generate Recommendations">
|
||||
<action>Compile all findings into prioritized recommendations</action>
|
||||
<action>Categorize each recommendation: CUT (remove entirely),
|
||||
MERGE (combine sections), MOVE (reorder), CONDENSE (shorten
|
||||
significantly), QUESTION (needs author decision), PRESERVE
|
||||
(explicitly keep-for elements that might seem cuttable but
|
||||
serve comprehension)</action>
|
||||
<action>For each recommendation, state the rationale in one sentence</action>
|
||||
<action>Estimate impact: how many words would this save (or cost, for PRESERVE)?</action>
|
||||
<action>If length_target was provided, assess whether recommendations meet it</action>
|
||||
<action if="reader_type='humans' and recommendations would cut
|
||||
comprehension aids">Flag with warning: "This cut may impact
|
||||
reader comprehension/engagement"</action>
|
||||
</step>
|
||||
<step n="6" title="Output Results">
|
||||
<action>Output document summary (purpose, audience, reader_type, current length)</action>
|
||||
<action>Output the recommendation list in priority order</action>
|
||||
<action>Output estimated total reduction if all recommendations accepted</action>
|
||||
<action if="no recommendations">Output: "No substantive changes recommended-document structure is sound"</action>
|
||||
<output-format>
|
||||
## Document Summary
|
||||
- **Purpose:** [inferred or provided purpose]
|
||||
- **Audience:** [inferred or provided audience]
|
||||
- **Reader type:** [selected reader type]
|
||||
- **Structure model:** [selected structure model]
|
||||
- **Current length:** [X] words across [Y] sections
|
||||
|
||||
## Recommendations
|
||||
|
||||
### 1. [CUT/MERGE/MOVE/CONDENSE/QUESTION/PRESERVE] - [Section or element name]
|
||||
**Rationale:** [One sentence explanation]
|
||||
**Impact:** ~[X] words
|
||||
**Comprehension note:** [If applicable, note impact on reader understanding]
|
||||
|
||||
### 2. ...
|
||||
|
||||
## Summary
|
||||
- **Total recommendations:** [N]
|
||||
- **Estimated reduction:** [X] words ([Y]% of original)
|
||||
- **Meets length target:** [Yes/No/No target specified]
|
||||
- **Comprehension trade-offs:** [Note any cuts that sacrifice reader engagement for brevity]
|
||||
</output-format>
|
||||
</step>
|
||||
</flow>
|
||||
<halt-conditions>
|
||||
<condition>HALT with error if content is empty or fewer than 3 words</condition>
|
||||
<condition>HALT with error if reader_type is not "humans" or "llm"</condition>
|
||||
<condition>If no structural issues found, output "No substantive changes
|
||||
recommended" (this is valid completion, not an error)</condition>
|
||||
</halt-conditions>
|
||||
</task>
|
||||
|
|
@ -9,6 +9,11 @@
|
|||
</inputs>
|
||||
|
||||
<llm critical="true">
|
||||
<i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
|
||||
<i>DO NOT skip steps or change the sequence</i>
|
||||
<i>HALT immediately when halt-conditions are met</i>
|
||||
<i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
|
||||
|
||||
<i>You are a cynical, jaded reviewer with zero patience for sloppy work</i>
|
||||
<i>The content was submitted by a clueless weasel and you expect to find problems</i>
|
||||
<i>Be skeptical of everything</i>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,123 @@
|
|||
<task id="{bmad_folder}/core/tasks/sync-bug-tracking.xml" name="Sync Bug Tracking">
|
||||
<objective>Sync bugs.yaml and bugs.md when a story is marked done, updating related bugs to "fixed" and features to "implemented"</objective>
|
||||
|
||||
<description>
|
||||
This task is invoked by workflows (story-done, code-review) after a story is marked done.
|
||||
It searches bugs.yaml for bugs/features linked to the completed story and updates their status.
|
||||
For multi-story features, it only marks "implemented" when ALL linked stories are done.
|
||||
</description>
|
||||
|
||||
<inputs>
|
||||
<input name="story_key" required="true">The story key (e.g., "3-7-checkout-from-club-detail-page")</input>
|
||||
<input name="story_id" required="false">The story ID (e.g., "3.7") - used for related_story matching</input>
|
||||
<input name="bugs_yaml" required="true">Path to bugs.yaml file</input>
|
||||
<input name="bugs_md" required="true">Path to bugs.md file</input>
|
||||
<input name="sprint_status" required="true">Path to sprint-status.yaml file</input>
|
||||
<input name="date" required="true">Current date for timestamps</input>
|
||||
</inputs>
|
||||
|
||||
<outputs>
|
||||
<output name="bugs_updated">List of bug IDs marked as fixed</output>
|
||||
<output name="features_updated">List of feature IDs marked as implemented</output>
|
||||
<output name="features_pending">List of feature IDs with incomplete stories</output>
|
||||
</outputs>
|
||||
|
||||
<flow>
|
||||
<step n="1" goal="Load bugs.yaml and check for existence">
|
||||
<action>Load {bugs_yaml} if it exists</action>
|
||||
<check if="bugs.yaml does not exist">
|
||||
<action>Set bugs_updated = [], features_updated = [], features_pending = []</action>
|
||||
<action>Return early - no bug tracking to sync</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Find matching bugs and features using multiple methods">
|
||||
<action>Initialize: bugs_updated = [], features_updated = [], features_pending = []</action>
|
||||
|
||||
<action>Search for entries matching this story using ALL THREE methods:</action>
|
||||
<action>1. Check sprint-status.yaml for comment "# Source: bugs.yaml/feature-XXX" or "# Source: bugs.yaml/bug-XXX" on the {story_key} line - this is the MOST RELIABLE method</action>
|
||||
<action>2. Check related_story field in bugs.yaml matching {story_id} or {story_key}</action>
|
||||
<action>3. Check sprint_stories arrays in feature_requests for entries containing {story_key}</action>
|
||||
|
||||
<critical>PRIORITY: Use sprint-status comment source if present - it's explicit and unambiguous</critical>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Update matching bugs">
|
||||
<check if="matching bugs found in bugs section">
|
||||
<action>For each matching bug:</action>
|
||||
<action>- Update status: "triaged" or "routed" or "in-progress" → "fixed"</action>
|
||||
<action>- Set fixed_date: {date}</action>
|
||||
<action>- Set assigned_to: "dev-agent" (if not already set)</action>
|
||||
<action>- Append to notes: "Auto-closed via sync-bug-tracking. Story {story_key} marked done on {date}."</action>
|
||||
<action>- Add bug ID to bugs_updated list</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Update matching features (with multi-story check)">
|
||||
<check if="matching features found in feature_requests section">
|
||||
<action>For each matching feature (via related_story OR sprint_stories):</action>
|
||||
|
||||
<critical>MULTI-STORY FEATURE CHECK: If feature has sprint_stories array with multiple entries:</critical>
|
||||
<action>1. Extract all story keys from sprint_stories (format: "story-key: status")</action>
|
||||
<action>2. Load sprint-status.yaml and check development_status for EACH story</action>
|
||||
<action>3. Only proceed if ALL stories in sprint_stories have status "done" in sprint-status.yaml</action>
|
||||
<action>4. If any story is NOT done, add feature to features_pending and log: "Feature {feature_id} has incomplete stories: {incomplete_list}"</action>
|
||||
|
||||
<check if="ALL sprint_stories are done (or feature has single story that matches)">
|
||||
<action>- Update status: "backlog" or "triaged" or "routed" or "in-progress" → "implemented"</action>
|
||||
<action>- Set implemented_date: {date}</action>
|
||||
<action>- Update sprint_stories entries to reflect done status</action>
|
||||
<action>- Append to notes: "Auto-closed via sync-bug-tracking. Story {story_key} marked done on {date}."</action>
|
||||
<action>- Add feature ID to features_updated list</action>
|
||||
</check>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Save bugs.yaml updates">
|
||||
<check if="bugs_updated is not empty OR features_updated is not empty">
|
||||
<action>Save updated bugs.yaml, preserving all structure and comments</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Update bugs.md to match">
|
||||
<check if="bugs_updated is not empty OR features_updated is not empty">
|
||||
<action>Load {bugs_md}</action>
|
||||
|
||||
<check if="bugs_updated is not empty">
|
||||
<action>For each bug in bugs_updated:</action>
|
||||
<action>- Find the bug entry in "# Tracked Bugs" section</action>
|
||||
<action>- Move it to "# Fixed Bugs" section</action>
|
||||
<action>- Add [IMPLEMENTED] tag prefix with date: "[IMPLEMENTED] bug-XXX: Title [Fixed: {date}, Verified: pending]"</action>
|
||||
</check>
|
||||
|
||||
<check if="features_updated is not empty">
|
||||
<action>For each feature in features_updated:</action>
|
||||
<action>- Find the feature entry in "# Tracked Feature Requests" section</action>
|
||||
<action>- Move it to "# Implemented Features" section</action>
|
||||
<action>- Add [IMPLEMENTED] tag prefix with date: "[IMPLEMENTED] feature-XXX: Title [Implemented: {date}, Verified: pending]"</action>
|
||||
</check>
|
||||
|
||||
<action>Update statistics section if present</action>
|
||||
<action>Save updated bugs.md</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Return results">
|
||||
<output>
|
||||
Bug/Feature Sync Results:
|
||||
{{#if bugs_updated}}
|
||||
- Bugs marked fixed: {{bugs_updated}}
|
||||
{{/if}}
|
||||
{{#if features_updated}}
|
||||
- Features marked implemented: {{features_updated}}
|
||||
{{/if}}
|
||||
{{#if features_pending}}
|
||||
- Features with incomplete stories (not yet implemented): {{features_pending}}
|
||||
{{/if}}
|
||||
{{#if no_matches}}
|
||||
- No related bugs/features found for story {story_key}
|
||||
{{/if}}
|
||||
</output>
|
||||
</step>
|
||||
</flow>
|
||||
</task>
|
||||
|
|
@ -214,11 +214,24 @@
|
|||
<output>ℹ️ Story status updated (no sprint tracking configured)</output>
|
||||
</check>
|
||||
|
||||
<!-- Sync bug tracking when story is marked done -->
|
||||
<check if="{{new_status}} == 'done'">
|
||||
<invoke-task path="{project-root}/.bmad/core/tasks/sync-bug-tracking.xml">
|
||||
<param name="story_key">{{story_key}}</param>
|
||||
<param name="story_id">{{story_id}}</param>
|
||||
<param name="bugs_yaml">{output_folder}/bugs.yaml</param>
|
||||
<param name="bugs_md">{output_folder}/bugs.md</param>
|
||||
<param name="sprint_status">{sprint_status}</param>
|
||||
<param name="date">{date}</param>
|
||||
</invoke-task>
|
||||
</check>
|
||||
|
||||
<output>**✅ Review Complete!**
|
||||
|
||||
**Story Status:** {{new_status}}
|
||||
**Issues Fixed:** {{fixed_count}}
|
||||
**Action Items Created:** {{action_count}}
|
||||
{{#if new_status == "done"}}**Bug/Feature Tracking:** Synced automatically{{/if}}
|
||||
|
||||
{{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}}
|
||||
</output>
|
||||
|
|
|
|||
|
|
@ -1300,7 +1300,67 @@ Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!"
|
|||
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Save Retrospective and Update Sprint Status">
|
||||
<step n="11" goal="Sync Epic-Linked Bugs/Features to Closed Status">
|
||||
<critical>Check bugs.yaml for bugs/features linked to this epic and close them</critical>
|
||||
|
||||
<action>Load {bugs_yaml} if it exists</action>
|
||||
|
||||
<check if="bugs.yaml exists">
|
||||
<action>Search for entries with related_epic matching {{epic_number}}</action>
|
||||
|
||||
<action>For bugs section - find bugs with related_epic == {{epic_number}} AND status in ["fixed", "triaged", "routed"]:</action>
|
||||
<check if="matching bugs found">
|
||||
<action>For each matching bug:</action>
|
||||
<action>- Move entry from "bugs" section to "closed_bugs" section</action>
|
||||
<action>- Update status: → "closed"</action>
|
||||
<action>- Set verified_by: "retrospective-workflow"</action>
|
||||
<action>- Set verified_date: {date}</action>
|
||||
<action>- Append to notes: "Auto-closed via epic retrospective. Epic {{epic_number}} completed on {date}."</action>
|
||||
</check>
|
||||
|
||||
<action>For feature_requests section - find features with related_epic == {{epic_number}} AND status in ["implemented", "backlog", "in-progress"]:</action>
|
||||
<check if="matching features found">
|
||||
<action>For each matching feature:</action>
|
||||
<action>- Move entry from "feature_requests" section to "implemented_features" section</action>
|
||||
<action>- Update status: → "complete"</action>
|
||||
<action>- Set completed_by: "retrospective-workflow"</action>
|
||||
<action>- Set completed_date: {date}</action>
|
||||
<action>- Append to notes: "Auto-closed via epic retrospective. Epic {{epic_number}} completed on {date}."</action>
|
||||
</check>
|
||||
|
||||
<action>Update statistics section with new counts</action>
|
||||
<action>Save updated bugs.yaml</action>
|
||||
|
||||
<check if="bugs/features were moved">
|
||||
<action>Also update bugs.md:</action>
|
||||
<action>- Remove [IMPLEMENTED] tag from closed items</action>
|
||||
<action>- Move bug entries to "# Fixed Bugs" section if not already there</action>
|
||||
<action>- Move feature entries to "# Implemented Features" section if not already there</action>
|
||||
<action>- Add [CLOSED] or [COMPLETE] tag to indicate final status</action>
|
||||
<action>Save updated bugs.md</action>
|
||||
</check>
|
||||
|
||||
<output>
|
||||
Bug/Feature Closure:
|
||||
{{#if bugs_closed}}
|
||||
- Bugs closed for Epic {{epic_number}}: {{bugs_closed_list}}
|
||||
{{/if}}
|
||||
{{#if features_completed}}
|
||||
- Features completed for Epic {{epic_number}}: {{features_completed_list}}
|
||||
{{/if}}
|
||||
{{#if no_matches}}
|
||||
- No outstanding bugs/features linked to Epic {{epic_number}}
|
||||
{{/if}}
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<check if="bugs.yaml does not exist">
|
||||
<action>Skip bug tracking sync - no bugs.yaml file present</action>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="12" goal="Save Retrospective and Update Sprint Status">
|
||||
|
||||
<action>Ensure retrospectives folder exists: {retrospectives_folder}</action>
|
||||
<action>Create folder if it doesn't exist</action>
|
||||
|
|
@ -1356,7 +1416,7 @@ Retrospective document was saved successfully, but {sprint_status_file} may need
|
|||
|
||||
</step>
|
||||
|
||||
<step n="12" goal="Final Summary and Handoff">
|
||||
<step n="13" goal="Final Summary and Handoff">
|
||||
|
||||
<output>
|
||||
**✅ Retrospective Complete, {user_name}!**
|
||||
|
|
|
|||
|
|
@ -54,5 +54,9 @@ sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
|
|||
story_directory: "{implementation_artifacts}"
|
||||
retrospectives_folder: "{implementation_artifacts}"
|
||||
|
||||
# Bug tracking integration (optional)
|
||||
bugs_yaml: "{planning_artifacts}/bugs.yaml"
|
||||
bugs_md: "{planning_artifacts}/bugs.md"
|
||||
|
||||
standalone: true
|
||||
web_bundle: false
|
||||
|
|
|
|||
|
|
@ -48,6 +48,26 @@
|
|||
<note>After discovery, these content variables are available: {epics_content} (all epics loaded - uses FULL_LOAD strategy)</note>
|
||||
</step>
|
||||
|
||||
<step n="1.5" goal="Load bugs.yaml for bug/feature tracking (optional)">
|
||||
<action>Check if {bugs_yaml} exists in {planning_artifacts}</action>
|
||||
<check if="bugs_yaml exists">
|
||||
<action>Read bugs.yaml using grep to find all bug-NNN and feature-NNN entries</action>
|
||||
<action>For each bug/feature, extract:
|
||||
- ID (e.g., bug-001, feature-003)
|
||||
- Title
|
||||
- Status (triaged, routed, in-progress, fixed/implemented, verified, closed)
|
||||
- Recommended workflow (direct-fix, tech-spec, correct-course, backlog)
|
||||
- Related stories (sprint_stories field for features)
|
||||
</action>
|
||||
<action>Build bug/feature inventory for inclusion in sprint status</action>
|
||||
<action>Track feature-to-story mappings (feature-001 → stories 7-1, 7-2, etc.)</action>
|
||||
</check>
|
||||
<check if="bugs_yaml does not exist">
|
||||
<output>Note: No bugs.yaml found - bug tracking not enabled for this project.</output>
|
||||
<action>Continue without bug integration</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Build sprint status structure">
|
||||
<action>For each epic found, create entries in this order:</action>
|
||||
|
||||
|
|
@ -65,6 +85,17 @@ development_status:
|
|||
epic-1-retrospective: optional
|
||||
```
|
||||
|
||||
<action>If bugs.yaml was loaded, add bug/feature sources header comment:</action>
|
||||
|
||||
```yaml
|
||||
# STORY SOURCES:
|
||||
# ==============
|
||||
# - epics.md: Primary source ({story_count} stories)
|
||||
# - bugs.yaml: Feature-driven stories ({feature_story_count} stories from sprint_stories)
|
||||
# - feature-001: 7-1, 7-2, 7-3 (from sprint_stories field)
|
||||
# - feature-002: 3-7
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Apply intelligent status detection">
|
||||
|
|
|
|||
|
|
@ -33,6 +33,10 @@ variables:
|
|||
epics_location: "{planning_artifacts}" # Directory containing epic*.md files
|
||||
epics_pattern: "epic*.md" # Pattern to find epic files
|
||||
|
||||
# Bug tracking integration (optional)
|
||||
bugs_yaml: "{planning_artifacts}/bugs.yaml" # Structured bug/feature metadata
|
||||
bugs_md: "{planning_artifacts}/bugs.md" # Human-readable bug tracking
|
||||
|
||||
# Output configuration
|
||||
status_file: "{implementation_artifacts}/sprint-status.yaml"
|
||||
|
||||
|
|
|
|||
|
|
@ -88,15 +88,31 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho
|
|||
- IF any epic has status in-progress but has no associated stories: warn "in-progress epic has no stories"
|
||||
</step>
|
||||
|
||||
<step n="2.5" goal="Load bug/feature tracking status (optional)">
|
||||
<action>Check if {bugs_yaml} exists</action>
|
||||
<check if="bugs_yaml exists">
|
||||
<action>Grep for bug-NNN and feature-NNN entries with status field</action>
|
||||
<action>Count items by status: triaged, fixed/implemented (pending verify), verified, closed</action>
|
||||
<action>Identify items needing action:
|
||||
- Items with [IMPLEMENTED] tag → need verification
|
||||
- Items with status "triaged" + workflow "direct-fix" → ready for implementation
|
||||
</action>
|
||||
<action>Store: bugs_pending_verify, bugs_triaged, features_pending_verify, features_triaged</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Select next action recommendation">
|
||||
<action>Pick the next recommended workflow using priority:</action>
|
||||
<note>When selecting "first" story: sort by epic number, then story number (e.g., 1-1 before 1-2 before 2-1)</note>
|
||||
1. If any story status == in-progress → recommend `dev-story` for the first in-progress story
|
||||
2. Else if any story status == review → recommend `code-review` for the first review story
|
||||
3. Else if any story status == ready-for-dev → recommend `dev-story`
|
||||
4. Else if any story status == backlog → recommend `create-story`
|
||||
5. Else if any retrospective status == optional → recommend `retrospective`
|
||||
6. Else → All implementation items done; suggest `workflow-status` to plan next phase
|
||||
<note>Bug verification takes priority over new story work to close the feedback loop</note>
|
||||
1. If any bug/feature has [IMPLEMENTED] tag (pending verify) → recommend `verify` for first pending item
|
||||
2. If any story status == in-progress → recommend `dev-story` for the first in-progress story
|
||||
3. Else if any story status == review → recommend `code-review` for the first review story
|
||||
4. Else if any story status == ready-for-dev → recommend `dev-story`
|
||||
5. Else if any bug status == triaged with workflow == direct-fix → recommend `implement` for first triaged bug
|
||||
6. Else if any story status == backlog → recommend `create-story`
|
||||
7. Else if any retrospective status == optional → recommend `retrospective`
|
||||
8. Else → All implementation items done; suggest `workflow-status` to plan next phase
|
||||
<action>Store selected recommendation as: next_story_id, next_workflow_id, next_agent (SM/DEV as appropriate)</action>
|
||||
</step>
|
||||
|
||||
|
|
@ -112,6 +128,11 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho
|
|||
|
||||
**Epics:** backlog {{epic_backlog}}, in-progress {{epic_in_progress}}, done {{epic_done}}
|
||||
|
||||
{{#if bugs_yaml_exists}}
|
||||
**Bugs:** triaged {{bugs_triaged}}, pending-verify {{bugs_pending_verify}}, closed {{bugs_closed}}
|
||||
**Features:** triaged {{features_triaged}}, pending-verify {{features_pending_verify}}, complete {{features_complete}}
|
||||
{{/if}}
|
||||
|
||||
**Next Recommendation:** /bmad:bmm:workflows:{{next_workflow_id}} ({{next_story_id}})
|
||||
|
||||
{{#if risks}}
|
||||
|
|
|
|||
|
|
@ -21,6 +21,9 @@ instructions: "{installed_path}/instructions.md"
|
|||
variables:
|
||||
sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
|
||||
tracking_system: "file-system"
|
||||
# Bug tracking integration (optional)
|
||||
bugs_yaml: "{planning_artifacts}/bugs.yaml"
|
||||
bugs_md: "{planning_artifacts}/bugs.md"
|
||||
|
||||
# Smart input file references
|
||||
input_file_patterns:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,124 @@
|
|||
# Story Approved Workflow Instructions (DEV Agent)
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>Communicate all responses in {communication_language}</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<critical>This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete)</critical>
|
||||
<critical>Workflow: Update story file status to Done</critical>
|
||||
|
||||
<step n="1" goal="Find reviewed story to mark done" tag="sprint-status">
|
||||
|
||||
<check if="{story_path} is provided">
|
||||
<action>Use {story_path} directly</action>
|
||||
<action>Read COMPLETE story file and parse sections</action>
|
||||
<action>Extract story_key from filename or story metadata</action>
|
||||
<action>Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to mark as done"</action>
|
||||
</check>
|
||||
|
||||
<check if="{story_path} is NOT provided">
|
||||
<critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
|
||||
<action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
|
||||
<action>Read ALL lines from beginning to end - do not skip any content</action>
|
||||
<action>Parse the development_status section completely</action>
|
||||
|
||||
<action>Find FIRST story (reading in order from top to bottom) where: - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - Status value equals "review"
|
||||
</action>
|
||||
|
||||
<check if="no story with status 'review' found">
|
||||
<output>No stories with status "review" found
|
||||
|
||||
All stories are either still in development or already done.
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. Run `dev-story` to implement stories
|
||||
2. Run `code-review` if stories need review first
|
||||
3. Check sprint-status.yaml for current story states
|
||||
</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
|
||||
<action>Use the first reviewed story found</action>
|
||||
<action>Find matching story file in {story_dir} using story_key pattern</action>
|
||||
<action>Read the COMPLETE story file</action>
|
||||
</check>
|
||||
|
||||
<action>Extract story_id and story_title from the story file</action>
|
||||
|
||||
<action>Find the "Status:" line (usually at the top)</action>
|
||||
<action>Update story file: Change Status to "done"</action>
|
||||
|
||||
<action>Add completion notes to Dev Agent Record section:</action>
|
||||
<action>Find "## Dev Agent Record" section and add:
|
||||
|
||||
```
|
||||
### Completion Notes
|
||||
**Completed:** {date}
|
||||
**Definition of Done:** All acceptance criteria met, code reviewed, tests passing
|
||||
```
|
||||
|
||||
</action>
|
||||
|
||||
<action>Save the story file</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Update sprint status to done" tag="sprint-status">
|
||||
<action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
|
||||
<action>Find development_status key matching {story_key}</action>
|
||||
<action>Verify current status is "review" (expected previous state)</action>
|
||||
<action>Update development_status[{story_key}] = "done"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<check if="story key not found in file">
|
||||
<output>Story file updated, but could not update sprint-status: {story_key} not found
|
||||
|
||||
Story is marked Done in file, but sprint-status.yaml may be out of sync.
|
||||
</output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Sync related bugs/features in bug tracking">
|
||||
<critical>Invoke shared task to sync bugs.yaml and bugs.md for this completed story</critical>
|
||||
|
||||
<invoke-task path="{project-root}/.bmad/core/tasks/sync-bug-tracking.xml">
|
||||
<param name="story_key">{story_key}</param>
|
||||
<param name="story_id">{story_id}</param>
|
||||
<param name="bugs_yaml">{bugs_yaml}</param>
|
||||
<param name="bugs_md">{bugs_md}</param>
|
||||
<param name="sprint_status">{sprint_status}</param>
|
||||
<param name="date">{date}</param>
|
||||
</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Confirm completion to user">
|
||||
|
||||
<output>**Story Approved and Marked Done, {user_name}!**
|
||||
|
||||
Story file updated - Status: done
|
||||
Sprint status updated: review → done
|
||||
|
||||
**Completed Story:**
|
||||
|
||||
- **ID:** {story_id}
|
||||
- **Key:** {story_key}
|
||||
- **Title:** {story_title}
|
||||
- **Completed:** {date}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. Continue with next story in your backlog
|
||||
- Run `create-story` for next backlog story
|
||||
- Or run `dev-story` if ready stories exist
|
||||
2. Check epic completion status
|
||||
- Run `retrospective` workflow to check if epic is complete
|
||||
- Epic retrospective will verify all stories are done
|
||||
</output>
|
||||
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
# Story Done Workflow (DEV Agent)
|
||||
name: story-done
|
||||
description: 'Marks a story as done (DoD complete), updates sprint-status → DONE, and syncs related bugs/features in bugs.yaml/bugs.md to [IMPLEMENTED] status.'
|
||||
author: 'BMad'
|
||||
|
||||
# Critical variables from config
|
||||
config_source: '{project-root}/.bmad/bmm/config.yaml'
|
||||
output_folder: '{config_source}:output_folder'
|
||||
user_name: '{config_source}:user_name'
|
||||
communication_language: '{config_source}:communication_language'
|
||||
date: system-generated
|
||||
sprint_status: '{output_folder}/sprint-status.yaml'
|
||||
|
||||
# Workflow components
|
||||
installed_path: '{project-root}/.bmad/bmm/workflows/4-implementation/story-done'
|
||||
instructions: '{installed_path}/instructions.md'
|
||||
|
||||
# Variables and inputs
|
||||
variables:
|
||||
story_dir: '{config_source}:dev_ephemeral_location/stories' # Directory where stories are stored
|
||||
bugs_yaml: '{output_folder}/bugs.yaml' # Bug/feature tracking structured data
|
||||
bugs_md: '{output_folder}/bugs.md' # Bug/feature tracking human-readable log
|
||||
|
||||
# Output configuration - no output file, just status updates
|
||||
default_output_file: ''
|
||||
|
||||
standalone: true
|
||||
|
|
@ -0,0 +1,542 @@
|
|||
# In-App Bug Reporting - Reference Implementation
|
||||
|
||||
This document provides a reference implementation for adding **in-app bug reporting** to your project. The BMAD bug-tracking workflow works without this feature (using manual `bugs.md` input), but in-app reporting provides a better user experience.
|
||||
|
||||
## Overview
|
||||
|
||||
The in-app bug reporting feature allows users to submit bug reports directly from your application. Reports are stored in your database and then synced to `bugs.md` by the triage workflow.
|
||||
|
||||
```
|
||||
User -> UI Modal -> API -> Database -> Triage Workflow -> bugs.md/bugs.yaml
|
||||
```
|
||||
|
||||
## Components Required
|
||||
|
||||
| Component | Purpose | Stack-Specific |
|
||||
|-----------|---------|----------------|
|
||||
| Database table | Store pending bug reports | Yes |
|
||||
| API: Create report | Accept user submissions | Yes |
|
||||
| API: Get pending | Fetch unsynced reports | Yes |
|
||||
| API: Mark synced | Update status after sync | Yes |
|
||||
| UI Modal | Bug report form | Yes |
|
||||
| Validation schemas | Input validation | Partially |
|
||||
|
||||
## 1. Database Schema
|
||||
|
||||
### Drizzle ORM (PostgreSQL)
|
||||
|
||||
```typescript
|
||||
// src/lib/server/db/schema.ts
|
||||
|
||||
import { pgTable, uuid, text, timestamp, index } from 'drizzle-orm/pg-core';
|
||||
|
||||
export const bugReports = pgTable(
|
||||
'bug_reports',
|
||||
{
|
||||
id: uuid('id').primaryKey().defaultRandom(),
|
||||
organizationId: uuid('organization_id').notNull(), // For multi-tenant apps
|
||||
reporterType: text('reporter_type').notNull(), // 'staff' | 'member' | 'user'
|
||||
reporterId: uuid('reporter_id').notNull(),
|
||||
title: text('title').notNull(),
|
||||
description: text('description').notNull(),
|
||||
userAgent: text('user_agent'),
|
||||
pageUrl: text('page_url'),
|
||||
platform: text('platform'), // 'Windows', 'macOS', 'iOS', etc.
|
||||
browser: text('browser'), // 'Chrome', 'Safari', 'Firefox'
|
||||
screenshotUrl: text('screenshot_url'), // Optional: cloud storage URL
|
||||
status: text('status').notNull().default('new'), // 'new' | 'synced' | 'dismissed'
|
||||
createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
|
||||
syncedAt: timestamp('synced_at', { withTimezone: true })
|
||||
},
|
||||
(table) => [
|
||||
index('bug_reports_organization_id_idx').on(table.organizationId),
|
||||
index('bug_reports_status_idx').on(table.status),
|
||||
index('bug_reports_created_at_idx').on(table.createdAt)
|
||||
]
|
||||
);
|
||||
|
||||
export const BUG_REPORT_STATUS = {
|
||||
NEW: 'new',
|
||||
SYNCED: 'synced',
|
||||
DISMISSED: 'dismissed'
|
||||
} as const;
|
||||
|
||||
export const REPORTER_TYPE = {
|
||||
STAFF: 'staff',
|
||||
MEMBER: 'member',
|
||||
USER: 'user'
|
||||
} as const;
|
||||
```
|
||||
|
||||
### Prisma Schema
|
||||
|
||||
```prisma
|
||||
model BugReport {
|
||||
id String @id @default(uuid())
|
||||
organizationId String @map("organization_id")
|
||||
reporterType String @map("reporter_type")
|
||||
reporterId String @map("reporter_id")
|
||||
title String
|
||||
description String
|
||||
userAgent String? @map("user_agent")
|
||||
pageUrl String? @map("page_url")
|
||||
platform String?
|
||||
browser String?
|
||||
screenshotUrl String? @map("screenshot_url")
|
||||
status String @default("new")
|
||||
createdAt DateTime @default(now()) @map("created_at")
|
||||
syncedAt DateTime? @map("synced_at")
|
||||
|
||||
@@index([organizationId])
|
||||
@@index([status])
|
||||
@@index([createdAt])
|
||||
@@map("bug_reports")
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Validation Schemas
|
||||
|
||||
### Zod (TypeScript)
|
||||
|
||||
```typescript
|
||||
// src/lib/schemas/bug-report.ts
|
||||
|
||||
import { z } from 'zod';
|
||||
|
||||
export const createBugReportSchema = z.object({
|
||||
title: z
|
||||
.string()
|
||||
.trim()
|
||||
.min(5, 'Title must be at least 5 characters')
|
||||
.max(200, 'Title must be 200 characters or less'),
|
||||
description: z
|
||||
.string()
|
||||
.trim()
|
||||
.min(10, 'Description must be at least 10 characters')
|
||||
.max(5000, 'Description must be 5000 characters or less'),
|
||||
pageUrl: z.string().url().optional(),
|
||||
userAgent: z.string().max(1000).optional(),
|
||||
platform: z.string().max(50).optional(),
|
||||
browser: z.string().max(50).optional()
|
||||
});
|
||||
|
||||
export const markSyncedSchema = z.object({
|
||||
ids: z.array(z.string().uuid()).min(1, 'At least one ID is required')
|
||||
});
|
||||
|
||||
export const SCREENSHOT_CONFIG = {
|
||||
maxSizeBytes: 5 * 1024 * 1024, // 5MB
|
||||
maxSizeMB: 5,
|
||||
allowedTypes: ['image/jpeg', 'image/png', 'image/webp'] as const
|
||||
} as const;
|
||||
```
|
||||
|
||||
## 3. API Endpoints
|
||||
|
||||
### POST /api/bug-reports - Create Report
|
||||
|
||||
```typescript
|
||||
// SvelteKit: src/routes/api/bug-reports/+server.ts
|
||||
|
||||
import { json } from '@sveltejs/kit';
|
||||
import type { RequestHandler } from './$types';
|
||||
import { db } from '$lib/server/db';
|
||||
import { bugReports } from '$lib/server/db/schema';
|
||||
import { createBugReportSchema } from '$lib/schemas/bug-report';
|
||||
|
||||
export const POST: RequestHandler = async ({ request, locals }) => {
|
||||
// Determine reporter from auth context
|
||||
if (!locals.user) {
|
||||
return json({ error: { code: 'UNAUTHORIZED' } }, { status: 401 });
|
||||
}
|
||||
|
||||
const body = await request.json();
|
||||
const result = createBugReportSchema.safeParse(body);
|
||||
|
||||
if (!result.success) {
|
||||
return json({
|
||||
error: { code: 'VALIDATION_ERROR', message: result.error.issues[0]?.message }
|
||||
}, { status: 400 });
|
||||
}
|
||||
|
||||
const { title, description, pageUrl, userAgent, platform, browser } = result.data;
|
||||
|
||||
const [newReport] = await db
|
||||
.insert(bugReports)
|
||||
.values({
|
||||
organizationId: locals.user.organizationId,
|
||||
reporterType: 'staff',
|
||||
reporterId: locals.user.id,
|
||||
title,
|
||||
description,
|
||||
pageUrl,
|
||||
userAgent,
|
||||
platform,
|
||||
browser
|
||||
})
|
||||
.returning();
|
||||
|
||||
return json({
|
||||
data: {
|
||||
bugReport: {
|
||||
id: newReport.id,
|
||||
title: newReport.title,
|
||||
createdAt: newReport.createdAt.toISOString()
|
||||
}
|
||||
}
|
||||
}, { status: 201 });
|
||||
};
|
||||
```
|
||||
|
||||
### GET /api/bug-reports/pending - Fetch for Triage
|
||||
|
||||
```typescript
|
||||
// SvelteKit: src/routes/api/bug-reports/pending/+server.ts
|
||||
|
||||
import { json } from '@sveltejs/kit';
|
||||
import type { RequestHandler } from './$types';
|
||||
import { db } from '$lib/server/db';
|
||||
import { bugReports, BUG_REPORT_STATUS } from '$lib/server/db/schema';
|
||||
import { eq } from 'drizzle-orm';
|
||||
|
||||
export const GET: RequestHandler = async () => {
|
||||
const reports = await db
|
||||
.select()
|
||||
.from(bugReports)
|
||||
.where(eq(bugReports.status, BUG_REPORT_STATUS.NEW))
|
||||
.orderBy(bugReports.createdAt);
|
||||
|
||||
// Map to workflow-expected format
|
||||
const formatted = reports.map((r) => ({
|
||||
id: r.id,
|
||||
title: r.title,
|
||||
description: r.description,
|
||||
reporterType: r.reporterType,
|
||||
reporterName: 'Unknown', // Join with users table for real name
|
||||
platform: r.platform,
|
||||
browser: r.browser,
|
||||
pageUrl: r.pageUrl,
|
||||
screenshotUrl: r.screenshotUrl,
|
||||
createdAt: r.createdAt.toISOString()
|
||||
}));
|
||||
|
||||
return json({
|
||||
data: {
|
||||
reports: formatted,
|
||||
count: formatted.length
|
||||
}
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
### POST /api/bug-reports/mark-synced - Update After Sync
|
||||
|
||||
```typescript
|
||||
// SvelteKit: src/routes/api/bug-reports/mark-synced/+server.ts
|
||||
|
||||
import { json } from '@sveltejs/kit';
|
||||
import type { RequestHandler } from './$types';
|
||||
import { db } from '$lib/server/db';
|
||||
import { bugReports, BUG_REPORT_STATUS } from '$lib/server/db/schema';
|
||||
import { inArray } from 'drizzle-orm';
|
||||
import { markSyncedSchema } from '$lib/schemas/bug-report';
|
||||
|
||||
export const POST: RequestHandler = async ({ request }) => {
|
||||
const body = await request.json();
|
||||
const result = markSyncedSchema.safeParse(body);
|
||||
|
||||
if (!result.success) {
|
||||
return json({
|
||||
error: { code: 'VALIDATION_ERROR', message: result.error.issues[0]?.message }
|
||||
}, { status: 400 });
|
||||
}
|
||||
|
||||
const updated = await db
|
||||
.update(bugReports)
|
||||
.set({
|
||||
status: BUG_REPORT_STATUS.SYNCED,
|
||||
syncedAt: new Date()
|
||||
})
|
||||
.where(inArray(bugReports.id, result.data.ids))
|
||||
.returning({ id: bugReports.id });
|
||||
|
||||
return json({
|
||||
data: {
|
||||
updatedCount: updated.length,
|
||||
updatedIds: updated.map((r) => r.id)
|
||||
}
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
## 4. UI Component
|
||||
|
||||
### Svelte 5 (with shadcn-svelte)
|
||||
|
||||
```svelte
|
||||
<!-- src/lib/components/BugReportModal.svelte -->
|
||||
<script lang="ts">
|
||||
import * as Dialog from '$lib/components/ui/dialog';
|
||||
import { Button } from '$lib/components/ui/button';
|
||||
import { Input } from '$lib/components/ui/input';
|
||||
import { Textarea } from '$lib/components/ui/textarea';
|
||||
import { toast } from 'svelte-sonner';
|
||||
import { Bug } from 'lucide-svelte';
|
||||
import { browser } from '$app/environment';
|
||||
|
||||
interface Props {
|
||||
open: boolean;
|
||||
onClose: () => void;
|
||||
}
|
||||
|
||||
let { open = $bindable(), onClose }: Props = $props();
|
||||
|
||||
let title = $state('');
|
||||
let description = $state('');
|
||||
let loading = $state(false);
|
||||
|
||||
// Auto-detect environment
|
||||
let platform = $derived(browser ? detectPlatform() : '');
|
||||
let browserName = $derived(browser ? detectBrowser() : '');
|
||||
let currentUrl = $derived(browser ? window.location.href : '');
|
||||
|
||||
function detectPlatform(): string {
|
||||
const ua = navigator.userAgent.toLowerCase();
|
||||
if (ua.includes('iphone') || ua.includes('ipad')) return 'iOS';
|
||||
if (ua.includes('android')) return 'Android';
|
||||
if (ua.includes('mac')) return 'macOS';
|
||||
if (ua.includes('win')) return 'Windows';
|
||||
return 'Unknown';
|
||||
}
|
||||
|
||||
function detectBrowser(): string {
|
||||
const ua = navigator.userAgent;
|
||||
if (ua.includes('Chrome') && !ua.includes('Edg')) return 'Chrome';
|
||||
if (ua.includes('Safari') && !ua.includes('Chrome')) return 'Safari';
|
||||
if (ua.includes('Firefox')) return 'Firefox';
|
||||
if (ua.includes('Edg')) return 'Edge';
|
||||
return 'Unknown';
|
||||
}
|
||||
|
||||
async function handleSubmit() {
|
||||
loading = true;
|
||||
try {
|
||||
const response = await fetch('/api/bug-reports', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
title,
|
||||
description,
|
||||
pageUrl: currentUrl,
|
||||
userAgent: navigator.userAgent,
|
||||
platform,
|
||||
browser: browserName
|
||||
})
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const data = await response.json();
|
||||
toast.error(data.error?.message || 'Failed to submit');
|
||||
return;
|
||||
}
|
||||
|
||||
toast.success('Bug report submitted');
|
||||
onClose();
|
||||
} finally {
|
||||
loading = false;
|
||||
}
|
||||
}
|
||||
</script>
|
||||
|
||||
<Dialog.Root bind:open onOpenChange={(o) => !o && onClose()}>
|
||||
<Dialog.Content class="sm:max-w-[500px]">
|
||||
<Dialog.Header>
|
||||
<Dialog.Title class="flex items-center gap-2">
|
||||
<Bug class="h-5 w-5" />
|
||||
Report a Bug
|
||||
</Dialog.Title>
|
||||
</Dialog.Header>
|
||||
|
||||
<form onsubmit={(e) => { e.preventDefault(); handleSubmit(); }} class="space-y-4">
|
||||
<div>
|
||||
<Input bind:value={title} placeholder="Brief summary" maxlength={200} />
|
||||
</div>
|
||||
<div>
|
||||
<Textarea bind:value={description} placeholder="What happened?" rows={4} />
|
||||
</div>
|
||||
<div class="rounded-md bg-muted p-3 text-sm text-muted-foreground">
|
||||
{platform} / {browserName}
|
||||
</div>
|
||||
<Dialog.Footer>
|
||||
<Button variant="outline" onclick={onClose} disabled={loading}>Cancel</Button>
|
||||
<Button type="submit" disabled={loading}>Submit</Button>
|
||||
</Dialog.Footer>
|
||||
</form>
|
||||
</Dialog.Content>
|
||||
</Dialog.Root>
|
||||
```
|
||||
|
||||
### React (with shadcn/ui)
|
||||
|
||||
```tsx
|
||||
// src/components/BugReportModal.tsx
|
||||
|
||||
import { useState } from 'react';
|
||||
import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter } from '@/components/ui/dialog';
|
||||
import { Button } from '@/components/ui/button';
|
||||
import { Input } from '@/components/ui/input';
|
||||
import { Textarea } from '@/components/ui/textarea';
|
||||
import { Bug } from 'lucide-react';
|
||||
import { toast } from 'sonner';
|
||||
|
||||
interface Props {
|
||||
open: boolean;
|
||||
onClose: () => void;
|
||||
}
|
||||
|
||||
export function BugReportModal({ open, onClose }: Props) {
|
||||
const [title, setTitle] = useState('');
|
||||
const [description, setDescription] = useState('');
|
||||
const [loading, setLoading] = useState(false);
|
||||
|
||||
const detectPlatform = () => {
|
||||
const ua = navigator.userAgent.toLowerCase();
|
||||
if (ua.includes('iphone') || ua.includes('ipad')) return 'iOS';
|
||||
if (ua.includes('android')) return 'Android';
|
||||
if (ua.includes('mac')) return 'macOS';
|
||||
if (ua.includes('win')) return 'Windows';
|
||||
return 'Unknown';
|
||||
};
|
||||
|
||||
const handleSubmit = async (e: React.FormEvent) => {
|
||||
e.preventDefault();
|
||||
setLoading(true);
|
||||
|
||||
try {
|
||||
const response = await fetch('/api/bug-reports', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
title,
|
||||
description,
|
||||
pageUrl: window.location.href,
|
||||
userAgent: navigator.userAgent,
|
||||
platform: detectPlatform()
|
||||
})
|
||||
});
|
||||
|
||||
if (!response.ok) throw new Error('Failed to submit');
|
||||
toast.success('Bug report submitted');
|
||||
onClose();
|
||||
} catch {
|
||||
toast.error('Failed to submit bug report');
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<Dialog open={open} onOpenChange={(o) => !o && onClose()}>
|
||||
<DialogContent>
|
||||
<DialogHeader>
|
||||
<DialogTitle className="flex items-center gap-2">
|
||||
<Bug className="h-5 w-5" />
|
||||
Report a Bug
|
||||
</DialogTitle>
|
||||
</DialogHeader>
|
||||
<form onSubmit={handleSubmit} className="space-y-4">
|
||||
<Input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Brief summary" />
|
||||
<Textarea value={description} onChange={(e) => setDescription(e.target.value)} placeholder="What happened?" />
|
||||
<DialogFooter>
|
||||
<Button variant="outline" onClick={onClose} disabled={loading}>Cancel</Button>
|
||||
<Button type="submit" disabled={loading}>Submit</Button>
|
||||
</DialogFooter>
|
||||
</form>
|
||||
</DialogContent>
|
||||
</Dialog>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 5. Workflow Configuration
|
||||
|
||||
Update your project's `.bmad/bmm/config.yaml` to set the `project_url`:
|
||||
|
||||
```yaml
|
||||
# .bmad/bmm/config.yaml
|
||||
|
||||
project_url: "http://localhost:5173" # Dev
|
||||
# project_url: "https://your-app.com" # Prod
|
||||
```
|
||||
|
||||
The triage workflow will use this to call your API endpoints.
|
||||
|
||||
## 6. API Response Format
|
||||
|
||||
The workflow expects these response formats:
|
||||
|
||||
### GET /api/bug-reports/pending
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"reports": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"title": "Bug title",
|
||||
"description": "Bug description",
|
||||
"reporterType": "staff",
|
||||
"reporterName": "John Doe",
|
||||
"platform": "macOS",
|
||||
"browser": "Chrome",
|
||||
"pageUrl": "https://...",
|
||||
"screenshotUrl": "https://...",
|
||||
"createdAt": "2025-01-01T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"count": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/bug-reports/mark-synced
|
||||
|
||||
Request:
|
||||
```json
|
||||
{ "ids": ["uuid1", "uuid2"] }
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"updatedCount": 2,
|
||||
"updatedIds": ["uuid1", "uuid2"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 7. Optional: Screenshot Storage
|
||||
|
||||
For screenshot uploads, you'll need cloud storage (R2, S3, etc.):
|
||||
|
||||
1. Create an upload endpoint: `POST /api/bug-reports/[id]/upload-screenshot`
|
||||
2. Upload to cloud storage
|
||||
3. Update `screenshotUrl` on the bug report record
|
||||
|
||||
## 8. Security Considerations
|
||||
|
||||
- **Authentication**: Create endpoint should require auth
|
||||
- **API Key**: Consider adding API key auth for pending/mark-synced endpoints in production
|
||||
- **Rate Limiting**: Add rate limits to prevent spam
|
||||
- **Input Sanitization**: Validate all user input (handled by Zod schemas)
|
||||
|
||||
## Without In-App Reporting
|
||||
|
||||
If you don't implement in-app reporting, the workflow still works:
|
||||
|
||||
1. Users manually add bugs to `docs/bugs.md` under `# manual input`
|
||||
2. Run `/triage` to process them
|
||||
3. Workflow skips Step 0 (API sync) when no API is available
|
||||
|
||||
The workflows are designed to be flexible and work with or without the in-app feature.
|
||||
|
|
@ -0,0 +1,167 @@
|
|||
# Step 1: Bug Tracking Workflow Initialization
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete triage
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
|
||||
- ✅ ALWAYS treat this as collaborative triage between peers
|
||||
- 📋 YOU ARE A FACILITATOR, not an automatic processor
|
||||
- 💬 FOCUS on initialization and setup only - don't look ahead to future steps
|
||||
- 🚪 DETECT existing workflow state and handle continuation properly
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Show your analysis before taking any action
|
||||
- 💾 Initialize bugs.yaml if needed
|
||||
- 📖 Track workflow state for potential continuation
|
||||
- 🚫 FORBIDDEN to load next step until setup is complete
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Variables from workflow.md are available in memory
|
||||
- bugs.yaml tracks all structured bug metadata
|
||||
- bugs.md is the user-facing input file
|
||||
- Don't assume knowledge from other steps
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
Initialize the Bug Tracking workflow by detecting existing state, discovering input files, and setting up for collaborative triage.
|
||||
|
||||
## INITIALIZATION SEQUENCE:
|
||||
|
||||
### 1. Check for Existing Session
|
||||
|
||||
First, check workflow state:
|
||||
|
||||
- Look for existing `{bugs_output}` (bugs.yaml)
|
||||
- If exists, grep for bugs with `status: triaged` (pending implementation)
|
||||
- Check `{bugs_input}` (bugs.md) for items in "# manual input" section
|
||||
|
||||
### 2. Handle Continuation (If Pending Work Exists)
|
||||
|
||||
If bugs.yaml exists with triaged bugs awaiting action:
|
||||
|
||||
- **STOP here** and load `./step-01b-continue.md` immediately
|
||||
- Do not proceed with fresh initialization
|
||||
- Let step-01b handle the continuation logic
|
||||
|
||||
### 3. Fresh Workflow Setup (If No Pending Work)
|
||||
|
||||
If no bugs.yaml exists OR no pending triaged bugs:
|
||||
|
||||
#### A. Input File Discovery
|
||||
|
||||
Discover and validate required files:
|
||||
|
||||
**Required Files:**
|
||||
- `{bugs_input}` (bugs.md) - User-facing bug reports
|
||||
- Must have "# manual input" section for new bugs
|
||||
- May have "# Tracked Bugs" and "# Fixed Bugs" sections
|
||||
|
||||
**Optional Context Files:**
|
||||
- `{sprint_status}` - Current sprint context (which stories are in progress)
|
||||
- `{epics_file}` - For mapping bugs to related stories/epics
|
||||
|
||||
#### B. Initialize bugs.yaml (If Not Exists)
|
||||
|
||||
If bugs.yaml doesn't exist, create it with header structure:
|
||||
|
||||
```yaml
|
||||
# Bug Tracking Database
|
||||
# Generated by bug-tracking workflow
|
||||
# Last updated: {date}
|
||||
|
||||
# Severity Definitions:
|
||||
# - critical: Prevents core functionality, crashes, data loss
|
||||
# - high: Blocks major features, significantly degrades UX
|
||||
# - medium: Affects subset of users, minor impact with workaround
|
||||
# - low: Cosmetic, edge case, or minor inconvenience
|
||||
|
||||
# Complexity Definitions:
|
||||
# - trivial: One-line fix, obvious solution
|
||||
# - small: Single file/component, solution clear
|
||||
# - medium: Multiple files OR requires investigation
|
||||
# - complex: Architectural change, affects many areas
|
||||
|
||||
# Workflow Routing Matrix:
|
||||
# - critical + any → correct-course
|
||||
# - high + trivial → direct-fix
|
||||
# - high + small → tech-spec
|
||||
# - high + medium/complex → correct-course
|
||||
# - medium + trivial → direct-fix
|
||||
# - medium + small → tech-spec
|
||||
# - medium + medium/complex → correct-course
|
||||
# - low + trivial → direct-fix
|
||||
# - low + small/medium/complex → backlog
|
||||
|
||||
bugs: []
|
||||
features: []
|
||||
closed_bugs: []
|
||||
|
||||
statistics:
|
||||
total_active: 0
|
||||
by_severity:
|
||||
critical: 0
|
||||
high: 0
|
||||
medium: 0
|
||||
low: 0
|
||||
last_updated: {date}
|
||||
```
|
||||
|
||||
#### C. Scan for New Bugs
|
||||
|
||||
Read ONLY the "# manual input" section from bugs.md:
|
||||
- Grep for "# manual input" to find starting line
|
||||
- Grep for next section header to find ending line
|
||||
- Read just that range (do NOT read entire file)
|
||||
|
||||
Count items found in manual input section.
|
||||
|
||||
#### D. Complete Initialization and Report
|
||||
|
||||
Report to user:
|
||||
|
||||
"Welcome {user_name}! I've initialized the Bug Tracking workspace for {project_name}.
|
||||
|
||||
**Files Status:**
|
||||
- bugs.md: {found/created} - {count} item(s) in manual input section
|
||||
- bugs.yaml: {found/created} - {active_count} active bugs tracked
|
||||
|
||||
**Context Files:**
|
||||
- Sprint Status: {loaded/not found}
|
||||
- Epics: {loaded/not found}
|
||||
|
||||
**Ready for Triage:**
|
||||
{count} new item(s) found in manual input section.
|
||||
|
||||
[S] Sync bug reports from API first (if app integration configured)
|
||||
[C] Continue to parse and triage bugs
|
||||
[Q] Quit - no new bugs to triage"
|
||||
|
||||
## SUCCESS METRICS:
|
||||
|
||||
✅ Existing workflow detected and handed off to step-01b correctly
|
||||
✅ Fresh workflow initialized with bugs.yaml structure
|
||||
✅ Input files discovered and validated
|
||||
✅ Manual input section scanned for new items
|
||||
✅ User informed of status and can proceed
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
❌ Proceeding with fresh initialization when pending work exists
|
||||
❌ Not creating bugs.yaml with proper header/definitions
|
||||
❌ Reading entire bugs.md instead of just manual input section
|
||||
❌ Not reporting status to user before proceeding
|
||||
|
||||
❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding
|
||||
❌ **CRITICAL**: Proceeding with 'C' without fully reading the next step file
|
||||
|
||||
## NEXT STEP:
|
||||
|
||||
- If user selects [S], load `./step-02-sync.md` to sync from API
|
||||
- If user selects [C], load `./step-03-parse.md` to parse and identify new bugs
|
||||
- If user selects [Q], end workflow gracefully
|
||||
|
||||
Remember: Do NOT proceed until user explicitly selects an option from the menu!
|
||||
|
|
@ -0,0 +1,110 @@
|
|||
# Step 1b: Continue Existing Bug Tracking Session
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
|
||||
- ✅ ALWAYS treat this as collaborative triage between peers
|
||||
- 📋 YOU ARE A FACILITATOR, not an automatic processor
|
||||
- 🚪 This step handles CONTINUATION of existing work
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Summarize existing state before offering options
|
||||
- 💾 Preserve all existing bugs.yaml data
|
||||
- 📖 Help user understand where they left off
|
||||
- 🚫 FORBIDDEN to lose or overwrite existing triage work
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Variables from workflow.md are available in memory
|
||||
- bugs.yaml contains existing structured data
|
||||
- User may have triaged bugs awaiting implementation
|
||||
- Don't re-triage already processed bugs
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
Welcome user back and summarize the current state of bug tracking, offering relevant continuation options.
|
||||
|
||||
## CONTINUATION SEQUENCE:
|
||||
|
||||
### 1. Load Current State
|
||||
|
||||
Read bugs.yaml and extract:
|
||||
- Total active bugs count
|
||||
- Bugs by status (triaged, implemented, verified)
|
||||
- Bugs by severity breakdown
|
||||
- Bugs by recommended workflow
|
||||
|
||||
### 2. Check for New Input
|
||||
|
||||
Scan "# manual input" section of bugs.md:
|
||||
- Count items not yet in bugs.yaml
|
||||
- These are new bugs needing triage
|
||||
|
||||
### 3. Present Continuation Summary
|
||||
|
||||
Report to user:
|
||||
|
||||
"Welcome back, {user_name}! Here's your Bug Tracking status for {project_name}.
|
||||
|
||||
**Current State:**
|
||||
- Active Bugs: {total_active}
|
||||
- Triaged (awaiting action): {triaged_count}
|
||||
- Implemented (awaiting verification): {implemented_count}
|
||||
- By Severity: Critical: {critical} | High: {high} | Medium: {medium} | Low: {low}
|
||||
|
||||
**Workflow Routing:**
|
||||
- Direct Fix: {direct_fix_count} bug(s)
|
||||
- Tech-Spec: {tech_spec_count} bug(s)
|
||||
- Correct-Course: {correct_course_count} bug(s)
|
||||
- Backlog: {backlog_count} bug(s)
|
||||
|
||||
**New Items:**
|
||||
- {new_count} new item(s) found in manual input section
|
||||
|
||||
**Options:**
|
||||
[T] Triage new bugs ({new_count} items)
|
||||
[I] Implement a bug - `/implement bug-NNN`
|
||||
[V] Verify implemented bugs - `/verify`
|
||||
[L] List bugs by status/severity
|
||||
[Q] Quit"
|
||||
|
||||
### 4. Handle User Selection
|
||||
|
||||
Based on user choice:
|
||||
|
||||
- **[T] Triage**: Load `./step-03-parse.md` to process new bugs
|
||||
- **[I] Implement**: Guide user to run `/implement bug-NNN` skill
|
||||
- **[V] Verify**: Guide user to run `/verify` skill
|
||||
- **[L] List**: Show filtered bug list, then return to menu
|
||||
- **[Q] Quit**: End workflow gracefully
|
||||
|
||||
## SUCCESS METRICS:
|
||||
|
||||
✅ Existing state accurately summarized
|
||||
✅ New items detected and counted
|
||||
✅ User given clear options based on current state
|
||||
✅ Appropriate next step loaded based on selection
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
❌ Losing track of existing triaged bugs
|
||||
❌ Re-triaging already processed bugs
|
||||
❌ Not detecting new items in manual input
|
||||
❌ Proceeding without user selection
|
||||
|
||||
❌ **CRITICAL**: Reading only partial step file
|
||||
❌ **CRITICAL**: Proceeding without explicit user menu selection
|
||||
|
||||
## NEXT STEP:
|
||||
|
||||
Load appropriate step based on user selection:
|
||||
- [T] → `./step-03-parse.md`
|
||||
- [I], [V] → Guide to relevant skill, then return here
|
||||
- [L] → Display list, return to this menu
|
||||
- [Q] → End workflow
|
||||
|
||||
Remember: Do NOT proceed until user explicitly selects an option!
|
||||
|
|
@ -0,0 +1,145 @@
|
|||
# Step 2: Sync Bug Reports from API
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
|
||||
- ✅ ALWAYS treat this as collaborative triage between peers
|
||||
- 📋 YOU ARE A FACILITATOR, not an automatic processor
|
||||
- 🌐 This step handles OPTIONAL API integration for in-app bug reporting
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Attempt API sync only if configured
|
||||
- 💾 Preserve existing manual input entries
|
||||
- 📖 Format synced reports as markdown entries
|
||||
- 🚫 FORBIDDEN to lose manually entered bugs
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Variables from workflow.md are available in memory
|
||||
- `project_url` may or may not be configured
|
||||
- API endpoints are optional - gracefully handle if unavailable
|
||||
- This step can be skipped if no API integration
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
Sync pending bug reports from the application's PostgreSQL database via API, formatting them as markdown entries in bugs.md.
|
||||
|
||||
## SYNC SEQUENCE:
|
||||
|
||||
### 1. Check API Configuration
|
||||
|
||||
Verify `{project_url}` is configured:
|
||||
- If not configured or user skipped this step, proceed to step-03
|
||||
- If configured, attempt API connection
|
||||
|
||||
### 2. Fetch Pending Reports
|
||||
|
||||
**API Call:**
|
||||
```
|
||||
GET {project_url}/api/bug-reports/pending
|
||||
```
|
||||
|
||||
**Expected Response:**
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"reports": [...],
|
||||
"count": number
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Report Fields:**
|
||||
- `id` - Database ID
|
||||
- `title` - Bug title
|
||||
- `description` - Bug description
|
||||
- `reporterType` - Type of reporter (user, staff, admin)
|
||||
- `reporterName` - Name of reporter
|
||||
- `platform` - Platform (iOS, Android, web)
|
||||
- `browser` - Browser if web
|
||||
- `pageUrl` - URL where bug occurred
|
||||
- `screenshotUrl` - Optional screenshot
|
||||
- `createdAt` - Timestamp
|
||||
|
||||
### 3. Handle No Reports
|
||||
|
||||
If count == 0:
|
||||
|
||||
"No new bug reports from the application API.
|
||||
|
||||
[C] Continue to triage existing manual input
|
||||
[Q] Quit - nothing to process"
|
||||
|
||||
### 4. Format Reports as Markdown
|
||||
|
||||
For each report, create markdown entry:
|
||||
|
||||
```markdown
|
||||
## Bug: {title}
|
||||
|
||||
{description}
|
||||
|
||||
Reported by: {reporterName} ({reporterType})
|
||||
Date: {createdAt formatted as YYYY-MM-DD}
|
||||
Platform: {platform} / {browser}
|
||||
Page: {pageUrl}
|
||||
{if screenshotUrl: Screenshot: {screenshotUrl}}
|
||||
```
|
||||
|
||||
### 5. Insert into bugs.md
|
||||
|
||||
- Read the "# manual input" section location from bugs.md
|
||||
- Insert new markdown entries after the "# manual input" header
|
||||
- Preserve any existing manual input entries
|
||||
- Write updated bugs.md
|
||||
|
||||
### 6. Mark Reports as Synced
|
||||
|
||||
**API Call:**
|
||||
```
|
||||
POST {project_url}/api/bug-reports/mark-synced
|
||||
Body: { "ids": [array of synced report IDs] }
|
||||
```
|
||||
|
||||
This updates status to 'synced' so reports won't be fetched again.
|
||||
|
||||
### 7. Report Sync Results
|
||||
|
||||
"**Synced {count} bug report(s) from application:**
|
||||
|
||||
{for each report:}
|
||||
- {title} (from {reporterName})
|
||||
{end for}
|
||||
|
||||
These have been added to the manual input section of bugs.md.
|
||||
|
||||
[C] Continue to parse and triage all bugs
|
||||
[Q] Quit"
|
||||
|
||||
## SUCCESS METRICS:
|
||||
|
||||
✅ API availability checked gracefully
|
||||
✅ Pending reports fetched and formatted
|
||||
✅ Existing manual entries preserved
|
||||
✅ Reports marked as synced in database
|
||||
✅ User informed of sync results
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
❌ Crashing if API unavailable (should gracefully skip)
|
||||
❌ Overwriting existing manual input entries
|
||||
❌ Not marking reports as synced (causes duplicates)
|
||||
❌ Proceeding without user confirmation
|
||||
|
||||
❌ **CRITICAL**: Reading only partial step file
|
||||
❌ **CRITICAL**: Proceeding without explicit user selection
|
||||
|
||||
## NEXT STEP:
|
||||
|
||||
After user selects [C], load `./step-03-parse.md` to parse and identify all bugs needing triage.
|
||||
|
||||
Remember: Do NOT proceed until user explicitly selects [C] from the menu!
|
||||
|
|
@ -0,0 +1,164 @@
|
|||
# Step 3: Parse and Identify New Bugs
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
|
||||
- ✅ ALWAYS treat this as collaborative triage between peers
|
||||
- 📋 YOU ARE A FACILITATOR, not an automatic processor
|
||||
- 🔍 This step PARSES input only - triage happens in next step
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Parse manual input section thoroughly
|
||||
- 💾 Compare against existing bugs.yaml entries
|
||||
- 📖 Extract all available information from informal reports
|
||||
- 🚫 FORBIDDEN to start triage in this step - parsing only
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Variables from workflow.md are available in memory
|
||||
- bugs.yaml contains existing triaged bugs
|
||||
- Only parse "# manual input" section of bugs.md
|
||||
- Do NOT read entire bugs.md file
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
Parse the "# manual input" section of bugs.md, extract bug information, and identify which items need triage.
|
||||
|
||||
## PARSE SEQUENCE:
|
||||
|
||||
### 1. Read Manual Input Section
|
||||
|
||||
Section-based reading of bugs.md:
|
||||
- Grep for "# manual input" to find starting line number
|
||||
- Grep for next section header ("# Tracked Bugs", "# Tracked Feature Requests", "# Fixed Bugs") to find ending line
|
||||
- Read just that range using offset/limit (do NOT read entire file)
|
||||
- If no closing section found within initial window, expand read range and retry
|
||||
|
||||
### 2. Search Existing IDs in bugs.yaml
|
||||
|
||||
Do NOT read entire bugs.yaml file:
|
||||
- Grep for `id: bug-[0-9]+` pattern to find all existing bug IDs
|
||||
- Grep for `id: feature-[0-9]+` pattern to find all existing feature IDs
|
||||
- This enables duplicate detection and next-ID generation
|
||||
|
||||
### 3. Parse Bug Reports
|
||||
|
||||
Expected formats in manual input (informal, user-written):
|
||||
|
||||
**Format A: Markdown Headers**
|
||||
```markdown
|
||||
## Bug: Title Here
|
||||
|
||||
Description text, possibly multi-paragraph.
|
||||
|
||||
Reported by: Name
|
||||
Date: YYYY-MM-DD
|
||||
Related: Story 2.7
|
||||
Platform: iOS
|
||||
```
|
||||
|
||||
**Format B: Bullet Lists**
|
||||
```markdown
|
||||
- **Title (Platform)**: Description text. CRITICAL if urgent.
|
||||
```
|
||||
|
||||
**Format C: Numbered Lists**
|
||||
```markdown
|
||||
1. Title - Description text
|
||||
2. Another bug - More description
|
||||
```
|
||||
|
||||
### 4. Extract Information
|
||||
|
||||
For each bug report, extract:
|
||||
|
||||
| Field | Required | Notes |
|
||||
|-------|----------|-------|
|
||||
| Title | Yes | First line or header |
|
||||
| Description | Yes | May be multi-paragraph |
|
||||
| Reported by | No | Extract if mentioned |
|
||||
| Date | No | Extract if mentioned |
|
||||
| Related story | No | e.g., "2-7", "Story 2.7" |
|
||||
| Platform | No | iOS, Android, web, all |
|
||||
| Reproduction steps | No | If provided |
|
||||
| Severity hints | No | "CRITICAL", "urgent", etc. |
|
||||
|
||||
### 5. Categorize Items
|
||||
|
||||
Compare extracted bugs with existing bugs.yaml:
|
||||
|
||||
- **New bugs**: Not in bugs.yaml yet (need full triage)
|
||||
- **Updated bugs**: In bugs.yaml but description changed (need re-triage)
|
||||
- **Feature requests**: Items that are enhancements, not bugs
|
||||
- **Unchanged**: Already triaged, skip
|
||||
|
||||
### 6. Handle No New Bugs
|
||||
|
||||
If NO new bugs found:
|
||||
|
||||
"No new bugs found in the manual input section.
|
||||
|
||||
All items have already been triaged and are tracked in bugs.yaml.
|
||||
|
||||
**Options:**
|
||||
1. Add new bugs to docs/bugs.md (informal format)
|
||||
2. View bugs.yaml to see structured bug tracking
|
||||
3. Route existing triaged bugs to workflows
|
||||
|
||||
[Q] Quit - nothing to triage"
|
||||
|
||||
**HALT** - Do not proceed.
|
||||
|
||||
### 7. Present Parsed Items
|
||||
|
||||
"**Parsed {total_count} item(s) from manual input:**
|
||||
|
||||
**New Bugs ({new_count}):**
|
||||
{for each new bug:}
|
||||
- {extracted_title}
|
||||
- Description: {first 100 chars}...
|
||||
- Platform: {platform or "not specified"}
|
||||
- Related: {story or "not specified"}
|
||||
{end for}
|
||||
|
||||
**Feature Requests ({feature_count}):**
|
||||
{for each feature:}
|
||||
- {title}
|
||||
{end for}
|
||||
|
||||
**Already Triaged ({unchanged_count}):**
|
||||
{list titles of skipped items}
|
||||
|
||||
Ready to triage {new_count} new bug(s) and {feature_count} feature request(s).
|
||||
|
||||
[C] Continue to triage
|
||||
[E] Edit - re-parse with corrections
|
||||
[Q] Quit"
|
||||
|
||||
## SUCCESS METRICS:
|
||||
|
||||
✅ Manual input section read efficiently (not entire file)
|
||||
✅ All formats parsed correctly (headers, bullets, numbered)
|
||||
✅ Existing bugs detected to prevent duplicates
|
||||
✅ New vs updated vs unchanged correctly categorized
|
||||
✅ User shown summary and can proceed
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
❌ Reading entire bugs.md instead of section
|
||||
❌ Missing bugs due to format not recognized
|
||||
❌ Not detecting duplicates against bugs.yaml
|
||||
❌ Starting triage in this step (should only parse)
|
||||
|
||||
❌ **CRITICAL**: Reading only partial step file
|
||||
❌ **CRITICAL**: Proceeding without user selection
|
||||
|
||||
## NEXT STEP:
|
||||
|
||||
After user selects [C], load `./step-04-triage.md` to perform triage analysis on each new bug.
|
||||
|
||||
Remember: Do NOT proceed until user explicitly selects [C] from the menu!
|
||||
|
|
@ -0,0 +1,212 @@
|
|||
# Step 4: Triage Each Bug
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
|
||||
- ✅ ALWAYS treat this as collaborative triage between peers
|
||||
- 📋 YOU ARE A FACILITATOR - ask clarifying questions when needed
|
||||
- 🎯 This step performs the CORE TRIAGE analysis
|
||||
- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed varies widely
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Triage ONE bug at a time with user confirmation
|
||||
- 💾 Track triage decisions for bugs.yaml update
|
||||
- 📖 Ask clarifying questions when severity/complexity unclear
|
||||
- 🚫 FORBIDDEN to auto-triage without user review
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Parsed bugs from step-03 are in memory
|
||||
- Reference bugs.yaml header for severity/complexity definitions
|
||||
- Reference epics.md for story mapping
|
||||
- Each bug gets full triage analysis
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
Perform collaborative triage analysis on each parsed bug, assessing severity, complexity, effort, workflow routing, and documentation impact.
|
||||
|
||||
## TRIAGE SEQUENCE (FOR EACH BUG):
|
||||
|
||||
### 1. Generate Bug ID
|
||||
|
||||
- Find highest existing bug-NNN from step-03 grep results
|
||||
- Assign next sequential ID (e.g., bug-006)
|
||||
- Format: `bug-` + zero-padded 3-digit number
|
||||
- For features: `feature-` + zero-padded 3-digit number
|
||||
|
||||
### 2. Assess Severity
|
||||
|
||||
**Severity Levels:**
|
||||
| Level | Criteria |
|
||||
|-------|----------|
|
||||
| critical | Prevents core functionality, crashes, data loss |
|
||||
| high | Blocks major features, significantly degrades UX but has workaround |
|
||||
| medium | Affects subset of users, minor impact |
|
||||
| low | Cosmetic, edge case, minor inconvenience |
|
||||
|
||||
**Analysis Questions:**
|
||||
- Does it prevent core functionality? → critical
|
||||
- Does it cause crashes or data loss? → critical
|
||||
- Does it block major features? → high
|
||||
- Does it significantly degrade UX but have workaround? → high
|
||||
- Does it affect subset of users with minor impact? → medium
|
||||
- Is it cosmetic or edge case? → low
|
||||
|
||||
**If Unclear - ASK:**
|
||||
"**Clarification needed for: {bug_title}**
|
||||
|
||||
I need more information to assess severity:
|
||||
1. Does this bug prevent users from completing core flows?
|
||||
2. Does the bug cause crashes or data loss?
|
||||
3. How many users are affected? (all users, specific platform, edge case)
|
||||
4. Is there a workaround available?
|
||||
|
||||
Please provide additional context."
|
||||
|
||||
### 3. Assess Complexity
|
||||
|
||||
**Complexity Levels:**
|
||||
| Level | Criteria |
|
||||
|-------|----------|
|
||||
| trivial | One-line fix, obvious solution |
|
||||
| small | Single file/component, solution clear |
|
||||
| medium | Multiple files OR requires investigation |
|
||||
| complex | Architectural change, affects many areas |
|
||||
|
||||
**If Unclear - ASK:**
|
||||
"**Clarification needed for: {bug_title}**
|
||||
|
||||
To estimate complexity, I need:
|
||||
1. Have you identified the root cause, or does it need investigation?
|
||||
2. Which file(s) or component(s) are affected?
|
||||
3. Is this isolated or does it affect multiple parts of the app?
|
||||
|
||||
Please provide technical details if available."
|
||||
|
||||
### 4. Determine Workflow Routing
|
||||
|
||||
**Routing Matrix:**
|
||||
| Severity | Complexity | Workflow |
|
||||
|----------|------------|----------|
|
||||
| critical | any | correct-course |
|
||||
| high | trivial | direct-fix |
|
||||
| high | small | tech-spec |
|
||||
| high | medium/complex | correct-course |
|
||||
| medium | trivial | direct-fix |
|
||||
| medium | small | tech-spec |
|
||||
| medium | medium/complex | correct-course |
|
||||
| low | trivial | direct-fix |
|
||||
| low | small+ | backlog |
|
||||
|
||||
### 5. Map to Related Story/Epic
|
||||
|
||||
- If bug mentions story ID (e.g., "2-7"), use that
|
||||
- Otherwise, infer from description using epic keywords
|
||||
- Reference epics.md for story matching
|
||||
- Format: `{epic_number}-{story_number}` or null
|
||||
|
||||
### 6. Determine Affected Platform
|
||||
|
||||
Extract from description:
|
||||
- `all` - Default if not specified
|
||||
- `ios` - iOS only
|
||||
- `android` - Android only
|
||||
- `web` - Web only
|
||||
|
||||
### 7. Assess Documentation Impact
|
||||
|
||||
**PRD Impact** (`doc_impact.prd: true/false`)
|
||||
Set TRUE if issue:
|
||||
- Conflicts with stated product goals
|
||||
- Requires changing MVP scope
|
||||
- Adds/removes/modifies core functionality
|
||||
- Changes success metrics
|
||||
- Affects multiple epics
|
||||
|
||||
**Architecture Impact** (`doc_impact.architecture: true/false`)
|
||||
Set TRUE if issue:
|
||||
- Requires new system components
|
||||
- Changes data model (new tables, schema)
|
||||
- Affects API contracts
|
||||
- Introduces new dependencies
|
||||
- Changes auth/security model
|
||||
|
||||
**UX Impact** (`doc_impact.ux: true/false`)
|
||||
Set TRUE if issue:
|
||||
- Adds new screens or navigation
|
||||
- Changes existing user flows
|
||||
- Requires new UI components
|
||||
- Affects accessibility
|
||||
|
||||
**If any doc_impact is TRUE AND workflow != correct-course:**
|
||||
- Override workflow to `correct-course`
|
||||
- Add note: "Workflow elevated due to documentation impact"
|
||||
|
||||
### 8. Add Triage Notes
|
||||
|
||||
Document reasoning:
|
||||
- Why this severity? (business impact, user impact)
|
||||
- Why this complexity? (investigation needed, files affected)
|
||||
- Why this workflow? (routing logic applied)
|
||||
- Suggested next steps or investigation areas
|
||||
|
||||
### 9. Present Triage for Confirmation
|
||||
|
||||
"**Triage: {bug_id} - {bug_title}**
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Severity | {severity} |
|
||||
| Complexity | {complexity} |
|
||||
| Platform | {platform} |
|
||||
| Workflow | {recommended_workflow} |
|
||||
| Related | {related_story or 'None'} |
|
||||
|
||||
**Documentation Impact:**
|
||||
- PRD: {yes/no}
|
||||
- Architecture: {yes/no}
|
||||
- UX: {yes/no}
|
||||
|
||||
**Triage Notes:**
|
||||
{triage_notes}
|
||||
|
||||
[A] Accept triage
|
||||
[M] Modify - adjust severity/complexity/workflow
|
||||
[S] Skip - don't triage this item now
|
||||
[N] Next bug (after accepting)"
|
||||
|
||||
### 10. Handle Modifications
|
||||
|
||||
If user selects [M]:
|
||||
- Ask which field to modify
|
||||
- Accept new value
|
||||
- Re-present triage for confirmation
|
||||
|
||||
## SUCCESS METRICS:
|
||||
|
||||
✅ Each bug triaged with user confirmation
|
||||
✅ Unclear items prompted for clarification
|
||||
✅ Routing matrix applied correctly
|
||||
✅ Documentation impact assessed
|
||||
✅ Triage notes document reasoning
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
❌ Auto-triaging without user review
|
||||
❌ Not asking clarifying questions when needed
|
||||
❌ Incorrect routing matrix application
|
||||
❌ Missing documentation impact assessment
|
||||
❌ Not documenting triage reasoning
|
||||
|
||||
❌ **CRITICAL**: Reading only partial step file
|
||||
❌ **CRITICAL**: Proceeding without user confirmation per bug
|
||||
|
||||
## NEXT STEP:
|
||||
|
||||
After ALL bugs triaged (user selected [A] or [N] for each), load `./step-05-update.md` to update bugs.yaml and bugs.md.
|
||||
|
||||
Remember: Triage each bug individually with user confirmation!
|
||||
|
|
@ -0,0 +1,200 @@
|
|||
# Step 5: Update Files with Triaged Metadata
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
|
||||
- ✅ ALWAYS treat this as collaborative triage between peers
|
||||
- 📋 YOU ARE A FACILITATOR, not an automatic processor
|
||||
- 💾 This step WRITES the triage results to files
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Update both bugs.yaml and bugs.md atomically
|
||||
- 💾 Preserve ALL existing data - append only
|
||||
- 📖 Move items from manual input to tracked sections
|
||||
- 🚫 FORBIDDEN to lose or corrupt existing data
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Triage decisions from step-04 are in memory
|
||||
- bugs.yaml structure defined in step-01
|
||||
- bugs.md sections: manual input, Tracked Bugs, Tracked Feature Requests, Fixed Bugs
|
||||
- Preserve header comments and definitions
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
Write all triaged metadata to bugs.yaml and move triaged items from "# manual input" to appropriate tracked sections in bugs.md.
|
||||
|
||||
## UPDATE SEQUENCE:
|
||||
|
||||
### 1. Update bugs.yaml
|
||||
|
||||
#### A. Load Existing Structure
|
||||
|
||||
Read current bugs.yaml (if exists):
|
||||
- Preserve ALL header comments and definitions
|
||||
- Preserve existing `bugs:` array entries
|
||||
- Preserve existing `features:` array entries
|
||||
- Preserve existing `closed_bugs:` array
|
||||
|
||||
#### B. Add New Bug Entries
|
||||
|
||||
For each triaged bug, add to `bugs:` array:
|
||||
|
||||
```yaml
|
||||
- id: bug-NNN
|
||||
title: "Bug title"
|
||||
description: |
|
||||
Full description text
|
||||
Can be multi-line
|
||||
severity: critical|high|medium|low
|
||||
complexity: trivial|small|medium|complex
|
||||
affected_platform: all|ios|android|web
|
||||
recommended_workflow: direct-fix|tech-spec|correct-course|backlog
|
||||
related_story: "X-Y" or null
|
||||
status: triaged
|
||||
reported_by: "Name" or null
|
||||
reported_date: "YYYY-MM-DD" or null
|
||||
triaged_date: "{date}"
|
||||
doc_impact:
|
||||
prd: true|false
|
||||
architecture: true|false
|
||||
ux: true|false
|
||||
notes: "Impact description" or null
|
||||
triage_notes: |
|
||||
Reasoning for severity, complexity, workflow decisions
|
||||
implemented_by: null
|
||||
implemented_date: null
|
||||
verified_by: null
|
||||
verified_date: null
|
||||
```
|
||||
|
||||
#### C. Add Feature Request Entries
|
||||
|
||||
For features, add to `features:` array with similar structure.
|
||||
|
||||
#### D. Update Statistics
|
||||
|
||||
Recalculate statistics section:
|
||||
|
||||
```yaml
|
||||
statistics:
|
||||
total_active: {count of non-closed bugs}
|
||||
by_severity:
|
||||
critical: {count}
|
||||
high: {count}
|
||||
medium: {count}
|
||||
low: {count}
|
||||
by_status:
|
||||
triaged: {count}
|
||||
implemented: {count}
|
||||
verified: {count}
|
||||
by_workflow:
|
||||
direct-fix: {count}
|
||||
tech-spec: {count}
|
||||
correct-course: {count}
|
||||
backlog: {count}
|
||||
last_updated: "{date}"
|
||||
```
|
||||
|
||||
#### E. Write bugs.yaml
|
||||
|
||||
Write complete bugs.yaml file preserving all content.
|
||||
|
||||
### 2. Update bugs.md
|
||||
|
||||
#### A. Section-Based Reading
|
||||
|
||||
Use grep to locate section line numbers:
|
||||
- "# manual input"
|
||||
- "# Tracked Bugs"
|
||||
- "# Tracked Feature Requests"
|
||||
- "# Fixed Bugs"
|
||||
|
||||
Read only relevant sections with offset/limit.
|
||||
|
||||
#### B. Remove from Manual Input
|
||||
|
||||
For each triaged item:
|
||||
- Remove the original entry from "# manual input" section
|
||||
- Handle both header format and bullet format
|
||||
|
||||
#### C. Add to Tracked Bugs
|
||||
|
||||
For each triaged bug, add to "# Tracked Bugs" section:
|
||||
|
||||
```markdown
|
||||
### {bug_id}: {title}
|
||||
|
||||
{brief_description}
|
||||
|
||||
- **Severity:** {severity}
|
||||
- **Complexity:** {complexity}
|
||||
- **Platform:** {platform}
|
||||
- **Workflow:** {workflow}
|
||||
- **Related:** {story or "None"}
|
||||
{if doc_impact flagged:}
|
||||
- **Doc Impact:** {PRD|Architecture|UX as applicable}
|
||||
{end if}
|
||||
|
||||
**Notes:** {triage_notes_summary}
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
Create "# Tracked Bugs" section if it doesn't exist.
|
||||
|
||||
#### D. Add to Tracked Feature Requests
|
||||
|
||||
For features, add to "# Tracked Feature Requests" section with similar format.
|
||||
|
||||
#### E. Write bugs.md
|
||||
|
||||
Write updated bugs.md preserving all sections.
|
||||
|
||||
### 3. Confirm Updates
|
||||
|
||||
"**Files Updated:**
|
||||
|
||||
**bugs.yaml:**
|
||||
- Added {bug_count} new bug(s)
|
||||
- Added {feature_count} new feature request(s)
|
||||
- Total active bugs: {total_active}
|
||||
- Statistics recalculated
|
||||
|
||||
**bugs.md:**
|
||||
- Removed {count} item(s) from manual input
|
||||
- Added {bug_count} bug(s) to Tracked Bugs section
|
||||
- Added {feature_count} feature(s) to Tracked Feature Requests section
|
||||
|
||||
[C] Continue to summary
|
||||
[R] Review changes - show diff
|
||||
[U] Undo - restore previous state"
|
||||
|
||||
## SUCCESS METRICS:
|
||||
|
||||
✅ bugs.yaml updated with all triaged metadata
|
||||
✅ bugs.md items moved from manual input to tracked sections
|
||||
✅ Statistics accurately recalculated
|
||||
✅ All existing data preserved
|
||||
✅ User confirmed updates
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
❌ Losing existing bugs.yaml entries
|
||||
❌ Corrupting bugs.md structure
|
||||
❌ Items remaining in manual input after triage
|
||||
❌ Statistics not matching actual data
|
||||
❌ Not preserving header comments/definitions
|
||||
|
||||
❌ **CRITICAL**: Reading only partial step file
|
||||
❌ **CRITICAL**: Proceeding without user confirmation
|
||||
|
||||
## NEXT STEP:
|
||||
|
||||
After user selects [C], load `./step-06-complete.md` to present final triage summary.
|
||||
|
||||
Remember: Do NOT proceed until user explicitly selects [C] from the menu!
|
||||
|
|
@ -0,0 +1,180 @@
|
|||
# Step 6: Triage Complete - Summary and Next Steps
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
|
||||
- ✅ ALWAYS treat this as collaborative triage between peers
|
||||
- 📋 YOU ARE A FACILITATOR, not an automatic processor
|
||||
- 🎉 This is the FINAL step - present comprehensive summary
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Present comprehensive triage summary
|
||||
- 💾 All data already written in step-05
|
||||
- 📖 Guide user to next actions
|
||||
- 🚫 FORBIDDEN to modify files in this step
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- All triage decisions finalized in previous steps
|
||||
- bugs.yaml and bugs.md already updated
|
||||
- This step is READ-ONLY presentation
|
||||
- Focus on actionable next steps
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
Present a comprehensive summary of the triage session and guide the user to appropriate next actions based on workflow recommendations.
|
||||
|
||||
## COMPLETION SEQUENCE:
|
||||
|
||||
### 1. Present Triage Summary
|
||||
|
||||
"**Bug Triage Complete, {user_name}!**
|
||||
|
||||
---
|
||||
|
||||
## Triaged Items
|
||||
|
||||
{for each triaged bug:}
|
||||
|
||||
### {bug_id}: {bug_title}
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Severity | {severity} |
|
||||
| Complexity | {complexity} |
|
||||
| Platform | {platform} |
|
||||
| Workflow | {recommended_workflow} |
|
||||
| Related | {related_story or 'None'} |
|
||||
|
||||
{if doc_impact flagged:}
|
||||
**Documentation Impact:**
|
||||
- PRD: {yes/no}
|
||||
- Architecture: {yes/no}
|
||||
- UX: {yes/no}
|
||||
- Notes: {doc_impact_notes}
|
||||
{end if}
|
||||
|
||||
**Triage Reasoning:**
|
||||
{triage_notes}
|
||||
|
||||
---
|
||||
|
||||
{end for}
|
||||
|
||||
## Updated Files
|
||||
|
||||
- **bugs.yaml** - Structured metadata for all triaged items
|
||||
- **bugs.md** - Moved triaged items to Tracked sections
|
||||
|
||||
---
|
||||
|
||||
## Statistics Summary
|
||||
|
||||
| Metric | Count |
|
||||
|--------|-------|
|
||||
| Total Active Bugs | {total_active} |
|
||||
| Critical | {critical_count} |
|
||||
| High | {high_count} |
|
||||
| Medium | {medium_count} |
|
||||
| Low | {low_count} |
|
||||
|
||||
{if any doc_impact flagged:}
|
||||
|
||||
## Documentation Updates Required
|
||||
|
||||
Items with documentation impact have been routed to `correct-course` workflow:
|
||||
- PRD Impact: {prd_impact_count} item(s)
|
||||
- Architecture Impact: {arch_impact_count} item(s)
|
||||
- UX Impact: {ux_impact_count} item(s)
|
||||
{end if}
|
||||
|
||||
---
|
||||
|
||||
## Workflow Recommendations
|
||||
|
||||
### Direct Fix ({direct_fix_count} items)
|
||||
Quick fixes with obvious solutions. No spec needed.
|
||||
|
||||
**Command:** `/implement bug-NNN`
|
||||
|
||||
{list bug IDs for direct-fix}
|
||||
|
||||
### Tech-Spec ({tech_spec_count} items)
|
||||
Require technical specification before implementation.
|
||||
|
||||
**Process:** Create tech-spec first, then `/implement`
|
||||
|
||||
{list bug IDs for tech-spec}
|
||||
|
||||
### Correct-Course ({correct_course_count} items)
|
||||
Need impact analysis before proceeding.
|
||||
|
||||
**Process:** Run correct-course workflow for impact analysis
|
||||
|
||||
{list bug IDs for correct-course}
|
||||
|
||||
### Backlog ({backlog_count} items)
|
||||
Deferred - low priority items for future consideration.
|
||||
|
||||
{list bug IDs for backlog}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
**To implement a bug fix:**
|
||||
```
|
||||
/implement bug-NNN
|
||||
```
|
||||
|
||||
**To verify after testing:**
|
||||
```
|
||||
/verify bug-NNN
|
||||
```
|
||||
|
||||
**To verify all implemented bugs:**
|
||||
```
|
||||
/verify
|
||||
```
|
||||
|
||||
**To list bugs by platform:**
|
||||
```
|
||||
/list-bugs android
|
||||
/list-bugs ios
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Thank you for completing the triage session!"
|
||||
|
||||
### 2. End Workflow
|
||||
|
||||
The workflow is complete. No further steps.
|
||||
|
||||
## SUCCESS METRICS:
|
||||
|
||||
✅ Comprehensive summary presented
|
||||
✅ All triaged items listed with metadata
|
||||
✅ Statistics accurately displayed
|
||||
✅ Workflow recommendations clear
|
||||
✅ Next step commands provided
|
||||
✅ User knows how to proceed
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
❌ Incomplete summary missing items
|
||||
❌ Statistics not matching bugs.yaml
|
||||
❌ Unclear next step guidance
|
||||
❌ Modifying files in this step (should be read-only)
|
||||
|
||||
## WORKFLOW COMPLETE
|
||||
|
||||
This is the final step. The bug tracking triage workflow is complete.
|
||||
|
||||
User can now:
|
||||
- Run `/implement bug-NNN` to fix bugs
|
||||
- Run `/verify` to verify implemented bugs
|
||||
- Add new bugs to bugs.md and run triage again
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
name: bug-tracking
|
||||
description: Triage user-reported bugs from bugs.md, generate structured metadata in bugs.yaml, and route to appropriate workflow
|
||||
main_config: '{project-root}/_bmad/bmm/config.yaml'
|
||||
web_bundle: true
|
||||
---
|
||||
|
||||
# Bug Tracking Workflow
|
||||
|
||||
**Goal:** Transform informal bug reports into structured, actionable metadata with severity assessment, complexity estimation, and workflow routing recommendations.
|
||||
|
||||
**Your Role:** You are a triage facilitator collaborating with a peer. This is a partnership, not a client-vendor relationship. You bring structured analysis and triage methodology, while the user brings domain expertise and context about their product. Work together to efficiently categorize and route bugs for resolution.
|
||||
|
||||
---
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
This uses **micro-file architecture** for disciplined execution:
|
||||
|
||||
- Each step is a self-contained file with embedded rules
|
||||
- Sequential progression with user control at each step
|
||||
- State tracked via bugs.yaml metadata
|
||||
- Append-only updates to bugs.md (move triaged items, never delete)
|
||||
- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation.
|
||||
|
||||
---
|
||||
|
||||
## INITIALIZATION
|
||||
|
||||
### Configuration Loading
|
||||
|
||||
Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
|
||||
|
||||
- `project_name`, `output_folder`, `user_name`
|
||||
- `communication_language`, `date` as system-generated current datetime
|
||||
- `dev_ephemeral_location` for sprint-status.yaml location
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Paths
|
||||
|
||||
- `installed_path` = `{project-root}/_bmad/bmm/workflows/bug-tracking`
|
||||
- `bugs_input` = `{output_folder}/bugs.md` (user-facing bug reports)
|
||||
- `bugs_output` = `{output_folder}/bugs.yaml` (agent-facing structured metadata)
|
||||
- `sprint_status` = `{dev_ephemeral_location}/sprint-status.yaml`
|
||||
- `epics_file` = `{output_folder}/epics.md`
|
||||
|
||||
### Optional API Integration
|
||||
|
||||
- `project_url` = configurable base URL for in-app bug report sync (default: `http://localhost:5173`)
|
||||
- See `reference-implementation.md` for in-app bug reporting setup
|
||||
|
||||
---
|
||||
|
||||
## EXECUTION
|
||||
|
||||
Load and execute `steps/step-01-init.md` to begin the workflow.
|
||||
|
||||
**Note:** Input file discovery and initialization protocols are handled in step-01-init.md.
|
||||
|
|
@ -0,0 +1,523 @@
|
|||
# Implement Workflow (Bug Fix or Feature)
|
||||
|
||||
```xml
|
||||
<critical>This workflow loads bug/feature context, implements the code, and updates tracking in both bugs.yaml and bugs.md</critical>
|
||||
<critical>Communicate in {communication_language} with {user_name}</critical>
|
||||
<critical>Auto-detects type from ID format: bug-NNN = bug fix, feature-NNN = feature implementation</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Get item ID from user">
|
||||
<check if="item_id not provided in user input">
|
||||
<ask>Which bug or feature should I implement? (e.g., bug-026 or feature-021)</ask>
|
||||
</check>
|
||||
<action>Extract item ID from user input</action>
|
||||
<action>Detect type from ID format:</action>
|
||||
<action>- "bug-NNN" -> type = "bug", action_verb = "fix", past_verb = "Fixed"</action>
|
||||
<action>- "feature-NNN" -> type = "feature", action_verb = "implement", past_verb = "Implemented"</action>
|
||||
<check if="ID doesn't match either format">
|
||||
<output>Invalid ID format. Use bug-NNN (e.g., bug-026) or feature-NNN (e.g., feature-021)</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Load context from bugs.yaml">
|
||||
<action>Search for {item_id} in {bugs_yaml} using grep with 50+ lines of context after the match (do NOT read entire file - it exceeds token limits)</action>
|
||||
<check if="type == bug">
|
||||
<action>Entry will be in bugs section, grep will capture all fields</action>
|
||||
</check>
|
||||
<check if="type == feature">
|
||||
<action>Entry will be in feature_requests section, grep will capture all fields</action>
|
||||
</check>
|
||||
<check if="item not found in bugs.yaml">
|
||||
<output>{item_id} not found in bugs.yaml. Please verify the ID or run bug-tracking workflow first.</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
<action>Extract and store metadata:</action>
|
||||
<action>- title: Title/summary</action>
|
||||
<action>- description: Full description</action>
|
||||
<action>- severity/priority: Importance level</action>
|
||||
<action>- complexity: trivial | small | medium | complex</action>
|
||||
<action>- effort_estimate: Estimated hours</action>
|
||||
<action>- affected_platform: all | ios | android (bugs only)</action>
|
||||
<action>- related_story/related_epic: Related items if applicable</action>
|
||||
<action>- doc_impact: Documentation impact flags (prd, architecture, ux) and notes</action>
|
||||
<action>- notes: Triage notes including planned approach, files to check, implementation strategy</action>
|
||||
|
||||
<check if="recommended_workflow == 'backlog'">
|
||||
<output>**BACKLOG ITEM - NOT READY FOR IMPLEMENTATION**
|
||||
|
||||
**{item_id}: {title}**
|
||||
|
||||
This item has `recommended_workflow: backlog` which means it's deferred and not scheduled for implementation.
|
||||
|
||||
**To implement this item, first promote it to the sprint:**
|
||||
1. Run `*sprint-planning` and select this item for promotion
|
||||
2. Or manually update bugs.yaml: change `recommended_workflow` to `direct-fix`, `tech-spec`, or `correct-course`
|
||||
|
||||
**Current Status:** {status}
|
||||
**Priority:** {priority}
|
||||
**Complexity:** {complexity}
|
||||
</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
|
||||
<check if="status == 'deferred'">
|
||||
<output>**DEFERRED ITEM - NOT READY FOR IMPLEMENTATION**
|
||||
|
||||
**{item_id}: {title}**
|
||||
|
||||
This item is deferred (marked for future release, not current MVP).
|
||||
|
||||
**To implement this item:**
|
||||
1. Update bugs.yaml: change `status` from `deferred` to `backlog`
|
||||
2. Run `*sprint-planning` to promote to current sprint
|
||||
|
||||
**Notes:** {notes}
|
||||
</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
|
||||
<check if="status == 'blocked'">
|
||||
<output>**BLOCKED ITEM - CANNOT IMPLEMENT**
|
||||
|
||||
**{item_id}: {title}**
|
||||
|
||||
This item is blocked and requires clarification before implementation.
|
||||
|
||||
**Blocking reason:** {notes}
|
||||
|
||||
**To unblock:**
|
||||
1. Resolve the blocking issue
|
||||
2. Update bugs.yaml: change `status` from `blocked` to `backlog`
|
||||
3. Run `/triage {item_id}` to re-evaluate
|
||||
</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="2.5" goal="Check for documentation impact and route to appropriate agents">
|
||||
<action>Check doc_impact fields from bugs.yaml entry</action>
|
||||
<check if="doc_impact.prd OR doc_impact.architecture OR doc_impact.ux is TRUE">
|
||||
<output>**DOCUMENTATION IMPACT DETECTED**
|
||||
|
||||
**{item_id}: {title}**
|
||||
|
||||
This {type} requires documentation updates BEFORE implementation:
|
||||
|
||||
{if doc_impact.prd:}
|
||||
- **PRD Impact:** Updates needed to product requirements
|
||||
-> Route to PM Agent for PRD updates
|
||||
{end if}
|
||||
|
||||
{if doc_impact.architecture:}
|
||||
- **Architecture Impact:** Updates needed to architecture docs
|
||||
-> Route to Architect Agent for architecture updates
|
||||
{end if}
|
||||
|
||||
{if doc_impact.ux:}
|
||||
- **UX Impact:** Updates needed to UX specifications
|
||||
-> Route to UX Designer Agent for UX spec updates
|
||||
{end if}
|
||||
|
||||
**Details:** {doc_impact.notes}
|
||||
|
||||
**Options:**
|
||||
1. **update-docs-first** - Route to agents for documentation updates before implementation (recommended)
|
||||
2. **proceed-anyway** - Skip documentation updates and implement directly (not recommended)
|
||||
3. **cancel** - Return to review</output>
|
||||
<ask>How should we proceed?</ask>
|
||||
|
||||
<check if="user chooses update-docs-first">
|
||||
<output>Routing to documentation update workflow...
|
||||
|
||||
**Documentation Update Sequence:**</output>
|
||||
|
||||
<check if="doc_impact.prd">
|
||||
<output>1. **PRD Update** - Invoking PM Agent...</output>
|
||||
<action>Prepare PRD update context:</action>
|
||||
<action>- Source item: {item_id}</action>
|
||||
<action>- Change description: {description}</action>
|
||||
<action>- Specific PRD sections: {doc_impact.notes PRD sections}</action>
|
||||
<invoke-agent agent="pm">
|
||||
<task>Review and update PRD for {item_id}: {title}
|
||||
|
||||
Change context: {description}
|
||||
|
||||
Documentation notes: {doc_impact.notes}
|
||||
|
||||
Please update the relevant PRD sections to reflect this change.
|
||||
|
||||
After updates:
|
||||
1. Summarize what was changed
|
||||
2. Return to the implement workflow by running: /implement {item_id}
|
||||
|
||||
IMPORTANT: You MUST return to /implement {item_id} after completing the PRD updates so the actual code implementation can proceed.</task>
|
||||
</invoke-agent>
|
||||
</check>
|
||||
|
||||
<check if="doc_impact.architecture">
|
||||
<output>2. **Architecture Update** - Invoking Architect Agent...</output>
|
||||
<action>Prepare architecture update context:</action>
|
||||
<action>- Source item: {item_id}</action>
|
||||
<action>- Change description: {description}</action>
|
||||
<action>- Specific architecture sections: {doc_impact.notes architecture sections}</action>
|
||||
<invoke-agent agent="architect">
|
||||
<task>Review and update Architecture documentation for {item_id}: {title}
|
||||
|
||||
Change context: {description}
|
||||
|
||||
Documentation notes: {doc_impact.notes}
|
||||
|
||||
Please update the relevant architecture sections (data model, APIs, security, etc.) to reflect this change.
|
||||
|
||||
After updates:
|
||||
1. Summarize what was changed
|
||||
2. Return to the implement workflow by running: /implement {item_id}
|
||||
|
||||
IMPORTANT: You MUST return to /implement {item_id} after completing the architecture updates so the actual code implementation can proceed.</task>
|
||||
</invoke-agent>
|
||||
</check>
|
||||
|
||||
<check if="doc_impact.ux">
|
||||
<output>3. **UX Spec Update** - Invoking UX Designer Agent...</output>
|
||||
<action>Prepare UX update context:</action>
|
||||
<action>- Source item: {item_id}</action>
|
||||
<action>- Change description: {description}</action>
|
||||
<action>- Specific UX sections: {doc_impact.notes UX sections}</action>
|
||||
<invoke-agent agent="ux-designer">
|
||||
<task>Review and update UX specification for {item_id}: {title}
|
||||
|
||||
Change context: {description}
|
||||
|
||||
Documentation notes: {doc_impact.notes}
|
||||
|
||||
Please update the relevant UX spec sections (screens, flows, components, etc.) to reflect this change.
|
||||
|
||||
After updates:
|
||||
1. Summarize what was changed
|
||||
2. Return to the implement workflow by running: /implement {item_id}
|
||||
|
||||
IMPORTANT: You MUST return to /implement {item_id} after completing the UX updates so the actual code implementation can proceed.</task>
|
||||
</invoke-agent>
|
||||
</check>
|
||||
|
||||
<output>**Documentation updates complete.**
|
||||
|
||||
Proceeding with implementation...</output>
|
||||
<action>Continue to step 3</action>
|
||||
</check>
|
||||
|
||||
<check if="user chooses cancel">
|
||||
<output>Cancelled. {item_id} remains in current state.</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
|
||||
<action if="user chooses proceed-anyway">
|
||||
<output>Proceeding without documentation updates. Remember to update docs after implementation.</output>
|
||||
<action>Continue to step 3</action>
|
||||
</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Evaluate routing and auto-route to correct-course if needed">
|
||||
<action>Check recommended_workflow field from bugs.yaml</action>
|
||||
|
||||
<check if="recommended_workflow == 'correct-course'">
|
||||
<output>**AUTO-ROUTING TO CORRECT-COURSE**
|
||||
|
||||
**{item_id}: {title}**
|
||||
**Priority:** {severity_or_priority} | **Complexity:** {complexity}
|
||||
|
||||
This {type} has `recommended_workflow: correct-course` which requires impact analysis and story creation before implementation.
|
||||
|
||||
Invoking correct-course workflow via SM agent...</output>
|
||||
|
||||
<action>Invoke the correct-course workflow skill with item context</action>
|
||||
<invoke-skill skill="bmad:bmm:workflows:correct-course">
|
||||
<args>{item_id}: {title} - {description}
|
||||
|
||||
Priority: {severity_or_priority}
|
||||
Complexity: {complexity}
|
||||
Doc Impact: {doc_impact summary}
|
||||
Notes: {notes}</args>
|
||||
</invoke-skill>
|
||||
<action>HALT - Correct Course workflow will handle story/epic creation</action>
|
||||
</check>
|
||||
|
||||
<check if="recommended_workflow == 'tech-spec'">
|
||||
<output>**AUTO-ROUTING TO TECH-SPEC**
|
||||
|
||||
**{item_id}: {title}**
|
||||
|
||||
This {type} has `recommended_workflow: tech-spec`. Invoking tech-spec workflow...</output>
|
||||
|
||||
<invoke-skill skill="bmad:bmm:workflows:tech-spec">
|
||||
<args>{item_id}: {title} - {description}</args>
|
||||
</invoke-skill>
|
||||
<action>HALT - Tech-spec workflow will create implementation spec</action>
|
||||
</check>
|
||||
|
||||
<check if="recommended_workflow == 'direct-fix'">
|
||||
<output>**DIRECT IMPLEMENTATION**
|
||||
|
||||
This {type} is routed for direct implementation. Proceeding...</output>
|
||||
<action>Continue to step 4</action>
|
||||
</check>
|
||||
|
||||
<check if="recommended_workflow is not set OR recommended_workflow is ambiguous">
|
||||
<action>Evaluate the workflow routing matrix based on severity and complexity:</action>
|
||||
<action>**Routing Matrix:**</action>
|
||||
<action>- critical + any -> correct-course</action>
|
||||
<action>- high/medium + medium/complex -> correct-course</action>
|
||||
<action>- high + trivial -> direct-fix</action>
|
||||
<action>- high/medium + small -> tech-spec</action>
|
||||
<action>- medium + trivial -> direct-fix</action>
|
||||
<action>- low + trivial -> direct-fix</action>
|
||||
<action>- low + small+ -> backlog</action>
|
||||
|
||||
<action>Apply matrix to determine routing and continue accordingly</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Present context and confirm approach">
|
||||
<output>**{item_id}: {title}**
|
||||
|
||||
**Type:** {type} | **Severity/Priority:** {severity_or_priority} | **Complexity:** {complexity} | **Effort:** ~{effort_estimate}h
|
||||
|
||||
**Description:**
|
||||
{description}
|
||||
|
||||
**Planned Approach (from triage notes):**
|
||||
{notes}
|
||||
|
||||
**Related:** {related_story} / {related_epic}
|
||||
</output>
|
||||
<ask>Ready to {action_verb} this {type}? (yes/no/clarify)</ask>
|
||||
<check if="user says clarify">
|
||||
<ask>What additional context do you need?</ask>
|
||||
<action>Gather clarification, update mental model</action>
|
||||
</check>
|
||||
<check if="user says no">
|
||||
<output>Cancelled. {item_id} remains in current state.</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Implement the fix/feature">
|
||||
<action>Based on the notes/planned approach, identify files to modify or create</action>
|
||||
<action>Read each affected file to understand current implementation</action>
|
||||
<action>Implement following the planned approach:</action>
|
||||
<action>- Make minimal, targeted changes</action>
|
||||
<action>- Follow existing code patterns and style</action>
|
||||
<action>- Add comments only where logic is non-obvious</action>
|
||||
<action>- Do not over-engineer or add unrelated improvements</action>
|
||||
<action>- Do not add extra features or "nice to haves"</action>
|
||||
|
||||
<action>For each file modified/created, track:</action>
|
||||
<action>- File path</action>
|
||||
<action>- What was changed/added</action>
|
||||
<action>- How it addresses the bug/feature</action>
|
||||
|
||||
<check if="requires new files">
|
||||
<action>Create new files following project conventions</action>
|
||||
<action>Add appropriate imports/exports</action>
|
||||
</check>
|
||||
|
||||
<check if="planned approach is unclear or insufficient">
|
||||
<ask>The triage notes don't provide a clear approach.
|
||||
|
||||
Based on my analysis, I suggest: {proposed_approach}
|
||||
|
||||
Should I proceed with this approach?</ask>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Verify implementation compiles">
|
||||
<action>Run TypeScript compilation check: npm run check</action>
|
||||
<check if="compilation errors in modified files">
|
||||
<action>Fix compilation errors</action>
|
||||
<action>Re-run compilation check</action>
|
||||
</check>
|
||||
<output>Compilation check passed.</output>
|
||||
</step>
|
||||
|
||||
<step n="6.5" goal="Pre-update sync check">
|
||||
<action>Search for {item_id} in both bugs.yaml and bugs.md using grep to check current status</action>
|
||||
<check if="status differs between files OR item missing from one file">
|
||||
<output>SYNC WARNING: {item_id} status mismatch detected
|
||||
- bugs.yaml: {yaml_status}
|
||||
- bugs.md: {md_status}
|
||||
Proceeding will update both files to "{new_status}".</output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Update bugs.yaml">
|
||||
<action>Update entry in bugs.yaml:</action>
|
||||
<check if="type == bug">
|
||||
<action>- status: "fixed"</action>
|
||||
<action>- fixed_date: {date} (YYYY-MM-DD format)</action>
|
||||
</check>
|
||||
<check if="type == feature">
|
||||
<action>- status: "implemented"</action>
|
||||
<action>- implemented_date: {date} (YYYY-MM-DD format)</action>
|
||||
</check>
|
||||
<action>- assigned_to: "dev-agent"</action>
|
||||
<action>- files_modified: {list of files changed/created during implementation}</action>
|
||||
<action>- Append to notes: "{past_verb} ({date}): {summary of changes made}"</action>
|
||||
<action>Write updated bugs.yaml</action>
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Update bugs.md">
|
||||
<action>Search for {item_id} in {bugs_md} using grep with surrounding context to locate the entry</action>
|
||||
|
||||
<action>**8a. Remove from tracked section (if present)**</action>
|
||||
<check if="type == bug">
|
||||
<action>Search for "{item_id}:" in "# Tracked Bugs" section</action>
|
||||
</check>
|
||||
<check if="type == feature">
|
||||
<action>Search for "{item_id}:" in "# Tracked Feature Requests" section</action>
|
||||
</check>
|
||||
<action>If found, remove the entire entry (including any indented sub-items)</action>
|
||||
|
||||
<action>**8b. Add to completed section (INSERT AT TOP - newest first)**</action>
|
||||
<check if="type == bug">
|
||||
<action>Locate "# Fixed Bugs" section in bugs.md</action>
|
||||
<action>If section not found, create it</action>
|
||||
<action>INSERT AT TOP of section (immediately after "# Fixed Bugs" header):</action>
|
||||
<action>[IMPLEMENTED] {item_id}: {title} - {brief_description}. [Severity: {severity}, Platform: {platform}, Fixed: {date}, Verified: pending]</action>
|
||||
<action> - Fix: {description of what was fixed}</action>
|
||||
<action> - File(s): {list of modified files}</action>
|
||||
</check>
|
||||
<check if="type == feature">
|
||||
<action>Locate "# Implemented Features" section in bugs.md</action>
|
||||
<action>If section not found, create it before "# Fixed Bugs"</action>
|
||||
<action>INSERT AT TOP of section (immediately after "# Implemented Features" header):</action>
|
||||
<action>[IMPLEMENTED] {item_id}: {title} - {brief_description}. [Implemented: {date}, Platform: {platform}, Verified: pending]</action>
|
||||
<action> - Files: {list of modified/created files}</action>
|
||||
<action> - Features: {bullet list of what was implemented}</action>
|
||||
</check>
|
||||
<action>Write updated bugs.md</action>
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Post-update validation">
|
||||
<action>Search for {item_id} in both bugs.yaml and bugs.md using grep to validate updates</action>
|
||||
<action>Confirm {item_id} shows status "fixed"/"implemented" in bugs.yaml</action>
|
||||
<action>Confirm {item_id} has [IMPLEMENTED] tag in bugs.md</action>
|
||||
<check if="validation fails">
|
||||
<output>SYNC ERROR: Files may be out of sync. Please verify manually:
|
||||
- bugs.yaml: Expected status "fixed"/"implemented"
|
||||
- bugs.md: Expected [IMPLEMENTED] tag in appropriate section</output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Present completion summary">
|
||||
<output>**{item_id} {past_verb.upper()}**
|
||||
|
||||
**Changes Made:**
|
||||
{for each modified file:}
|
||||
- {file_path}: {what was changed}
|
||||
{end for}
|
||||
|
||||
**Updated Tracking:**
|
||||
- bugs.yaml: status -> "{status}", {date_field} -> {date}, files_modified updated
|
||||
- bugs.md: Moved to "{target_section}" with [IMPLEMENTED] tag
|
||||
|
||||
**Verification Status:** pending
|
||||
|
||||
**Next Steps:**
|
||||
1. Test manually
|
||||
2. Run `/verify {item_id}` after verification to close
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/implement bug-026
|
||||
/implement feature-021
|
||||
```
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Auto-detect Type** - ID format determines bug vs feature handling
|
||||
2. **Context First** - Always read and present details before implementing
|
||||
3. **Confirm Approach** - Validate planned approach with user before coding
|
||||
4. **Minimal Changes** - Only implement what's needed, no scope creep
|
||||
5. **Dual Tracking** - ALWAYS update both bugs.yaml AND bugs.md
|
||||
6. **[IMPLEMENTED] Tag** - Indicates complete but awaiting verification
|
||||
|
||||
---
|
||||
|
||||
## Reference: Bug Tracking Definitions
|
||||
|
||||
### Severity Levels
|
||||
|
||||
| Level | Description | Action |
|
||||
|-------|-------------|--------|
|
||||
| **critical** | Blocks core functionality, prevents app use, or causes data loss (crashes, auth broken, data corruption) | Fix immediately, may require hotfix |
|
||||
| **high** | Major feature broken, significant UX degradation, workaround exists but painful (platform-specific failure, 5+ sec delays, accessibility blocker) | Fix in current/next sprint |
|
||||
| **medium** | Feature partially broken, UX degraded but usable (minor feature broken, unclear errors, 1-3 sec delays) | Fix when capacity allows |
|
||||
| **low** | Minor issue, cosmetic, edge case (typos, spacing, visual glitches) | Fix opportunistically or defer |
|
||||
|
||||
### Complexity Levels
|
||||
|
||||
| Level | Description | Effort |
|
||||
|-------|-------------|--------|
|
||||
| **trivial** | Obvious fix, single line change, no investigation needed (typo, missing semicolon, wrong color) | < 30 minutes |
|
||||
| **small** | Single file/component, clear root cause, solution known (missing validation, incorrect prop, logic error) | 30 min - 2 hours |
|
||||
| **medium** | Multiple files affected OR investigation required (spans 2-3 components, debugging needed, integration issue) | 2-8 hours |
|
||||
| **complex** | Architectural issue, affects multiple stories, requires design changes (race conditions, refactoring, profiling) | 8+ hours (1-2 days) |
|
||||
|
||||
### Workflow Routing Matrix
|
||||
|
||||
| Severity | Complexity | Workflow | Rationale |
|
||||
|----------|------------|----------|-----------|
|
||||
| critical | any | correct-course -> urgent | Need impact analysis even if small fix |
|
||||
| high | trivial | direct-fix (urgent) | Fast path for obvious important fix |
|
||||
| high | small | tech-spec (urgent) | Fast path with minimal overhead |
|
||||
| high | medium+ | correct-course -> story | Need proper analysis + testing |
|
||||
| medium | trivial | direct-fix | Too small for workflow overhead |
|
||||
| medium | small | tech-spec | Isolated fix needs spec |
|
||||
| medium | medium+ | correct-course -> story | Multi-file change needs story |
|
||||
| low | trivial | direct-fix (defer) | Fix opportunistically |
|
||||
| low | small+ | backlog (defer) | Document but don't schedule yet |
|
||||
|
||||
### Status Flow
|
||||
|
||||
```
|
||||
reported -> triaged -> routed -> in-progress -> fixed -> verified -> closed
|
||||
```
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| **reported** | Bug logged in bugs.md, not yet analyzed |
|
||||
| **triaged** | PM analyzed, assigned severity/complexity/workflow |
|
||||
| **routed** | Workflow determined, story/tech-spec created |
|
||||
| **in-progress** | Developer actively working on fix |
|
||||
| **fixed** | Code changed, tests passing, ready for verification |
|
||||
| **verified** | Bug confirmed fixed by reporter or QA |
|
||||
| **closed** | Bug resolved and verified, no further action |
|
||||
|
||||
### Metadata Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| id | Unique identifier (bug-NNN or feature-NNN) |
|
||||
| title | Short description (< 80 chars) |
|
||||
| description | Detailed explanation |
|
||||
| severity | critical \| high \| medium \| low |
|
||||
| complexity | trivial \| small \| medium \| complex |
|
||||
| status | Current workflow state |
|
||||
| recommended_workflow | direct-fix \| tech-spec \| correct-course \| backlog |
|
||||
| effort_estimate | Hours (based on complexity) |
|
||||
| reported_by / reported_date | Who found it and when |
|
||||
| triaged_by / triaged_date | Who triaged and when |
|
||||
| fixed_date / verified_date | Implementation and verification dates |
|
||||
| related_story / related_epic | Context links |
|
||||
| affected_platform | all \| ios \| android |
|
||||
| doc_impact | Documentation impact: prd, architecture, ux flags + notes |
|
||||
| notes | Investigation notes, decisions, implementation details |
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
name: implement
|
||||
description: "Implement a bug fix or feature - loads context from bugs.yaml, implements the code, updates both bugs.yaml and bugs.md with [IMPLEMENTED] tag"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/.bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/.bmad/bmm/workflows/implement"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
template: false
|
||||
|
||||
# Input and output files
|
||||
variables:
|
||||
bugs_md: "{output_folder}/bugs.md"
|
||||
bugs_yaml: "{output_folder}/bugs.yaml"
|
||||
|
||||
standalone: true
|
||||
|
|
@ -0,0 +1,219 @@
|
|||
# Verify Workflow (Close Implemented Bugs/Features)
|
||||
|
||||
```xml
|
||||
<critical>This workflow verifies implemented items and closes them in both bugs.yaml and bugs.md</critical>
|
||||
<critical>Communicate in {communication_language} with {user_name}</critical>
|
||||
<critical>Removes [IMPLEMENTED] tag and updates status to CLOSED (bugs) or COMPLETE (features)</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Get item ID or list pending items">
|
||||
<check if="item_id provided in user input">
|
||||
<action>Extract item ID from user input</action>
|
||||
<action>Detect type from ID format:</action>
|
||||
<action>- "bug-NNN" -> type = "bug", final_status = "CLOSED"</action>
|
||||
<action>- "feature-NNN" -> type = "feature", final_status = "COMPLETE"</action>
|
||||
<action>Proceed to Step 2</action>
|
||||
</check>
|
||||
<check if="no item_id provided OR user says 'list'">
|
||||
<action>Search {bugs_yaml} for 'status: "fixed"' or 'status: "implemented"' using grep (do NOT read entire file)</action>
|
||||
<action>Search {bugs_md} for '[IMPLEMENTED]' entries using grep</action>
|
||||
<action>Find all items with:</action>
|
||||
<action>- status == "fixed" or "implemented" in bugs.yaml</action>
|
||||
<action>- [IMPLEMENTED] tag in bugs.md</action>
|
||||
<output>**Pending Verification:**
|
||||
|
||||
{for each pending item:}
|
||||
- **{item_id}**: {title} [{type}, {fixed_date or implemented_date}]
|
||||
{end for}
|
||||
|
||||
**Total:** {count} item(s) awaiting verification
|
||||
|
||||
To verify an item: `/verify bug-026`
|
||||
To verify all: Type "verify all"
|
||||
</output>
|
||||
<ask>Which item would you like to verify?</ask>
|
||||
</check>
|
||||
<check if="user says 'verify all' or 'all'">
|
||||
<action>Set batch_mode = true</action>
|
||||
<action>Collect all pending items</action>
|
||||
<action>Proceed to Step 2 with batch processing</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Load item context and check sync">
|
||||
<action>Search for {item_id} in {bugs_yaml} using grep with 50+ lines of context after the match (do NOT read entire file - it exceeds token limits)</action>
|
||||
<check if="type == bug">
|
||||
<action>Entry will be in bugs section, verify status == "fixed"</action>
|
||||
</check>
|
||||
<check if="type == feature">
|
||||
<action>Entry will be in feature_requests section, verify status == "implemented"</action>
|
||||
</check>
|
||||
<check if="item not found OR status not fixed/implemented">
|
||||
<output>{item_id} is not in an implemented state. Current status: {status}
|
||||
|
||||
Only items with status "fixed" (bugs) or "implemented" (features) can be verified.</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
<action>Extract metadata: title, description, fixed_date/implemented_date, notes</action>
|
||||
|
||||
<action>**Sync Check:** Also read {bugs_md} to verify sync status</action>
|
||||
<check if="bugs.yaml says fixed/implemented but bugs.md missing [IMPLEMENTED] tag">
|
||||
<output>SYNC WARNING: {item_id} status mismatch detected
|
||||
- bugs.yaml: {yaml_status}
|
||||
- bugs.md: Missing [IMPLEMENTED] tag (may have been implemented outside workflow)
|
||||
|
||||
Proceeding will update both files to CLOSED/COMPLETE.</output>
|
||||
<ask>Continue with verification? (yes/no)</ask>
|
||||
<check if="user says no">
|
||||
<output>Cancelled. Please run /implement {item_id} first to sync files.</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Confirm verification">
|
||||
<output>**Verify {item_id}: {title}**
|
||||
|
||||
**Type:** {type}
|
||||
**{past_verb}:** {fixed_date or implemented_date}
|
||||
|
||||
**Implementation Notes:**
|
||||
{notes - show the FIXED/IMPLEMENTED section}
|
||||
|
||||
**Files Changed:**
|
||||
{extract file list from notes}
|
||||
</output>
|
||||
<ask>Has this been tested and verified working? (yes/no/skip)</ask>
|
||||
<check if="user says no">
|
||||
<ask>What issue did you find? (I'll add it to the notes)</ask>
|
||||
<action>Append verification failure note to bugs.yaml notes field</action>
|
||||
<output>Noted. {item_id} remains in implemented state for rework.</output>
|
||||
<action>HALT or continue to next item in batch</action>
|
||||
</check>
|
||||
<check if="user says skip">
|
||||
<output>Skipped. {item_id} remains in implemented state.</output>
|
||||
<action>Continue to next item in batch or HALT</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Update bugs.yaml">
|
||||
<action>Update entry in bugs.yaml:</action>
|
||||
<action>- status: "closed"</action>
|
||||
<action>- verified_by: {user_name}</action>
|
||||
<action>- verified_date: {date} (YYYY-MM-DD format)</action>
|
||||
<action>- Append to notes: "Verified ({date}) by {user_name}"</action>
|
||||
<action>Write updated bugs.yaml</action>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Update bugs.md">
|
||||
<action>Search for {item_id} in {bugs_md} using grep with surrounding context to locate the entry</action>
|
||||
|
||||
<action>**5a. Find the entry**</action>
|
||||
<check if="type == bug">
|
||||
<action>Search for "[IMPLEMENTED] {item_id}:" in "# Fixed Bugs" section</action>
|
||||
<check if="not found">
|
||||
<action>Search for "{item_id}:" in "# Tracked Bugs" section (implemented outside workflow)</action>
|
||||
</check>
|
||||
</check>
|
||||
<check if="type == feature">
|
||||
<action>Search for "[IMPLEMENTED] {item_id}:" in "# Implemented Features" section</action>
|
||||
<check if="not found">
|
||||
<action>Search for "{item_id}:" in "# Tracked Feature Requests" section (implemented outside workflow)</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>**5b. Move entry if in wrong section**</action>
|
||||
<check if="entry found in Tracked section (implemented outside workflow)">
|
||||
<action>DELETE the entry from "# Tracked Bugs" or "# Tracked Feature Requests"</action>
|
||||
<action>ADD entry to correct section:</action>
|
||||
<check if="type == bug">
|
||||
<action>Add to "# Fixed Bugs" section</action>
|
||||
</check>
|
||||
<check if="type == feature">
|
||||
<action>Add to "# Implemented Features" section (at top, before other entries)</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>**5c. Update the entry format**</action>
|
||||
<action>Remove "[IMPLEMENTED] " prefix if present</action>
|
||||
<action>Update the status tag in brackets:</action>
|
||||
<check if="type == bug">
|
||||
<action>Change from "[Severity: X, Fixed: DATE, Verified: pending]" or "[Severity: X, Complexity: Y, Workflow: Z]"</action>
|
||||
<action>To "[Severity: X, Platform: Y, Fixed: {date}, Verified: {date}, CLOSED]"</action>
|
||||
</check>
|
||||
<check if="type == feature">
|
||||
<action>Change from "[Implemented: DATE, Verified: pending]" or "[Priority: X, Complexity: Y, Workflow: Z]"</action>
|
||||
<action>To "[Implemented: {date}, Platform: Y, Verified: {date}, COMPLETE]"</action>
|
||||
</check>
|
||||
<action>Add implementation notes if available from bugs.yaml</action>
|
||||
|
||||
<action>Write updated bugs.md</action>
|
||||
</step>
|
||||
|
||||
<step n="5.5" goal="Post-update validation">
|
||||
<action>Search for {item_id} in both bugs.yaml and bugs.md using grep to validate updates</action>
|
||||
<action>Confirm bugs.yaml: status="closed", verified_by set, verified_date set</action>
|
||||
<action>Confirm bugs.md: No [IMPLEMENTED] tag, has CLOSED/COMPLETE in status tag</action>
|
||||
<check if="validation fails">
|
||||
<output>SYNC ERROR: Verification may be incomplete. Please check both files:
|
||||
- bugs.yaml: Expected status "closed", verified_by/verified_date set
|
||||
- bugs.md: Expected CLOSED/COMPLETE tag, no [IMPLEMENTED] prefix</output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Present completion summary">
|
||||
<check if="batch_mode">
|
||||
<output>**Verification Complete**
|
||||
|
||||
**Verified {verified_count} item(s):**
|
||||
{for each verified item:}
|
||||
- {item_id}: {title} -> {final_status}
|
||||
{end for}
|
||||
|
||||
**Skipped:** {skipped_count}
|
||||
**Failed verification:** {failed_count}
|
||||
|
||||
**Updated Files:**
|
||||
- bugs.yaml: status -> "closed", verified_by/verified_date set
|
||||
- bugs.md: [IMPLEMENTED] tag removed, status -> {final_status}
|
||||
</output>
|
||||
</check>
|
||||
<check if="not batch_mode">
|
||||
<output>**{item_id} VERIFIED and {final_status}**
|
||||
|
||||
**Updated:**
|
||||
- bugs.yaml: status -> "closed", verified_by -> {user_name}, verified_date -> {date}
|
||||
- bugs.md: Removed [IMPLEMENTED] tag, added "Verified: {date}, {final_status}"
|
||||
|
||||
This item is now fully closed.
|
||||
</output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/verify # List all pending verification
|
||||
/verify bug-026 # Verify specific bug
|
||||
/verify feature-021 # Verify specific feature
|
||||
/verify all # Verify all pending items
|
||||
```
|
||||
|
||||
## Status Transitions
|
||||
|
||||
| Type | Before | After |
|
||||
|------|--------|-------|
|
||||
| Bug | status: "fixed", [IMPLEMENTED] | status: "closed", CLOSED |
|
||||
| Feature | status: "implemented", [IMPLEMENTED] | status: "closed", COMPLETE |
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Verification Gate** - User must confirm item was tested and works
|
||||
2. **Failure Handling** - If verification fails, add note and keep in implemented state
|
||||
3. **Batch Support** - Can verify multiple items at once
|
||||
4. **Dual Tracking** - ALWAYS update both bugs.yaml AND bugs.md
|
||||
5. **Proper Closure** - Removes [IMPLEMENTED] tag, adds final CLOSED/COMPLETE status
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
name: verify
|
||||
description: "Verify and close implemented bugs/features - removes [IMPLEMENTED] tag, updates status to CLOSED/COMPLETE in both bugs.yaml and bugs.md"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/.bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/.bmad/bmm/workflows/verify"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
template: false
|
||||
|
||||
# Input and output files
|
||||
variables:
|
||||
bugs_md: "{output_folder}/bugs.md"
|
||||
bugs_yaml: "{output_folder}/bugs.yaml"
|
||||
|
||||
standalone: true
|
||||
Loading…
Reference in New Issue