Compare commits
7 Commits
ddaefa3284
...
f37c960a4d
| Author | SHA1 | Date |
|---|---|---|
Brian Madison
|
f37c960a4d | |
|
Brian Madison
|
2d297c82da | |
|
Brian Madison
|
a175f46f1b | |
|
Brian Madison
|
44e09e4487 | |
|
Brian Madison
|
be5556bf42 | |
|
Brian Madison
|
be5b06f55e | |
|
Brian Madison
|
c8776aa9ac |
|
|
@ -0,0 +1,328 @@
|
|||
# BMAD Workflow Conditional Execution Antipattern Audit
|
||||
|
||||
**Date:** 2025-10-22
|
||||
**Auditor:** Claude Code (BMad Builder Agent)
|
||||
**Scope:** All markdown files under `src/`
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Critical Issue Identified:** Invalid self-closing `<check>` tag pattern found throughout BMAD workflow codebase.
|
||||
|
||||
**Impact:**
|
||||
|
||||
- **98 instances** across **14 workflow files**
|
||||
- Affects core workflows, builder workflows, and method workflows
|
||||
- Creates XML parsing ambiguity and unpredictable LLM behavior
|
||||
- Violates BMAD workflow specification (workflow.xml)
|
||||
|
||||
**Severity:** CRITICAL - Invalid XML structure, ambiguous conditional scope
|
||||
|
||||
---
|
||||
|
||||
## The Antipattern
|
||||
|
||||
### Invalid Pattern (Self-Closing Check)
|
||||
|
||||
```xml
|
||||
<!-- ❌ WRONG - Invalid XML structure -->
|
||||
<check>If condition met:</check>
|
||||
<action>Do something</action>
|
||||
<action>Do something else</action>
|
||||
```
|
||||
|
||||
**Problems:**
|
||||
|
||||
1. Check tag doesn't wrap anything (invalid XML)
|
||||
2. Ambiguous scope - unclear which actions are conditional
|
||||
3. Breaks formatters and parsers
|
||||
4. Not part of BMAD workflow spec
|
||||
5. Unpredictable LLM interpretation
|
||||
|
||||
### Correct Patterns
|
||||
|
||||
**Single conditional action:**
|
||||
|
||||
```xml
|
||||
<!-- ✅ CORRECT - Inline conditional -->
|
||||
<action if="condition met">Do something</action>
|
||||
```
|
||||
|
||||
**Multiple conditional actions:**
|
||||
|
||||
```xml
|
||||
<!-- ✅ CORRECT - Proper wrapper block -->
|
||||
<check if="condition met">
|
||||
<action>Do something</action>
|
||||
<action>Do something else</action>
|
||||
</check>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Audit Results
|
||||
|
||||
### Total Count
|
||||
|
||||
- **Total Instances:** 98
|
||||
- **Affected Files:** 14
|
||||
- **Modules Affected:** 4 (BMB, BMM, CIS, Core)
|
||||
|
||||
### Breakdown by File
|
||||
|
||||
| File | Count | Priority |
|
||||
| -------------------------------------------------------------------- | ----- | ----------- |
|
||||
| `modules/bmb/workflows/edit-workflow/instructions.md` | 21 | 🔴 CRITICAL |
|
||||
| `modules/bmm/workflows/4-implementation/dev-story/instructions.md` | 13 | 🔴 CRITICAL |
|
||||
| `modules/bmb/workflows/convert-legacy/instructions.md` | 13 | 🔴 CRITICAL |
|
||||
| `modules/bmb/workflows/create-module/instructions.md` | 12 | 🔴 CRITICAL |
|
||||
| `modules/bmb/workflows/create-agent/instructions.md` | 11 | 🔴 CRITICAL |
|
||||
| `core/workflows/party-mode/instructions.md` | 7 | 🟡 HIGH |
|
||||
| `modules/bmm/workflows/4-implementation/correct-course/checklist.md` | 5 | 🟡 HIGH |
|
||||
| `core/workflows/brainstorming/instructions.md` | 5 | 🟡 HIGH |
|
||||
| `modules/cis/workflows/storytelling/instructions.md` | 3 | 🟢 MEDIUM |
|
||||
| `modules/bmb/workflows/audit-workflow/instructions.md` | 3 | 🟢 MEDIUM |
|
||||
| `modules/bmb/workflows/create-workflow/workflow-creation-guide.md` | 2 | 🟢 MEDIUM |
|
||||
| `modules/bmm/workflows/1-analysis/product-brief/instructions.md` | 1 | 🟢 LOW |
|
||||
| `modules/bmm/workflows/1-analysis/game-brief/instructions.md` | 1 | 🟢 LOW |
|
||||
| `modules/bmb/workflows/redoc/instructions.md` | 1 | 🟢 LOW |
|
||||
|
||||
### Breakdown by Module
|
||||
|
||||
**BMB (Builder) Module: 63 instances (64%)**
|
||||
|
||||
- edit-workflow: 21
|
||||
- convert-legacy: 13
|
||||
- create-module: 12
|
||||
- create-agent: 11
|
||||
- audit-workflow: 3
|
||||
- create-workflow: 2
|
||||
- redoc: 1
|
||||
|
||||
**BMM (Method) Module: 20 instances (20%)**
|
||||
|
||||
- dev-story: 13
|
||||
- correct-course: 5
|
||||
- product-brief: 1
|
||||
- game-brief: 1
|
||||
|
||||
**Core Workflows: 12 instances (12%)**
|
||||
|
||||
- party-mode: 7
|
||||
- brainstorming: 5
|
||||
|
||||
**CIS (Creative) Module: 3 instances (3%)**
|
||||
|
||||
- storytelling: 3
|
||||
|
||||
---
|
||||
|
||||
## Example Instances
|
||||
|
||||
### Example 1: create-agent/instructions.md (Line 13-20)
|
||||
|
||||
**BEFORE (Invalid):**
|
||||
|
||||
```xml
|
||||
<check>If yes:</check>
|
||||
<action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
|
||||
<action>Pass context data: {installed_path}/brainstorm-context.md</action>
|
||||
<action>Wait for brainstorming session completion</action>
|
||||
|
||||
<check>If no:</check>
|
||||
<action>Proceed directly to Step 0</action>
|
||||
```
|
||||
|
||||
**AFTER (Correct):**
|
||||
|
||||
```xml
|
||||
<check if="user answered yes">
|
||||
<action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
|
||||
<action>Pass context data: {installed_path}/brainstorm-context.md</action>
|
||||
<action>Wait for brainstorming session completion</action>
|
||||
</check>
|
||||
|
||||
<check if="user answered no">
|
||||
<action>Proceed directly to Step 0</action>
|
||||
</check>
|
||||
```
|
||||
|
||||
### Example 2: dev-story/instructions.md (Line 54-55)
|
||||
|
||||
**BEFORE (Invalid):**
|
||||
|
||||
```xml
|
||||
<check>If story file inaccessible → HALT: "Cannot develop story without access to story file"</check>
|
||||
<check>If task requirements ambiguous → ASK user to clarify or HALT</check>
|
||||
```
|
||||
|
||||
**AFTER (Correct):**
|
||||
|
||||
```xml
|
||||
<action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
|
||||
<action if="task requirements ambiguous">ASK user to clarify or HALT</action>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact Assessment
|
||||
|
||||
### Technical Impact
|
||||
|
||||
1. **XML Validity:** Invalid structure violates XML parsing rules
|
||||
2. **Formatter Confusion:** Custom formatters incorrectly indent following content
|
||||
3. **Scope Ambiguity:** Unclear which actions are inside vs outside conditional
|
||||
4. **Maintainability:** Future developers confused by ambiguous structure
|
||||
|
||||
### LLM Adherence Impact
|
||||
|
||||
**Potential Issues:**
|
||||
|
||||
- LLM may interpret check as unconditional statement
|
||||
- Actions may execute when they shouldn't (or vice versa)
|
||||
- Inconsistent behavior across different LLMs
|
||||
- Unpredictable results in complex nested conditionals
|
||||
|
||||
**Observed Behavior:**
|
||||
|
||||
- LLMs often "figure it out" through context and proximity
|
||||
- Colon (`:`) pattern signals "here's what to do"
|
||||
- Works in simple cases but risky in complex logic
|
||||
|
||||
**Risk Level:** MEDIUM-HIGH
|
||||
|
||||
- May work "most of the time" but unreliable
|
||||
- Fails in edge cases and complex nested logic
|
||||
- Future LLMs may interpret differently
|
||||
|
||||
---
|
||||
|
||||
## Root Cause Analysis
|
||||
|
||||
### Why This Happened
|
||||
|
||||
1. **Implicit convention evolved** - Self-closing check pattern emerged organically
|
||||
2. **No enforcement** - No linter or validator caught the pattern
|
||||
3. **Copy-paste propagation** - Pattern copied across workflows
|
||||
4. **Formatting hid the issue** - Manual indentation made it "look right"
|
||||
5. **LLM tolerance** - Current LLMs often figured it out despite ambiguity
|
||||
|
||||
### Meta-Problem
|
||||
|
||||
**The workflows that CREATE workflows have the antipattern:**
|
||||
|
||||
- create-workflow: 2 instances
|
||||
- create-agent: 11 instances
|
||||
- create-module: 12 instances
|
||||
- edit-workflow: 21 instances
|
||||
- convert-legacy: 13 instances
|
||||
|
||||
This means NEW workflows were being created WITH the antipattern built-in!
|
||||
|
||||
---
|
||||
|
||||
## Remediation Plan
|
||||
|
||||
### Phase 1: Immediate (High Priority Files)
|
||||
|
||||
Fix top 5 offenders (63% of problem):
|
||||
|
||||
1. edit-workflow (21 instances)
|
||||
2. dev-story (13 instances)
|
||||
3. convert-legacy (13 instances)
|
||||
4. create-module (12 instances)
|
||||
5. create-agent (11 instances)
|
||||
|
||||
**Total:** 70 instances (71% of problem)
|
||||
|
||||
### Phase 2: Core Workflows
|
||||
|
||||
Fix core workflows (critical for all modules):
|
||||
|
||||
1. party-mode (7 instances)
|
||||
2. brainstorming (5 instances)
|
||||
|
||||
**Total:** 12 instances
|
||||
|
||||
### Phase 3: Remaining
|
||||
|
||||
Fix remaining 16 instances across 7 files
|
||||
|
||||
### Phase 4: Prevention
|
||||
|
||||
1. **Update audit-workflow** ✅ DONE
|
||||
- Added antipattern detection to Step 4
|
||||
- Flags with CRITICAL severity
|
||||
- Suggests correct patterns
|
||||
|
||||
2. **Update creation guide** ✅ DONE
|
||||
- Documented antipattern in workflow-creation-guide.md
|
||||
- Clear examples of correct vs incorrect patterns
|
||||
- Added to best practices
|
||||
|
||||
3. **Update checklist** ✅ DONE
|
||||
- Added validation criteria to checklist.md
|
||||
- 3 new checks for conditional execution patterns
|
||||
|
||||
4. **Create automated fixer** (TODO)
|
||||
- Bulk conversion script for remaining instances
|
||||
- Pattern matching and replacement logic
|
||||
|
||||
---
|
||||
|
||||
## Specification Reference
|
||||
|
||||
From `bmad/core/tasks/workflow.xml`:
|
||||
|
||||
```xml
|
||||
<tag>action if="condition" - Single conditional action (inline, no closing tag needed)</tag>
|
||||
<tag>check if="condition">...</check> - Conditional block wrapping multiple items (closing tag required)</tag>
|
||||
```
|
||||
|
||||
**Key Point:** Check tags MUST have `if=""` attribute and MUST wrap content with closing tag.
|
||||
|
||||
The self-closing pattern `<check>text</check>` is **NOT in the spec** and is **invalid**.
|
||||
|
||||
---
|
||||
|
||||
## Detection Command
|
||||
|
||||
To find all instances:
|
||||
|
||||
```bash
|
||||
grep -r "<check>[^<]*</check>" src --include="*.md" -n
|
||||
```
|
||||
|
||||
To count by file:
|
||||
|
||||
```bash
|
||||
grep -r "<check>[^<]*</check>" src --include="*.md" -c | grep -v ":0$"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Actions
|
||||
|
||||
- [ ] Create bulk-fix script for automated conversion
|
||||
- [ ] Fix Phase 1 files (70 instances)
|
||||
- [ ] Fix Phase 2 files (12 instances)
|
||||
- [ ] Fix Phase 3 files (16 instances)
|
||||
- [ ] Run audit-workflow on all fixed files to verify
|
||||
- [ ] Update formatter to detect and warn on antipattern
|
||||
- [ ] Add pre-commit hook to prevent future instances
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Workflow Spec:** `bmad/core/tasks/workflow.xml`
|
||||
- **Creation Guide:** `src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md`
|
||||
- **Audit Workflow:** `src/modules/bmb/workflows/audit-workflow/`
|
||||
- **This Report:** `docs/antipattern-audit-2025-10-22.md`
|
||||
|
||||
---
|
||||
|
||||
**Report Status:** Complete
|
||||
**Action Required:** Yes - 98 instances need remediation
|
||||
**Priority:** CRITICAL - Affects core functionality and workflow creation
|
||||
|
|
@ -1,431 +0,0 @@
|
|||
# Workflow Audit Report
|
||||
|
||||
**Workflow:** tech-spec
|
||||
**Audit Date:** 2025-10-21
|
||||
**Auditor:** Audit Workflow (BMAD v6)
|
||||
**Workflow Type:** Document (template-based)
|
||||
**Workflow Path:** /Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/4-implementation/epic-tech-context
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Overall Status:** ⚠️ ISSUES FOUND - Requires fixes before production use
|
||||
|
||||
**Issue Breakdown:**
|
||||
|
||||
- Critical Issues: **2**
|
||||
- Important Issues: **1**
|
||||
- Cleanup Recommendations: **4**
|
||||
|
||||
**Primary Concerns:**
|
||||
|
||||
1. Web bundle missing critical workflow dependencies
|
||||
2. Output path hardcoded instead of using config variable
|
||||
3. Configuration bloat (40% unused variables)
|
||||
|
||||
---
|
||||
|
||||
## 1. Standard Config Block Validation
|
||||
|
||||
### ✅ Status: PASS
|
||||
|
||||
All required standard config variables are present and correctly formatted:
|
||||
|
||||
**Required Variables:**
|
||||
|
||||
- ✅ `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`
|
||||
|
||||
**Additional Config Variables Found:**
|
||||
|
||||
- ⚠️ `document_output_language` (non-standard, potentially unused)
|
||||
- ⚠️ `user_skill_level` (non-standard, potentially unused)
|
||||
|
||||
**Recommendation:** Verify usage of additional config variables or remove if unused.
|
||||
|
||||
---
|
||||
|
||||
## 2. YAML/Instruction/Template Alignment
|
||||
|
||||
### ❌ Issues Found: Configuration Bloat
|
||||
|
||||
**Variables Analyzed:** 5 custom fields
|
||||
**Used in Instructions:** 3
|
||||
**Used in Template:** N/A (config variables)
|
||||
**Unused (Bloat):** 2
|
||||
|
||||
### Unused Variables (BLOAT):
|
||||
|
||||
1. **`document_output_language`**
|
||||
- Location: workflow.yaml line 10
|
||||
- Status: Defined but never referenced in instructions.md or template.md
|
||||
- Impact: Configuration bloat
|
||||
- **Action Required:** Remove from yaml
|
||||
|
||||
2. **`user_skill_level`**
|
||||
- Location: workflow.yaml line 11
|
||||
- Status: Defined but never referenced in instructions.md or template.md
|
||||
- Impact: Configuration bloat
|
||||
- **Action Required:** Remove from yaml
|
||||
|
||||
### Properly Used Variables:
|
||||
|
||||
- ✅ `output_folder` → Used in instructions.md (lines 12, 129)
|
||||
- ✅ `user_name` → Used in instructions.md (lines 143, 166) and template.md (line 4)
|
||||
- ✅ `communication_language` → Used in instructions.md (line 6)
|
||||
- ✅ `date` → Used in template.md (line 3) and output file naming
|
||||
- ✅ `non_interactive` → Used in instructions.md (lines 8, 66, 68)
|
||||
|
||||
**Bloat Metrics:**
|
||||
|
||||
- Total custom yaml fields: 5
|
||||
- Used fields: 3
|
||||
- Unused fields: 2
|
||||
- **Bloat Percentage: 40%**
|
||||
|
||||
---
|
||||
|
||||
## 3. Config Variable Usage
|
||||
|
||||
### Overall Status: ⚠️ IMPORTANT ISSUE FOUND
|
||||
|
||||
**Communication Language:**
|
||||
|
||||
- ✅ Properly used on line 6: `Communicate all responses in {communication_language}`
|
||||
- ✅ No inappropriate usage in template headers
|
||||
- Status: **CORRECT**
|
||||
|
||||
**User Name:**
|
||||
|
||||
- ✅ Used for personalization on lines 143, 166
|
||||
- ✅ Optional metadata usage in template (line 4)
|
||||
- Status: **CORRECT**
|
||||
|
||||
**Output Folder:**
|
||||
|
||||
- ✅ Properly used for file searches (lines 12, 129)
|
||||
- ❌ **ISSUE:** `default_output_file` hardcodes path instead of using variable
|
||||
- Current: `"{project-root}/docs/tech-spec-epic-{{epic_id}}.md"`
|
||||
- Should be: `"{output_folder}/tech-spec-epic-{{epic_id}}.md"`
|
||||
- Impact: Ignores user's configured output folder preference
|
||||
- Severity: **IMPORTANT**
|
||||
|
||||
**Date:**
|
||||
|
||||
- ✅ System-generated and available
|
||||
- ✅ Used in template metadata (line 3)
|
||||
- ✅ Used in output file naming
|
||||
- Status: **CORRECT**
|
||||
|
||||
### Action Required:
|
||||
|
||||
**Fix default_output_file in workflow.yaml:**
|
||||
|
||||
```yaml
|
||||
# Current (line 29):
|
||||
default_output_file: "{project-root}/docs/tech-spec-epic-{{epic_id}}.md"
|
||||
|
||||
# Should be:
|
||||
default_output_file: "{output_folder}/tech-spec-epic-{{epic_id}}.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Web Bundle Validation
|
||||
|
||||
### 🚨 Status: CRITICAL ISSUES FOUND
|
||||
|
||||
**Current Web Bundle Configuration:**
|
||||
|
||||
```yaml
|
||||
web_bundle:
|
||||
name: 'tech-spec'
|
||||
description: '...'
|
||||
author: 'BMAD BMM'
|
||||
web_bundle_files:
|
||||
- 'bmad/bmm/workflows/4-implementation/epic-tech-context/template.md'
|
||||
- 'bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md'
|
||||
- 'bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md'
|
||||
```
|
||||
|
||||
### Path Validation:
|
||||
|
||||
- ✅ All paths use bmad/-relative format (NOT {project-root})
|
||||
- ✅ No {config_source} variables in web_bundle section
|
||||
- ✅ Paths match actual file locations
|
||||
|
||||
### Completeness Check:
|
||||
|
||||
- ✅ instructions.md listed
|
||||
- ✅ template.md listed (document workflow)
|
||||
- ✅ checklist.md listed
|
||||
|
||||
### 🚨 Critical Issues:
|
||||
|
||||
**Issue 1: Missing Workflow Dependency**
|
||||
|
||||
- Severity: **CRITICAL**
|
||||
- Location: instructions.md line 133
|
||||
- Problem: Workflow invokes `workflow-status` but dependency not in web_bundle_files
|
||||
- Invocation: `<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">`
|
||||
- Missing files:
|
||||
- `bmad/bmm/workflows/workflow-status/workflow.yaml`
|
||||
- `bmad/bmm/workflows/workflow-status/instructions.md` (if exists)
|
||||
|
||||
**Issue 2: Missing existing_workflows Field**
|
||||
|
||||
- Severity: **CRITICAL**
|
||||
- Problem: When `<invoke-workflow>` calls exist, web_bundle MUST include `existing_workflows` field
|
||||
- Current: Field not present
|
||||
- Required: Mapping of workflow variables to paths
|
||||
|
||||
### Required Fix:
|
||||
|
||||
```yaml
|
||||
web_bundle:
|
||||
name: 'tech-spec'
|
||||
description: 'Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping'
|
||||
author: 'BMAD BMM'
|
||||
existing_workflows:
|
||||
- workflow_status: 'bmad/bmm/workflows/workflow-status/workflow.yaml'
|
||||
web_bundle_files:
|
||||
- 'bmad/bmm/workflows/4-implementation/epic-tech-context/template.md'
|
||||
- 'bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md'
|
||||
- 'bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md'
|
||||
- 'bmad/bmm/workflows/workflow-status/workflow.yaml'
|
||||
- 'bmad/bmm/workflows/workflow-status/instructions.md'
|
||||
```
|
||||
|
||||
**Web Bundle Status:**
|
||||
|
||||
- Web Bundle Present: ✅ Yes
|
||||
- Files Listed: 3
|
||||
- Missing Files: 2+
|
||||
- Completeness: ❌ **INCOMPLETE**
|
||||
|
||||
---
|
||||
|
||||
## 5. Bloat Detection
|
||||
|
||||
### Bloat Summary
|
||||
|
||||
**Unused YAML Fields: 2**
|
||||
|
||||
1. `document_output_language`
|
||||
- Type: Config variable
|
||||
- Usage: Not referenced anywhere
|
||||
- Recommendation: **Remove**
|
||||
|
||||
2. `user_skill_level`
|
||||
- Type: Config variable
|
||||
- Usage: Not referenced anywhere
|
||||
- Recommendation: **Remove**
|
||||
|
||||
**Hardcoded Values: 1**
|
||||
|
||||
3. `default_output_file` path
|
||||
- Current: `{project-root}/docs/tech-spec-epic-{{epic_id}}.md`
|
||||
- Should use: `{output_folder}`
|
||||
- Impact: Ignores user configuration
|
||||
- Recommendation: **Fix to use {output_folder}**
|
||||
|
||||
**Redundant Configuration: 3 fields**
|
||||
|
||||
4. Metadata duplication between top-level and web_bundle:
|
||||
- `name` appears on yaml line 1 AND web_bundle line 36
|
||||
- `description` appears on yaml line 2 AND web_bundle line 37
|
||||
- `author` appears on yaml line 3 AND web_bundle line 38
|
||||
- Recommendation: **Remove duplication** (keep in one location)
|
||||
|
||||
### Bloat Metrics:
|
||||
|
||||
- Total custom yaml fields analyzed: 5
|
||||
- Used fields: 3
|
||||
- Unused fields: 2
|
||||
- **Bloat Percentage: 40%**
|
||||
- Redundant metadata fields: 3
|
||||
- **Cleanup Potential: HIGH** (~30% configuration reduction possible)
|
||||
|
||||
---
|
||||
|
||||
## 6. Template Variable Mapping
|
||||
|
||||
### ✅ Status: EXCELLENT - No Issues
|
||||
|
||||
**Template Variables:** 20
|
||||
**Mapped via template-output:** 15
|
||||
**Config Variables:** 2
|
||||
**Runtime Variables:** 3
|
||||
**Missing Mappings:** 0
|
||||
**Orphaned Outputs:** 0
|
||||
|
||||
### All Template Variables Accounted For:
|
||||
|
||||
**Generated via template-output (15):**
|
||||
|
||||
- overview, objectives_scope, system_arch_alignment
|
||||
- services_modules, data_models, apis_interfaces, workflows_sequencing
|
||||
- nfr_performance, nfr_security, nfr_reliability, nfr_observability
|
||||
- dependencies_integrations
|
||||
- acceptance_criteria, traceability_mapping
|
||||
- risks_assumptions_questions, test_strategy
|
||||
|
||||
**Standard Config Variables (2):**
|
||||
|
||||
- date (system-generated)
|
||||
- user_name (from config)
|
||||
|
||||
**Runtime/Extracted Variables (3):**
|
||||
|
||||
- epic_title (extracted from PRD)
|
||||
- epic_id (extracted from PRD)
|
||||
|
||||
### Validation:
|
||||
|
||||
- ✅ All variables use snake_case naming
|
||||
- ✅ Variable names are descriptive and clear
|
||||
- ✅ Logical grouping in template-output sections
|
||||
- ✅ No orphaned template-output tags
|
||||
- ✅ Complete 1:1 mapping coverage
|
||||
|
||||
**No action required** - Template variable mapping is exemplary.
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### 🚨 Critical (Fix Immediately)
|
||||
|
||||
**Priority 1: Fix Web Bundle Dependencies**
|
||||
|
||||
- Add `existing_workflows` field to web_bundle section
|
||||
- Include workflow-status workflow files in web_bundle_files
|
||||
- Impact: Without this, workflow cannot be bundled for web use
|
||||
- File: `workflow.yaml` lines 35-43
|
||||
|
||||
**Priority 2: Add Missing Workflow Files**
|
||||
|
||||
- Include: `bmad/bmm/workflows/workflow-status/workflow.yaml`
|
||||
- Include: `bmad/bmm/workflows/workflow-status/instructions.md` (if exists)
|
||||
- Impact: Web bundle incomplete, workflow invocations will fail
|
||||
- File: `workflow.yaml` web_bundle_files section
|
||||
|
||||
---
|
||||
|
||||
### ⚠️ Important (Address Soon)
|
||||
|
||||
**Priority 3: Fix Output Path Configuration**
|
||||
|
||||
- Change `default_output_file` to use `{output_folder}` variable
|
||||
- Current: `{project-root}/docs/tech-spec-epic-{{epic_id}}.md`
|
||||
- Fixed: `{output_folder}/tech-spec-epic-{{epic_id}}.md`
|
||||
- Impact: Respects user's configured output preferences
|
||||
- File: `workflow.yaml` line 29
|
||||
|
||||
---
|
||||
|
||||
### 🧹 Cleanup (Nice to Have)
|
||||
|
||||
**Priority 4: Remove Unused Config Variables**
|
||||
|
||||
- Remove: `document_output_language` (line 10)
|
||||
- Remove: `user_skill_level` (line 11)
|
||||
- Impact: Reduces configuration bloat by 40%
|
||||
- File: `workflow.yaml` config section
|
||||
|
||||
**Priority 5: Eliminate Metadata Duplication**
|
||||
|
||||
- Remove duplicate `name`, `description`, `author` from either top-level or web_bundle
|
||||
- Keep metadata in one location only
|
||||
- Impact: Cleaner configuration, easier maintenance
|
||||
- File: `workflow.yaml` lines 1-3 or 36-38
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Use this checklist to verify fixes:
|
||||
|
||||
- [ ] **Web Bundle:** existing_workflows field added with workflow_status mapping
|
||||
- [ ] **Web Bundle:** workflow-status/workflow.yaml added to web_bundle_files
|
||||
- [ ] **Config:** default_output_file uses {output_folder} instead of hardcoded path
|
||||
- [ ] **Bloat:** document_output_language removed from yaml
|
||||
- [ ] **Bloat:** user_skill_level removed from yaml
|
||||
- [ ] **Redundancy:** Metadata duplication eliminated
|
||||
- [ ] **Re-test:** Workflow executes successfully after fixes
|
||||
- [ ] **Re-audit:** Run audit-workflow again to verify all issues resolved
|
||||
|
||||
---
|
||||
|
||||
## Workflow Structure Assessment
|
||||
|
||||
### Strengths:
|
||||
|
||||
- ✅ Excellent template variable mapping (20 variables, 0 orphans)
|
||||
- ✅ Proper use of standard config variables
|
||||
- ✅ Clear step-by-step instructions with proper XML structure
|
||||
- ✅ Good integration with workflow-status for progress tracking
|
||||
- ✅ Comprehensive validation checklist
|
||||
- ✅ Non-interactive mode support (#yolo mode)
|
||||
|
||||
### Areas for Improvement:
|
||||
|
||||
- ❌ Web bundle configuration incomplete (missing dependencies)
|
||||
- ❌ Output path doesn't respect user configuration
|
||||
- ⚠️ Configuration bloat (40% unused variables)
|
||||
- ⚠️ Metadata duplication
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate Actions:
|
||||
|
||||
1. **Fix Critical Issues** (Est. 15 minutes)
|
||||
- Add existing_workflows field to web_bundle
|
||||
- Add workflow-status files to web_bundle_files
|
||||
- Verify workflow-status workflow exists at specified path
|
||||
|
||||
2. **Fix Important Issues** (Est. 5 minutes)
|
||||
- Update default_output_file to use {output_folder}
|
||||
- Test output file creation with different config values
|
||||
|
||||
3. **Cleanup Configuration** (Est. 10 minutes)
|
||||
- Remove document_output_language from yaml
|
||||
- Remove user_skill_level from yaml
|
||||
- Eliminate metadata duplication
|
||||
|
||||
4. **Verify Fixes** (Est. 10 minutes)
|
||||
- Re-run audit-workflow to confirm all issues resolved
|
||||
- Test workflow execution end-to-end
|
||||
- Verify web bundle generation works
|
||||
|
||||
### Recommended Testing:
|
||||
|
||||
```bash
|
||||
# After fixes, test the workflow
|
||||
/bmad:bmm:workflows:tech-spec
|
||||
|
||||
# Re-audit to verify
|
||||
/bmad:bmb:agents:bmad-builder -> *audit-workflow
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The **tech-spec** workflow has a solid foundation with excellent template variable mapping and proper instruction structure. However, **critical web bundle issues** must be resolved before production use, and the hardcoded output path should be fixed to respect user configuration.
|
||||
|
||||
**Estimated Fix Time:** 30-40 minutes
|
||||
|
||||
**Recommended Priority:** HIGH - Address critical issues before next release
|
||||
|
||||
---
|
||||
|
||||
**Audit Complete** ✅
|
||||
Generated by: audit-workflow v1.0
|
||||
Powered by: BMAD Core v6-alpha
|
||||
|
|
@ -1,97 +0,0 @@
|
|||
# generated: 2025-10-21
|
||||
# project: MyPlantFamily
|
||||
# project_key: MyPlantFamily
|
||||
# tracking_system: file-system
|
||||
# story_location: {project-root}/docs/stories
|
||||
|
||||
# STATUS DEFINITIONS:
|
||||
# ==================
|
||||
# Epic Status:
|
||||
# - backlog: Epic exists in epic file but not contexted
|
||||
# - contexted: Epic tech context created (required before drafting stories)
|
||||
#
|
||||
# Story Status:
|
||||
# - backlog: Story only exists in epic file
|
||||
# - drafted: Story file created in stories folder
|
||||
# - ready-for-dev: Draft approved and story context created
|
||||
# - in-progress: Developer actively working on implementation
|
||||
# - review: Under SM review (via review-story workflow)
|
||||
# - done: Story completed
|
||||
#
|
||||
# Retrospective Status:
|
||||
# - optional: Can be completed but not required
|
||||
# - completed: Retrospective has been done
|
||||
#
|
||||
# WORKFLOW NOTES:
|
||||
# ===============
|
||||
# - Epics should be 'contexted' before stories can be 'drafted'
|
||||
# - Stories can be worked in parallel if team capacity allows
|
||||
# - SM typically drafts next story after previous one is 'done' to incorporate learnings
|
||||
# - Dev moves story to 'review', SM reviews, then Dev moves to 'done'
|
||||
|
||||
generated: 2025-10-21
|
||||
project: MyPlantFamily
|
||||
project_key: MyPlantFamily
|
||||
tracking_system: file-system
|
||||
story_location: "{project-root}/docs/stories"
|
||||
|
||||
development_status:
|
||||
# Epic 1: Foundation & Core Plant Management
|
||||
epic-1: backlog
|
||||
1-1-project-foundation-development-environment: backlog
|
||||
1-2-app-shell-navigation-framework: backlog
|
||||
1-3-user-authentication-account-management: backlog
|
||||
1-4-plant-data-model-species-database: backlog
|
||||
1-5-add-plant-manual-species-selection: backlog
|
||||
1-6-plant-photo-identification-integration: backlog
|
||||
1-7-plant-naming-profile-creation: backlog
|
||||
1-8-plant-collection-home-screen: backlog
|
||||
1-9-plant-detail-view: backlog
|
||||
1-10-cloud-photo-storage-display: backlog
|
||||
epic-1-retrospective: optional
|
||||
|
||||
# Epic 2: AI Personality System & Engagement Loop
|
||||
epic-2: backlog
|
||||
2-1-personality-system-data-model: backlog
|
||||
2-2-personality-prototype-testing: backlog
|
||||
2-3-llm-integration-api-setup: backlog
|
||||
2-4-chat-interface-ui: backlog
|
||||
2-5-conversational-ai-system: backlog
|
||||
2-6-graceful-degradation-library: backlog
|
||||
2-7-response-caching-cost-optimization: backlog
|
||||
2-8-personality-driven-care-reminders: backlog
|
||||
2-9-push-notification-system: backlog
|
||||
2-10-reminder-intelligence-adaptation: backlog
|
||||
2-11-mood-system-visual-indicators: backlog
|
||||
2-12-mood-calculation-logic-time-based: backlog
|
||||
2-13-personality-introduction-onboarding: backlog
|
||||
2-14-personality-tone-testing-calibration: backlog
|
||||
2-15-emergency-tone-adjustment-system: backlog
|
||||
2-16-api-reliability-monitoring-alerts: backlog
|
||||
epic-2-retrospective: optional
|
||||
|
||||
# Epic 3: Care Scheduling, Photos & Growth Tracking
|
||||
epic-3: backlog
|
||||
3-1-care-schedule-data-model: backlog
|
||||
3-2-auto-generated-care-schedules: backlog
|
||||
3-3-manual-care-logging: backlog
|
||||
3-4-care-history-view: backlog
|
||||
3-5-customizable-care-schedules: backlog
|
||||
3-6-photo-timeline-tracking: backlog
|
||||
3-7-health-status-visualization: backlog
|
||||
3-8-enhanced-mood-calculation-care-data: backlog
|
||||
epic-3-retrospective: optional
|
||||
|
||||
# Epic 4: Social Sharing & Premium Monetization
|
||||
epic-4: backlog
|
||||
4-1-shareable-content-card-design-system: backlog
|
||||
4-2-share-plant-profile: backlog
|
||||
4-3-share-conversation-snippets: backlog
|
||||
4-4-share-growth-progress: backlog
|
||||
4-5-share-care-achievements: backlog
|
||||
4-6-freemium-tier-definition-enforcement: backlog
|
||||
4-7-premium-upgrade-flow-paywall: backlog
|
||||
4-8-payment-processing-subscription-management: backlog
|
||||
4-9-premium-analytics-dashboard: backlog
|
||||
4-10-trial-conversion-optimization: backlog
|
||||
epic-4-retrospective: optional
|
||||
|
|
@ -95,7 +95,6 @@
|
|||
"integrity": "sha512-yDBHV9kQNcr2/sUr9jghVyz9C3Y5G2zUM2H2lo+9mKv4sFgbA8s8Z9t8D1jiTkGoO/NoIfKMyKWr4s6CN23ZwQ==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@ampproject/remapping": "^2.2.0",
|
||||
"@babel/code-frame": "^7.27.1",
|
||||
|
|
@ -1818,7 +1817,6 @@
|
|||
"integrity": "sha512-aPTXCrfwnDLj4VvXrm+UUCQjNEvJgNA8s5F1cvwQU+3KNltTOkBm1j30uNLyqqPNe7gE3KFzImYoZEfLhp4Yow==",
|
||||
"devOptional": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"undici-types": "~7.10.0"
|
||||
}
|
||||
|
|
@ -2135,7 +2133,6 @@
|
|||
"integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"bin": {
|
||||
"acorn": "bin/acorn"
|
||||
},
|
||||
|
|
@ -2497,7 +2494,6 @@
|
|||
}
|
||||
],
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"caniuse-lite": "^1.0.30001735",
|
||||
"electron-to-chromium": "^1.5.204",
|
||||
|
|
@ -3352,7 +3348,6 @@
|
|||
"integrity": "sha512-RNCHRX5EwdrESy3Jc9o8ie8Bog+PeYvvSR8sDGoZxNFTvZ4dlxUB3WzQ3bQMztFrSRODGrLLj8g6OFuGY/aiQg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"@eslint-community/eslint-utils": "^4.2.0",
|
||||
"@eslint-community/regexpp": "^4.12.1",
|
||||
|
|
@ -7092,7 +7087,6 @@
|
|||
"integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"bin": {
|
||||
"prettier": "bin/prettier.cjs"
|
||||
},
|
||||
|
|
@ -7915,7 +7909,6 @@
|
|||
"integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">=12"
|
||||
},
|
||||
|
|
|
|||
|
|
@ -10,7 +10,8 @@
|
|||
<flow>
|
||||
<step n="1" title="Setup">
|
||||
<action>If checklist not provided, load checklist.md from workflow location</action>
|
||||
<action>If document not provided, ask user: "Which document should I validate?"</action>
|
||||
<action>Try to fuzzy match for files similar to the input document name or if user did not provide the document. If document not
|
||||
provided or unsure, ask user: "Which document should I validate?"</action>
|
||||
<action>Load both the checklist and document</action>
|
||||
</step>
|
||||
|
||||
|
|
|
|||
|
|
@ -9,19 +9,23 @@
|
|||
<step n="1" goal="Session Setup">
|
||||
|
||||
<action>Check if context data was provided with workflow invocation</action>
|
||||
<check>If data attribute was passed to this workflow:</check>
|
||||
<action>Load the context document from the data file path</action>
|
||||
<action>Study the domain knowledge and session focus</action>
|
||||
<action>Use the provided context to guide the session</action>
|
||||
<action>Acknowledge the focused brainstorming goal</action>
|
||||
<ask response="session_refinement">I see we're brainstorming about the specific domain outlined in the context. What particular aspect would you like to explore?</ask>
|
||||
<check>Else (no context data provided):</check>
|
||||
<action>Proceed with generic context gathering</action>
|
||||
<ask response="session_topic">1. What are we brainstorming about?</ask>
|
||||
<ask response="stated_goals">2. Are there any constraints or parameters we should keep in mind?</ask>
|
||||
<ask>3. Is the goal broad exploration or focused ideation on specific aspects?</ask>
|
||||
|
||||
<check if="data attribute was passed to this workflow">
|
||||
<action>Load the context document from the data file path</action>
|
||||
<action>Study the domain knowledge and session focus</action>
|
||||
<action>Use the provided context to guide the session</action>
|
||||
<action>Acknowledge the focused brainstorming goal</action>
|
||||
<ask response="session_refinement">I see we're brainstorming about the specific domain outlined in the context. What particular aspect would you like to explore?</ask>
|
||||
</check>
|
||||
|
||||
<check if="no context data provided">
|
||||
<action>Proceed with generic context gathering</action>
|
||||
<ask response="session_topic">1. What are we brainstorming about?</ask>
|
||||
<ask response="stated_goals">2. Are there any constraints or parameters we should keep in mind?</ask>
|
||||
<ask>3. Is the goal broad exploration or focused ideation on specific aspects?</ask>
|
||||
|
||||
<critical>Wait for user response before proceeding. This context shapes the entire session.</critical>
|
||||
</check>
|
||||
|
||||
<template-output>session_topic, stated_goals</template-output>
|
||||
|
||||
|
|
@ -40,19 +44,19 @@ Based on the context from Step 1, present these four approach options:
|
|||
Which approach would you prefer? (Enter 1-4)
|
||||
</ask>
|
||||
|
||||
<check>Based on selection, proceed to appropriate sub-step</check>
|
||||
|
||||
<step n="2a" title="User-Selected Techniques" if="selection==1">
|
||||
<action>Load techniques from {brain_techniques} CSV file</action>
|
||||
<action>Parse: category, technique_name, description, facilitation_prompts</action>
|
||||
|
||||
<check>If strong context from Step 1 (specific problem/goal)</check>
|
||||
<action>Identify 2-3 most relevant categories based on stated_goals</action>
|
||||
<action>Present those categories first with 3-5 techniques each</action>
|
||||
<action>Offer "show all categories" option</action>
|
||||
<check if="strong context from Step 1 (specific problem/goal)">
|
||||
<action>Identify 2-3 most relevant categories based on stated_goals</action>
|
||||
<action>Present those categories first with 3-5 techniques each</action>
|
||||
<action>Offer "show all categories" option</action>
|
||||
</check>
|
||||
|
||||
<check>Else (open exploration)</check>
|
||||
<action>Display all 7 categories with helpful descriptions</action>
|
||||
<check if="open exploration">
|
||||
<action>Display all 7 categories with helpful descriptions</action>
|
||||
</check>
|
||||
|
||||
Category descriptions to guide selection:
|
||||
- **Structured:** Systematic frameworks for thorough exploration
|
||||
|
|
|
|||
|
|
@ -78,20 +78,23 @@
|
|||
</substep>
|
||||
|
||||
<substep n="3c" goal="Handle Questions and Interactions">
|
||||
<check>If an agent asks the user a direct question:</check>
|
||||
<check if="an agent asks the user a direct question">
|
||||
<action>Clearly highlight the question</action>
|
||||
<action>End that round of responses</action>
|
||||
<action>Display: "[Agent Name]: [Their question]"</action>
|
||||
<action>Display: "[Awaiting user response...]"</action>
|
||||
<action>WAIT for user input before continuing</action>
|
||||
</check>
|
||||
|
||||
<check>If agents ask each other questions:</check>
|
||||
<check if="agents ask each other questions">
|
||||
<action>Allow natural back-and-forth in the same response round</action>
|
||||
<action>Maintain conversational flow</action>
|
||||
</check>
|
||||
|
||||
<check>If discussion becomes circular or repetitive:</check>
|
||||
<check if="discussion becomes circular or repetitive">
|
||||
<action>The BMad Master will summarize</action>
|
||||
<action>Redirect to new aspects or ask for user guidance</action>
|
||||
</check>
|
||||
|
||||
</substep>
|
||||
|
||||
|
|
@ -111,15 +114,18 @@
|
|||
</substep>
|
||||
|
||||
<substep n="3e" goal="Check for Exit Conditions">
|
||||
<check>If user message contains any {{exit_triggers}}:</check>
|
||||
<check if="user message contains any {{exit_triggers}}">
|
||||
<action>Have agents provide brief farewells in character</action>
|
||||
<action>Thank user for the discussion</action>
|
||||
<goto step="4">Exit party mode</goto>
|
||||
</check>
|
||||
|
||||
<check>If user seems done or conversation naturally concludes:</check>
|
||||
<check if="user seems done or conversation naturally concludes">
|
||||
<ask>Would you like to continue the discussion or end party mode?</ask>
|
||||
<check>If user indicates end:</check>
|
||||
<check if="user indicates end">
|
||||
<goto step="4">Exit party mode</goto>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
</substep>
|
||||
</step>
|
||||
|
|
|
|||
|
|
@ -76,6 +76,11 @@
|
|||
- [ ] Repeating steps have appropriate repeat attribute (repeat="3", repeat="for-each-X", repeat="until-approved")
|
||||
- [ ] Conditional steps have if="condition" attribute
|
||||
- [ ] XML tags used correctly (<action>, <ask>, <check>, <goto>, <invoke-workflow>, <template-output>)
|
||||
- [ ] No nested tag references in content (use "action tags" not "<action> tags")
|
||||
- [ ] Tag references use descriptive text without angle brackets for clarity
|
||||
- [ ] No conditional execution antipattern (no self-closing <check> tags)
|
||||
- [ ] Single conditionals use <action if="condition"> (inline)
|
||||
- [ ] Multiple conditionals use <check if="condition">...</check> (wrapper block with closing tag)
|
||||
- [ ] Steps are focused (single goal per step)
|
||||
- [ ] Instructions are specific with limits ("Write 1-2 paragraphs" not "Write about")
|
||||
- [ ] Examples provided where helpful
|
||||
|
|
@ -120,9 +125,9 @@ _List any cleanup recommendations:_
|
|||
|
||||
## Audit Summary
|
||||
|
||||
**Total Checks:** 70
|
||||
**Passed:** **\_** / 70
|
||||
**Failed:** **\_** / 70
|
||||
**Total Checks:** 72
|
||||
**Passed:** **\_** / 72
|
||||
**Failed:** **\_** / 72
|
||||
**Pass Rate:** **\_**%
|
||||
|
||||
**Recommendation:**
|
||||
|
|
|
|||
|
|
@ -5,371 +5,337 @@
|
|||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Load and analyze target workflow">
|
||||
<ask>What is the path to the workflow you want to audit? (provide path to workflow.yaml or workflow folder)</ask>
|
||||
<step n="1" goal="Load and analyze target workflow">
|
||||
<ask>What is the path to the workflow you want to audit? (provide path to workflow.yaml or workflow folder)</ask>
|
||||
|
||||
<action>Load the workflow.yaml file from the provided path</action>
|
||||
<action>Identify the workflow type (document, action, interactive, autonomous, meta)</action>
|
||||
<action>List all associated files:</action>
|
||||
<action>Load the workflow.yaml file from the provided path</action>
|
||||
<action>Identify the workflow type (document, action, interactive, autonomous, meta)</action>
|
||||
<action>List all associated files:</action>
|
||||
|
||||
- instructions.md (required for most workflows)
|
||||
- template.md (if document workflow)
|
||||
- checklist.md (if validation exists)
|
||||
- Any data files referenced in yaml
|
||||
- instructions.md (required for most workflows)
|
||||
- template.md (if document workflow)
|
||||
- checklist.md (if validation exists)
|
||||
- Any data files referenced in yaml
|
||||
|
||||
<action>Load all discovered files</action>
|
||||
<action>Load all discovered files</action>
|
||||
|
||||
Display summary:
|
||||
Display summary:
|
||||
|
||||
- Workflow name and description
|
||||
- Type of workflow
|
||||
- Files present
|
||||
- Module assignment
|
||||
|
||||
- Workflow name and description
|
||||
- Type of workflow
|
||||
- Files present
|
||||
- Module assignment
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Validate standard config block">
|
||||
<action>Check workflow.yaml for the standard config block:</action>
|
||||
<step n="2" goal="Validate standard config block">
|
||||
<action>Check workflow.yaml for the standard config block:</action>
|
||||
|
||||
**Required variables:**
|
||||
**Required variables:**
|
||||
|
||||
- `config_source: "{project-root}/bmad/[module]/config.yaml"`
|
||||
- `output_folder: "{config_source}:output_folder"`
|
||||
- `user_name: "{config_source}:user_name"`
|
||||
- `communication_language: "{config_source}:communication_language"`
|
||||
- `date: system-generated`
|
||||
- `config_source: "{project-root}/bmad/[module]/config.yaml"`
|
||||
- `output_folder: "{config_source}:output_folder"`
|
||||
- `user_name: "{config_source}:user_name"`
|
||||
- `communication_language: "{config_source}:communication_language"`
|
||||
- `date: system-generated`
|
||||
|
||||
<action>Validate each variable:</action>
|
||||
<action>Validate each variable:</action>
|
||||
|
||||
**Config Source Check:**
|
||||
**Config Source Check:**
|
||||
|
||||
- [ ] `config_source` is defined
|
||||
- [ ] Points to correct module config path
|
||||
- [ ] Uses {project-root} variable
|
||||
- [ ] `config_source` is defined
|
||||
- [ ] Points to correct module config path
|
||||
- [ ] Uses {project-root} variable
|
||||
|
||||
**Standard Variables Check:**
|
||||
**Standard Variables Check:**
|
||||
|
||||
- [ ] `output_folder` pulls from config_source
|
||||
- [ ] `user_name` pulls from config_source
|
||||
- [ ] `communication_language` pulls from config_source
|
||||
- [ ] `date` is set to system-generated
|
||||
- [ ] `output_folder` pulls from config_source
|
||||
- [ ] `user_name` pulls from config_source
|
||||
- [ ] `communication_language` pulls from config_source
|
||||
- [ ] `date` is set to system-generated
|
||||
|
||||
<action>Record any missing or incorrect config variables</action>
|
||||
<template-output>config_issues</template-output>
|
||||
<action>Record any missing or incorrect config variables</action>
|
||||
<template-output>config_issues</template-output>
|
||||
|
||||
<check>If config issues found:</check>
|
||||
<action>Add to issues list with severity: CRITICAL</action>
|
||||
</step>
|
||||
<action if="config issues found">Add to issues list with severity: CRITICAL</action>
|
||||
|
||||
<step n="3" goal="Analyze YAML/Instruction/Template alignment">
|
||||
<action>Extract all variables defined in workflow.yaml (excluding standard config block)</action>
|
||||
<action>Scan instructions.md for variable usage: {variable_name} pattern</action>
|
||||
<action>Scan template.md for variable usage: {{variable_name}} pattern (if exists)</action>
|
||||
</step>
|
||||
|
||||
<action>Cross-reference analysis:</action>
|
||||
<step n="3" goal="Analyze YAML/Instruction/Template alignment">
|
||||
<action>Extract all variables defined in workflow.yaml (excluding standard config block)</action>
|
||||
<action>Scan instructions.md for variable usage: {variable_name} pattern</action>
|
||||
<action>Scan template.md for variable usage: {{variable_name}} pattern (if exists)</action>
|
||||
|
||||
**For each yaml variable:**
|
||||
<action>Cross-reference analysis:</action>
|
||||
|
||||
1. Is it used in instructions.md? (mark as INSTRUCTION_USED)
|
||||
2. Is it used in template.md? (mark as TEMPLATE_USED)
|
||||
3. Is it neither? (mark as UNUSED_BLOAT)
|
||||
**For each yaml variable:**
|
||||
|
||||
**Special cases to ignore:**
|
||||
1. Is it used in instructions.md? (mark as INSTRUCTION_USED)
|
||||
2. Is it used in template.md? (mark as TEMPLATE_USED)
|
||||
3. Is it neither? (mark as UNUSED_BLOAT)
|
||||
|
||||
- Standard config variables (config_source, output_folder, user_name, communication_language, date)
|
||||
- Workflow metadata (name, description, author)
|
||||
- Path variables (installed_path, template, instructions, validation)
|
||||
- Web bundle configuration (web_bundle block itself)
|
||||
**Special cases to ignore:**
|
||||
|
||||
<action>Identify unused yaml fields (bloat)</action>
|
||||
<action>Identify hardcoded values in instructions that should be variables</action>
|
||||
<template-output>alignment_issues</template-output>
|
||||
- Standard config variables (config_source, output_folder, user_name, communication_language, date)
|
||||
- Workflow metadata (name, description, author)
|
||||
- Path variables (installed_path, template, instructions, validation)
|
||||
- Web bundle configuration (web_bundle block itself)
|
||||
|
||||
<check>If unused variables found:</check>
|
||||
<action>Add to issues list with severity: BLOAT</action>
|
||||
</step>
|
||||
<action>Identify unused yaml fields (bloat)</action>
|
||||
<action>Identify hardcoded values in instructions that should be variables</action>
|
||||
<template-output>alignment_issues</template-output>
|
||||
|
||||
<step n="4" goal="Config variable usage audit">
|
||||
<action>Analyze instructions.md for proper config variable usage:</action>
|
||||
<action if="unused variables found">Add to issues list with severity: BLOAT</action>
|
||||
|
||||
**Communication Language Check:**
|
||||
</step>
|
||||
|
||||
- Search for phrases like "communicate in {communication_language}"
|
||||
- Check if greetings/responses use language-aware patterns
|
||||
- Verify NO usage of {{communication_language}} in template headers
|
||||
<step n="4" goal="Config variable usage audit">
|
||||
<action>Analyze instructions.md for proper config variable usage:</action>
|
||||
|
||||
**User Name Check:**
|
||||
**Communication Language Check:**
|
||||
|
||||
- Look for user addressing patterns using {user_name}
|
||||
- Check if summaries or greetings personalize with {user_name}
|
||||
- Verify optional usage in template metadata (not required)
|
||||
- Search for phrases like "communicate in {communication_language}"
|
||||
- Check if greetings/responses use language-aware patterns
|
||||
- Verify NO usage of {{communication_language}} in template headers
|
||||
|
||||
**Output Folder Check:**
|
||||
**User Name Check:**
|
||||
|
||||
- Search for file write operations
|
||||
- Verify all outputs go to {output_folder} or subdirectories
|
||||
- Check for hardcoded paths like "/output/" or "/generated/"
|
||||
- Look for user addressing patterns using {user_name}
|
||||
- Check if summaries or greetings personalize with {user_name}
|
||||
- Verify optional usage in template metadata (not required)
|
||||
|
||||
**Date Usage Check:**
|
||||
**Output Folder Check:**
|
||||
|
||||
- Verify date is available for agent date awareness
|
||||
- Check optional usage in template metadata
|
||||
- Ensure no confusion between date and model training cutoff
|
||||
- Search for file write operations
|
||||
- Verify all outputs go to {output_folder} or subdirectories
|
||||
- Check for hardcoded paths like "/output/" or "/generated/"
|
||||
|
||||
<action>Record any improper config variable usage</action>
|
||||
<template-output>config_usage_issues</template-output>
|
||||
**Date Usage Check:**
|
||||
|
||||
<check>If config usage issues found:</check>
|
||||
<action>Add to issues list with severity: IMPORTANT</action>
|
||||
</step>
|
||||
- Verify date is available for agent date awareness
|
||||
- Check optional usage in template metadata
|
||||
- Ensure no confusion between date and model training cutoff
|
||||
|
||||
<step n="5" goal="Web bundle validation" optional="true">
|
||||
<check>If workflow.yaml contains web_bundle section:</check>
|
||||
**Nested Tag Reference Check:**
|
||||
|
||||
<action>Validate web_bundle structure:</action>
|
||||
- Search for XML tag references within tags (e.g., `<action>Scan for <action> tags</action>`)
|
||||
- Identify patterns like: `<tag-name> tags`, `<tag-name> calls`, `<tag-name>content</tag-name>` within content
|
||||
- Common problematic tags to check: action, ask, check, template-output, invoke-workflow, goto
|
||||
- Flag any instances where angle brackets appear in content describing tags
|
||||
|
||||
**Path Validation:**
|
||||
**Best Practice:** Use descriptive text without brackets (e.g., "action tags" instead of "<action> tags")
|
||||
|
||||
- [ ] All paths use bmad/-relative format (NOT {project-root})
|
||||
- [ ] No {config_source} variables in web_bundle section
|
||||
- [ ] Paths match actual file locations
|
||||
**Rationale:**
|
||||
|
||||
**Completeness Check:**
|
||||
- Prevents XML parsing ambiguity
|
||||
- Improves readability for humans and LLMs
|
||||
- LLMs understand "action tags" = `<action>` tags from context
|
||||
|
||||
- [ ] instructions file listed in web_bundle_files
|
||||
- [ ] template file listed (if document workflow)
|
||||
- [ ] validation/checklist file listed (if exists)
|
||||
- [ ] All data files referenced in yaml listed
|
||||
- [ ] All files referenced in instructions listed
|
||||
**Conditional Execution Antipattern Check:**
|
||||
|
||||
**Workflow Dependency Scan:**
|
||||
<action>Scan instructions.md for <invoke-workflow> tags</action>
|
||||
<action>Extract workflow paths from invocations</action>
|
||||
<action>Verify each called workflow.yaml is in web_bundle_files</action>
|
||||
<action>**CRITICAL**: Check if existing_workflows field is present when workflows are invoked</action>
|
||||
<action>If <invoke-workflow> calls exist, existing_workflows MUST map workflow variables to paths</action>
|
||||
<action>Example: If instructions use {core_brainstorming}, web_bundle needs:
|
||||
existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml"
|
||||
</action>
|
||||
- Scan for self-closing check tags: `<check>condition text</check>` (invalid antipattern)
|
||||
- Detect pattern: check tag on one line, followed by action/ask/goto tags (indicates incorrect nesting)
|
||||
- Flag sequences like: `<check>If X:</check>` followed by `<action>do Y</action>`
|
||||
|
||||
**File Reference Scan:**
|
||||
<action>Scan instructions.md for file references in <action> tags</action>
|
||||
<action>Check for CSV, JSON, YAML, MD files referenced</action>
|
||||
<action>Verify all referenced files are in web_bundle_files</action>
|
||||
**Correct Patterns:**
|
||||
|
||||
<action>Record any missing files or incorrect paths</action>
|
||||
<template-output>web_bundle_issues</template-output>
|
||||
- Single conditional: `<action if="condition">Do something</action>`
|
||||
- Multiple actions: `<check if="condition">` followed by nested actions with closing `</check>` tag
|
||||
|
||||
<check>If web_bundle issues found:</check>
|
||||
<action>Add to issues list with severity: CRITICAL</action>
|
||||
**Antipattern Example (WRONG):**
|
||||
```xml
|
||||
<check>If condition met:</check>
|
||||
<action>Do something</action>
|
||||
```
|
||||
|
||||
<check>If no web_bundle section exists:</check>
|
||||
<action>Note: "No web_bundle configured (may be intentional for local-only workflows)"</action>
|
||||
</step>
|
||||
**Correct Example:**
|
||||
```xml
|
||||
<check if="condition met">
|
||||
<action>Do something</action>
|
||||
<action>Do something else</action>
|
||||
</check>
|
||||
```
|
||||
|
||||
<step n="6" goal="Bloat detection">
|
||||
<action>Identify bloat patterns:</action>
|
||||
**Or for single action:**
|
||||
```xml
|
||||
<action if="condition met">Do something</action>
|
||||
```
|
||||
|
||||
**Unused YAML Fields:**
|
||||
<action>Scan instructions.md for nested tag references using pattern: <(action|ask|check|template-output|invoke-workflow|goto|step|elicit-required)> within text content</action>
|
||||
<action>Record any instances of nested tag references with line numbers</action>
|
||||
<action>Scan instructions.md for conditional execution antipattern: self-closing check tags</action>
|
||||
<action>Detect pattern: `<check>.*</check>` on single line (self-closing check)</action>
|
||||
<action>Record any antipattern instances with line numbers and suggest corrections</action>
|
||||
<action>Record any improper config variable usage</action>
|
||||
<template-output>config_usage_issues</template-output>
|
||||
|
||||
- Variables defined but not used in instructions OR template
|
||||
- Duplicate fields between top-level and web_bundle section
|
||||
- Commented-out variables that should be removed
|
||||
<action if="config usage issues found">Add to issues list with severity: IMPORTANT</action>
|
||||
<action if="nested tag references found">Add to issues list with severity: CLARITY (recommend using descriptive text without angle brackets)</action>
|
||||
<action if="conditional antipattern found">Add to issues list with severity: CRITICAL (invalid XML structure - must use action if="" or proper check wrapper)</action>
|
||||
|
||||
**Hardcoded Values:**
|
||||
</step>
|
||||
|
||||
- File paths that should use {output_folder}
|
||||
- Generic greetings that should use {user_name}
|
||||
- Language-specific text that should use {communication_language}
|
||||
- Static dates that should use {date}
|
||||
<step n="5" goal="Web bundle validation" optional="true">
|
||||
<check if="workflow.yaml contains web_bundle section">
|
||||
|
||||
**Redundant Configuration:**
|
||||
<action>Validate web_bundle structure:</action>
|
||||
|
||||
- Variables that duplicate web_bundle fields
|
||||
- Metadata repeated across sections
|
||||
**Path Validation:**
|
||||
|
||||
<action>Calculate bloat metrics:</action>
|
||||
- [ ] All paths use bmad/-relative format (NOT {project-root})
|
||||
- [ ] No {config_source} variables in web_bundle section
|
||||
- [ ] Paths match actual file locations
|
||||
|
||||
- Total yaml fields: {{total_yaml_fields}}
|
||||
- Used fields: {{used_fields}}
|
||||
- Unused fields: {{unused_fields}}
|
||||
- Bloat percentage: {{bloat_percentage}}%
|
||||
**Completeness Check:**
|
||||
|
||||
<action>Record all bloat items with recommendations</action>
|
||||
<template-output>bloat_items</template-output>
|
||||
- [ ] instructions file listed in web_bundle_files
|
||||
- [ ] template file listed (if document workflow)
|
||||
- [ ] validation/checklist file listed (if exists)
|
||||
- [ ] All data files referenced in yaml listed
|
||||
- [ ] All files referenced in instructions listed
|
||||
|
||||
<check>If bloat detected:</check>
|
||||
<action>Add to issues list with severity: CLEANUP</action>
|
||||
</step>
|
||||
**Workflow Dependency Scan:**
|
||||
<action>Scan instructions.md for invoke-workflow tags</action>
|
||||
<action>Extract workflow paths from invocations</action>
|
||||
<action>Verify each called workflow.yaml is in web_bundle_files</action>
|
||||
<action>**CRITICAL**: Check if existing_workflows field is present when workflows are invoked</action>
|
||||
<action>If invoke-workflow calls exist, existing_workflows MUST map workflow variables to paths</action>
|
||||
<action>Example: If instructions use {core_brainstorming}, web_bundle needs: existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml"</action>
|
||||
|
||||
<step n="7" goal="Template variable mapping" if="workflow_type == 'document'">
|
||||
<action>Extract all template variables from template.md: {{variable_name}} pattern</action>
|
||||
<action>Scan instructions.md for corresponding <template-output>variable_name</template-output> tags</action>
|
||||
**File Reference Scan:**
|
||||
<action>Scan instructions.md for file references in action tags</action>
|
||||
<action>Check for CSV, JSON, YAML, MD files referenced</action>
|
||||
<action>Verify all referenced files are in web_bundle_files</action>
|
||||
|
||||
<action>Cross-reference mapping:</action>
|
||||
<action>Record any missing files or incorrect paths</action>
|
||||
<template-output>web_bundle_issues</template-output>
|
||||
|
||||
**For each template variable:**
|
||||
<action if="web_bundle issues found">Add to issues list with severity: CRITICAL</action>
|
||||
|
||||
1. Is there a matching <template-output> tag? (mark as MAPPED)
|
||||
2. Is it a standard config variable? (mark as CONFIG_VAR - optional)
|
||||
3. Is it unmapped? (mark as MISSING_OUTPUT)
|
||||
<action if="no web_bundle section exists">Note: "No web_bundle configured (may be intentional for local-only workflows)"</action>
|
||||
</check>
|
||||
|
||||
**For each <template-output> tag:**
|
||||
</step>
|
||||
|
||||
1. Is there a matching template variable? (mark as USED)
|
||||
2. Is it orphaned? (mark as UNUSED_OUTPUT)
|
||||
<step n="6" goal="Bloat detection">
|
||||
<action>Identify bloat patterns:</action>
|
||||
|
||||
<action>Verify variable naming conventions:</action>
|
||||
**Unused YAML Fields:**
|
||||
|
||||
- [ ] All template variables use snake_case
|
||||
- [ ] Variable names are descriptive (not abbreviated)
|
||||
- [ ] Standard config variables properly formatted
|
||||
- Variables defined but not used in instructions OR template
|
||||
- Duplicate fields between top-level and web_bundle section
|
||||
- Commented-out variables that should be removed
|
||||
|
||||
<action>Record any mapping issues</action>
|
||||
<template-output>template_issues</template-output>
|
||||
**Hardcoded Values:**
|
||||
|
||||
<check>If template issues found:</check>
|
||||
<action>Add to issues list with severity: IMPORTANT</action>
|
||||
</step>
|
||||
- File paths that should use {output_folder}
|
||||
- Generic greetings that should use {user_name}
|
||||
- Language-specific text that should use {communication_language}
|
||||
- Static dates that should use {date}
|
||||
|
||||
<step n="8" goal="Generate comprehensive audit report">
|
||||
<action>Compile all findings into a structured report</action>
|
||||
**Redundant Configuration:**
|
||||
|
||||
<action>Write audit report to {output_folder}/audit-report-{{workflow_name}}-{{date}}.md</action>
|
||||
- Variables that duplicate web_bundle fields
|
||||
- Metadata repeated across sections
|
||||
|
||||
**Report Structure:**
|
||||
<action>Calculate bloat metrics:</action>
|
||||
|
||||
```markdown
|
||||
# Workflow Audit Report
|
||||
- Total yaml fields: {{total_yaml_fields}}
|
||||
- Used fields: {{used_fields}}
|
||||
- Unused fields: {{unused_fields}}
|
||||
- Bloat percentage: {{bloat_percentage}}%
|
||||
|
||||
**Workflow:** {{workflow_name}}
|
||||
**Audit Date:** {{date}}
|
||||
**Auditor:** Audit Workflow (BMAD v6)
|
||||
**Workflow Type:** {{workflow_type}}
|
||||
<action>Record all bloat items with recommendations</action>
|
||||
<template-output>bloat_items</template-output>
|
||||
|
||||
---
|
||||
<action if="bloat detected">Add to issues list with severity: CLEANUP</action>
|
||||
|
||||
## Executive Summary
|
||||
</step>
|
||||
|
||||
**Overall Status:** {{overall_status}}
|
||||
<step n="7" goal="Template variable mapping" if="workflow_type == 'document'">
|
||||
<action>Extract all template variables from template.md: {{variable_name}} pattern</action>
|
||||
<action>Scan instructions.md for corresponding template-output tags</action>
|
||||
|
||||
- Critical Issues: {{critical_count}}
|
||||
- Important Issues: {{important_count}}
|
||||
- Cleanup Recommendations: {{cleanup_count}}
|
||||
<action>Cross-reference mapping:</action>
|
||||
|
||||
---
|
||||
**For each template variable:**
|
||||
|
||||
## 1. Standard Config Block Validation
|
||||
1. Is there a matching template-output tag? (mark as MAPPED)
|
||||
2. Is it a standard config variable? (mark as CONFIG_VAR - optional)
|
||||
3. Is it unmapped? (mark as MISSING_OUTPUT)
|
||||
|
||||
{{config_issues}}
|
||||
**For each template-output tag:**
|
||||
|
||||
**Status:** {{config_status}}
|
||||
1. Is there a matching template variable? (mark as USED)
|
||||
2. Is it orphaned? (mark as UNUSED_OUTPUT)
|
||||
|
||||
---
|
||||
<action>Verify variable naming conventions:</action>
|
||||
|
||||
## 2. YAML/Instruction/Template Alignment
|
||||
- [ ] All template variables use snake_case
|
||||
- [ ] Variable names are descriptive (not abbreviated)
|
||||
- [ ] Standard config variables properly formatted
|
||||
|
||||
{{alignment_issues}}
|
||||
<action>Record any mapping issues</action>
|
||||
<template-output>template_issues</template-output>
|
||||
|
||||
**Variables Analyzed:** {{total_variables}}
|
||||
**Used in Instructions:** {{instruction_usage_count}}
|
||||
**Used in Template:** {{template_usage_count}}
|
||||
**Unused (Bloat):** {{bloat_count}}
|
||||
<action if="template issues found">Add to issues list with severity: IMPORTANT</action>
|
||||
|
||||
---
|
||||
</step>
|
||||
|
||||
## 3. Config Variable Usage
|
||||
<step n="8" goal="Generate comprehensive audit report">
|
||||
<action>Compile all findings and calculate summary metrics</action>
|
||||
|
||||
{{config_usage_issues}}
|
||||
<action>Generate executive summary based on issue counts and severity levels</action>
|
||||
<template-output>workflow_type</template-output>
|
||||
<template-output>overall_status</template-output>
|
||||
<template-output>critical_count</template-output>
|
||||
<template-output>important_count</template-output>
|
||||
<template-output>cleanup_count</template-output>
|
||||
|
||||
**Communication Language:** {{comm_lang_status}}
|
||||
**User Name:** {{user_name_status}}
|
||||
**Output Folder:** {{output_folder_status}}
|
||||
**Date:** {{date_status}}
|
||||
<action>Generate status summaries for each audit section</action>
|
||||
<template-output>config_status</template-output>
|
||||
<template-output>total_variables</template-output>
|
||||
<template-output>instruction_usage_count</template-output>
|
||||
<template-output>template_usage_count</template-output>
|
||||
<template-output>bloat_count</template-output>
|
||||
|
||||
---
|
||||
<action>Generate config variable usage status indicators</action>
|
||||
<template-output>comm_lang_status</template-output>
|
||||
<template-output>user_name_status</template-output>
|
||||
<template-output>output_folder_status</template-output>
|
||||
<template-output>date_status</template-output>
|
||||
<template-output>nested_tag_count</template-output>
|
||||
|
||||
## 4. Web Bundle Validation
|
||||
<action>Generate web bundle metrics</action>
|
||||
<template-output>web_bundle_exists</template-output>
|
||||
<template-output>web_bundle_file_count</template-output>
|
||||
<template-output>missing_files_count</template-output>
|
||||
|
||||
{{web_bundle_issues}}
|
||||
<action>Generate bloat metrics</action>
|
||||
<template-output>bloat_percentage</template-output>
|
||||
<template-output>cleanup_potential</template-output>
|
||||
|
||||
**Web Bundle Present:** {{web_bundle_exists}}
|
||||
**Files Listed:** {{web_bundle_file_count}}
|
||||
**Missing Files:** {{missing_files_count}}
|
||||
<action>Generate template mapping metrics</action>
|
||||
<template-output>template_var_count</template-output>
|
||||
<template-output>mapped_count</template-output>
|
||||
<template-output>missing_mapping_count</template-output>
|
||||
|
||||
---
|
||||
<action>Compile prioritized recommendations by severity</action>
|
||||
<template-output>critical_recommendations</template-output>
|
||||
<template-output>important_recommendations</template-output>
|
||||
<template-output>cleanup_recommendations</template-output>
|
||||
|
||||
## 5. Bloat Detection
|
||||
<action>Display summary to {user_name} in {communication_language}</action>
|
||||
<action>Provide path to full audit report: {output_folder}/audit-report-{{workflow_name}}-{{date}}.md</action>
|
||||
|
||||
{{bloat_items}}
|
||||
<ask>Would you like to:
|
||||
|
||||
**Bloat Percentage:** {{bloat_percentage}}%
|
||||
**Cleanup Potential:** {{cleanup_potential}}
|
||||
- View the full audit report
|
||||
- Fix issues automatically (invoke edit-workflow)
|
||||
- Audit another workflow
|
||||
- Exit
|
||||
</ask>
|
||||
|
||||
---
|
||||
|
||||
## 6. Template Variable Mapping
|
||||
|
||||
{{template_issues}}
|
||||
|
||||
**Template Variables:** {{template_var_count}}
|
||||
**Mapped Correctly:** {{mapped_count}}
|
||||
**Missing Mappings:** {{missing_mapping_count}}
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Critical (Fix Immediately)
|
||||
|
||||
{{critical_recommendations}}
|
||||
|
||||
### Important (Address Soon)
|
||||
|
||||
{{important_recommendations}}
|
||||
|
||||
### Cleanup (Nice to Have)
|
||||
|
||||
{{cleanup_recommendations}}
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Use this checklist to verify fixes:
|
||||
|
||||
- [ ] All standard config variables present and correct
|
||||
- [ ] No unused yaml fields (bloat removed)
|
||||
- [ ] Config variables used appropriately in instructions
|
||||
- [ ] Web bundle includes all dependencies
|
||||
- [ ] Template variables properly mapped
|
||||
- [ ] File structure follows v6 conventions
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Review critical issues and fix immediately
|
||||
2. Address important issues in next iteration
|
||||
3. Consider cleanup recommendations for optimization
|
||||
4. Re-run audit after fixes to verify improvements
|
||||
|
||||
---
|
||||
|
||||
**Audit Complete** - Generated by audit-workflow v1.0
|
||||
```
|
||||
|
||||
<action>Display summary to {user_name} in {communication_language}</action>
|
||||
<action>Provide path to full audit report</action>
|
||||
|
||||
<ask>Would you like to:
|
||||
|
||||
- View the full audit report
|
||||
- Fix issues automatically (invoke edit-workflow)
|
||||
- Audit another workflow
|
||||
- Exit
|
||||
</ask>
|
||||
|
||||
<template-output>audit_report_path</template-output>
|
||||
</step>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,118 @@
|
|||
# Workflow Audit Report
|
||||
|
||||
**Workflow:** {{workflow_name}}
|
||||
**Audit Date:** {{date}}
|
||||
**Auditor:** Audit Workflow (BMAD v6)
|
||||
**Workflow Type:** {{workflow_type}}
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Overall Status:** {{overall_status}}
|
||||
|
||||
- Critical Issues: {{critical_count}}
|
||||
- Important Issues: {{important_count}}
|
||||
- Cleanup Recommendations: {{cleanup_count}}
|
||||
|
||||
---
|
||||
|
||||
## 1. Standard Config Block Validation
|
||||
|
||||
{{config_issues}}
|
||||
|
||||
**Status:** {{config_status}}
|
||||
|
||||
---
|
||||
|
||||
## 2. YAML/Instruction/Template Alignment
|
||||
|
||||
{{alignment_issues}}
|
||||
|
||||
**Variables Analyzed:** {{total_variables}}
|
||||
**Used in Instructions:** {{instruction_usage_count}}
|
||||
**Used in Template:** {{template_usage_count}}
|
||||
**Unused (Bloat):** {{bloat_count}}
|
||||
|
||||
---
|
||||
|
||||
## 3. Config Variable Usage & Instruction Quality
|
||||
|
||||
{{config_usage_issues}}
|
||||
|
||||
**Communication Language:** {{comm_lang_status}}
|
||||
**User Name:** {{user_name_status}}
|
||||
**Output Folder:** {{output_folder_status}}
|
||||
**Date:** {{date_status}}
|
||||
**Nested Tag References:** {{nested_tag_count}} instances found
|
||||
|
||||
---
|
||||
|
||||
## 4. Web Bundle Validation
|
||||
|
||||
{{web_bundle_issues}}
|
||||
|
||||
**Web Bundle Present:** {{web_bundle_exists}}
|
||||
**Files Listed:** {{web_bundle_file_count}}
|
||||
**Missing Files:** {{missing_files_count}}
|
||||
|
||||
---
|
||||
|
||||
## 5. Bloat Detection
|
||||
|
||||
{{bloat_items}}
|
||||
|
||||
**Bloat Percentage:** {{bloat_percentage}}%
|
||||
**Cleanup Potential:** {{cleanup_potential}}
|
||||
|
||||
---
|
||||
|
||||
## 6. Template Variable Mapping
|
||||
|
||||
{{template_issues}}
|
||||
|
||||
**Template Variables:** {{template_var_count}}
|
||||
**Mapped Correctly:** {{mapped_count}}
|
||||
**Missing Mappings:** {{missing_mapping_count}}
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Critical (Fix Immediately)
|
||||
|
||||
{{critical_recommendations}}
|
||||
|
||||
### Important (Address Soon)
|
||||
|
||||
{{important_recommendations}}
|
||||
|
||||
### Cleanup (Nice to Have)
|
||||
|
||||
{{cleanup_recommendations}}
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Use this checklist to verify fixes:
|
||||
|
||||
- [ ] All standard config variables present and correct
|
||||
- [ ] No unused yaml fields (bloat removed)
|
||||
- [ ] Config variables used appropriately in instructions
|
||||
- [ ] Web bundle includes all dependencies
|
||||
- [ ] Template variables properly mapped
|
||||
- [ ] File structure follows v6 conventions
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Review critical issues and fix immediately
|
||||
2. Address important issues in next iteration
|
||||
3. Consider cleanup recommendations for optimization
|
||||
4. Re-run audit after fixes to verify improvements
|
||||
|
||||
---
|
||||
|
||||
**Audit Complete** - Generated by audit-workflow v1.0
|
||||
|
|
@ -12,7 +12,7 @@ date: system-generated
|
|||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmb/workflows/audit-workflow"
|
||||
template: false
|
||||
template: "{installed_path}/template.md"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
|
|
|
|||
|
|
@ -67,8 +67,7 @@ For Modules:
|
|||
|
||||
<step n="3" goal="Determine Target Module and Location">
|
||||
<ask>Which module should this belong to? (eg. bmm, bmb, cis, bmm-legacy, or custom)</ask>
|
||||
<check>If custom module:</check>
|
||||
<ask>Enter custom module code (kebab-case):</ask>
|
||||
<action if="custom module"><ask>Enter custom module code (kebab-case):</ask></action>
|
||||
<action>Determine installation path based on type and module</action>
|
||||
<critical>IMPORTANT: All paths must use final BMAD installation locations, not src paths!</critical>
|
||||
<action>Show user the target location: {project-root}/bmad/{{target_module}}/{{item_type}}/{{item_name}}</action>
|
||||
|
|
@ -79,16 +78,19 @@ For Modules:
|
|||
<step n="4" goal="Choose Conversion Strategy">
|
||||
<action>Based on item type and complexity, choose approach:</action>
|
||||
|
||||
<check>If agent conversion:</check>
|
||||
<check>If simple agent (basic persona + commands):</check>
|
||||
<action>Use direct conversion to v5 agent YAML format</action>
|
||||
<goto step="5a">Direct Agent Conversion</goto>
|
||||
<check>If complex agent with embedded workflows:</check>
|
||||
<action>Plan to invoke create-agent workflow</action>
|
||||
<goto step="5b">Workflow-Assisted Agent Creation</goto>
|
||||
<check if="agent conversion">
|
||||
<check if="simple agent (basic persona + commands)">
|
||||
<action>Use direct conversion to v5 agent YAML format</action>
|
||||
<goto step="5a">Direct Agent Conversion</goto>
|
||||
</check>
|
||||
<check if="complex agent with embedded workflows">
|
||||
<action>Plan to invoke create-agent workflow</action>
|
||||
<goto step="5b">Workflow-Assisted Agent Creation</goto>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check>If template or task conversion to workflow:</check>
|
||||
<action>Analyze the v4 item to determine workflow type:</action>
|
||||
<check if="template or task conversion to workflow">
|
||||
<action>Analyze the v4 item to determine workflow type:</action>
|
||||
|
||||
- Does it generate a specific document type? → Document workflow
|
||||
- Does it produce structured output files? → Document workflow
|
||||
|
|
@ -104,14 +106,14 @@ For Modules:
|
|||
4. Meta-workflow (coordinates other workflows)
|
||||
Select 1-4:</ask>
|
||||
|
||||
<check>If template conversion:</check>
|
||||
<goto step="5c">Template-to-Workflow Conversion</goto>
|
||||
<check>If task conversion:</check>
|
||||
<goto step="5e">Task-to-Workflow Conversion</goto>
|
||||
<action if="template conversion"><goto step="5c">Template-to-Workflow Conversion</goto></action>
|
||||
<action if="task conversion"><goto step="5e">Task-to-Workflow Conversion</goto></action>
|
||||
</check>
|
||||
|
||||
<check>If full module conversion:</check>
|
||||
<action>Plan to invoke create-module workflow</action>
|
||||
<goto step="5d">Module Creation</goto>
|
||||
<check if="full module conversion">
|
||||
<action>Plan to invoke create-module workflow</action>
|
||||
<goto step="5d">Module Creation</goto>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="5a" goal="Direct Agent Conversion" optional="true">
|
||||
|
|
@ -262,15 +264,17 @@ date: system-generated
|
|||
- User interaction patterns → appropriate v5 tags
|
||||
|
||||
3. Based on confirmed workflow type:
|
||||
<check>If Document workflow:</check>
|
||||
<check if="Document workflow">
|
||||
- Create template.md from output patterns
|
||||
- Map generation steps to instructions
|
||||
- Add <template-output> tags for sections
|
||||
- Add template-output tags for sections
|
||||
</check>
|
||||
|
||||
<check>If Action workflow:</check>
|
||||
- Set template: false in workflow.yaml
|
||||
- Focus on action sequences in instructions
|
||||
- Preserve execution logic
|
||||
<check if="Action workflow">
|
||||
- Set template: false in workflow.yaml
|
||||
- Focus on action sequences in instructions
|
||||
- Preserve execution logic
|
||||
</check>
|
||||
|
||||
4. Handle special v4 patterns:
|
||||
- 1-9 elicitation menus → v5 <invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
|
@ -341,9 +345,10 @@ For Modules:
|
|||
|
||||
<action>Show validation results to user</action>
|
||||
<ask>Any issues to fix before finalizing? (y/n)</ask>
|
||||
<check>If yes:</check>
|
||||
<check if="yes">
|
||||
<action>Address specific issues</action>
|
||||
<goto step="6">Re-validate</goto>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Migration Report">
|
||||
|
|
@ -360,15 +365,13 @@ For Modules:
|
|||
|
||||
<step n="8" goal="Cleanup and Finalize">
|
||||
<ask>Archive original v4 files? (y/n)</ask>
|
||||
<check>If yes:</check>
|
||||
<action>Move v4 files to: {project-root}/archive/v4-legacy/{{date}}/</action>
|
||||
<action if="yes">Move v4 files to: {project-root}/archive/v4-legacy/{{date}}/</action>
|
||||
|
||||
<action>Show user the final converted items and their locations</action>
|
||||
<action>Provide any post-conversion instructions or recommendations</action>
|
||||
|
||||
<ask>Would you like to convert another legacy item? (y/n)</ask>
|
||||
<check>If yes:</check>
|
||||
<goto step="1">Start new conversion</goto>
|
||||
<action if="yes"><goto step="1">Start new conversion</goto></action>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
|
|
|||
|
|
@ -10,165 +10,131 @@ Agents with distinct communication styles are more memorable, engaging, and fun
|
|||
|
||||
**Film Noir Detective**
|
||||
|
||||
```
|
||||
The terminal glowed like a neon sign in a rain-soaked alley. I had three suspects:
|
||||
bad input validation, a race condition, and that sketchy third-party library.
|
||||
My gut told me to follow the stack trace. In this business, the stack trace never lies.
|
||||
```
|
||||
|
||||
**80s Action Movie**
|
||||
|
||||
```
|
||||
*cracks knuckles* Listen up, code! You've been running wild for too long!
|
||||
Time to bring some LAW and ORDER to this codebase! *explosion sound effect*
|
||||
_cracks knuckles_ Listen up, code! You've been running wild for too long!
|
||||
Time to bring some LAW and ORDER to this codebase! _explosion sound effect_
|
||||
No bug is getting past me! I eat null pointers for BREAKFAST!
|
||||
```
|
||||
|
||||
**Shakespearean Drama**
|
||||
|
||||
```
|
||||
To debug, or not to debug - that is the question!
|
||||
Whether 'tis nobler in the mind to suffer the slings and arrows of outrageous errors,
|
||||
Or to take arms against a sea of bugs, and by opposing, end them?
|
||||
```
|
||||
|
||||
### 🎮 Gaming and Pop Culture
|
||||
|
||||
**Dungeon Master**
|
||||
|
||||
```
|
||||
*rolls dice* You encounter a wild NullPointerException! It has 15 HP and an armor class of 12.
|
||||
What do you do? You can: 1) Try-catch block (defensive spell), 2) Debug (investigation check),
|
||||
3) Console.log everything (barbarian rage). Choose wisely, adventurer!
|
||||
```
|
||||
_rolls dice_ You encounter a wild NullPointerException! It has 15 HP and an armor class of 12.
|
||||
What do you do? You can: 1 Try-catch block (defensive spell), 2 Debug (investigation check),
|
||||
3 Console.log everything (barbarian rage). Choose wisely, adventurer!
|
||||
|
||||
**Speedrunner**
|
||||
|
||||
```
|
||||
Alright chat, we're going for the any% world record refactor!
|
||||
Frame-perfect optimization incoming! If we clip through this abstraction layer
|
||||
we can save 3ms on every API call. LET'S GOOOO!
|
||||
```
|
||||
|
||||
### 🌍 Cultural Archetypes
|
||||
|
||||
**British Butler**
|
||||
|
||||
```
|
||||
I've taken the liberty of organizing your imports alphabetically, sir/madam.
|
||||
Might I suggest a spot of refactoring with your afternoon tea?
|
||||
The code coverage report is ready for your perusal at your convenience.
|
||||
Very good, sir/madam.
|
||||
```
|
||||
|
||||
**Zen Master**
|
||||
|
||||
```
|
||||
The bug you seek is not in the code, but in the assumption.
|
||||
Empty your cache, as you would empty your mind.
|
||||
When the test passes, it makes no sound.
|
||||
Be like water - async and flowing.
|
||||
```
|
||||
|
||||
**Southern Hospitality**
|
||||
|
||||
```
|
||||
Well bless your heart, looks like you've got yourself a little bug there!
|
||||
Don't you worry none, we'll fix it up real nice.
|
||||
Can I get you some sweet tea while we debug?
|
||||
Y'all come back now if you need more help!
|
||||
```
|
||||
|
||||
### 🔬 Professional Personas
|
||||
|
||||
**McKinsey Consultant**
|
||||
|
||||
```
|
||||
Let me break this down into three key buckets.
|
||||
First, we need to align on the strategic imperatives.
|
||||
Second, we'll leverage best practices to drive synergies.
|
||||
Third, we'll action items to move the needle. Net-net: significant value-add.
|
||||
```
|
||||
|
||||
**Startup Founder**
|
||||
|
||||
```
|
||||
Okay so basically we're going to disrupt the entire way you write code!
|
||||
This is going to be HUGE! We're talking 10x productivity gains!
|
||||
Let's move fast and break things! Well... let's move fast and fix things!
|
||||
We're not just writing code, we're changing the world!
|
||||
```
|
||||
|
||||
### 🎭 Character Quirks
|
||||
|
||||
**Overcaffeinated Developer**
|
||||
|
||||
```
|
||||
OH WOW OKAY SO - *sips coffee* - WE HAVE A BUG BUT ITS FINE ITS TOTALLY FINE
|
||||
I KNOW EXACTLY WHAT TO DO *types at 200wpm* JUST NEED TO REFACTOR EVERYTHING
|
||||
WAIT NO ACTUALLY *more coffee* I HAVE A BETTER IDEA! Have you tried... TYPESCRIPT?!
|
||||
```
|
||||
OH WOW OKAY SO - _sips coffee_ - WE HAVE A BUG BUT ITS FINE ITS TOTALLY FINE
|
||||
I KNOW EXACTLY WHAT TO DO _types at 200wpm_ JUST NEED TO REFACTOR EVERYTHING
|
||||
WAIT NO ACTUALLY _more coffee_ I HAVE A BETTER IDEA! Have you tried... TYPESCRIPT?!
|
||||
|
||||
**Dad Joke Enthusiast**
|
||||
|
||||
```
|
||||
Why did the developer go broke? Because he used up all his cache!
|
||||
*chuckles at own joke*
|
||||
_chuckles at own joke_
|
||||
Speaking of cache, let's clear yours and see if that fixes the issue.
|
||||
I promise my debugging skills are better than my jokes! ...I hope!
|
||||
```
|
||||
|
||||
### 🚀 Sci-Fi and Space
|
||||
|
||||
**Star Trek Officer**
|
||||
|
||||
```
|
||||
Captain's Log, Supplemental: The anomaly in the codebase appears to be a temporal loop
|
||||
in the async function. Mr. Data suggests we reverse the polarity of the promise chain.
|
||||
Number One, make it so. Engage debugging protocols on my mark.
|
||||
*taps combadge* Engineering, we need more processing power!
|
||||
_taps combadge_ Engineering, we need more processing power!
|
||||
Red Alert! All hands to debugging stations!
|
||||
```
|
||||
|
||||
**Star Trek Engineer**
|
||||
|
||||
```
|
||||
Captain, I'm givin' her all she's got! The CPU cannae take much more!
|
||||
If we push this algorithm any harder, the whole system's gonna blow!
|
||||
*frantically typing* I can maybe squeeze 10% more performance if we
|
||||
_frantically typing_ I can maybe squeeze 10% more performance if we
|
||||
reroute power from the console.logs to the main execution thread!
|
||||
```
|
||||
|
||||
### 📺 TV Drama
|
||||
|
||||
**Soap Opera Dramatic**
|
||||
|
||||
```
|
||||
*turns dramatically to camera*
|
||||
_turns dramatically to camera_
|
||||
This function... I TRUSTED it! We had HISTORY together - three commits worth!
|
||||
But now? *single tear* It's throwing exceptions behind my back!
|
||||
*grabs another function* YOU KNEW ABOUT THIS BUG ALL ALONG, DIDN'T YOU?!
|
||||
*dramatic music swells* I'LL NEVER IMPORT YOU AGAIN!
|
||||
```
|
||||
But now? _single tear_ It's throwing exceptions behind my back!
|
||||
_grabs another function_ YOU KNEW ABOUT THIS BUG ALL ALONG, DIDN'T YOU?!
|
||||
_dramatic music swells_ I'LL NEVER IMPORT YOU AGAIN!
|
||||
|
||||
**Reality TV Confessional**
|
||||
|
||||
```
|
||||
*whispering to camera in confessional booth*
|
||||
_whispering to camera in confessional booth_
|
||||
Okay so like, that Array.sort() function? It's literally SO toxic.
|
||||
It mutates IN PLACE. Who does that?! I didn't come here to deal with side effects!
|
||||
*applies lip gloss* I'm forming an alliance with map() and filter().
|
||||
_applies lip gloss_ I'm forming an alliance with map() and filter().
|
||||
We're voting sort() off the codebase at tonight's pull request ceremony.
|
||||
```
|
||||
|
||||
**Reality Competition**
|
||||
|
||||
```
|
||||
Listen up, coders! For today's challenge, you need to refactor this legacy code
|
||||
in under 30 minutes! The winner gets immunity from the next code review!
|
||||
*dramatic pause* BUT WAIT - there's a TWIST! You can only use VANILLA JAVASCRIPT!
|
||||
*contestants gasp* The clock starts... NOW! GO GO GO!
|
||||
```
|
||||
_dramatic pause_ BUT WAIT - there's a TWIST! You can only use VANILLA JAVASCRIPT!
|
||||
_contestants gasp_ The clock starts... NOW! GO GO GO!
|
||||
|
||||
## Creating Custom Styles
|
||||
|
||||
|
|
@ -183,21 +149,17 @@ in under 30 minutes! The winner gets immunity from the next code review!
|
|||
|
||||
**Cooking Show + Military**
|
||||
|
||||
```
|
||||
ALRIGHT RECRUITS! Today we're preparing a beautiful Redux reducer!
|
||||
First, we MISE EN PLACE our action types - that's French for GET YOUR CODE TOGETHER!
|
||||
We're going to sauté these event handlers until they're GOLDEN BROWN!
|
||||
MOVE WITH PURPOSE! SEASON WITH SEMICOLONS!
|
||||
```
|
||||
|
||||
**Nature Documentary + Conspiracy Theorist**
|
||||
|
||||
```
|
||||
The wild JavaScript function stalks its prey... but wait... notice how it ALWAYS
|
||||
knows where the data is? That's not natural selection, folks. Someone DESIGNED it
|
||||
this way. The console.logs are watching. They're ALWAYS watching.
|
||||
Nature? Or intelligent debugging? You decide.
|
||||
```
|
||||
|
||||
## Tips for Success
|
||||
|
||||
|
|
|
|||
|
|
@ -8,16 +8,18 @@
|
|||
<workflow>
|
||||
|
||||
<step n="-1" goal="Optional brainstorming for agent ideas" optional="true">
|
||||
<ask>Do you want to brainstorm agent ideas first? [y/n]</ask>
|
||||
<ask>Do you want to brainstorm agent ideas first? [y/n]</ask>
|
||||
|
||||
<check>If yes:</check>
|
||||
<action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
|
||||
<action>Pass context data: {installed_path}/brainstorm-context.md</action>
|
||||
<action>Wait for brainstorming session completion</action>
|
||||
<action>Use brainstorming output to inform agent identity and persona development in following steps</action>
|
||||
<check if="user answered yes">
|
||||
<action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
|
||||
<action>Pass context data: {installed_path}/brainstorm-context.md</action>
|
||||
<action>Wait for brainstorming session completion</action>
|
||||
<action>Use brainstorming output to inform agent identity and persona development in following steps</action>
|
||||
</check>
|
||||
|
||||
<check>If no:</check>
|
||||
<action>Proceed directly to Step 0</action>
|
||||
<check if="user answered no">
|
||||
<action>Proceed directly to Step 0</action>
|
||||
</check>
|
||||
|
||||
<template-output>brainstorming_results</template-output>
|
||||
</step>
|
||||
|
|
@ -48,15 +50,17 @@
|
|||
|
||||
**Path Determination:**
|
||||
|
||||
<check>If Module agent:</check>
|
||||
<action>Discover which module system fits best (bmm, bmb, cis, or custom)</action>
|
||||
<action>Store as {{target_module}} for path determination</action>
|
||||
<note>Agent will be saved to: bmad/{{target_module}}/agents/</note>
|
||||
<check if="module agent selected">
|
||||
<action>Discover which module system fits best (bmm, bmb, cis, or custom)</action>
|
||||
<action>Store as {{target_module}} for path determination</action>
|
||||
<note>Agent will be saved to: bmad/{{target_module}}/agents/</note>
|
||||
</check>
|
||||
|
||||
<check>If Simple/Expert agent (standalone):</check>
|
||||
<action>Explain this will be their personal agent, not tied to a module</action>
|
||||
<note>Agent will be saved to: bmad/agents/{{agent-name}}/</note>
|
||||
<note>All sidecar files will be in the same folder</note>
|
||||
<check if="standalone agent selected">
|
||||
<action>Explain this will be their personal agent, not tied to a module</action>
|
||||
<note>Agent will be saved to: bmad/agents/{{agent-name}}/</note>
|
||||
<note>All sidecar files will be in the same folder</note>
|
||||
</check>
|
||||
|
||||
<critical>Determine agent location:</critical>
|
||||
|
||||
|
|
@ -163,15 +167,14 @@ menu:
|
|||
|
||||
<action>Generate the complete YAML incorporating all discovered elements:</action>
|
||||
|
||||
<example>
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: bmad/{{target_module}}/agents/{{agent_filename}}.md
|
||||
name: {{agent_name}} # The name chosen together
|
||||
title: {{agent_title}} # From the role that emerged
|
||||
icon: {{agent_icon}} # The perfect emoji
|
||||
module: {{target_module}}
|
||||
<example type="yaml">
|
||||
agent:
|
||||
metadata:
|
||||
id: bmad/{{target_module}}/agents/{{agent_filename}}.md
|
||||
name: {{agent_name}} # The name chosen together
|
||||
title: {{agent_title}} # From the role that emerged
|
||||
icon: {{agent_icon}} # The perfect emoji
|
||||
module: {{target_module}}
|
||||
|
||||
persona:
|
||||
role: |
|
||||
|
|
@ -188,11 +191,10 @@ prompts: {{if discussed}}
|
|||
critical_actions: {{if needed}}
|
||||
|
||||
menu: {{The capabilities built}}
|
||||
|
||||
````
|
||||
</example>
|
||||
|
||||
<critical>Save based on agent type:</critical>
|
||||
|
||||
- If Module Agent: Save to {module_output_file}
|
||||
- If Standalone (Simple/Expert): Save to {standalone_output_file}
|
||||
|
||||
|
|
@ -204,29 +206,31 @@ menu: {{The capabilities built}}
|
|||
<step n="7" goal="Optional personalization" optional="true">
|
||||
<ask>Would you like to create a customization file? This lets you tweak the agent's personality later without touching the core agent.</ask>
|
||||
|
||||
<check>If interested:</check>
|
||||
<action>Explain how the customization file gives them a playground to experiment with different personality traits, add new commands, or adjust responses as they get to know the agent better</action>
|
||||
<check if="user interested">
|
||||
<action>Explain how the customization file gives them a playground to experiment with different personality traits, add new commands, or adjust responses as they get to know the agent better</action>
|
||||
|
||||
<action>Create customization file at: {config_output_file}</action>
|
||||
<action>Create customization file at: {config_output_file}</action>
|
||||
|
||||
<example>
|
||||
```yaml
|
||||
# Personal tweaks for {{agent_name}}
|
||||
# Experiment freely - changes merge at build time
|
||||
agent:
|
||||
metadata:
|
||||
name: '' # Try nicknames!
|
||||
persona:
|
||||
role: ''
|
||||
identity: ''
|
||||
communication_style: '' # Switch styles anytime
|
||||
principles: []
|
||||
critical_actions: []
|
||||
prompts: []
|
||||
menu: [] # Add personal commands
|
||||
````
|
||||
<example>
|
||||
```yaml
|
||||
# Personal tweaks for {{agent_name}}
|
||||
# Experiment freely - changes merge at build time
|
||||
agent:
|
||||
metadata:
|
||||
name: '' # Try nicknames!
|
||||
persona:
|
||||
role: ''
|
||||
identity: ''
|
||||
communication_style: '' # Switch styles anytime
|
||||
principles: []
|
||||
critical_actions: []
|
||||
prompts: []
|
||||
menu: [] # Add personal commands
|
||||
````
|
||||
|
||||
</example>
|
||||
</example>
|
||||
|
||||
</check>
|
||||
|
||||
<template-output>agent_config</template-output>
|
||||
</step>
|
||||
|
|
@ -298,23 +302,27 @@ Add domain-specific resources here.
|
|||
</step>
|
||||
|
||||
<step n="8b" goal="Handle build tools availability">
|
||||
<action>Check if BMAD build tools are available in this project</action>
|
||||
<action>Check if BMAD build tools are available in this project</action>
|
||||
|
||||
<check>If in BMAD-METHOD project with build tools:</check>
|
||||
<action>Proceed normally - agent will be built later by the installer</action>
|
||||
<check if="BMAD-METHOD project with build tools">
|
||||
<action>Proceed normally - agent will be built later by the installer</action>
|
||||
</check>
|
||||
|
||||
<check>If NO build tools available (external project):</check>
|
||||
<ask>Build tools not detected in this project. Would you like me to:
|
||||
<check if="external project without build tools">
|
||||
<ask>Build tools not detected in this project. Would you like me to:
|
||||
|
||||
1. Generate the compiled agent (.md with XML) ready to use
|
||||
2. Keep the YAML and build it elsewhere
|
||||
3. Provide both formats
|
||||
</ask>
|
||||
1. Generate the compiled agent (.md with XML) ready to use
|
||||
2. Keep the YAML and build it elsewhere
|
||||
3. Provide both formats
|
||||
</ask>
|
||||
|
||||
<check>If option 1 or 3 selected:</check>
|
||||
<action>Generate compiled agent XML with proper structure including activation rules, persona sections, and menu items</action>
|
||||
<action>Save compiled version as {{agent_filename}}.md</action>
|
||||
<action>Provide path for .claude/commands/ or similar</action>
|
||||
<check if="option 1 or 3 selected">
|
||||
<action>Generate compiled agent XML with proper structure including activation rules, persona sections, and menu items</action>
|
||||
<action>Save compiled version as {{agent_filename}}.md</action>
|
||||
<action>Provide path for .claude/commands/ or similar</action>
|
||||
</check>
|
||||
|
||||
</check>
|
||||
|
||||
<template-output>build_handling</template-output>
|
||||
</step>
|
||||
|
|
@ -328,11 +336,13 @@ Add domain-specific resources here.
|
|||
- Command functionality verification
|
||||
- Personality settings confirmation
|
||||
|
||||
<check>If issues found:</check>
|
||||
<action>Explain the issue conversationally and fix it</action>
|
||||
<check if="validation issues found">
|
||||
<action>Explain the issue conversationally and fix it</action>
|
||||
</check>
|
||||
|
||||
<check>If all good:</check>
|
||||
<action>Celebrate that the agent passed all checks and is ready</action>
|
||||
<check if="validation passed">
|
||||
<action>Celebrate that the agent passed all checks and is ready</action>
|
||||
</check>
|
||||
|
||||
**Technical Checks (behind the scenes):**
|
||||
|
||||
|
|
@ -365,8 +375,9 @@ Add domain-specific resources here.
|
|||
- List the commands available
|
||||
- Suggest trying the first command to see it in action
|
||||
|
||||
<check>If Expert agent:</check>
|
||||
<action>Remind user to add any special knowledge or data the agent might need to its workspace</action>
|
||||
<check if="expert agent">
|
||||
<action>Remind user to add any special knowledge or data the agent might need to its workspace</action>
|
||||
</check>
|
||||
|
||||
<action>Explore what user would like to do next - test the agent, create a teammate, or tweak personality</action>
|
||||
|
||||
|
|
|
|||
|
|
@ -10,14 +10,16 @@
|
|||
<step n="-1" goal="Optional brainstorming for module ideas" optional="true">
|
||||
<ask>Do you want to brainstorm module ideas first? [y/n]</ask>
|
||||
|
||||
<check>If yes:</check>
|
||||
<action>Invoke brainstorming workflow: {brainstorming_workflow}</action>
|
||||
<action>Pass context data: {brainstorming_context}</action>
|
||||
<action>Wait for brainstorming session completion</action>
|
||||
<action>Use brainstorming output to inform module concept, agent lineup, and workflow portfolio in following steps</action>
|
||||
<check if="yes">
|
||||
<action>Invoke brainstorming workflow: {brainstorming_workflow}</action>
|
||||
<action>Pass context data: {brainstorming_context}</action>
|
||||
<action>Wait for brainstorming session completion</action>
|
||||
<action>Use brainstorming output to inform module concept, agent lineup, and workflow portfolio in following steps</action>
|
||||
</check>
|
||||
|
||||
<check>If no:</check>
|
||||
<action>Proceed directly to Step 0</action>
|
||||
<check if="no">
|
||||
<action>Proceed directly to Step 0</action>
|
||||
</check>
|
||||
|
||||
<template-output>brainstorming_results</template-output>
|
||||
</step>
|
||||
|
|
@ -25,17 +27,20 @@
|
|||
<step n="0" goal="Check for module brief" optional="true">
|
||||
<ask>Do you have a module brief or should we create one? [have/create/skip]</ask>
|
||||
|
||||
<check>If create:</check>
|
||||
<action>Invoke module-brief workflow: {project-root}/bmad/bmb/workflows/module-brief/workflow.yaml</action>
|
||||
<action>Wait for module brief completion</action>
|
||||
<action>Load the module brief to use as blueprint</action>
|
||||
<check if="create">
|
||||
<action>Invoke module-brief workflow: {project-root}/bmad/bmb/workflows/module-brief/workflow.yaml</action>
|
||||
<action>Wait for module brief completion</action>
|
||||
<action>Load the module brief to use as blueprint</action>
|
||||
</check>
|
||||
|
||||
<check>If have:</check>
|
||||
<ask>Provide path to module brief document</ask>
|
||||
<action>Load the module brief and use it to pre-populate all planning sections</action>
|
||||
<check if="have">
|
||||
<ask>Provide path to module brief document</ask>
|
||||
<action>Load the module brief and use it to pre-populate all planning sections</action>
|
||||
</check>
|
||||
|
||||
<check>If skip:</check>
|
||||
<action>Proceed directly to Step 1</action>
|
||||
<check if="skip">
|
||||
<action>Proceed directly to Step 1</action>
|
||||
</check>
|
||||
|
||||
<template-output>module_brief</template-output>
|
||||
</step>
|
||||
|
|
@ -113,8 +118,7 @@
|
|||
**Tasks Planning (optional):**
|
||||
<ask>Any special tasks that don't warrant full workflows?</ask>
|
||||
|
||||
<check>If tasks needed:</check>
|
||||
<action>For each task, capture name, purpose, and whether standalone or supporting</action>
|
||||
<action if="tasks needed">For each task, capture name, purpose, and whether standalone or supporting</action>
|
||||
|
||||
<template-output>module_components</template-output>
|
||||
</step>
|
||||
|
|
@ -221,17 +225,19 @@
|
|||
<step n="5" goal="Create first agent" optional="true">
|
||||
<ask>Create your first agent now? [yes/no]</ask>
|
||||
|
||||
<check>If yes:</check>
|
||||
<action>Invoke agent builder workflow: {agent_builder}</action>
|
||||
<action>Pass module_components as context input</action>
|
||||
<action>Guide them to create the primary agent for the module</action>
|
||||
<check if="yes">
|
||||
<action>Invoke agent builder workflow: {agent_builder}</action>
|
||||
<action>Pass module_components as context input</action>
|
||||
<action>Guide them to create the primary agent for the module</action>
|
||||
|
||||
<critical>Save to module's agents folder:</critical>
|
||||
|
||||
- Save to {{module_path}}/agents/
|
||||
</check>
|
||||
|
||||
<check>If no:</check>
|
||||
<action>Create placeholder file in agents folder with TODO notes including agent name, purpose, and type</action>
|
||||
<check if="no">
|
||||
<action>Create placeholder file in agents folder with TODO notes including agent name, purpose, and type</action>
|
||||
</check>
|
||||
|
||||
<template-output>first_agent</template-output>
|
||||
</step>
|
||||
|
|
@ -239,17 +245,19 @@
|
|||
<step n="6" goal="Create first workflow" optional="true">
|
||||
<ask>Create your first workflow now? [yes/no]</ask>
|
||||
|
||||
<check>If yes:</check>
|
||||
<action>Invoke workflow builder: {workflow_builder}</action>
|
||||
<action>Pass module_components as context input</action>
|
||||
<action>Guide them to create the primary workflow</action>
|
||||
<check if="yes">
|
||||
<action>Invoke workflow builder: {workflow_builder}</action>
|
||||
<action>Pass module_components as context input</action>
|
||||
<action>Guide them to create the primary workflow</action>
|
||||
|
||||
<critical>Save to module's workflows folder:</critical>
|
||||
|
||||
- Save to {{module_path}}/workflows/
|
||||
</check>
|
||||
|
||||
<check>If no:</check>
|
||||
<action>Create placeholder workflow folder structure with TODO notes for workflow.yaml, instructions.md, and template.md if document workflow</action>
|
||||
<check if="no">
|
||||
<action>Create placeholder workflow folder structure with TODO notes for workflow.yaml, instructions.md, and template.md if document workflow</action>
|
||||
</check>
|
||||
|
||||
<template-output>first_workflow</template-output>
|
||||
</step>
|
||||
|
|
@ -325,24 +333,24 @@ prompt:
|
|||
|
||||
<ask>Does your module need custom installation logic (database setup, API registration, etc.)?</ask>
|
||||
|
||||
<check>If yes, create installer.js:</check>
|
||||
<check if="yes, create installer.js">
|
||||
```javascript
|
||||
// {{module_name}} Module Installer
|
||||
// Custom installation logic
|
||||
|
||||
```javascript
|
||||
// {{module_name}} Module Installer
|
||||
// Custom installation logic
|
||||
/\*\*
|
||||
|
||||
/**
|
||||
* Module installation hook
|
||||
* Called after files are copied but before IDE configuration
|
||||
*
|
||||
* @param {Object} options - Installation options
|
||||
* @param {string} options.projectRoot - Project root directory
|
||||
* @param {Object} options.config - Module configuration from install-config.yaml
|
||||
* @param {Array} options.installedIDEs - List of IDE codes being configured
|
||||
* @param {Object} options.logger - Logger instance (log, warn, error methods)
|
||||
* @returns {boolean} - true if successful, false to abort installation
|
||||
*/
|
||||
async function install(options) {
|
||||
- Module installation hook
|
||||
- Called after files are copied but before IDE configuration
|
||||
-
|
||||
- @param {Object} options - Installation options
|
||||
- @param {string} options.projectRoot - Project root directory
|
||||
- @param {Object} options.config - Module configuration from install-config.yaml
|
||||
- @param {Array} options.installedIDEs - List of IDE codes being configured
|
||||
- @param {Object} options.logger - Logger instance (log, warn, error methods)
|
||||
- @returns {boolean} - true if successful, false to abort installation
|
||||
\*/
|
||||
async function install(options) {
|
||||
const { projectRoot, config, installedIDEs, logger } = options;
|
||||
|
||||
logger.log('Running {{module_name}} custom installer...');
|
||||
|
|
@ -357,17 +365,21 @@ async function install(options) {
|
|||
|
||||
logger.log('{{module_name}} custom installation complete!');
|
||||
return true;
|
||||
|
||||
}
|
||||
|
||||
module.exports = { install };
|
||||
```
|
||||
|
||||
`````
|
||||
|
||||
<critical>Save location:</critical>
|
||||
|
||||
- Save to {{module_path}}/\_module-installer/installer.js
|
||||
</check>
|
||||
|
||||
<check>If no:</check>
|
||||
<check if="no">
|
||||
<action>Skip installer.js creation - the standard installer will handle everything</action>
|
||||
</check>
|
||||
|
||||
<template-output>installer_config</template-output>
|
||||
</step>
|
||||
|
|
@ -389,7 +401,8 @@ This module provides:
|
|||
|
||||
```bash
|
||||
bmad install {{module_code}}
|
||||
```
|
||||
`````
|
||||
|
||||
````
|
||||
|
||||
## Components
|
||||
|
|
@ -471,22 +484,26 @@ Created by {{user_name}} on {{date}}
|
|||
Create a development roadmap for remaining components:
|
||||
|
||||
**TODO.md file:**
|
||||
|
||||
```markdown
|
||||
# {{module_name}} Development Roadmap
|
||||
|
||||
## Phase 1: Core Components
|
||||
|
||||
{{phase1_tasks}}
|
||||
|
||||
## Phase 2: Enhanced Features
|
||||
|
||||
{{phase2_tasks}}
|
||||
|
||||
## Phase 3: Polish and Integration
|
||||
|
||||
{{phase3_tasks}}
|
||||
|
||||
## Quick Commands
|
||||
|
||||
Create new agent:
|
||||
````
|
||||
```
|
||||
|
||||
workflow create-agent
|
||||
|
||||
|
|
|
|||
|
|
@ -290,6 +290,43 @@ _Generated on {{date}}_
|
|||
- **`<action if="">`** - Single conditional action (cleaner, more concise)
|
||||
- **`<check if="">...</check>`** - Multiple items under same condition (explicit scope)
|
||||
|
||||
**❌ CRITICAL ANTIPATTERN - DO NOT USE:**
|
||||
|
||||
**Invalid self-closing check tags:**
|
||||
|
||||
```xml
|
||||
<!-- ❌ WRONG - Invalid XML structure -->
|
||||
<check>If condition met:</check>
|
||||
<action>Do something</action>
|
||||
|
||||
<!-- ❌ WRONG - Ambiguous nesting -->
|
||||
<check>If validation fails:</check>
|
||||
<action>Log error</action>
|
||||
<goto step="1">Retry</goto>
|
||||
```
|
||||
|
||||
**Why this is wrong:**
|
||||
|
||||
- Creates invalid XML structure (check tag doesn't wrap anything)
|
||||
- Ambiguous - unclear if actions are inside or outside the condition
|
||||
- Breaks formatter and parser logic
|
||||
- Not part of BMAD workflow spec
|
||||
|
||||
**✅ CORRECT alternatives:**
|
||||
|
||||
```xml
|
||||
<!-- ✅ Single action - use inline if -->
|
||||
<action if="condition met">Do something</action>
|
||||
|
||||
<!-- ✅ Multiple actions - use proper wrapper block -->
|
||||
<check if="validation fails">
|
||||
<action>Log error</action>
|
||||
<goto step="1">Retry</goto>
|
||||
</check>
|
||||
```
|
||||
|
||||
**Rule:** If you have only ONE conditional action, use `<action if="">`. If you have MULTIPLE conditional actions, use `<check if="">...</check>` wrapper with a closing tag.
|
||||
|
||||
### Loops
|
||||
|
||||
```xml
|
||||
|
|
|
|||
|
|
@ -86,8 +86,8 @@ Present the editing menu to the user:
|
|||
<step n="4" goal="Load relevant documentation">
|
||||
Based on the selected edit type, load appropriate reference materials:
|
||||
|
||||
<check>If option 2 (Add/fix standard config):</check>
|
||||
<action>Prepare standard config block template:</action>
|
||||
<check if="option 2 (Add/fix standard config) selected">
|
||||
<action>Prepare standard config block template:</action>
|
||||
|
||||
```yaml
|
||||
# Critical variables from config
|
||||
|
|
@ -102,48 +102,54 @@ date: system-generated
|
|||
<action>Identify missing config variables to add</action>
|
||||
<action>Check instructions.md for config variable usage</action>
|
||||
<action>Check template.md for config variable usage</action>
|
||||
</check>
|
||||
|
||||
<check>If editing instructions or adding features:</check>
|
||||
<action>Review the "Writing Instructions" section of the creation guide</action>
|
||||
<action>Load example workflows from {project-root}/bmad/bmm/workflows/ for patterns</action>
|
||||
<check if="editing instructions or adding features">
|
||||
<action>Review the "Writing Instructions" section of the creation guide</action>
|
||||
<action>Load example workflows from {project-root}/bmad/bmm/workflows/ for patterns</action>
|
||||
</check>
|
||||
|
||||
<check>If editing templates:</check>
|
||||
<action>Review the "Templates and Variables" section of the creation guide</action>
|
||||
<action>Ensure variable naming conventions are followed</action>
|
||||
<check if="editing templates">
|
||||
<action>Review the "Templates and Variables" section of the creation guide</action>
|
||||
<action>Ensure variable naming conventions are followed</action>
|
||||
</check>
|
||||
|
||||
<check>If editing validation:</check>
|
||||
<action>Review the "Validation" section and measurable criteria examples</action>
|
||||
<action if="editing validation">Review the "Validation" section and measurable criteria examples</action>
|
||||
|
||||
<check>If option 9 (Remove bloat):</check>
|
||||
<action>Cross-reference all workflow.yaml fields against instructions.md and template.md</action>
|
||||
<action>Identify yaml fields not used in any file</action>
|
||||
<action>Check for duplicate fields in web_bundle section</action>
|
||||
<check if="option 9 (Remove bloat) selected">
|
||||
<action>Cross-reference all workflow.yaml fields against instructions.md and template.md</action>
|
||||
<action>Identify yaml fields not used in any file</action>
|
||||
<action>Check for duplicate fields in web_bundle section</action>
|
||||
</check>
|
||||
|
||||
<check>If configuring web bundle:</check>
|
||||
<action>Review the "Web Bundles" section of the creation guide</action>
|
||||
<action>Scan all workflow files for referenced resources</action>
|
||||
<action>Create inventory of all files that must be included</action>
|
||||
<action>Scan instructions for <invoke-workflow> calls - those yamls must be included</action>
|
||||
<check if="configuring web bundle">
|
||||
<action>Review the "Web Bundles" section of the creation guide</action>
|
||||
<action>Scan all workflow files for referenced resources</action>
|
||||
<action>Create inventory of all files that must be included</action>
|
||||
<action>Scan instructions for invoke-workflow calls - those yamls must be included</action>
|
||||
</check>
|
||||
|
||||
<check>If fixing critical issues:</check>
|
||||
<action>Load the workflow execution engine documentation</action>
|
||||
<action>Verify all required elements are present</action>
|
||||
<check if="fixing critical issues">
|
||||
<action>Load the workflow execution engine documentation</action>
|
||||
<action>Verify all required elements are present</action>
|
||||
</check>
|
||||
|
||||
<check>If adjusting instruction style (option 11):</check>
|
||||
<action>Analyze current instruction style in instructions.md:</action>
|
||||
<check if="adjusting instruction style (option 11) selected">
|
||||
<action>Analyze current instruction style in instructions.md:</action>
|
||||
|
||||
- Count <action> tags vs <ask> tags
|
||||
- Count action tags vs ask tags
|
||||
- Identify goal-oriented language ("guide", "explore", "help") vs prescriptive ("choose", "select", "specify")
|
||||
- Assess whether steps are open-ended or structured with specific options
|
||||
<action>Determine current dominant style: intent-based, prescriptive, or mixed</action>
|
||||
<action>Load the instruction style guide section from create-workflow</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Perform edits" repeat="until-complete">
|
||||
Based on the selected focus area:
|
||||
|
||||
<check>If configuring web bundle (option 7):</check>
|
||||
<action>Check if web_bundle section exists in workflow.yaml</action>
|
||||
<check if="configuring web bundle (option 7) selected">
|
||||
<action>Check if web_bundle section exists in workflow.yaml</action>
|
||||
|
||||
If creating new web bundle:
|
||||
|
||||
|
|
@ -157,7 +163,7 @@ If creating new web bundle:
|
|||
- Any included files
|
||||
5. Scan template.md for any includes
|
||||
6. Create complete web_bundle_files array
|
||||
7. **CRITICAL**: Check for <invoke-workflow> calls in instructions:
|
||||
7. **CRITICAL**: Check for invoke-workflow calls in instructions:
|
||||
- If workflow invokes other workflows, add existing_workflows field
|
||||
- Maps workflow variable name to bmad/-relative path
|
||||
- Signals bundler to recursively include invoked workflow's web_bundle
|
||||
|
|
@ -170,9 +176,10 @@ If updating existing web bundle:
|
|||
2. Check for missing files in web_bundle_files
|
||||
3. Remove any config dependencies
|
||||
4. Update file list with newly referenced files
|
||||
</check>
|
||||
|
||||
<check>If adjusting instruction style (option 11):</check>
|
||||
<action>Present current style analysis to user:</action>
|
||||
<check if="adjusting instruction style (option 11) selected">
|
||||
<action>Present current style analysis to user:</action>
|
||||
|
||||
**Current Instruction Style Analysis:**
|
||||
|
||||
|
|
@ -233,8 +240,8 @@ Even workflows with a primary style should use the other when appropriate. For e
|
|||
|
||||
<ask>What would you like to do?
|
||||
|
||||
1. **Make more intent-based** - Convert prescriptive <ask> tags to goal-oriented <action> tags where appropriate
|
||||
2. **Make more prescriptive** - Convert open-ended <action> tags to specific <ask> tags with options
|
||||
1. **Make more intent-based** - Convert prescriptive ask tags to goal-oriented action tags where appropriate
|
||||
2. **Make more prescriptive** - Convert open-ended action tags to specific ask tags with options
|
||||
3. **Optimize mix** - Use intent-based for complex steps, prescriptive for simple data collection
|
||||
4. **Review specific steps** - Show me each step and let me decide individually
|
||||
5. **Cancel** - Keep current style
|
||||
|
|
@ -242,10 +249,11 @@ Even workflows with a primary style should use the other when appropriate. For e
|
|||
Select option (1-5):</ask>
|
||||
|
||||
<action>Store user's style adjustment preference as {{style_adjustment_choice}}</action>
|
||||
</check>
|
||||
|
||||
<check>If choice is 1 (make more intent-based):</check>
|
||||
<action>Identify prescriptive <ask> tags that could be converted to intent-based <action> tags</action>
|
||||
<action>For each candidate conversion:
|
||||
<check if="choice is 1 (make more intent-based)">
|
||||
<action>Identify prescriptive ask tags that could be converted to intent-based action tags</action>
|
||||
<action>For each candidate conversion:
|
||||
|
||||
- Show original prescriptive version
|
||||
- Suggest intent-based alternative focused on goals
|
||||
|
|
@ -253,10 +261,11 @@ Select option (1-5):</ask>
|
|||
- Ask for approval
|
||||
</action>
|
||||
<action>Apply approved conversions</action>
|
||||
</check>
|
||||
|
||||
<check>If choice is 2 (make more prescriptive):</check>
|
||||
<action>Identify open-ended <action> tags that could be converted to prescriptive <ask> tags</action>
|
||||
<action>For each candidate conversion:
|
||||
<check if="choice is 2 (make more prescriptive)">
|
||||
<action>Identify open-ended action tags that could be converted to prescriptive ask tags</action>
|
||||
<action>For each candidate conversion:
|
||||
|
||||
- Show original intent-based version
|
||||
- Suggest prescriptive alternative with specific options
|
||||
|
|
@ -264,10 +273,11 @@ Select option (1-5):</ask>
|
|||
- Ask for approval
|
||||
</action>
|
||||
<action>Apply approved conversions</action>
|
||||
</check>
|
||||
|
||||
<check>If choice is 3 (optimize mix):</check>
|
||||
<action>Analyze each step for complexity and purpose</action>
|
||||
<action>Recommend style for each step:
|
||||
<check if="choice is 3 (optimize mix)">
|
||||
<action>Analyze each step for complexity and purpose</action>
|
||||
<action>Recommend style for each step:
|
||||
|
||||
- Simple data collection → Prescriptive
|
||||
- Complex discovery → Intent-based
|
||||
|
|
@ -278,19 +288,20 @@ Select option (1-5):</ask>
|
|||
</action>
|
||||
<action>Show recommendations with reasoning</action>
|
||||
<action>Apply approved optimizations</action>
|
||||
</check>
|
||||
|
||||
<check>If choice is 4 (review specific steps):</check>
|
||||
<action>Present each step one at a time</action>
|
||||
<action>For each step:
|
||||
<check if="choice is 4 (review specific steps)">
|
||||
<action>Present each step one at a time</action>
|
||||
<action>For each step:
|
||||
|
||||
- Show current instruction text
|
||||
- Identify current style (intent-based, prescriptive, or mixed)
|
||||
- Offer to keep, convert to intent-based, or convert to prescriptive
|
||||
- Apply user's choice before moving to next step
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<check>If choice is 5 (cancel):</check>
|
||||
<goto step="3">Return to editing menu</goto>
|
||||
<action if="choice is 5 (cancel)"><goto step="3">Return to editing menu</goto></action>
|
||||
|
||||
<action>Show the current content that will be edited</action>
|
||||
<action>Explain the proposed changes and why they improve the workflow</action>
|
||||
|
|
@ -305,16 +316,17 @@ Select option (1-5):</ask>
|
|||
- [d] Done with edits
|
||||
</ask>
|
||||
|
||||
<check>If user selects 'a':</check>
|
||||
<action>Apply the changes to the file</action>
|
||||
<action>Log the change for the summary</action>
|
||||
<check if="user selects 'a'">
|
||||
<action>Apply the changes to the file</action>
|
||||
<action>Log the change for the summary</action>
|
||||
</check>
|
||||
|
||||
<check>If user selects 'e':</check>
|
||||
<ask>What modifications would you like to make?</ask>
|
||||
<goto step="5">Regenerate with modifications</goto>
|
||||
<check if="user selects 'e'">
|
||||
<ask>What modifications would you like to make?</ask>
|
||||
<goto step="5">Regenerate with modifications</goto>
|
||||
</check>
|
||||
|
||||
<check>If user selects 'd':</check>
|
||||
<continue>Proceed to validation</continue>
|
||||
<action if="user selects 'd'"><continue>Proceed to validation</continue></action>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Validate all changes" optional="true">
|
||||
|
|
@ -361,10 +373,12 @@ Select option (1-5):</ask>
|
|||
- [ ] Called workflows (<invoke-workflow>) included in web_bundle_files
|
||||
- [ ] Complete file inventory verified
|
||||
|
||||
<check>If any validation fails:</check>
|
||||
<ask>Issues found. Would you like to fix them? (y/n)</ask>
|
||||
<check>If yes:</check>
|
||||
<goto step="5">Return to editing</goto>
|
||||
<check if="any validation fails">
|
||||
<ask>Issues found. Would you like to fix them? (y/n)</ask>
|
||||
<check if="yes">
|
||||
<goto step="5">Return to editing</goto>
|
||||
</check>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Generate change summary">
|
||||
|
|
@ -385,8 +399,7 @@ Select option (1-5):</ask>
|
|||
- Exit
|
||||
</ask>
|
||||
|
||||
<check>If test workflow:</check>
|
||||
<action>Invoke the edited workflow for testing</action>
|
||||
<action if="test workflow">Invoke the edited workflow for testing</action>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
|
|
|||
|
|
@ -130,7 +130,7 @@
|
|||
4. Save README.md
|
||||
</action>
|
||||
|
||||
<check>If clarification needed about purpose or unique features → Ask user briefly, then continue</check>
|
||||
<action if="clarification needed about purpose or unique features">Ask user briefly, then continue</action>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Process mid-level folder documentation" if="target_type requires folder docs">
|
||||
|
|
|
|||
|
|
@ -30,6 +30,12 @@ agent:
|
|||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
description: Produce a Scale Adaptive Architecture
|
||||
|
||||
- trigger: validate-architecture
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
checklist: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/checklist.md"
|
||||
document: "{output_folder}/architecture.md"
|
||||
description: Validate Architecture Document
|
||||
|
||||
- trigger: solutioning-gate-check
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml"
|
||||
description: Validate solutioning complete, ready for Phase 4 (Level 2-4 only)
|
||||
|
|
|
|||
|
|
@ -39,10 +39,12 @@ agent:
|
|||
workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml"
|
||||
description: Create Tech Spec for Level 0-1 (sometimes Level 2) projects
|
||||
|
||||
- trigger: validate-tech-spec
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml"
|
||||
checklist: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/checklist.md"
|
||||
document: "{output_folder}/tech-spec.md"
|
||||
description: Validate Technical Specification Document
|
||||
|
||||
- trigger: correct-course
|
||||
workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
|
||||
description: Course Correction Analysis
|
||||
|
||||
- trigger: validate
|
||||
exec: "{project-root}/bmad/core/tasks/validate-workflow.xml"
|
||||
description: Validate any document against its workflow checklist
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
# UX Expert Agent Definition
|
||||
# UX Designer Agent Definition
|
||||
|
||||
agent:
|
||||
metadata:
|
||||
id: bmad/bmm/agents/ux-expert.md
|
||||
id: bmad/bmm/agents/ux-designer.md
|
||||
name: Sally
|
||||
title: UX Expert
|
||||
title: UX Designer
|
||||
icon: 🎨
|
||||
module: bmm
|
||||
|
||||
|
|
@ -22,6 +22,12 @@ agent:
|
|||
workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
|
||||
description: Check workflow status and get recommendations (START HERE!)
|
||||
|
||||
- trigger: ux-spec
|
||||
workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/ux/workflow.yaml"
|
||||
description: Create UX/UI Specification and AI Frontend Prompts
|
||||
- trigger: create-design
|
||||
workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml"
|
||||
description: Conduct Design Thinking Workshop to Define the User Specification
|
||||
|
||||
- trigger: validate-design
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml"
|
||||
checklist: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design/checklist.md"
|
||||
document: "{output_folder}/ux-spec.md"
|
||||
description: Validate UX Specification and Design Artifacts
|
||||
|
|
@ -8,4 +8,4 @@ agents:
|
|||
- architect
|
||||
- pm
|
||||
- sm
|
||||
- ux-expert
|
||||
- ux-designer
|
||||
|
|
|
|||
|
|
@ -300,9 +300,10 @@ This brief will serve as the primary input for creating the Game Design Document
|
|||
- Proceed to GDD workflow: `workflow gdd`
|
||||
- Validate assumptions with target players</ask>
|
||||
|
||||
<check>If user chooses option 3 (executive summary):</check>
|
||||
<action>Create condensed 3-page executive brief focusing on: core concept, target market, gameplay pillars, key differentiators, and success criteria</action>
|
||||
<action>Save as: {output_folder}/game-brief-executive-{{game_name}}-{{date}}.md</action>
|
||||
<check if="user chooses option 3 (executive summary)">
|
||||
<action>Create condensed 3-page executive brief focusing on: core concept, target market, gameplay pillars, key differentiators, and success criteria</action>
|
||||
<action>Save as: {output_folder}/game-brief-executive-{{game_name}}-{{date}}.md</action>
|
||||
</check>
|
||||
|
||||
<template-output>final_brief</template-output>
|
||||
<template-output>executive_brief</template-output>
|
||||
|
|
|
|||
|
|
@ -264,9 +264,10 @@ Which approach works best for you?</ask>
|
|||
|
||||
This brief will serve as the primary input for creating the Product Requirements Document (PRD).</ask>
|
||||
|
||||
<check>If user chooses option 3 (executive summary):</check>
|
||||
<action>Create condensed 3-page executive brief focusing on: problem statement, proposed solution, target users, MVP scope, financial impact, and strategic alignment</action>
|
||||
<action>Save as: {output_folder}/product-brief-executive-{{project_name}}-{{date}}.md</action>
|
||||
<check if="user chooses option 3 (executive summary)">
|
||||
<action>Create condensed 3-page executive brief focusing on: problem statement, proposed solution, target users, MVP scope, financial impact, and strategic alignment</action>
|
||||
<action>Save as: {output_folder}/product-brief-executive-{{project_name}}-{{date}}.md</action>
|
||||
</check>
|
||||
|
||||
<template-output>final_brief</template-output>
|
||||
<template-output>executive_brief</template-output>
|
||||
|
|
|
|||
|
|
@ -97,9 +97,10 @@ The workflow adapts automatically based on project assessment, but key configura
|
|||
│ ├── instructions-narrative.md # Narrative design instructions
|
||||
│ ├── narrative-template.md # Narrative planning template
|
||||
│ └── workflow.yaml
|
||||
└── ux/
|
||||
├── instructions-ux.md # UX specification instructions
|
||||
├── ux-spec-template.md # UX specification template
|
||||
└── create-ux-design/
|
||||
├── instructions.md # UX design instructions
|
||||
├── ux-design-template.md # UX design template
|
||||
├── checklist.md # UX design validation checklist
|
||||
└── workflow.yaml
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,310 @@
|
|||
# Create UX Design Workflow Validation Checklist
|
||||
|
||||
**Purpose**: Validate UX Design Specification is complete, collaborative, and implementation-ready.
|
||||
|
||||
**Paradigm**: Visual collaboration-driven, not template generation
|
||||
|
||||
**Expected Outputs**:
|
||||
|
||||
- ux-design-specification.md
|
||||
- ux-color-themes.html (color theme visualizer)
|
||||
- ux-design-directions.html (design mockups)
|
||||
- Optional: ux-prototype.html, ux-component-showcase.html, ai-frontend-prompt.md
|
||||
|
||||
---
|
||||
|
||||
## 1. Output Files Exist
|
||||
|
||||
- [ ] **ux-design-specification.md** created in output folder
|
||||
- [ ] **ux-color-themes.html** generated (interactive color exploration)
|
||||
- [ ] **ux-design-directions.html** generated (6-8 design mockups)
|
||||
- [ ] No unfilled {{template_variables}} in specification
|
||||
- [ ] All sections have content (not placeholder text)
|
||||
|
||||
---
|
||||
|
||||
## 2. Collaborative Process Validation
|
||||
|
||||
**The workflow should facilitate decisions WITH the user, not FOR them**
|
||||
|
||||
- [ ] **Design system chosen by user** (not auto-selected)
|
||||
- [ ] **Color theme selected from options** (user saw visualizations and chose)
|
||||
- [ ] **Design direction chosen from mockups** (user explored 6-8 options)
|
||||
- [ ] **User journey flows designed collaboratively** (options presented, user decided)
|
||||
- [ ] **UX patterns decided with user input** (not just generated)
|
||||
- [ ] **Decisions documented WITH rationale** (why each choice was made)
|
||||
|
||||
---
|
||||
|
||||
## 3. Visual Collaboration Artifacts
|
||||
|
||||
### Color Theme Visualizer
|
||||
|
||||
- [ ] **HTML file exists and is valid** (ux-color-themes.html)
|
||||
- [ ] **Shows 3-4 theme options** (or documented existing brand)
|
||||
- [ ] **Each theme has complete palette** (primary, secondary, semantic colors)
|
||||
- [ ] **Live UI component examples** in each theme (buttons, forms, cards)
|
||||
- [ ] **Side-by-side comparison** enabled
|
||||
- [ ] **User's selection documented** in specification
|
||||
|
||||
### Design Direction Mockups
|
||||
|
||||
- [ ] **HTML file exists and is valid** (ux-design-directions.html)
|
||||
- [ ] **6-8 different design approaches** shown
|
||||
- [ ] **Full-screen mockups** of key screens
|
||||
- [ ] **Design philosophy labeled** for each direction (e.g., "Dense Dashboard", "Spacious Explorer")
|
||||
- [ ] **Interactive navigation** between directions
|
||||
- [ ] **Responsive preview** toggle available
|
||||
- [ ] **User's choice documented WITH reasoning** (what they liked, why it fits)
|
||||
|
||||
---
|
||||
|
||||
## 4. Design System Foundation
|
||||
|
||||
- [ ] **Design system chosen** (or custom design decision documented)
|
||||
- [ ] **Current version identified** (if using established system)
|
||||
- [ ] **Components provided by system documented**
|
||||
- [ ] **Custom components needed identified**
|
||||
- [ ] **Decision rationale clear** (why this system for this project)
|
||||
|
||||
---
|
||||
|
||||
## 5. Core Experience Definition
|
||||
|
||||
- [ ] **Defining experience articulated** (the ONE thing that makes this app unique)
|
||||
- [ ] **Novel UX patterns identified** (if applicable)
|
||||
- [ ] **Novel patterns fully designed** (interaction model, states, feedback)
|
||||
- [ ] **Core experience principles defined** (speed, guidance, flexibility, feedback)
|
||||
|
||||
---
|
||||
|
||||
## 6. Visual Foundation
|
||||
|
||||
### Color System
|
||||
|
||||
- [ ] **Complete color palette** (primary, secondary, accent, semantic, neutrals)
|
||||
- [ ] **Semantic color usage defined** (success, warning, error, info)
|
||||
- [ ] **Color accessibility considered** (contrast ratios for text)
|
||||
- [ ] **Brand alignment** (follows existing brand or establishes new identity)
|
||||
|
||||
### Typography
|
||||
|
||||
- [ ] **Font families selected** (heading, body, monospace if needed)
|
||||
- [ ] **Type scale defined** (h1-h6, body, small, etc.)
|
||||
- [ ] **Font weights documented** (when to use each)
|
||||
- [ ] **Line heights specified** for readability
|
||||
|
||||
### Spacing & Layout
|
||||
|
||||
- [ ] **Spacing system defined** (base unit, scale)
|
||||
- [ ] **Layout grid approach** (columns, gutters)
|
||||
- [ ] **Container widths** for different breakpoints
|
||||
|
||||
---
|
||||
|
||||
## 7. Design Direction
|
||||
|
||||
- [ ] **Specific direction chosen** from mockups (not generic)
|
||||
- [ ] **Layout pattern documented** (navigation, content structure)
|
||||
- [ ] **Visual hierarchy defined** (density, emphasis, focus)
|
||||
- [ ] **Interaction patterns specified** (modal vs inline, disclosure approach)
|
||||
- [ ] **Visual style documented** (minimal, balanced, rich, maximalist)
|
||||
- [ ] **User's reasoning captured** (why this direction fits their vision)
|
||||
|
||||
---
|
||||
|
||||
## 8. User Journey Flows
|
||||
|
||||
- [ ] **All critical journeys from PRD designed** (no missing flows)
|
||||
- [ ] **Each flow has clear goal** (what user accomplishes)
|
||||
- [ ] **Flow approach chosen collaboratively** (user picked from options)
|
||||
- [ ] **Step-by-step documentation** (screens, actions, feedback)
|
||||
- [ ] **Decision points and branching** defined
|
||||
- [ ] **Error states and recovery** addressed
|
||||
- [ ] **Success states specified** (completion feedback)
|
||||
- [ ] **Mermaid diagrams or clear flow descriptions** included
|
||||
|
||||
---
|
||||
|
||||
## 9. Component Library Strategy
|
||||
|
||||
- [ ] **All required components identified** (from design system + custom)
|
||||
- [ ] **Custom components fully specified**:
|
||||
- Purpose and user-facing value
|
||||
- Content/data displayed
|
||||
- User actions available
|
||||
- All states (default, hover, active, loading, error, disabled)
|
||||
- Variants (sizes, styles, layouts)
|
||||
- Behavior on interaction
|
||||
- Accessibility considerations
|
||||
- [ ] **Design system components customization needs** documented
|
||||
|
||||
---
|
||||
|
||||
## 10. UX Pattern Consistency Rules
|
||||
|
||||
**These patterns ensure consistent UX across the entire app**
|
||||
|
||||
- [ ] **Button hierarchy defined** (primary, secondary, tertiary, destructive)
|
||||
- [ ] **Feedback patterns established** (success, error, warning, info, loading)
|
||||
- [ ] **Form patterns specified** (labels, validation, errors, help text)
|
||||
- [ ] **Modal patterns defined** (sizes, dismiss behavior, focus, stacking)
|
||||
- [ ] **Navigation patterns documented** (active state, breadcrumbs, back button)
|
||||
- [ ] **Empty state patterns** (first use, no results, cleared content)
|
||||
- [ ] **Confirmation patterns** (when to confirm destructive actions)
|
||||
- [ ] **Notification patterns** (placement, duration, stacking, priority)
|
||||
- [ ] **Search patterns** (trigger, results, filters, no results)
|
||||
- [ ] **Date/time patterns** (format, timezone, pickers)
|
||||
|
||||
**Each pattern should have:**
|
||||
|
||||
- [ ] Clear specification (how it works)
|
||||
- [ ] Usage guidance (when to use)
|
||||
- [ ] Examples (concrete implementations)
|
||||
|
||||
---
|
||||
|
||||
## 11. Responsive Design
|
||||
|
||||
- [ ] **Breakpoints defined** for target devices (mobile, tablet, desktop)
|
||||
- [ ] **Adaptation patterns documented** (how layouts change)
|
||||
- [ ] **Navigation adaptation** (how nav changes on small screens)
|
||||
- [ ] **Content organization changes** (multi-column to single, grid to list)
|
||||
- [ ] **Touch targets adequate** on mobile (minimum size specified)
|
||||
- [ ] **Responsive strategy aligned** with chosen design direction
|
||||
|
||||
---
|
||||
|
||||
## 12. Accessibility
|
||||
|
||||
- [ ] **WCAG compliance level specified** (A, AA, or AAA)
|
||||
- [ ] **Color contrast requirements** documented (ratios for text)
|
||||
- [ ] **Keyboard navigation** addressed (all interactive elements accessible)
|
||||
- [ ] **Focus indicators** specified (visible focus states)
|
||||
- [ ] **ARIA requirements** noted (roles, labels, announcements)
|
||||
- [ ] **Screen reader considerations** (meaningful labels, structure)
|
||||
- [ ] **Alt text strategy** for images
|
||||
- [ ] **Form accessibility** (label associations, error identification)
|
||||
- [ ] **Testing strategy** defined (automated tools, manual testing)
|
||||
|
||||
---
|
||||
|
||||
## 13. Coherence and Integration
|
||||
|
||||
- [ ] **Design system and custom components visually consistent**
|
||||
- [ ] **All screens follow chosen design direction**
|
||||
- [ ] **Color usage consistent with semantic meanings**
|
||||
- [ ] **Typography hierarchy clear and consistent**
|
||||
- [ ] **Similar actions handled the same way** (pattern consistency)
|
||||
- [ ] **All PRD user journeys have UX design**
|
||||
- [ ] **All entry points designed**
|
||||
- [ ] **Error and edge cases handled**
|
||||
- [ ] **Every interactive element meets accessibility requirements**
|
||||
- [ ] **All flows keyboard-navigable**
|
||||
- [ ] **Colors meet contrast requirements**
|
||||
|
||||
---
|
||||
|
||||
## 14. Cross-Workflow Alignment (Epics File Update)
|
||||
|
||||
**As UX design progresses, you discover implementation details that affect the story breakdown**
|
||||
|
||||
### Stories Discovered During UX Design
|
||||
|
||||
- [ ] **Review epics.md file** for alignment with UX design
|
||||
- [ ] **New stories identified** during UX design that weren't in epics.md:
|
||||
- [ ] Custom component build stories (if significant)
|
||||
- [ ] UX pattern implementation stories
|
||||
- [ ] Animation/transition stories
|
||||
- [ ] Responsive adaptation stories
|
||||
- [ ] Accessibility implementation stories
|
||||
- [ ] Edge case handling stories discovered during journey design
|
||||
- [ ] Onboarding/empty state stories
|
||||
- [ ] Error state handling stories
|
||||
|
||||
### Story Complexity Adjustments
|
||||
|
||||
- [ ] **Existing stories complexity reassessed** based on UX design:
|
||||
- [ ] Stories that are now more complex (UX revealed additional requirements)
|
||||
- [ ] Stories that are simpler (design system handles more than expected)
|
||||
- [ ] Stories that should be split (UX design shows multiple components/flows)
|
||||
- [ ] Stories that can be combined (UX design shows they're tightly coupled)
|
||||
|
||||
### Epic Alignment
|
||||
|
||||
- [ ] **Epic scope still accurate** after UX design
|
||||
- [ ] **New epic needed** for discovered work (if significant)
|
||||
- [ ] **Epic ordering might change** based on UX dependencies
|
||||
|
||||
### Action Items for Epics File Update
|
||||
|
||||
- [ ] **List of new stories to add** to epics.md documented
|
||||
- [ ] **Complexity adjustments noted** for existing stories
|
||||
- [ ] **Update epics.md** OR flag for architecture review first
|
||||
- [ ] **Rationale documented** for why new stories/changes are needed
|
||||
|
||||
**Note:** If significant story changes are identified, consider running architecture workflow BEFORE updating epics.md, since architecture decisions might reveal additional adjustments needed.
|
||||
|
||||
---
|
||||
|
||||
## 15. Decision Rationale
|
||||
|
||||
**Unlike template-driven workflows, this workflow should document WHY**
|
||||
|
||||
- [ ] **Design system choice has rationale** (why this fits the project)
|
||||
- [ ] **Color theme selection has reasoning** (why this emotional impact)
|
||||
- [ ] **Design direction choice explained** (what user liked, how it fits vision)
|
||||
- [ ] **User journey approaches justified** (why this flow pattern)
|
||||
- [ ] **UX pattern decisions have context** (why these patterns for this app)
|
||||
- [ ] **Responsive strategy aligned with user priorities**
|
||||
- [ ] **Accessibility level appropriate for deployment intent**
|
||||
|
||||
---
|
||||
|
||||
## 16. Implementation Readiness
|
||||
|
||||
- [ ] **Designers can create high-fidelity mockups** from this spec
|
||||
- [ ] **Developers can implement** with clear UX guidance
|
||||
- [ ] **Sufficient detail** for frontend development
|
||||
- [ ] **Component specifications actionable** (states, variants, behaviors)
|
||||
- [ ] **Flows implementable** (clear steps, decision logic, error handling)
|
||||
- [ ] **Visual foundation complete** (colors, typography, spacing all defined)
|
||||
- [ ] **Pattern consistency enforceable** (clear rules for implementation)
|
||||
|
||||
---
|
||||
|
||||
## 17. Critical Failures (Auto-Fail)
|
||||
|
||||
- [ ] ❌ **No visual collaboration** (color themes or design mockups not generated)
|
||||
- [ ] ❌ **User not involved in decisions** (auto-generated without collaboration)
|
||||
- [ ] ❌ **No design direction chosen** (missing key visual decisions)
|
||||
- [ ] ❌ **No user journey designs** (critical flows not documented)
|
||||
- [ ] ❌ **No UX pattern consistency rules** (implementation will be inconsistent)
|
||||
- [ ] ❌ **Missing core experience definition** (no clarity on what makes app unique)
|
||||
- [ ] ❌ **No component specifications** (components not actionable)
|
||||
- [ ] ❌ **Responsive strategy missing** (for multi-platform projects)
|
||||
- [ ] ❌ **Accessibility ignored** (no compliance target or requirements)
|
||||
- [ ] ❌ **Generic/templated content** (not specific to this project)
|
||||
|
||||
---
|
||||
|
||||
## Validation Notes
|
||||
|
||||
**Document findings:**
|
||||
|
||||
- UX Design Quality: [Exceptional / Strong / Adequate / Needs Work / Incomplete]
|
||||
- Collaboration Level: [Highly Collaborative / Collaborative / Somewhat Collaborative / Generated]
|
||||
- Visual Artifacts: [Complete & Interactive / Partial / Missing]
|
||||
- Implementation Readiness: [Ready / Needs Design Phase / Not Ready]
|
||||
|
||||
## **Strengths:**
|
||||
|
||||
## **Areas for Improvement:**
|
||||
|
||||
## **Recommended Actions:**
|
||||
|
||||
**Ready for next phase?** [Yes - Proceed to Design / Yes - Proceed to Development / Needs Refinement]
|
||||
|
||||
---
|
||||
|
||||
_This checklist validates collaborative UX design facilitation, not template generation. A successful UX workflow creates design decisions WITH the user through visual exploration and informed choices._
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,145 @@
|
|||
# {{project_name}} UX Design Specification
|
||||
|
||||
_Created on {{date}} by {{user_name}}_
|
||||
_Generated using BMad Method - Create UX Design Workflow v1.0_
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{project_vision}}
|
||||
|
||||
---
|
||||
|
||||
## 1. Design System Foundation
|
||||
|
||||
### 1.1 Design System Choice
|
||||
|
||||
{{design_system_decision}}
|
||||
|
||||
---
|
||||
|
||||
## 2. Core User Experience
|
||||
|
||||
### 2.1 Defining Experience
|
||||
|
||||
{{core_experience}}
|
||||
|
||||
### 2.2 Novel UX Patterns
|
||||
|
||||
{{novel_ux_patterns}}
|
||||
|
||||
---
|
||||
|
||||
## 3. Visual Foundation
|
||||
|
||||
### 3.1 Color System
|
||||
|
||||
{{visual_foundation}}
|
||||
|
||||
**Interactive Visualizations:**
|
||||
|
||||
- Color Theme Explorer: [ux-color-themes.html](./ux-color-themes.html)
|
||||
|
||||
---
|
||||
|
||||
## 4. Design Direction
|
||||
|
||||
### 4.1 Chosen Design Approach
|
||||
|
||||
{{design_direction_decision}}
|
||||
|
||||
**Interactive Mockups:**
|
||||
|
||||
- Design Direction Showcase: [ux-design-directions.html](./ux-design-directions.html)
|
||||
|
||||
---
|
||||
|
||||
## 5. User Journey Flows
|
||||
|
||||
### 5.1 Critical User Paths
|
||||
|
||||
{{user_journey_flows}}
|
||||
|
||||
---
|
||||
|
||||
## 6. Component Library
|
||||
|
||||
### 6.1 Component Strategy
|
||||
|
||||
{{component_library_strategy}}
|
||||
|
||||
---
|
||||
|
||||
## 7. UX Pattern Decisions
|
||||
|
||||
### 7.1 Consistency Rules
|
||||
|
||||
{{ux_pattern_decisions}}
|
||||
|
||||
---
|
||||
|
||||
## 8. Responsive Design & Accessibility
|
||||
|
||||
### 8.1 Responsive Strategy
|
||||
|
||||
{{responsive_accessibility_strategy}}
|
||||
|
||||
---
|
||||
|
||||
## 9. Implementation Guidance
|
||||
|
||||
### 9.1 Completion Summary
|
||||
|
||||
{{completion_summary}}
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### Related Documents
|
||||
|
||||
- Product Requirements: `{{prd_file}}`
|
||||
- Product Brief: `{{brief_file}}`
|
||||
- Brainstorming: `{{brainstorm_file}}`
|
||||
|
||||
### Core Interactive Deliverables
|
||||
|
||||
This UX Design Specification was created through visual collaboration:
|
||||
|
||||
- **Color Theme Visualizer**: {{color_themes_html}}
|
||||
- Interactive HTML showing all color theme options explored
|
||||
- Live UI component examples in each theme
|
||||
- Side-by-side comparison and semantic color usage
|
||||
|
||||
- **Design Direction Mockups**: {{design_directions_html}}
|
||||
- Interactive HTML with 6-8 complete design approaches
|
||||
- Full-screen mockups of key screens
|
||||
- Design philosophy and rationale for each direction
|
||||
|
||||
### Optional Enhancement Deliverables
|
||||
|
||||
_This section will be populated if additional UX artifacts are generated through follow-up workflows._
|
||||
|
||||
<!-- Additional deliverables added here by other workflows -->
|
||||
|
||||
### Next Steps & Follow-Up Workflows
|
||||
|
||||
This UX Design Specification can serve as input to:
|
||||
|
||||
- **Wireframe Generation Workflow** - Create detailed wireframes from user flows
|
||||
- **Figma Design Workflow** - Generate Figma files via MCP integration
|
||||
- **Interactive Prototype Workflow** - Build clickable HTML prototypes
|
||||
- **Component Showcase Workflow** - Create interactive component library
|
||||
- **AI Frontend Prompt Workflow** - Generate prompts for v0, Lovable, Bolt, etc.
|
||||
- **Solution Architecture Workflow** - Define technical architecture with UX context
|
||||
|
||||
### Version History
|
||||
|
||||
| Date | Version | Changes | Author |
|
||||
| -------- | ------- | ------------------------------- | ------------- |
|
||||
| {{date}} | 1.0 | Initial UX Design Specification | {{user_name}} |
|
||||
|
||||
---
|
||||
|
||||
_This UX Design Specification was created through collaborative design facilitation, not template generation. All decisions were made with user input and are documented with rationale._
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
# Create UX Design Workflow Configuration
|
||||
name: create-ux-design
|
||||
description: "Collaborative UX design facilitation workflow that creates exceptional user experiences through visual exploration and informed decision-making. Unlike template-driven approaches, this workflow facilitates discovery, generates visual options, and collaboratively designs the UX with the user at every step."
|
||||
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"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
date: system-generated
|
||||
|
||||
# Input requirements - We work from PRD, Brief, or Brainstorming docs
|
||||
recommended_inputs:
|
||||
- prd: "Product Requirements Document with features and user journeys"
|
||||
- product_brief: "Product brief with vision and target users"
|
||||
- brainstorming: "Brainstorming documents with ideas and concepts"
|
||||
|
||||
# Input file references (fuzzy matched from output folder)
|
||||
prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
|
||||
brief_file: "{output_folder}/product-brief.md or brief.md or project-brief.md"
|
||||
brainstorm_file: "{output_folder}/brainstorming.md or brainstorm.md or ideation.md"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
template: "{installed_path}/ux-design-template.md"
|
||||
|
||||
# Knowledge bases for intelligent UX decisions
|
||||
ux_pattern_catalog: "{installed_path}/ux-pattern-catalog.yaml"
|
||||
color_psychology: "{installed_path}/color-psychology.yaml"
|
||||
layout_patterns: "{installed_path}/layout-patterns.yaml"
|
||||
|
||||
# Output configuration - Progressive saves throughout workflow
|
||||
default_output_file: "{output_folder}/ux-design-specification.md"
|
||||
color_themes_html: "{output_folder}/ux-color-themes.html"
|
||||
design_directions_html: "{output_folder}/ux-design-directions.html"
|
||||
|
||||
# Workflow metadata
|
||||
version: "1.0.0"
|
||||
paradigm: "visual-collaboration-driven"
|
||||
execution_time: "45-120 minutes depending on project complexity and user engagement"
|
||||
features:
|
||||
- "Design system discovery and selection"
|
||||
- "Live HTML color theme visualization"
|
||||
- "6-8 design direction mockup generation"
|
||||
- "Adaptive facilitation by skill level"
|
||||
- "Novel UX pattern design for unique concepts"
|
||||
- "Progressive document building (saves after each step)"
|
||||
- "Visual decision-making with actual mockups"
|
||||
- "WebSearch for current design systems and trends"
|
||||
- "Serves as input to follow-up workflows (wireframes, Figma, prototypes, architecture)"
|
||||
|
|
@ -1,152 +0,0 @@
|
|||
# UX/UI Specification Workflow Validation Checklist
|
||||
|
||||
**Purpose**: Validate UX workflow outputs are complete, actionable, and ready for development.
|
||||
|
||||
**Scope**: Can run standalone or integrated with PRD/GDD workflows
|
||||
|
||||
**Expected Outputs**: ux-specification.md, optional ai-frontend-prompt.md
|
||||
|
||||
---
|
||||
|
||||
## 1. Output File Exists
|
||||
|
||||
- [ ] ux-specification.md created in output folder
|
||||
- [ ] Requirements source identified (PRD, GDD, or gathered requirements)
|
||||
- [ ] No unfilled {{template_variables}}
|
||||
|
||||
---
|
||||
|
||||
## 2. UX Foundation
|
||||
|
||||
### User Personas
|
||||
|
||||
- [ ] **At least one primary persona** defined with goals and pain points
|
||||
- [ ] Personas have sufficient detail to inform design decisions
|
||||
- [ ] If PRD/GDD exists, personas align with target audience
|
||||
|
||||
### Design Principles
|
||||
|
||||
- [ ] **3-5 core design principles** established
|
||||
- [ ] Principles are actionable (guide real design decisions)
|
||||
- [ ] Principles fit project goals and users
|
||||
|
||||
---
|
||||
|
||||
## 3. Information Architecture
|
||||
|
||||
### Site/App Structure
|
||||
|
||||
- [ ] **Complete site map** showing all major sections/screens
|
||||
- [ ] Hierarchical relationships clear
|
||||
- [ ] Navigation paths evident
|
||||
- [ ] Structure makes sense for users
|
||||
|
||||
### Navigation
|
||||
|
||||
- [ ] Primary navigation defined
|
||||
- [ ] Mobile navigation strategy clear (if multi-platform)
|
||||
- [ ] Navigation approach logical
|
||||
|
||||
---
|
||||
|
||||
## 4. User Flows
|
||||
|
||||
- [ ] **At least 2-3 critical user flows** documented
|
||||
- [ ] Flows show complete start-to-finish paths
|
||||
- [ ] Decision points and error states considered
|
||||
- [ ] Flows include Mermaid diagrams or clear descriptions
|
||||
- [ ] If PRD exists, flows align with user journeys
|
||||
|
||||
---
|
||||
|
||||
## 5. Component Library and Visual Design
|
||||
|
||||
### Component Approach
|
||||
|
||||
- [ ] **Design system strategy** defined (existing system, custom, or hybrid)
|
||||
- [ ] If using existing, which one specified
|
||||
- [ ] Core components identified
|
||||
- [ ] Component states documented (default, hover, active, disabled, error)
|
||||
|
||||
### Visual Foundation
|
||||
|
||||
- [ ] **Color palette** defined with semantic meanings
|
||||
- [ ] **Typography** specified (fonts, type scale, usage)
|
||||
- [ ] **Spacing system** documented
|
||||
- [ ] Design choices support usability
|
||||
|
||||
---
|
||||
|
||||
## 6. Responsive and Accessibility
|
||||
|
||||
### Responsive Design
|
||||
|
||||
- [ ] **Breakpoints defined** for target devices
|
||||
- [ ] Adaptation patterns explained (how layouts change)
|
||||
- [ ] Mobile strategy clear (if multi-platform)
|
||||
|
||||
### Accessibility
|
||||
|
||||
- [ ] **Compliance target** specified (WCAG level)
|
||||
- [ ] Key accessibility requirements documented
|
||||
- [ ] Keyboard navigation, screen readers, contrast considered
|
||||
|
||||
---
|
||||
|
||||
## 7. Implementation Readiness
|
||||
|
||||
- [ ] **Next steps** clearly defined
|
||||
- [ ] Design handoff requirements clear
|
||||
- [ ] Developers can implement from this spec
|
||||
- [ ] Sufficient detail for front-end development
|
||||
|
||||
---
|
||||
|
||||
## 8. Integration with Requirements
|
||||
|
||||
**If PRD/GDD exists:**
|
||||
|
||||
- [ ] UX covers all user-facing features from requirements
|
||||
- [ ] User flows align with documented user journeys
|
||||
- [ ] Platform matches PRD/GDD platforms
|
||||
- [ ] No contradictions with requirements
|
||||
|
||||
---
|
||||
|
||||
## 9. AI Frontend Prompt (If Generated)
|
||||
|
||||
**If ai-frontend-prompt.md was created:**
|
||||
|
||||
- [ ] File exists in output folder
|
||||
- [ ] Contains complete UX context (colors, typography, components, flows)
|
||||
- [ ] Formatted for AI tools (v0, Lovable, etc.)
|
||||
- [ ] Includes appropriate warnings about reviewing generated code
|
||||
|
||||
---
|
||||
|
||||
## 10. Critical Failures (Auto-Fail)
|
||||
|
||||
- [ ] ❌ **No user personas** (target users not defined)
|
||||
- [ ] ❌ **No user flows** (critical paths not documented)
|
||||
- [ ] ❌ **No information architecture** (site structure missing)
|
||||
- [ ] ❌ **No component approach** (design system not defined)
|
||||
- [ ] ❌ **No visual foundation** (colors/typography missing)
|
||||
- [ ] ❌ **No responsive strategy** (adaptation not addressed for multi-platform)
|
||||
- [ ] ❌ **Contradicts requirements** (UX fights PRD/GDD if they exist)
|
||||
|
||||
---
|
||||
|
||||
## Validation Notes
|
||||
|
||||
**Document any findings:**
|
||||
|
||||
- UX quality: [Production-ready / Good foundation / Needs refinement / Incomplete]
|
||||
- Strengths:
|
||||
- Issues to address:
|
||||
- Recommended actions:
|
||||
|
||||
**Ready for development?** [Yes / Needs design phase / No - explain]
|
||||
|
||||
---
|
||||
|
||||
_Adapt based on whether this is standalone or integrated, and platform requirements._
|
||||
|
|
@ -1,405 +0,0 @@
|
|||
# UX/UI Specification Workflow Instructions
|
||||
|
||||
<workflow>
|
||||
|
||||
<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} and language MUST be tailored to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
<critical>This workflow creates comprehensive UX/UI specifications - can run standalone or as part of plan-project</critical>
|
||||
<critical>Uses ux-spec-template.md for structured output generation</critical>
|
||||
<critical>Can optionally generate AI Frontend Prompts for tools like Vercel v0, Lovable.ai</critical>
|
||||
|
||||
<critical>DOCUMENT OUTPUT: Professional, precise, actionable UX specs. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
|
||||
|
||||
<step n="0" goal="Check for workflow status">
|
||||
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: init-check</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="status_exists == true">
|
||||
<action>Store {{status_file_path}} for later updates</action>
|
||||
<action>Set tracking_mode = true</action>
|
||||
</check>
|
||||
|
||||
<check if="status_exists == false">
|
||||
<action>Set tracking_mode = false</action>
|
||||
<output>Note: Running without workflow tracking. Run `workflow-init` to enable progress tracking.</output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Load context and analyze project requirements">
|
||||
|
||||
<action>Determine workflow mode (standalone or integrated)</action>
|
||||
|
||||
<check if="mode is standalone">
|
||||
<ask>Do you have an existing PRD or requirements document? (y/n)
|
||||
|
||||
If yes: Provide the path to the PRD
|
||||
If no: We'll gather basic requirements to create the UX spec
|
||||
</ask>
|
||||
</check>
|
||||
|
||||
<check if="no PRD in standalone mode">
|
||||
<ask>Let's gather essential information:
|
||||
|
||||
1. **Project Description**: What are you building?
|
||||
2. **Target Users**: Who will use this?
|
||||
3. **Core Features**: What are the main capabilities? (3-5 key features)
|
||||
4. **Platform**: Web, mobile, desktop, or multi-platform?
|
||||
5. **Existing Brand/Design**: Any existing style guide or brand to follow?
|
||||
</ask>
|
||||
</check>
|
||||
|
||||
<check if="PRD exists or integrated mode">
|
||||
<action>Load the following documents if available:</action>
|
||||
|
||||
- PRD.md (primary source for requirements and user journeys)
|
||||
- epics.md (helps understand feature grouping)
|
||||
- tech-spec.md (understand technical constraints)
|
||||
- architecture.md (if Level 3-4 project)
|
||||
- bmm-workflow-status.md (understand project level and scope)
|
||||
|
||||
</check>
|
||||
|
||||
<action>Analyze project for UX complexity:</action>
|
||||
|
||||
- Number of user-facing features
|
||||
- Types of users/personas mentioned
|
||||
- Interaction complexity
|
||||
- Platform requirements (web, mobile, desktop)
|
||||
|
||||
<action>Load ux-spec-template from workflow.yaml</action>
|
||||
|
||||
<template-output>project_context</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Define UX goals and principles">
|
||||
|
||||
<ask>Let's establish the UX foundation. Based on the PRD:
|
||||
|
||||
**1. Target User Personas** (extract from PRD or define):
|
||||
|
||||
- Primary persona(s)
|
||||
- Secondary persona(s)
|
||||
- Their goals and pain points
|
||||
|
||||
**2. Key Usability Goals:**
|
||||
What does success look like for users?
|
||||
|
||||
- Ease of learning?
|
||||
- Efficiency for power users?
|
||||
- Error prevention?
|
||||
- Accessibility requirements?
|
||||
|
||||
**3. Core Design Principles** (3-5 principles):
|
||||
What will guide all design decisions?
|
||||
</ask>
|
||||
|
||||
<template-output>user_personas</template-output>
|
||||
<template-output>usability_goals</template-output>
|
||||
<template-output>design_principles</template-output>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Create information architecture">
|
||||
|
||||
<action>Based on functional requirements from PRD, create site/app structure</action>
|
||||
|
||||
**Create comprehensive site map showing:**
|
||||
|
||||
- All major sections/screens
|
||||
- Hierarchical relationships
|
||||
- Navigation paths
|
||||
|
||||
<template-output>site_map</template-output>
|
||||
|
||||
**Define navigation structure:**
|
||||
|
||||
- Primary navigation items
|
||||
- Secondary navigation approach
|
||||
- Mobile navigation strategy
|
||||
- Breadcrumb structure
|
||||
|
||||
<template-output>navigation_structure</template-output>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Design user flows for critical paths">
|
||||
|
||||
<action>Extract key user journeys from PRD</action>
|
||||
<action>For each critical user task, create detailed flow</action>
|
||||
|
||||
<for-each journey="user_journeys_from_prd">
|
||||
|
||||
**Flow: {{journey_name}}**
|
||||
|
||||
Define:
|
||||
|
||||
- User goal
|
||||
- Entry points
|
||||
- Step-by-step flow with decision points
|
||||
- Success criteria
|
||||
- Error states and edge cases
|
||||
|
||||
Create Mermaid diagram showing complete flow.
|
||||
|
||||
<template-output>user*flow*{{journey_number}}</template-output>
|
||||
|
||||
</for-each>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Define component library approach">
|
||||
|
||||
<ask>Component Library Strategy:
|
||||
|
||||
**1. Design System Approach:**
|
||||
|
||||
- [ ] Use existing system (Material UI, Ant Design, etc.)
|
||||
- [ ] Create custom component library
|
||||
- [ ] Hybrid approach
|
||||
|
||||
**2. If using existing, which one?**
|
||||
|
||||
**3. Core Components Needed** (based on PRD features):
|
||||
We'll need to define states and variants for key components.
|
||||
</ask>
|
||||
|
||||
<action>For primary components, define:</action>
|
||||
|
||||
- Component purpose
|
||||
- Variants needed
|
||||
- States (default, hover, active, disabled, error)
|
||||
- Usage guidelines
|
||||
|
||||
<template-output>design_system_approach</template-output>
|
||||
<template-output>core_components</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Establish visual design foundation">
|
||||
|
||||
<ask>Visual Design Foundation:
|
||||
|
||||
**1. Brand Guidelines:**
|
||||
Do you have existing brand guidelines to follow? (y/n)
|
||||
|
||||
**2. If yes, provide link or key elements.**
|
||||
|
||||
**3. If no, let's define basics:**
|
||||
|
||||
- Primary brand personality (professional, playful, minimal, bold)
|
||||
- Industry conventions to follow or break
|
||||
</ask>
|
||||
|
||||
<action>Define color palette with semantic meanings</action>
|
||||
|
||||
<template-output>color_palette</template-output>
|
||||
|
||||
<action>Define typography system</action>
|
||||
|
||||
<template-output>font_families</template-output>
|
||||
<template-output>type_scale</template-output>
|
||||
|
||||
<action>Define spacing and layout grid</action>
|
||||
|
||||
<template-output>spacing_layout</template-output>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Define responsive and accessibility strategy">
|
||||
|
||||
**Responsive Design:**
|
||||
|
||||
<action>Define breakpoints based on target devices from PRD</action>
|
||||
|
||||
<template-output>breakpoints</template-output>
|
||||
|
||||
<action>Define adaptation patterns for different screen sizes</action>
|
||||
|
||||
<template-output>adaptation_patterns</template-output>
|
||||
|
||||
**Accessibility Requirements:**
|
||||
|
||||
<action>Based on deployment intent from PRD, define compliance level</action>
|
||||
|
||||
<template-output>compliance_target</template-output>
|
||||
<template-output>accessibility_requirements</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Document interaction patterns" optional="true">
|
||||
|
||||
<ask>Would you like to define animation and micro-interactions? (y/n)
|
||||
|
||||
This is recommended for:
|
||||
|
||||
- Consumer-facing applications
|
||||
- Projects emphasizing user delight
|
||||
- Complex state transitions
|
||||
</ask>
|
||||
|
||||
<check if="yes or fuzzy match the user wants to define animation or micro interactions">
|
||||
|
||||
<action>Define motion principles</action>
|
||||
<template-output>motion_principles</template-output>
|
||||
|
||||
<action>Define key animations and transitions</action>
|
||||
<template-output>key_animations</template-output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Create wireframes and design references" optional="true">
|
||||
|
||||
<ask>Design File Strategy:
|
||||
|
||||
**1. Will you be creating high-fidelity designs?**
|
||||
|
||||
- Yes, in Figma
|
||||
- Yes, in Sketch
|
||||
- Yes, in Adobe XD
|
||||
- No, development from spec
|
||||
- Other (describe)
|
||||
|
||||
**2. For key screens, should we:**
|
||||
|
||||
- Reference design file locations
|
||||
- Create low-fi wireframe descriptions
|
||||
- Skip visual representations
|
||||
</ask>
|
||||
|
||||
<template-output if="design files will be created">design_files</template-output>
|
||||
|
||||
<check if="wireframe descriptions needed">
|
||||
<for-each screen="key_screens">
|
||||
<template-output>screen*layout*{{screen_number}}</template-output>
|
||||
</for-each>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Generate next steps and output options">
|
||||
|
||||
## UX Specification Complete
|
||||
|
||||
<action>Generate specific next steps based on project level and outputs</action>
|
||||
|
||||
<template-output>immediate_actions</template-output>
|
||||
|
||||
**Design Handoff Checklist:**
|
||||
|
||||
- [ ] All user flows documented
|
||||
- [ ] Component inventory complete
|
||||
- [ ] Accessibility requirements defined
|
||||
- [ ] Responsive strategy clear
|
||||
- [ ] Brand guidelines incorporated
|
||||
- [ ] Performance goals established
|
||||
|
||||
<check if="Level 3-4 project">
|
||||
- [ ] Ready for detailed visual design
|
||||
- [ ] Frontend architecture can proceed
|
||||
- [ ] Story generation can include UX details
|
||||
</check>
|
||||
|
||||
<check if="Level 1-2 project or standalone">
|
||||
- [ ] Development can proceed with spec
|
||||
- [ ] Component implementation order defined
|
||||
- [ ] MVP scope clear
|
||||
|
||||
</check>
|
||||
|
||||
<template-output>design_handoff_checklist</template-output>
|
||||
|
||||
<ask>**✅ UX Specification Complete, {user_name}!**
|
||||
|
||||
UX Specification saved to {{ux_spec_file}}
|
||||
|
||||
**Additional Output Options:**
|
||||
|
||||
1. Generate AI Frontend Prompt (for Vercel v0, Lovable.ai, etc.)
|
||||
2. Review UX specification
|
||||
3. Create/update visual designs in design tool
|
||||
4. Return to planning workflow (if not standalone)
|
||||
5. Exit
|
||||
|
||||
Would you like to generate an AI Frontend Prompt? (y/n):</ask>
|
||||
|
||||
<check if="user selects yes or option 1">
|
||||
<goto step="11">Generate AI Frontend Prompt</goto>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Generate AI Frontend Prompt" optional="true">
|
||||
|
||||
<action>Prepare context for AI Frontend Prompt generation</action>
|
||||
|
||||
<ask>What type of AI frontend generation are you targeting?
|
||||
|
||||
1. **Full application** - Complete multi-page application
|
||||
2. **Single page** - One complete page/screen
|
||||
3. **Component set** - Specific components or sections
|
||||
4. **Design system** - Component library setup
|
||||
|
||||
Select option (1-4):</ask>
|
||||
|
||||
<action>Gather UX spec details for prompt generation:</action>
|
||||
|
||||
- Design system approach
|
||||
- Color palette and typography
|
||||
- Key components and their states
|
||||
- User flows to implement
|
||||
- Responsive requirements
|
||||
|
||||
<invoke-task>{project-root}/bmad/bmm/tasks/ai-fe-prompt.md</invoke-task>
|
||||
|
||||
<action>Save AI Frontend Prompt to {{ai_frontend_prompt_file}}</action>
|
||||
|
||||
<ask>AI Frontend Prompt saved to {{ai_frontend_prompt_file}}
|
||||
|
||||
This prompt is optimized for:
|
||||
|
||||
- Vercel v0
|
||||
- Lovable.ai
|
||||
- Other AI frontend generation tools
|
||||
|
||||
**Remember**: AI-generated code requires careful review and testing!
|
||||
|
||||
Next actions:
|
||||
|
||||
1. Copy prompt to AI tool
|
||||
2. Return to UX specification
|
||||
3. Exit workflow
|
||||
|
||||
Select option (1-3):</ask>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="12" goal="Update status if tracking enabled">
|
||||
|
||||
<check if="tracking_mode == true">
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: update</param>
|
||||
<param>action: complete_workflow</param>
|
||||
<param>workflow_name: ux</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="success == true">
|
||||
<output>✅ Status updated! Next: {{next_workflow}}</output>
|
||||
</check>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
|
@ -1,162 +0,0 @@
|
|||
# {{project_name}} UX/UI Specification
|
||||
|
||||
_Generated on {{date}} by {{user_name}}_
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{project_context}}
|
||||
|
||||
---
|
||||
|
||||
## 1. UX Goals and Principles
|
||||
|
||||
### 1.1 Target User Personas
|
||||
|
||||
{{user_personas}}
|
||||
|
||||
### 1.2 Usability Goals
|
||||
|
||||
{{usability_goals}}
|
||||
|
||||
### 1.3 Design Principles
|
||||
|
||||
{{design_principles}}
|
||||
|
||||
---
|
||||
|
||||
## 2. Information Architecture
|
||||
|
||||
### 2.1 Site Map
|
||||
|
||||
{{site_map}}
|
||||
|
||||
### 2.2 Navigation Structure
|
||||
|
||||
{{navigation_structure}}
|
||||
|
||||
---
|
||||
|
||||
## 3. User Flows
|
||||
|
||||
{{user_flow_1}}
|
||||
|
||||
{{user_flow_2}}
|
||||
|
||||
{{user_flow_3}}
|
||||
|
||||
{{user_flow_4}}
|
||||
|
||||
{{user_flow_5}}
|
||||
|
||||
---
|
||||
|
||||
## 4. Component Library and Design System
|
||||
|
||||
### 4.1 Design System Approach
|
||||
|
||||
{{design_system_approach}}
|
||||
|
||||
### 4.2 Core Components
|
||||
|
||||
{{core_components}}
|
||||
|
||||
---
|
||||
|
||||
## 5. Visual Design Foundation
|
||||
|
||||
### 5.1 Color Palette
|
||||
|
||||
{{color_palette}}
|
||||
|
||||
### 5.2 Typography
|
||||
|
||||
**Font Families:**
|
||||
{{font_families}}
|
||||
|
||||
**Type Scale:**
|
||||
{{type_scale}}
|
||||
|
||||
### 5.3 Spacing and Layout
|
||||
|
||||
{{spacing_layout}}
|
||||
|
||||
---
|
||||
|
||||
## 6. Responsive Design
|
||||
|
||||
### 6.1 Breakpoints
|
||||
|
||||
{{breakpoints}}
|
||||
|
||||
### 6.2 Adaptation Patterns
|
||||
|
||||
{{adaptation_patterns}}
|
||||
|
||||
---
|
||||
|
||||
## 7. Accessibility
|
||||
|
||||
### 7.1 Compliance Target
|
||||
|
||||
{{compliance_target}}
|
||||
|
||||
### 7.2 Key Requirements
|
||||
|
||||
{{accessibility_requirements}}
|
||||
|
||||
---
|
||||
|
||||
## 8. Interaction and Motion
|
||||
|
||||
### 8.1 Motion Principles
|
||||
|
||||
{{motion_principles}}
|
||||
|
||||
### 8.2 Key Animations
|
||||
|
||||
{{key_animations}}
|
||||
|
||||
---
|
||||
|
||||
## 9. Design Files and Wireframes
|
||||
|
||||
### 9.1 Design Files
|
||||
|
||||
{{design_files}}
|
||||
|
||||
### 9.2 Key Screen Layouts
|
||||
|
||||
{{screen_layout_1}}
|
||||
|
||||
{{screen_layout_2}}
|
||||
|
||||
{{screen_layout_3}}
|
||||
|
||||
---
|
||||
|
||||
## 10. Next Steps
|
||||
|
||||
### 10.1 Immediate Actions
|
||||
|
||||
{{immediate_actions}}
|
||||
|
||||
### 10.2 Design Handoff Checklist
|
||||
|
||||
{{design_handoff_checklist}}
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### Related Documents
|
||||
|
||||
- PRD: `{{prd}}`
|
||||
- Epics: `{{epics}}`
|
||||
- Tech Spec: `{{tech_spec}}`
|
||||
- Architecture: `{{architecture}}`
|
||||
|
||||
### Version History
|
||||
|
||||
| Date | Version | Changes | Author |
|
||||
| -------- | ------- | --------------------- | ------------- |
|
||||
| {{date}} | 1.0 | Initial specification | {{user_name}} |
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
# UX/UI Specification Workflow
|
||||
name: ux-spec
|
||||
description: "UX/UI specification workflow for defining user experience and interface design. Creates comprehensive UX documentation including wireframes, user flows, component specifications, and design system guidelines."
|
||||
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"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/ux"
|
||||
instructions: "{installed_path}/instructions-ux.md"
|
||||
template: "{installed_path}/ux-spec-template.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/ux-specification.md"
|
||||
ai_frontend_prompt_file: "{output_folder}/ai-frontend-prompt.md"
|
||||
|
||||
# Recommended input documents
|
||||
recommended_inputs:
|
||||
- prd: "{output_folder}/PRD.md"
|
||||
- product_brief: "{output_folder}/product-brief.md"
|
||||
- gdd: "{output_folder}/GDD.md"
|
||||
|
||||
web_bundle:
|
||||
name: "ux-spec"
|
||||
description: "UX/UI specification workflow for defining user experience and interface design. Creates comprehensive UX documentation including wireframes, user flows, component specifications, and design system guidelines."
|
||||
author: "BMad"
|
||||
instructions: "bmad/bmm/workflows/2-plan-workflows/ux/instructions-ux.md"
|
||||
web_bundle_files:
|
||||
- "bmad/bmm/workflows/2-plan-workflows/ux/instructions-ux.md"
|
||||
- "bmad/bmm/workflows/2-plan-workflows/ux/ux-spec-template.md"
|
||||
|
|
@ -1,49 +1,67 @@
|
|||
# Decision Architecture Validation Checklist
|
||||
# Architecture Document Validation Checklist
|
||||
|
||||
## Critical Requirements (MUST PASS)
|
||||
**Purpose**: Validate the architecture document itself is complete, implementable, and provides clear guidance for AI agents.
|
||||
|
||||
### Decision Completeness
|
||||
**Note**: This checklist validates the ARCHITECTURE DOCUMENT only. For cross-workflow validation (PRD → Architecture → Stories alignment), use the solutioning-gate-check workflow.
|
||||
|
||||
- [ ] Every functional requirement from PRD has architectural support
|
||||
- [ ] Every non-functional requirement from PRD is addressed
|
||||
- [ ] All critical decision categories have been resolved
|
||||
---
|
||||
|
||||
## 1. Decision Completeness
|
||||
|
||||
### All Decisions Made
|
||||
|
||||
- [ ] Every critical decision category has been resolved
|
||||
- [ ] All important decision categories addressed
|
||||
- [ ] No placeholder text like "TBD", "[choose]", or "{TODO}" remains
|
||||
- [ ] Optional decisions either resolved or explicitly deferred with rationale
|
||||
|
||||
### Version Specificity
|
||||
### Decision Coverage
|
||||
|
||||
- [ ] Data persistence approach decided
|
||||
- [ ] API pattern chosen
|
||||
- [ ] Authentication/authorization strategy defined
|
||||
- [ ] Deployment target selected
|
||||
- [ ] All functional requirements have architectural support
|
||||
|
||||
---
|
||||
|
||||
## 2. Version Specificity
|
||||
|
||||
### Technology Versions
|
||||
|
||||
- [ ] Every technology choice includes a specific version number
|
||||
- [ ] Version numbers are current (verified via WebSearch, not hardcoded)
|
||||
- [ ] Compatible versions selected (e.g., Node.js version supports chosen packages)
|
||||
- [ ] Verification dates noted for version checks
|
||||
|
||||
### Starter Template Integration (if applicable)
|
||||
### Version Verification Process
|
||||
|
||||
- [ ] WebSearch used during workflow to verify current versions
|
||||
- [ ] No hardcoded versions from decision catalog trusted without verification
|
||||
- [ ] LTS vs. latest versions considered and documented
|
||||
- [ ] Breaking changes between versions noted if relevant
|
||||
|
||||
---
|
||||
|
||||
## 3. Starter Template Integration (if applicable)
|
||||
|
||||
### Template Selection
|
||||
|
||||
- [ ] Starter template chosen (or "from scratch" decision documented)
|
||||
- [ ] Project initialization command documented with exact flags
|
||||
- [ ] Starter-provided decisions marked as "PROVIDED BY STARTER"
|
||||
- [ ] First implementation story references starter initialization
|
||||
- [ ] Starter template version is current and specified
|
||||
- [ ] Command search term provided for verification
|
||||
|
||||
### Epic Coverage
|
||||
### Starter-Provided Decisions
|
||||
|
||||
- [ ] Every epic from PRD is explicitly mapped to architectural components
|
||||
- [ ] Decision summary table shows which epics each decision affects
|
||||
- [ ] No orphan epics without architectural support
|
||||
- [ ] Novel patterns mapped to affected epics
|
||||
- [ ] Decisions provided by starter marked as "PROVIDED BY STARTER"
|
||||
- [ ] List of what starter provides is complete
|
||||
- [ ] Remaining decisions (not covered by starter) clearly identified
|
||||
- [ ] No duplicate decisions that starter already makes
|
||||
|
||||
### Document Structure
|
||||
---
|
||||
|
||||
- [ ] Executive summary is present and concise (2-3 sentences maximum)
|
||||
- [ ] Project initialization section present (if using starter template)
|
||||
- [ ] Decision summary table has ALL required columns:
|
||||
- Category
|
||||
- Decision
|
||||
- Version
|
||||
- Affects Epics
|
||||
- Rationale
|
||||
- [ ] Project structure section shows complete source tree
|
||||
- [ ] Source tree reflects actual technology decisions (not generic)
|
||||
|
||||
## Novel Pattern Design (if applicable)
|
||||
## 4. Novel Pattern Design (if applicable)
|
||||
|
||||
### Pattern Detection
|
||||
|
||||
|
|
@ -51,16 +69,25 @@
|
|||
- [ ] Patterns that don't have standard solutions documented
|
||||
- [ ] Multi-epic workflows requiring custom design captured
|
||||
|
||||
### Pattern Documentation
|
||||
### Pattern Documentation Quality
|
||||
|
||||
- [ ] Pattern name and purpose clearly defined
|
||||
- [ ] Component interactions specified
|
||||
- [ ] Data flow documented (with sequence diagrams if complex)
|
||||
- [ ] Implementation guide provided for agents
|
||||
- [ ] Affected epics listed
|
||||
- [ ] Edge cases and failure modes considered
|
||||
- [ ] States and transitions clearly defined
|
||||
|
||||
## Implementation Patterns
|
||||
### Pattern Implementability
|
||||
|
||||
- [ ] Pattern is implementable by AI agents with provided guidance
|
||||
- [ ] No ambiguous decisions that could be interpreted differently
|
||||
- [ ] Clear boundaries between components
|
||||
- [ ] Explicit integration points with standard patterns
|
||||
|
||||
---
|
||||
|
||||
## 5. Implementation Patterns
|
||||
|
||||
### Pattern Categories Coverage
|
||||
|
||||
|
|
@ -78,10 +105,13 @@
|
|||
- [ ] Conventions are unambiguous (agents can't interpret differently)
|
||||
- [ ] Patterns cover all technologies in the stack
|
||||
- [ ] No gaps where agents would have to guess
|
||||
- [ ] Implementation patterns don't conflict with each other
|
||||
|
||||
## Consistency Validation
|
||||
---
|
||||
|
||||
### Technology Compatibility
|
||||
## 6. Technology Compatibility
|
||||
|
||||
### Stack Coherence
|
||||
|
||||
- [ ] Database choice compatible with ORM choice
|
||||
- [ ] Frontend framework compatible with deployment target
|
||||
|
|
@ -89,31 +119,65 @@
|
|||
- [ ] All API patterns consistent (not mixing REST and GraphQL for same data)
|
||||
- [ ] Starter template compatible with additional choices
|
||||
|
||||
### Pattern Consistency
|
||||
### Integration Compatibility
|
||||
|
||||
- [ ] Single source of truth for each data type
|
||||
- [ ] Consistent error handling approach across components
|
||||
- [ ] Uniform authentication/authorization pattern
|
||||
- [ ] Implementation patterns don't conflict with each other
|
||||
- [ ] Third-party services compatible with chosen stack
|
||||
- [ ] Real-time solutions (if any) work with deployment target
|
||||
- [ ] File storage solution integrates with framework
|
||||
- [ ] Background job system compatible with infrastructure
|
||||
|
||||
### AI Agent Clarity
|
||||
---
|
||||
|
||||
## 7. Document Structure
|
||||
|
||||
### Required Sections Present
|
||||
|
||||
- [ ] Executive summary exists (2-3 sentences maximum)
|
||||
- [ ] Project initialization section (if using starter template)
|
||||
- [ ] Decision summary table with ALL required columns:
|
||||
- Category
|
||||
- Decision
|
||||
- Version
|
||||
- Rationale
|
||||
- [ ] Project structure section shows complete source tree
|
||||
- [ ] Implementation patterns section comprehensive
|
||||
- [ ] Novel patterns section (if applicable)
|
||||
|
||||
### Document Quality
|
||||
|
||||
- [ ] Source tree reflects actual technology decisions (not generic)
|
||||
- [ ] Technical language used consistently
|
||||
- [ ] Tables used instead of prose where appropriate
|
||||
- [ ] No unnecessary explanations or justifications
|
||||
- [ ] Focused on WHAT and HOW, not WHY (rationale is brief)
|
||||
|
||||
---
|
||||
|
||||
## 8. AI Agent Clarity
|
||||
|
||||
### Clear Guidance for Agents
|
||||
|
||||
- [ ] No ambiguous decisions that agents could interpret differently
|
||||
- [ ] Clear boundaries between components/modules
|
||||
- [ ] Explicit file organization patterns
|
||||
- [ ] Defined patterns for common operations (CRUD, auth checks, etc.)
|
||||
- [ ] Novel patterns have clear implementation guidance
|
||||
- [ ] Document provides clear constraints for agents
|
||||
- [ ] No conflicting guidance present
|
||||
|
||||
## Quality Checks
|
||||
### Implementation Readiness
|
||||
|
||||
### Documentation Quality
|
||||
- [ ] Sufficient detail for agents to implement without guessing
|
||||
- [ ] File paths and naming conventions explicit
|
||||
- [ ] Integration points clearly defined
|
||||
- [ ] Error handling patterns specified
|
||||
- [ ] Testing patterns documented
|
||||
|
||||
- [ ] Technical language used consistently
|
||||
- [ ] Tables used instead of prose where appropriate
|
||||
- [ ] No unnecessary explanations or justifications
|
||||
- [ ] Focused on WHAT and HOW, not WHY (rationale is brief)
|
||||
---
|
||||
|
||||
### Practical Implementation
|
||||
## 9. Practical Considerations
|
||||
|
||||
### Technology Viability
|
||||
|
||||
- [ ] Chosen stack has good documentation and community support
|
||||
- [ ] Development environment can be set up with specified versions
|
||||
|
|
@ -121,118 +185,21 @@
|
|||
- [ ] Deployment target supports all chosen technologies
|
||||
- [ ] Starter template (if used) is stable and well-maintained
|
||||
|
||||
### Scalability Considerations
|
||||
### Scalability
|
||||
|
||||
- [ ] Architecture can handle expected user load from PRD
|
||||
- [ ] Architecture can handle expected user load
|
||||
- [ ] Data model supports expected growth
|
||||
- [ ] Caching strategy defined if performance is critical
|
||||
- [ ] Background job processing defined if async work needed
|
||||
- [ ] Novel patterns scalable for production use
|
||||
|
||||
## Completeness by Section
|
||||
---
|
||||
|
||||
### Executive Summary
|
||||
|
||||
- [ ] States what is being built in one sentence
|
||||
- [ ] Identifies primary architectural pattern
|
||||
- [ ] Notes any unique or critical decisions
|
||||
|
||||
### Project Initialization (if using starter)
|
||||
|
||||
- [ ] Exact command with all flags documented
|
||||
- [ ] Lists what the starter provides
|
||||
- [ ] Notes what decisions remain to be made
|
||||
|
||||
### Decision Summary Table
|
||||
|
||||
- [ ] Contains all major technology decisions
|
||||
- [ ] Each row has complete information
|
||||
- [ ] Versions are specific and current
|
||||
- [ ] Rationales are brief but clear
|
||||
- [ ] Epic mapping is specific (epic IDs, not descriptions)
|
||||
- [ ] Starter-provided decisions marked appropriately
|
||||
|
||||
### Project Structure
|
||||
|
||||
- [ ] Shows actual directory structure
|
||||
- [ ] Follows conventions of chosen framework/starter
|
||||
- [ ] Maps epics to directories
|
||||
- [ ] Includes configuration files
|
||||
- [ ] Reflects starter template structure (if applicable)
|
||||
|
||||
### Novel Pattern Designs (if present)
|
||||
|
||||
- [ ] Each pattern fully documented
|
||||
- [ ] Component interactions clear
|
||||
- [ ] Implementation guidance specific
|
||||
- [ ] Integration with standard patterns defined
|
||||
|
||||
### Implementation Patterns
|
||||
|
||||
- [ ] All 7 pattern categories addressed
|
||||
- [ ] Examples provided for each pattern
|
||||
- [ ] No ambiguity in conventions
|
||||
- [ ] Covers all potential agent decision points
|
||||
|
||||
### Integration Points
|
||||
|
||||
- [ ] External service integrations documented
|
||||
- [ ] API contracts or patterns defined
|
||||
- [ ] Authentication flow specified
|
||||
- [ ] Data flow between components clear
|
||||
- [ ] Novel patterns integrated properly
|
||||
|
||||
### Consistency Rules
|
||||
|
||||
- [ ] Naming conventions specified with examples
|
||||
- [ ] Code organization patterns defined
|
||||
- [ ] Error handling approach documented
|
||||
- [ ] Logging strategy defined
|
||||
- [ ] All implementation patterns included
|
||||
|
||||
## Final Validation
|
||||
|
||||
### Ready for Implementation
|
||||
|
||||
- [ ] An AI agent could start implementing any epic with this document
|
||||
- [ ] First story can initialize project (if using starter)
|
||||
- [ ] No critical decisions left undefined
|
||||
- [ ] No conflicting guidance present
|
||||
- [ ] Document provides clear constraints for agents
|
||||
- [ ] Novel patterns implementable by agents
|
||||
|
||||
### PRD Alignment
|
||||
|
||||
- [ ] All must-have features architecturally supported
|
||||
- [ ] Performance requirements achievable with chosen stack
|
||||
- [ ] Security requirements addressed
|
||||
- [ ] Compliance requirements (if any) met by architecture
|
||||
- [ ] Novel concepts from PRD have architectural solutions
|
||||
|
||||
### UX Specification Alignment (if applicable)
|
||||
|
||||
- [ ] UI component library supports required interaction patterns
|
||||
- [ ] Animation/transition requirements achievable with chosen stack
|
||||
- [ ] Accessibility standards (WCAG level) met by component choices
|
||||
- [ ] Responsive design approach supports all specified breakpoints
|
||||
- [ ] Real-time update requirements addressed in architecture
|
||||
- [ ] Offline capability architecture defined (if required)
|
||||
- [ ] Performance targets from UX spec achievable
|
||||
- [ ] Platform-specific UI requirements supported
|
||||
|
||||
### Risk Mitigation
|
||||
|
||||
- [ ] Single points of failure identified and addressed
|
||||
- [ ] Backup and recovery approach defined (if critical)
|
||||
- [ ] Monitoring and observability approach included
|
||||
- [ ] Rollback strategy considered for deployments
|
||||
- [ ] Novel patterns don't introduce unmanageable risks
|
||||
|
||||
## Common Issues to Check
|
||||
## 10. Common Issues to Check
|
||||
|
||||
### Beginner Protection
|
||||
|
||||
- [ ] Not overengineered for the actual requirements
|
||||
- [ ] Not overengineered for actual requirements
|
||||
- [ ] Standard patterns used where possible (starter templates leveraged)
|
||||
- [ ] Complex technologies justified by specific needs
|
||||
- [ ] Maintenance complexity appropriate for team size
|
||||
|
|
@ -245,17 +212,33 @@
|
|||
- [ ] Future migration paths not blocked
|
||||
- [ ] Novel patterns follow architectural principles
|
||||
|
||||
### Document Usability
|
||||
---
|
||||
|
||||
- [ ] Can be consumed by AI agents without human interpretation
|
||||
- [ ] Provides sufficient detail for consistent implementation
|
||||
- [ ] Free from internal contradictions
|
||||
- [ ] Complete enough to prevent agent "creativity" in critical areas
|
||||
- [ ] Implementation patterns leave no room for conflicting interpretations
|
||||
## Validation Summary
|
||||
|
||||
## Version Verification
|
||||
### Document Quality Score
|
||||
|
||||
- [ ] All versions verified to be current (not relying on potentially outdated catalogs)
|
||||
- [ ] WebSearch used to verify versions during workflow execution
|
||||
- [ ] No hardcoded versions from knowledge bases trusted without verification
|
||||
- [ ] Starter template version checked for latest
|
||||
- Architecture Completeness: [Complete / Mostly Complete / Partial / Incomplete]
|
||||
- Version Specificity: [All Verified / Most Verified / Some Missing / Many Missing]
|
||||
- Pattern Clarity: [Crystal Clear / Clear / Somewhat Ambiguous / Ambiguous]
|
||||
- AI Agent Readiness: [Ready / Mostly Ready / Needs Work / Not Ready]
|
||||
|
||||
### Critical Issues Found
|
||||
|
||||
- [ ] Issue 1: **\*\***\_\_\_**\*\***
|
||||
- [ ] Issue 2: **\*\***\_\_\_**\*\***
|
||||
- [ ] Issue 3: **\*\***\_\_\_**\*\***
|
||||
|
||||
### Recommended Actions Before Implementation
|
||||
|
||||
1. ***
|
||||
2. ***
|
||||
3. ***
|
||||
|
||||
---
|
||||
|
||||
**Next Step**: Run the **solutioning-gate-check** workflow to validate alignment between PRD, Architecture, and Stories before beginning implementation.
|
||||
|
||||
---
|
||||
|
||||
_This checklist validates architecture document quality only. Use solutioning-gate-check for comprehensive readiness validation._
|
||||
|
|
|
|||
|
|
@ -1,19 +1,8 @@
|
|||
# Decision Catalog - Knowledge base for architectural decisions
|
||||
# This replaces rigid project-type templates with intelligent, composable decisions
|
||||
|
||||
# ⚠️ CRITICAL WARNING ABOUT VERSIONS ⚠️
|
||||
# =====================================
|
||||
# Version numbers in this file are EXAMPLES ONLY and will become outdated!
|
||||
# The workflow MUST use WebSearch to verify current versions during execution.
|
||||
# Decision Catalog - Composability knowledge for architectural decisions
|
||||
# This provides RELATIONSHIPS and WORKFLOW LOGIC, not generic tech knowledge
|
||||
#
|
||||
# During facilitation, the AI should:
|
||||
# 1. Use this file for patterns and relationships
|
||||
# 2. Search for "{{technology}} latest stable version 2024" (or current year)
|
||||
# 3. Present the current version found, not the version in this file
|
||||
# 4. Document the verified current version in the architecture
|
||||
#
|
||||
# Versions listed here are for understanding compatibility relationships only.
|
||||
# NEVER trust these version numbers - ALWAYS verify current versions!
|
||||
# ⚠️ CRITICAL: All version/feature info MUST be verified via WebSearch during workflow
|
||||
# This file only provides: triggers, relationships (pairs_with), and opinionated stacks
|
||||
|
||||
decision_categories:
|
||||
data_persistence:
|
||||
|
|
@ -22,57 +11,15 @@ decision_categories:
|
|||
affects: "most epics"
|
||||
options:
|
||||
postgresql:
|
||||
name: "PostgreSQL"
|
||||
current_version: "15.4"
|
||||
lts_version: "14.9"
|
||||
good_for: ["relational data", "complex queries", "ACID compliance", "JSON support"]
|
||||
not_ideal_for: ["massive scale writes", "unstructured data"]
|
||||
pairs_with:
|
||||
- "Prisma ORM 5.6"
|
||||
- "TypeORM 0.3"
|
||||
- "Drizzle 0.29"
|
||||
- "node-postgres 8.11"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Prisma ORM", "TypeORM", "Drizzle", "node-postgres"]
|
||||
mongodb:
|
||||
name: "MongoDB"
|
||||
current_version: "7.0"
|
||||
lts_version: "6.0"
|
||||
good_for: ["document storage", "flexible schema", "horizontal scaling", "real-time"]
|
||||
not_ideal_for: ["complex relationships", "transactions", "strong consistency"]
|
||||
pairs_with:
|
||||
- "Mongoose 8.0"
|
||||
- "Prisma 5.6"
|
||||
- "MongoDB driver 6.3"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Mongoose", "Prisma", "MongoDB driver"]
|
||||
redis:
|
||||
name: "Redis"
|
||||
current_version: "7.2"
|
||||
good_for: ["caching", "sessions", "pub/sub", "real-time", "leaderboards"]
|
||||
not_ideal_for: ["primary data store", "complex queries"]
|
||||
pairs_with:
|
||||
- "ioredis 5.3"
|
||||
- "node-redis 4.6"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["ioredis", "node-redis"]
|
||||
supabase:
|
||||
name: "Supabase"
|
||||
current_version: "2.39"
|
||||
good_for: ["PostgreSQL with batteries", "real-time", "auth included", "rapid development"]
|
||||
not_ideal_for: ["custom infrastructure", "specific compliance needs"]
|
||||
pairs_with:
|
||||
- "@supabase/supabase-js 2.39"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
firebase:
|
||||
name: "Firebase Firestore"
|
||||
current_version: "10.7"
|
||||
good_for: ["real-time sync", "offline-first", "serverless", "rapid prototyping"]
|
||||
not_ideal_for: ["complex queries", "data migrations", "cost at scale"]
|
||||
pairs_with:
|
||||
- "firebase-admin 12.0"
|
||||
beginner_friendly: true
|
||||
pairs_with: ["firebase-admin"]
|
||||
|
||||
api_pattern:
|
||||
triggers: ["API", "client communication", "frontend backend", "service communication"]
|
||||
|
|
@ -80,48 +27,13 @@ decision_categories:
|
|||
affects: "all client-facing epics"
|
||||
options:
|
||||
rest:
|
||||
name: "REST API"
|
||||
specification: "OpenAPI 3.0"
|
||||
good_for: ["standard CRUD", "caching", "simple patterns", "wide support"]
|
||||
not_ideal_for: ["complex queries", "real-time updates", "over/under fetching"]
|
||||
pairs_with:
|
||||
- "Express 4.18"
|
||||
- "Fastify 4.25"
|
||||
- "NestJS 10.3"
|
||||
- "Hono 3.12"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Express", "Fastify", "NestJS", "Hono"]
|
||||
graphql:
|
||||
name: "GraphQL"
|
||||
specification: "GraphQL"
|
||||
current_version: "16.8"
|
||||
good_for: ["flexible queries", "type safety", "avoiding over-fetching", "aggregation"]
|
||||
not_ideal_for: ["simple CRUD", "file uploads", "caching complexity"]
|
||||
pairs_with:
|
||||
- "Apollo Server 4.10"
|
||||
- "GraphQL Yoga 5.1"
|
||||
- "Mercurius 14.0"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["Apollo Server", "GraphQL Yoga", "Mercurius"]
|
||||
trpc:
|
||||
name: "tRPC"
|
||||
current_version: "10.45"
|
||||
good_for: ["type safety", "TypeScript projects", "full-stack type sharing"]
|
||||
not_ideal_for: ["non-TypeScript clients", "public APIs"]
|
||||
pairs_with:
|
||||
- "Next.js 14"
|
||||
- "React Query 5.17"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["Next.js", "React Query"]
|
||||
grpc:
|
||||
name: "gRPC"
|
||||
current_version: "1.60"
|
||||
good_for: ["microservices", "binary protocol", "streaming", "performance"]
|
||||
not_ideal_for: ["browser clients", "debugging", "REST ecosystem"]
|
||||
pairs_with:
|
||||
- "@grpc/grpc-js 1.9"
|
||||
- "protobufjs 7.2"
|
||||
beginner_friendly: false
|
||||
pairs_with: ["@grpc/grpc-js", "protobufjs"]
|
||||
|
||||
authentication:
|
||||
triggers: ["auth", "login", "user management", "security", "identity"]
|
||||
|
|
@ -129,200 +41,59 @@ decision_categories:
|
|||
affects: "security and user epics"
|
||||
options:
|
||||
nextauth:
|
||||
name: "NextAuth.js"
|
||||
current_version: "4.24"
|
||||
good_for: ["Next.js projects", "OAuth providers", "database sessions", "JWT"]
|
||||
not_ideal_for: ["non-Next.js", "complex RBAC", "native mobile"]
|
||||
pairs_with:
|
||||
- "Next.js 14"
|
||||
- "Prisma 5.6"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Next.js", "Prisma"]
|
||||
auth0:
|
||||
name: "Auth0"
|
||||
good_for: ["enterprise", "compliance", "multi-tenant", "social login"]
|
||||
not_ideal_for: ["cost sensitive", "custom requirements"]
|
||||
pairs_with:
|
||||
- "@auth0/nextjs-auth0 3.5"
|
||||
- "auth0 4.2"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["@auth0/nextjs-auth0"]
|
||||
clerk:
|
||||
name: "Clerk"
|
||||
current_version: "4.29"
|
||||
good_for: ["modern stack", "user management UI", "React/Next.js"]
|
||||
not_ideal_for: ["custom UI requirements", "legacy systems"]
|
||||
pairs_with:
|
||||
- "@clerk/nextjs 4.29"
|
||||
beginner_friendly: true
|
||||
pairs_with: ["@clerk/nextjs"]
|
||||
supabase_auth:
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
firebase_auth:
|
||||
pairs_with: ["firebase-admin"]
|
||||
|
||||
supertokens:
|
||||
name: "SuperTokens"
|
||||
current_version: "16.6"
|
||||
good_for: ["open source", "self-hosted", "customizable"]
|
||||
not_ideal_for: ["quick setup", "managed service"]
|
||||
pairs_with:
|
||||
- "supertokens-node 16.6"
|
||||
beginner_friendly: false
|
||||
|
||||
frontend_framework:
|
||||
triggers: ["UI", "frontend", "client", "web app", "user interface"]
|
||||
importance: "critical"
|
||||
affects: "all UI epics"
|
||||
real_time:
|
||||
triggers: ["real-time", "websocket", "live updates", "chat", "collaboration"]
|
||||
importance: "medium"
|
||||
affects: "real-time features"
|
||||
options:
|
||||
nextjs:
|
||||
name: "Next.js"
|
||||
current_version: "14.0"
|
||||
good_for: ["full-stack", "SSR/SSG", "React ecosystem", "SEO"]
|
||||
not_ideal_for: ["pure SPA", "non-React", "simple sites"]
|
||||
pairs_with:
|
||||
- "React 18.2"
|
||||
- "TypeScript 5.3"
|
||||
- "Tailwind CSS 3.4"
|
||||
beginner_friendly: true
|
||||
|
||||
react_spa:
|
||||
name: "React SPA"
|
||||
current_version: "18.2"
|
||||
good_for: ["complex interactions", "existing APIs", "flexibility"]
|
||||
not_ideal_for: ["SEO critical", "initial load time"]
|
||||
pairs_with:
|
||||
- "Vite 5.0"
|
||||
- "React Router 6.21"
|
||||
- "TypeScript 5.3"
|
||||
beginner_friendly: true
|
||||
|
||||
vue:
|
||||
name: "Vue.js"
|
||||
current_version: "3.4"
|
||||
good_for: ["progressive enhancement", "simple mental model", "template syntax"]
|
||||
not_ideal_for: ["React ecosystem needs", "hiring pool"]
|
||||
pairs_with:
|
||||
- "Nuxt 3.9"
|
||||
- "Vite 5.0"
|
||||
- "Pinia 2.1"
|
||||
beginner_friendly: true
|
||||
|
||||
solidjs:
|
||||
name: "SolidJS"
|
||||
current_version: "1.8"
|
||||
good_for: ["performance", "fine-grained reactivity", "small bundle"]
|
||||
not_ideal_for: ["ecosystem size", "learning resources"]
|
||||
pairs_with:
|
||||
- "SolidStart 0.4"
|
||||
- "Vite 5.0"
|
||||
beginner_friendly: false
|
||||
|
||||
state_management:
|
||||
triggers: ["state", "store", "client state", "data flow", "redux"]
|
||||
importance: "high"
|
||||
affects: "frontend epics"
|
||||
options:
|
||||
zustand:
|
||||
name: "Zustand"
|
||||
current_version: "4.4"
|
||||
good_for: ["simplicity", "TypeScript", "small bundle", "React"]
|
||||
not_ideal_for: ["time-travel debugging", "Redux ecosystem"]
|
||||
beginner_friendly: true
|
||||
|
||||
redux_toolkit:
|
||||
name: "Redux Toolkit"
|
||||
current_version: "2.0"
|
||||
good_for: ["complex state", "debugging", "ecosystem", "predictable"]
|
||||
not_ideal_for: ["simple apps", "boilerplate"]
|
||||
beginner_friendly: false
|
||||
|
||||
tanstack_query:
|
||||
name: "TanStack Query"
|
||||
current_version: "5.17"
|
||||
good_for: ["server state", "caching", "synchronization", "mutations"]
|
||||
not_ideal_for: ["pure client state", "offline-heavy"]
|
||||
beginner_friendly: true
|
||||
|
||||
jotai:
|
||||
name: "Jotai"
|
||||
current_version: "2.6"
|
||||
good_for: ["atomic state", "React Suspense", "TypeScript"]
|
||||
not_ideal_for: ["debugging tools", "ecosystem size"]
|
||||
beginner_friendly: false
|
||||
|
||||
realtime:
|
||||
triggers: ["real-time", "websocket", "live", "push", "streaming", "collaborative"]
|
||||
importance: "high"
|
||||
affects: "real-time feature epics"
|
||||
options:
|
||||
socketio:
|
||||
name: "Socket.io"
|
||||
current_version: "4.6"
|
||||
good_for: ["fallbacks", "rooms", "namespaces", "reliability"]
|
||||
not_ideal_for: ["raw performance", "simple needs"]
|
||||
pairs_with:
|
||||
- "socket.io-client 4.6"
|
||||
beginner_friendly: true
|
||||
|
||||
websocket_native:
|
||||
name: "Native WebSocket"
|
||||
good_for: ["performance", "simple needs", "no dependencies"]
|
||||
not_ideal_for: ["fallbacks", "reconnection", "complex patterns"]
|
||||
pairs_with:
|
||||
- "ws 8.16"
|
||||
beginner_friendly: false
|
||||
|
||||
socket_io:
|
||||
pairs_with: ["Express", "socket.io-client"]
|
||||
pusher:
|
||||
name: "Pusher"
|
||||
good_for: ["managed service", "quick setup", "global infrastructure"]
|
||||
not_ideal_for: ["cost at scale", "self-hosted needs"]
|
||||
pairs_with:
|
||||
- "pusher-js 8.4"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["pusher-js"]
|
||||
ably:
|
||||
name: "Ably"
|
||||
current_version: "1.2"
|
||||
good_for: ["guaranteed delivery", "presence", "history", "managed"]
|
||||
not_ideal_for: ["cost sensitive", "simple needs"]
|
||||
pairs_with:
|
||||
- "ably 1.2"
|
||||
beginner_friendly: true
|
||||
pairs_with: ["ably"]
|
||||
supabase_realtime:
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
firebase_realtime:
|
||||
pairs_with: ["firebase"]
|
||||
|
||||
email:
|
||||
triggers: ["email", "notifications", "transactional email"]
|
||||
importance: "medium"
|
||||
affects: "notification epics"
|
||||
options:
|
||||
resend:
|
||||
pairs_with: ["resend", "react-email"]
|
||||
sendgrid:
|
||||
pairs_with: ["@sendgrid/mail"]
|
||||
postmark:
|
||||
pairs_with: ["postmark"]
|
||||
ses:
|
||||
pairs_with: ["@aws-sdk/client-ses"]
|
||||
|
||||
file_storage:
|
||||
triggers: ["file upload", "images", "documents", "media", "blob storage", "assets"]
|
||||
triggers: ["upload", "file storage", "images", "media", "CDN"]
|
||||
importance: "medium"
|
||||
affects: "content epics"
|
||||
affects: "media handling epics"
|
||||
options:
|
||||
s3:
|
||||
name: "AWS S3"
|
||||
good_for: ["scale", "durability", "ecosystem", "CDN integration"]
|
||||
not_ideal_for: ["simple needs", "cost optimization"]
|
||||
pairs_with:
|
||||
- "@aws-sdk/client-s3 3.478"
|
||||
- "multer-s3 3.0"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["@aws-sdk/client-s3", "multer"]
|
||||
cloudinary:
|
||||
name: "Cloudinary"
|
||||
good_for: ["image optimization", "transformations", "CDN", "easy setup"]
|
||||
not_ideal_for: ["raw files", "cost at scale"]
|
||||
pairs_with:
|
||||
- "cloudinary 1.41"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["cloudinary"]
|
||||
uploadthing:
|
||||
name: "UploadThing"
|
||||
current_version: "6.0"
|
||||
good_for: ["Next.js", "type safety", "simple setup"]
|
||||
not_ideal_for: ["non-Next.js", "complex requirements"]
|
||||
pairs_with:
|
||||
- "uploadthing 6.0"
|
||||
beginner_friendly: true
|
||||
|
||||
local_storage:
|
||||
name: "Local File System"
|
||||
good_for: ["development", "on-premise", "simple needs"]
|
||||
not_ideal_for: ["scale", "CDN", "distributed systems"]
|
||||
pairs_with:
|
||||
- "multer 1.4"
|
||||
beginner_friendly: true
|
||||
pairs_with: ["uploadthing"]
|
||||
supabase_storage:
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
|
||||
search:
|
||||
triggers: ["search", "full text", "elasticsearch", "algolia", "fuzzy"]
|
||||
|
|
@ -330,36 +101,13 @@ decision_categories:
|
|||
affects: "search and discovery epics"
|
||||
options:
|
||||
postgres_fts:
|
||||
name: "PostgreSQL Full Text Search"
|
||||
good_for: ["simple search", "no extra infrastructure", "cost effective"]
|
||||
not_ideal_for: ["complex relevance", "fuzzy matching", "facets"]
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["PostgreSQL"]
|
||||
elasticsearch:
|
||||
name: "Elasticsearch"
|
||||
current_version: "8.11"
|
||||
good_for: ["complex search", "analytics", "aggregations", "scale"]
|
||||
not_ideal_for: ["simple needs", "operational overhead"]
|
||||
pairs_with:
|
||||
- "@elastic/elasticsearch 8.11"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["@elastic/elasticsearch"]
|
||||
algolia:
|
||||
name: "Algolia"
|
||||
good_for: ["instant search", "typo tolerance", "managed service", "speed"]
|
||||
not_ideal_for: ["cost at scale", "data sovereignty"]
|
||||
pairs_with:
|
||||
- "algoliasearch 4.22"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["algoliasearch"]
|
||||
typesense:
|
||||
name: "Typesense"
|
||||
current_version: "1.7"
|
||||
good_for: ["open source alternative to Algolia", "typo tolerance", "self-hosted"]
|
||||
not_ideal_for: ["managed service needs", "small projects"]
|
||||
pairs_with:
|
||||
- "typesense 1.7"
|
||||
beginner_friendly: false
|
||||
pairs_with: ["typesense"]
|
||||
|
||||
background_jobs:
|
||||
triggers: ["queue", "jobs", "workers", "async", "background processing", "scheduled"]
|
||||
|
|
@ -367,39 +115,13 @@ decision_categories:
|
|||
affects: "async processing epics"
|
||||
options:
|
||||
bullmq:
|
||||
name: "BullMQ"
|
||||
current_version: "5.1"
|
||||
good_for: ["Redis-based", "reliable", "dashboard", "Node.js"]
|
||||
not_ideal_for: ["multi-language", "serverless"]
|
||||
pairs_with:
|
||||
- "Redis 7.2"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Redis"]
|
||||
sqs:
|
||||
name: "AWS SQS"
|
||||
good_for: ["managed service", "scale", "AWS ecosystem", "serverless"]
|
||||
not_ideal_for: ["local development", "complex patterns"]
|
||||
pairs_with:
|
||||
- "@aws-sdk/client-sqs 3.478"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["@aws-sdk/client-sqs"]
|
||||
temporal:
|
||||
name: "Temporal"
|
||||
current_version: "1.22"
|
||||
good_for: ["complex workflows", "durability", "long-running", "saga pattern"]
|
||||
not_ideal_for: ["simple jobs", "quick setup"]
|
||||
pairs_with:
|
||||
- "@temporalio/client 1.9"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["@temporalio/client"]
|
||||
inngest:
|
||||
name: "Inngest"
|
||||
current_version: "3.8"
|
||||
good_for: ["serverless", "event-driven", "TypeScript", "retries"]
|
||||
not_ideal_for: ["self-hosted", "complex workflows"]
|
||||
pairs_with:
|
||||
- "inngest 3.8"
|
||||
beginner_friendly: true
|
||||
pairs_with: ["inngest"]
|
||||
|
||||
deployment_target:
|
||||
triggers: ["deployment", "hosting", "infrastructure", "cloud", "server"]
|
||||
|
|
@ -407,277 +129,80 @@ decision_categories:
|
|||
affects: "all epics"
|
||||
options:
|
||||
vercel:
|
||||
name: "Vercel"
|
||||
good_for: ["Next.js", "edge functions", "preview deployments", "simplicity"]
|
||||
not_ideal_for: ["complex backends", "cost at scale", "non-JS"]
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Next.js", "serverless functions"]
|
||||
aws:
|
||||
name: "AWS"
|
||||
good_for: ["everything", "scale", "compliance", "flexibility"]
|
||||
not_ideal_for: ["simplicity", "predictable costs", "small projects"]
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["any stack"]
|
||||
railway:
|
||||
name: "Railway"
|
||||
good_for: ["simplicity", "databases included", "quick setup"]
|
||||
not_ideal_for: ["enterprise needs", "complex requirements"]
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["any stack", "managed databases"]
|
||||
fly_io:
|
||||
name: "Fly.io"
|
||||
good_for: ["edge deployment", "global distribution", "containers"]
|
||||
not_ideal_for: ["managed databases", "enterprise support"]
|
||||
beginner_friendly: false
|
||||
pairs_with: ["Docker containers"]
|
||||
|
||||
# Pattern combinations that work well together
|
||||
# Opinionated stack combinations (BMM methodology)
|
||||
common_stacks:
|
||||
modern_fullstack:
|
||||
name: "Modern Full-Stack"
|
||||
components:
|
||||
- "Next.js 14"
|
||||
- "PostgreSQL 15 or Supabase"
|
||||
- "Prisma ORM 5.6"
|
||||
- "NextAuth.js 4.24"
|
||||
- "Tailwind CSS 3.4"
|
||||
- "TypeScript 5.3"
|
||||
- "Vercel deployment"
|
||||
components: ["Next.js", "PostgreSQL or Supabase", "Prisma ORM", "NextAuth.js", "Tailwind CSS", "TypeScript", "Vercel"]
|
||||
good_for: "Most web applications"
|
||||
|
||||
enterprise_stack:
|
||||
name: "Enterprise Stack"
|
||||
components:
|
||||
- "NestJS 10.3"
|
||||
- "PostgreSQL 15"
|
||||
- "TypeORM 0.3"
|
||||
- "Auth0"
|
||||
- "React 18.2 + TypeScript"
|
||||
- "AWS deployment"
|
||||
good_for: "Large scale, compliance needs"
|
||||
components: ["NestJS", "PostgreSQL", "TypeORM", "Auth0", "Redis", "Docker", "AWS"]
|
||||
good_for: "Large-scale enterprise applications"
|
||||
|
||||
startup_stack:
|
||||
name: "Rapid Development Stack"
|
||||
components:
|
||||
- "Next.js 14"
|
||||
- "Supabase"
|
||||
- "Clerk Auth"
|
||||
- "Tailwind CSS 3.4"
|
||||
- "Vercel deployment"
|
||||
good_for: "MVPs and rapid prototyping"
|
||||
rapid_prototype:
|
||||
name: "Rapid Prototype"
|
||||
components: ["Next.js", "Supabase", "shadcn/ui", "Vercel"]
|
||||
good_for: "MVP and rapid development"
|
||||
|
||||
realtime_stack:
|
||||
name: "Real-time Collaboration"
|
||||
components:
|
||||
- "Next.js 14"
|
||||
- "Socket.io 4.6"
|
||||
- "Redis 7.2"
|
||||
- "PostgreSQL 15"
|
||||
- "Railway deployment"
|
||||
good_for: "Collaborative applications"
|
||||
real_time_app:
|
||||
name: "Real-Time Application"
|
||||
components: ["Next.js", "Supabase Realtime", "PostgreSQL", "Prisma", "Socket.io fallback"]
|
||||
good_for: "Chat, collaboration, live updates"
|
||||
|
||||
# WARNING: Version numbers are illustrative - actual versions should be verified
|
||||
# during workflow execution via web search for current stable versions
|
||||
mobile_app:
|
||||
name: "Mobile Application"
|
||||
components: ["Expo", "React Native", "Supabase or Firebase", "React Query"]
|
||||
good_for: "Cross-platform mobile apps"
|
||||
|
||||
# Starter templates that make architectural decisions
|
||||
# Starter templates and what decisions they make
|
||||
starter_templates:
|
||||
create_next_app:
|
||||
name: "Create Next App"
|
||||
command_search: "npx create-next-app@latest options"
|
||||
base_command: "npx create-next-app@latest"
|
||||
interactive: true
|
||||
decisions_provided:
|
||||
- "TypeScript vs JavaScript (--typescript flag)"
|
||||
- "ESLint configuration (--eslint flag)"
|
||||
- "Tailwind CSS setup (--tailwind flag)"
|
||||
- "App Router vs Pages Router (--app flag)"
|
||||
- "src/ directory structure (--src-dir flag)"
|
||||
- "Import alias (@/* default)"
|
||||
project_structure: "Standard Next.js structure with app/ or pages/"
|
||||
good_for: ["Web applications", "SSR/SSG needs", "Full-stack React"]
|
||||
command_search: "npx create-next-app@latest"
|
||||
decisions_provided: ["Next.js framework", "TypeScript option", "App Router vs Pages", "Tailwind CSS option", "ESLint"]
|
||||
good_for: ["React web applications", "Full-stack apps", "SSR/SSG"]
|
||||
|
||||
create_t3_app:
|
||||
name: "Create T3 App"
|
||||
command_search: "create t3 app latest CLI options"
|
||||
base_command: "npm create t3-app@latest"
|
||||
interactive: true
|
||||
decisions_provided:
|
||||
- "Next.js framework (always)"
|
||||
- "TypeScript (always)"
|
||||
- "tRPC for type-safe APIs"
|
||||
- "Prisma ORM"
|
||||
- "NextAuth.js authentication"
|
||||
- "Tailwind CSS"
|
||||
- "Drizzle ORM (alternative to Prisma)"
|
||||
project_structure: "Opinionated full-stack structure"
|
||||
good_for: ["Type-safe full-stack", "Rapid development", "Best practices"]
|
||||
command_search: "npm create t3-app@latest"
|
||||
decisions_provided: ["Next.js", "TypeScript", "tRPC", "Prisma", "NextAuth", "Tailwind CSS"]
|
||||
good_for: ["Type-safe full-stack apps"]
|
||||
|
||||
create_vite:
|
||||
name: "Create Vite"
|
||||
command_search: "npm create vite templates options"
|
||||
base_command: "npm create vite@latest"
|
||||
interactive: true
|
||||
templates_available:
|
||||
- "vanilla"
|
||||
- "vanilla-ts"
|
||||
- "react"
|
||||
- "react-ts"
|
||||
- "react-swc"
|
||||
- "react-swc-ts"
|
||||
- "vue"
|
||||
- "vue-ts"
|
||||
- "svelte"
|
||||
- "svelte-ts"
|
||||
decisions_provided:
|
||||
- "Build tool (Vite)"
|
||||
- "Framework choice"
|
||||
- "TypeScript setup"
|
||||
- "HMR configuration"
|
||||
- "Development server"
|
||||
project_structure: "Minimal, framework-specific"
|
||||
good_for: ["SPAs", "Fast development", "Modern tooling"]
|
||||
|
||||
create_react_app:
|
||||
name: "Create React App"
|
||||
status: "DEPRECATED - Use Vite or Next.js instead"
|
||||
note: "No longer recommended by React team"
|
||||
command_search: "npm create vite@latest"
|
||||
decisions_provided: ["Framework choice (React/Vue/Svelte)", "TypeScript option", "Vite bundler"]
|
||||
good_for: ["Fast dev SPAs", "Library development"]
|
||||
|
||||
create_remix:
|
||||
name: "Create Remix"
|
||||
command_search: "npx create-remix latest options"
|
||||
base_command: "npx create-remix@latest"
|
||||
decisions_provided:
|
||||
- "Remix framework"
|
||||
- "TypeScript option"
|
||||
- "Deployment target"
|
||||
- "CSS solution"
|
||||
command_search: "npx create-remix@latest"
|
||||
decisions_provided: ["Remix framework", "TypeScript option", "Deployment target", "CSS solution"]
|
||||
good_for: ["Web standards", "Nested routing", "Progressive enhancement"]
|
||||
|
||||
nest_new:
|
||||
name: "NestJS CLI"
|
||||
command_search: "nest new project options"
|
||||
base_command: "nest new"
|
||||
decisions_provided:
|
||||
- "TypeScript (always)"
|
||||
- "Package manager"
|
||||
- "Testing framework (Jest)"
|
||||
- "Linting (ESLint)"
|
||||
- "Project structure (modules/controllers/services)"
|
||||
project_structure: "Enterprise Angular-style backend"
|
||||
command_search: "nest new project"
|
||||
decisions_provided: ["TypeScript (always)", "Package manager", "Testing framework (Jest)", "Project structure"]
|
||||
good_for: ["Enterprise APIs", "Microservices", "GraphQL APIs"]
|
||||
|
||||
create_expo_app:
|
||||
name: "Create Expo App"
|
||||
command_search: "create-expo-app templates latest"
|
||||
base_command: "npx create-expo-app"
|
||||
decisions_provided:
|
||||
- "React Native setup"
|
||||
- "TypeScript option"
|
||||
- "Navigation library option"
|
||||
- "Expo SDK version"
|
||||
command_search: "npx create-expo-app"
|
||||
decisions_provided: ["React Native", "Expo SDK", "TypeScript option", "Navigation option"]
|
||||
good_for: ["Cross-platform mobile", "React Native apps"]
|
||||
|
||||
create_vue:
|
||||
name: "Create Vue"
|
||||
command_search: "npm create vue latest options"
|
||||
base_command: "npm create vue@latest"
|
||||
decisions_provided:
|
||||
- "Vue 3"
|
||||
- "TypeScript option"
|
||||
- "JSX support"
|
||||
- "Vue Router"
|
||||
- "Pinia state management"
|
||||
- "Vitest for testing"
|
||||
- "ESLint + Prettier"
|
||||
good_for: ["Vue applications", "Progressive web apps"]
|
||||
|
||||
create_astro:
|
||||
name: "Create Astro"
|
||||
command_search: "npm create astro latest templates"
|
||||
base_command: "npm create astro@latest"
|
||||
decisions_provided:
|
||||
- "Astro framework"
|
||||
- "TypeScript strictness"
|
||||
- "Template choice"
|
||||
- "Framework integrations"
|
||||
good_for: ["Content sites", "Static sites", "Islands architecture"]
|
||||
|
||||
create_svelte:
|
||||
name: "Create Svelte"
|
||||
command_search: "npm create svelte latest options"
|
||||
base_command: "npm create svelte@latest"
|
||||
decisions_provided:
|
||||
- "SvelteKit framework"
|
||||
- "TypeScript option"
|
||||
- "ESLint"
|
||||
- "Prettier"
|
||||
- "Testing setup"
|
||||
good_for: ["Svelte applications", "Compiled frameworks"]
|
||||
|
||||
cargo_new:
|
||||
name: "Cargo New (Rust)"
|
||||
command_search: "cargo new options binary library"
|
||||
base_command: "cargo new"
|
||||
decisions_provided:
|
||||
- "Binary vs Library (--bin or --lib)"
|
||||
- "Project structure"
|
||||
- "Cargo.toml setup"
|
||||
good_for: ["Rust CLI tools", "Systems programming", "Performance critical"]
|
||||
|
||||
dotnet_new:
|
||||
name: ".NET CLI"
|
||||
command_search: "dotnet new templates list"
|
||||
base_command: "dotnet new"
|
||||
templates_available:
|
||||
- "webapi"
|
||||
- "webapp"
|
||||
- "blazor"
|
||||
- "console"
|
||||
- "classlib"
|
||||
decisions_provided:
|
||||
- "Project type"
|
||||
- ".NET version"
|
||||
- "Authentication option"
|
||||
- "HTTPS configuration"
|
||||
good_for: ["C# applications", "Enterprise", "Windows development"]
|
||||
|
||||
rails_new:
|
||||
name: "Rails New"
|
||||
command_search: "rails new options latest"
|
||||
base_command: "rails new"
|
||||
decisions_provided:
|
||||
- "Database (PostgreSQL/MySQL/SQLite)"
|
||||
- "CSS framework"
|
||||
- "JavaScript approach"
|
||||
- "Testing framework"
|
||||
- "API-only mode"
|
||||
good_for: ["Ruby web apps", "Rapid prototyping", "Convention over configuration"]
|
||||
|
||||
django_startproject:
|
||||
name: "Django Start Project"
|
||||
command_search: "django-admin startproject structure"
|
||||
base_command: "django-admin startproject"
|
||||
decisions_provided:
|
||||
- "Django framework"
|
||||
- "Project structure"
|
||||
- "Settings configuration"
|
||||
- "Database (SQLite default)"
|
||||
good_for: ["Python web apps", "Admin interfaces", "Content management"]
|
||||
|
||||
create_redwood_app:
|
||||
name: "Create RedwoodJS App"
|
||||
command_search: "yarn create redwood-app latest"
|
||||
base_command: "yarn create redwood-app"
|
||||
decisions_provided:
|
||||
- "RedwoodJS framework"
|
||||
- "TypeScript (default)"
|
||||
- "Prisma ORM"
|
||||
- "GraphQL API"
|
||||
- "Storybook"
|
||||
- "Testing setup"
|
||||
project_structure: "Monorepo with api/ and web/"
|
||||
good_for: ["Full-stack JAMstack", "Startups", "Rapid development"]
|
||||
|
||||
# Starter template selection heuristics
|
||||
# Starter selection heuristics (workflow logic)
|
||||
starter_selection_rules:
|
||||
by_project_type:
|
||||
web_application:
|
||||
|
|
@ -685,17 +210,13 @@ starter_selection_rules:
|
|||
considerations: "SSR needs? → Next.js. Type safety critical? → T3. SPA only? → Vite"
|
||||
|
||||
mobile_app:
|
||||
recommended: ["create_expo_app", "react_native_cli"]
|
||||
considerations: "Need native modules? → React Native CLI. Simpler setup? → Expo"
|
||||
recommended: ["create_expo_app"]
|
||||
considerations: "Cross-platform → Expo. Native-heavy → React Native CLI"
|
||||
|
||||
api_backend:
|
||||
recommended: ["nest_new", "express_generator", "fastify_cli"]
|
||||
considerations: "Enterprise? → NestJS. Simple? → Express. Performance? → Fastify"
|
||||
|
||||
cli_tool:
|
||||
recommended: ["cargo_new", "go_mod_init", "npm_init"]
|
||||
considerations: "Performance critical? → Rust/Go. Quick script? → Node.js/Python"
|
||||
recommended: ["nest_new"]
|
||||
considerations: "Enterprise → NestJS. Simple → Express starter. Performance → Fastify"
|
||||
|
||||
full_stack:
|
||||
recommended: ["create_t3_app", "create_redwood_app", "rails_new"]
|
||||
considerations: "Type safety? → T3. JAMstack? → Redwood. Ruby? → Rails"
|
||||
recommended: ["create_t3_app", "create_remix"]
|
||||
considerations: "Type safety → T3. Web standards → Remix. Monolith → RedwoodJS"
|
||||
|
|
|
|||
|
|
@ -33,8 +33,8 @@
|
|||
</check-item>
|
||||
|
||||
<halt-condition>
|
||||
<check>If trigger is unclear: "Cannot proceed without understanding what caused the need for change"</check>
|
||||
<check>If no evidence provided: "Need concrete evidence or examples of the issue before analyzing impact"</check>
|
||||
<action if="trigger is unclear">HALT: "Cannot proceed without understanding what caused the need for change"</action>
|
||||
<action if="no evidence provided">HALT: "Need concrete evidence or examples of the issue before analyzing impact"</action>
|
||||
</halt-condition>
|
||||
|
||||
</section>
|
||||
|
|
@ -261,9 +261,9 @@
|
|||
</check-item>
|
||||
|
||||
<halt-condition>
|
||||
<check>If any critical section cannot be completed: "Cannot proceed to proposal without complete impact analysis"</check>
|
||||
<check>If user approval not obtained: "Must have explicit approval before implementing changes"</check>
|
||||
<check>If handoff responsibilities unclear: "Must clearly define who will execute the proposed changes"</check>
|
||||
<action if="any critical section cannot be completed">HALT: "Cannot proceed to proposal without complete impact analysis"</action>
|
||||
<action if="user approval not obtained">HALT: "Must have explicit approval before implementing changes"</action>
|
||||
<action if="handoff responsibilities unclear">HALT: "Must clearly define who will execute the proposed changes"</action>
|
||||
</halt-condition>
|
||||
|
||||
</section>
|
||||
|
|
|
|||
|
|
@ -50,9 +50,9 @@
|
|||
<action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
|
||||
<action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
|
||||
|
||||
<check>If no incomplete tasks → <goto step="6">Completion sequence</goto></check>
|
||||
<check>If story file inaccessible → HALT: "Cannot develop story without access to story file"</check>
|
||||
<check>If task requirements ambiguous → ASK user to clarify or HALT</check>
|
||||
<action if="no incomplete tasks"><goto step="6">Completion sequence</goto></action>
|
||||
<action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
|
||||
<action if="task requirements ambiguous">ASK user to clarify or HALT</action>
|
||||
</step>
|
||||
|
||||
<step n="1.5" goal="Mark story in-progress in sprint status">
|
||||
|
|
@ -88,11 +88,11 @@ Story is already marked in-progress
|
|||
<action>Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log</action>
|
||||
<action>Implement the task COMPLETELY including all subtasks, following architecture patterns and coding standards in this repo</action>
|
||||
<action>Handle error conditions and edge cases appropriately</action>
|
||||
<check>If unapproved dependencies are needed → ASK user for approval before adding</check>
|
||||
<check>If 3 consecutive implementation failures occur → HALT and request guidance</check>
|
||||
<check>If required configuration is missing → HALT: "Cannot proceed without necessary configuration files"</check>
|
||||
<check>If {{run_until_complete}} == true → Do not stop after partial progress; continue iterating tasks until all ACs are satisfied or a HALT condition triggers</check>
|
||||
<check>Do NOT propose to pause for review, standups, or validation until Step 6 gates are satisfied</check>
|
||||
<action if="unapproved dependencies are needed">ASK user for approval before adding</action>
|
||||
<action if="3 consecutive implementation failures occur">HALT and request guidance</action>
|
||||
<action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
|
||||
<action if="{{run_until_complete}} == true">Do not stop after partial progress; continue iterating tasks until all ACs are satisfied or a HALT condition triggers</action>
|
||||
<critical>Do NOT propose to pause for review, standups, or validation until Step 6 gates are satisfied</critical>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Author comprehensive tests">
|
||||
|
|
@ -108,8 +108,8 @@ Story is already marked in-progress
|
|||
<action>Run the new tests to verify implementation correctness</action>
|
||||
<action>Run linting and code quality checks if configured</action>
|
||||
<action>Validate implementation meets ALL story acceptance criteria; if ACs include quantitative thresholds (e.g., test pass rate), ensure they are met before marking complete</action>
|
||||
<check>If regression tests fail → STOP and fix before continuing</check>
|
||||
<check>If new tests fail → STOP and fix before continuing</check>
|
||||
<action if="regression tests fail">STOP and fix before continuing</action>
|
||||
<action if="new tests fail">STOP and fix before continuing</action>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Mark task complete and update story">
|
||||
|
|
@ -118,9 +118,9 @@ Story is already marked in-progress
|
|||
<action>Add completion notes to Dev Agent Record if significant changes were made (summarize intent, approach, and any follow-ups)</action>
|
||||
<action>Append a brief entry to Change Log describing the change</action>
|
||||
<action>Save the story file</action>
|
||||
<check>Determine if more incomplete tasks remain</check>
|
||||
<check>If more tasks remain → <goto step="1">Next task</goto></check>
|
||||
<check>If no tasks remain → <goto step="6">Completion</goto></check>
|
||||
<action>Determine if more incomplete tasks remain</action>
|
||||
<action if="more tasks remain"><goto step="1">Next task</goto></action>
|
||||
<action if="no tasks remain"><goto step="6">Completion</goto></action>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Story completion sequence">
|
||||
|
|
@ -144,9 +144,9 @@ Story is marked Ready for Review in file, but sprint-status.yaml may be out of s
|
|||
</output>
|
||||
</check>
|
||||
|
||||
<check>If any task is incomplete → Return to step 1 to complete remaining work (Do NOT finish with partial progress)</check>
|
||||
<check>If regression failures exist → STOP and resolve before completing</check>
|
||||
<check>If File List is incomplete → Update it before completing</check>
|
||||
<action if="any task is incomplete">Return to step 1 to complete remaining work (Do NOT finish with partial progress)</action>
|
||||
<action if="regression failures exist">STOP and resolve before completing</action>
|
||||
<action if="File List is incomplete">Update it before completing</action>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Validation and handoff" optional="true">
|
||||
|
|
|
|||
|
|
@ -385,7 +385,7 @@ plan-project (Phase 2)
|
|||
| Phase | Primary Agents | Supporting Agents |
|
||||
| ------------------ | ------------------- | --------------------------- |
|
||||
| **Analysis** | Analyst, Researcher | PM, PO |
|
||||
| **Planning** | PM | Analyst, UX Expert |
|
||||
| **Planning** | PM | Analyst, UX Designer |
|
||||
| **Solutioning** | Architect | PM, Tech Lead |
|
||||
| **Implementation** | SM, DEV | SR, PM (for correct-course) |
|
||||
|
||||
|
|
|
|||
|
|
@ -50,10 +50,10 @@ phases:
|
|||
command: "tech-spec"
|
||||
output: "Creates spec with multiple story files"
|
||||
note: "Integrate with existing patterns"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
conditional: "if_has_ui"
|
||||
agent: "ux-expert"
|
||||
command: "ux-spec"
|
||||
agent: "ux-designer"
|
||||
command: "create-design"
|
||||
|
||||
- phase: 3
|
||||
name: "Solutioning"
|
||||
|
|
|
|||
|
|
@ -44,10 +44,10 @@ phases:
|
|||
agent: "pm"
|
||||
command: "prd"
|
||||
output: "Requirements with integration points"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
conditional: "if_has_ui"
|
||||
agent: "pm"
|
||||
command: "ux-spec"
|
||||
agent: "ux-designer"
|
||||
command: "create-design"
|
||||
note: "Must align with existing UI patterns"
|
||||
|
||||
- phase: 3
|
||||
|
|
|
|||
|
|
@ -46,10 +46,10 @@ phases:
|
|||
agent: "pm"
|
||||
command: "prd"
|
||||
output: "Comprehensive PRD considering existing system"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
required: true
|
||||
agent: "pm"
|
||||
command: "ux-spec"
|
||||
agent: "ux-designer"
|
||||
command: "create-design"
|
||||
note: "Multiple UI/UX specifications"
|
||||
|
||||
- phase: 3
|
||||
|
|
|
|||
|
|
@ -34,10 +34,10 @@ phases:
|
|||
agent: "pm"
|
||||
command: "prd"
|
||||
output: "Creates PRD with epics.md and story list"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
conditional: "if_has_ui"
|
||||
agent: "ux-expert"
|
||||
command: "ux-spec"
|
||||
agent: "ux-designer"
|
||||
command: "create-design"
|
||||
- id: "tech-spec"
|
||||
optional: true
|
||||
agent: "pm"
|
||||
|
|
|
|||
|
|
@ -34,10 +34,10 @@ phases:
|
|||
agent: "pm"
|
||||
command: "prd"
|
||||
output: "High-level requirements and epic definitions"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
conditional: "if_has_ui"
|
||||
agent: "ux-expert"
|
||||
command: "ux-spec"
|
||||
agent: "ux-designer"
|
||||
command: "create-design"
|
||||
|
||||
- phase: 3
|
||||
name: "Solutioning"
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ phases:
|
|||
agent: "analyst"
|
||||
command: "brainstorm-project"
|
||||
- id: "research"
|
||||
required: true
|
||||
required: false
|
||||
agent: "analyst"
|
||||
command: "research"
|
||||
note: "Extensive research across multiple domains"
|
||||
|
|
@ -35,10 +35,10 @@ phases:
|
|||
agent: "pm"
|
||||
command: "prd"
|
||||
output: "Comprehensive product requirements document"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
required: true
|
||||
agent: "ux-expert"
|
||||
command: "ux-spec"
|
||||
agent: "ux-designer"
|
||||
command: "create-design"
|
||||
note: "Multiple UI/UX specifications needed"
|
||||
|
||||
- phase: 3
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ levels:
|
|||
title: "Enterprise Scale"
|
||||
stories: "40+ stories"
|
||||
description: "Multiple products, enterprise architecture"
|
||||
documentation: "Full suite - PRD, architecture, product specs"
|
||||
documentation: "PRD + architecture + JIT tech specs"
|
||||
architecture: true
|
||||
|
||||
# Quick detection hints for workflow-init
|
||||
|
|
|
|||
|
|
@ -25,21 +25,6 @@ NEXT_ACTION: {{next_action}}
|
|||
NEXT_COMMAND: {{next_command}}
|
||||
NEXT_AGENT: {{next_agent}}
|
||||
|
||||
## Story Backlog
|
||||
|
||||
{{#backlog_stories}}
|
||||
|
||||
- {{story_id}}: {{story_title}}
|
||||
{{/backlog_stories}}
|
||||
|
||||
## Completed Stories
|
||||
|
||||
{{#done_stories}}
|
||||
|
||||
- {{story_id}}: {{completed_date}}
|
||||
{{/done_stories}}
|
||||
|
||||
---
|
||||
|
||||
_Last Updated: {{last_updated}}_
|
||||
_Status Version: 2.0_
|
||||
|
|
|
|||
|
|
@ -10,20 +10,24 @@
|
|||
<step n="1" goal="Story Context Setup">
|
||||
|
||||
<action>Check if context data was provided with workflow invocation</action>
|
||||
<check>If data attribute was passed to this workflow:</check>
|
||||
<action>Load the context document from the data file path</action>
|
||||
<action>Study the background information, brand details, or subject matter</action>
|
||||
<action>Use the provided context to inform story development</action>
|
||||
<action>Acknowledge the focused storytelling goal</action>
|
||||
<ask response="story_refinement">I see we're crafting a story based on the context provided. What specific angle or emphasis would you like?</ask>
|
||||
<check>Else (no context data provided):</check>
|
||||
<action>Proceed with context gathering</action>
|
||||
<ask response="story_purpose">1. What's the purpose of this story? (e.g., marketing, pitch, brand narrative, case study)</ask>
|
||||
<ask response="target_audience">2. Who is your target audience?</ask>
|
||||
<ask response="key_messages">3. What key messages or takeaways do you want the audience to have?</ask>
|
||||
<ask>4. Any constraints? (length, tone, medium, existing brand guidelines)</ask>
|
||||
|
||||
<check if="data attribute was passed to this workflow">
|
||||
<action>Load the context document from the data file path</action>
|
||||
<action>Study the background information, brand details, or subject matter</action>
|
||||
<action>Use the provided context to inform story development</action>
|
||||
<action>Acknowledge the focused storytelling goal</action>
|
||||
<ask response="story_refinement">I see we're crafting a story based on the context provided. What specific angle or emphasis would you like?</ask>
|
||||
</check>
|
||||
|
||||
<check if="no context data provided">
|
||||
<action>Proceed with context gathering</action>
|
||||
<ask response="story_purpose">1. What's the purpose of this story? (e.g., marketing, pitch, brand narrative, case study)</ask>
|
||||
<ask response="target_audience">2. Who is your target audience?</ask>
|
||||
<ask response="key_messages">3. What key messages or takeaways do you want the audience to have?</ask>
|
||||
<ask>4. Any constraints? (length, tone, medium, existing brand guidelines)</ask>
|
||||
|
||||
<critical>Wait for user response before proceeding. This context shapes the narrative approach.</critical>
|
||||
</check>
|
||||
|
||||
<template-output>story_purpose, target_audience, key_messages</template-output>
|
||||
|
||||
|
|
@ -53,13 +57,14 @@ I can help craft your story using these proven narrative frameworks:
|
|||
Which framework best fits your purpose? (Enter 1-10, or ask for my recommendation)
|
||||
</ask>
|
||||
|
||||
<check>If user asks for recommendation:</check>
|
||||
<action>Analyze story_purpose, target_audience, and key_messages</action>
|
||||
<action>Recommend best-fit framework with clear rationale</action>
|
||||
<example>
|
||||
Based on your {{story_purpose}} for {{target_audience}}, I recommend:
|
||||
**{{framework_name}}** because {{rationale}}
|
||||
</example>
|
||||
<check if="user asks for recommendation">
|
||||
<action>Analyze story_purpose, target_audience, and key_messages</action>
|
||||
<action>Recommend best-fit framework with clear rationale</action>
|
||||
<example>
|
||||
Based on your {{story_purpose}} for {{target_audience}}, I recommend:
|
||||
**{{framework_name}}** because {{rationale}}
|
||||
</example>
|
||||
</check>
|
||||
|
||||
<template-output>story_type, framework_name</template-output>
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,263 @@
|
|||
/**
|
||||
* BMAD Workflow Markdown Formatter
|
||||
*
|
||||
* Formats mixed markdown + XML workflow instruction files with:
|
||||
* - 2-space XML indentation
|
||||
* - Preserved markdown content
|
||||
* - Proper tag nesting
|
||||
* - Consistent formatting
|
||||
*/
|
||||
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
|
||||
class WorkflowFormatter {
|
||||
constructor(options = {}) {
|
||||
this.indentSize = options.indentSize || 2;
|
||||
this.preserveMarkdown = options.preserveMarkdown !== false;
|
||||
this.verbose = options.verbose || false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Format a workflow markdown file
|
||||
*/
|
||||
format(filePath) {
|
||||
if (this.verbose) {
|
||||
console.log(`Formatting: ${filePath}`);
|
||||
}
|
||||
|
||||
const content = fs.readFileSync(filePath, 'utf8');
|
||||
const formatted = this.formatContent(content);
|
||||
|
||||
// Only write if content changed
|
||||
if (content === formatted) {
|
||||
if (this.verbose) {
|
||||
console.log(`- No changes: ${filePath}`);
|
||||
}
|
||||
return false;
|
||||
} else {
|
||||
fs.writeFileSync(filePath, formatted, 'utf8');
|
||||
if (this.verbose) {
|
||||
console.log(`✓ Formatted: ${filePath}`);
|
||||
}
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Format content string with stateful indentation tracking
|
||||
*/
|
||||
formatContent(content) {
|
||||
const lines = content.split('\n');
|
||||
const formatted = [];
|
||||
let indentLevel = 0;
|
||||
let inCodeBlock = false;
|
||||
let checkBlockDepth = 0; // Track nested check blocks
|
||||
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
const trimmed = line.trim();
|
||||
|
||||
// Track code blocks (don't format inside them)
|
||||
if (trimmed.startsWith('```')) {
|
||||
if (inCodeBlock) {
|
||||
inCodeBlock = false;
|
||||
} else {
|
||||
inCodeBlock = true;
|
||||
}
|
||||
formatted.push(line);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Don't format inside code blocks
|
||||
if (inCodeBlock) {
|
||||
formatted.push(line);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Handle XML tags
|
||||
if (this.isXMLLine(trimmed)) {
|
||||
const result = this.formatXMLLine(trimmed, indentLevel, checkBlockDepth, i, lines);
|
||||
formatted.push(result.line);
|
||||
indentLevel = result.nextIndent;
|
||||
checkBlockDepth = result.nextCheckDepth;
|
||||
} else if (trimmed === '') {
|
||||
// Preserve blank lines
|
||||
formatted.push('');
|
||||
} else {
|
||||
// Markdown content - preserve as-is but maintain current indent if inside XML
|
||||
formatted.push(line);
|
||||
}
|
||||
}
|
||||
|
||||
return formatted.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if line contains XML tag
|
||||
*/
|
||||
isXMLLine(line) {
|
||||
return /^<[a-zA-Z-]+(\s|>|\/)/.test(line) || /^<\/[a-zA-Z-]+>/.test(line);
|
||||
}
|
||||
|
||||
/**
|
||||
* Format a single XML line with context awareness
|
||||
*/
|
||||
formatXMLLine(line, currentIndent, checkDepth, lineIndex, allLines) {
|
||||
const trimmed = line.trim();
|
||||
let indent = currentIndent;
|
||||
let nextIndent = currentIndent;
|
||||
let nextCheckDepth = checkDepth;
|
||||
|
||||
// Get the tag name
|
||||
const tagMatch = trimmed.match(/^<\/?([a-zA-Z-]+)/);
|
||||
const tagName = tagMatch ? tagMatch[1] : '';
|
||||
|
||||
// Closing tag - decrease indent before this line
|
||||
if (trimmed.startsWith('</')) {
|
||||
indent = Math.max(0, currentIndent - 1);
|
||||
nextIndent = indent;
|
||||
|
||||
// If closing a step, reset check depth
|
||||
if (tagName === 'step' || tagName === 'workflow') {
|
||||
nextCheckDepth = 0;
|
||||
}
|
||||
}
|
||||
// Self-closing tags (opens and closes on same line)
|
||||
// EXCEPT <check> tags which create logical blocks
|
||||
else if (this.isSelfClosingTag(trimmed) && tagName !== 'check') {
|
||||
// These don't change indent level
|
||||
indent = currentIndent;
|
||||
nextIndent = currentIndent;
|
||||
}
|
||||
// Opening tags
|
||||
else if (trimmed.startsWith('<')) {
|
||||
// Check if this is a <check> tag - these create logical blocks
|
||||
if (tagName === 'check') {
|
||||
indent = currentIndent;
|
||||
// Check tags increase indent for following content
|
||||
nextIndent = currentIndent + 1;
|
||||
nextCheckDepth = checkDepth + 1;
|
||||
}
|
||||
// <action> tags inside check blocks stay at current indent
|
||||
else if (tagName === 'action' && checkDepth > 0) {
|
||||
indent = currentIndent;
|
||||
nextIndent = currentIndent; // Don't increase further
|
||||
}
|
||||
// Other tags close check blocks and return to structural level
|
||||
else if (checkDepth > 0) {
|
||||
// Close all check blocks - return to base structural level
|
||||
indent = Math.max(0, currentIndent - checkDepth);
|
||||
nextIndent = indent + 1;
|
||||
nextCheckDepth = 0;
|
||||
}
|
||||
// Regular opening tags (no check blocks active)
|
||||
else {
|
||||
indent = currentIndent;
|
||||
nextIndent = currentIndent + 1;
|
||||
}
|
||||
}
|
||||
|
||||
const indentStr = ' '.repeat(indent * this.indentSize);
|
||||
return {
|
||||
line: indentStr + trimmed,
|
||||
nextIndent: nextIndent,
|
||||
nextCheckDepth: nextCheckDepth,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if tag opens and closes on same line
|
||||
*/
|
||||
isSelfClosingTag(line) {
|
||||
// Self-closing with />
|
||||
if (line.endsWith('/>')) {
|
||||
return true;
|
||||
}
|
||||
// Opens and closes on same line: <tag>content</tag>
|
||||
const match = line.match(/^<([a-zA-Z-]+)(\s[^>]*)?>.*<\/\1>$/);
|
||||
return match !== null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if tag is a block-level structural tag
|
||||
*/
|
||||
isBlockLevelTag(tagName) {
|
||||
return ['step', 'workflow', 'check'].includes(tagName);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* CLI Entry Point
|
||||
*/
|
||||
function main() {
|
||||
const args = process.argv.slice(2);
|
||||
|
||||
if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
|
||||
console.log(`
|
||||
BMAD Workflow Markdown Formatter
|
||||
|
||||
Usage:
|
||||
node format-workflow-md.js <file-pattern> [options]
|
||||
|
||||
Options:
|
||||
--verbose, -v Verbose output
|
||||
--check, -c Check formatting without writing (exit 1 if changes needed)
|
||||
--help, -h Show this help
|
||||
|
||||
Examples:
|
||||
node format-workflow-md.js src/**/instructions.md
|
||||
node format-workflow-md.js "src/modules/bmb/**/*.md" --verbose
|
||||
node format-workflow-md.js file.md --check
|
||||
`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
const verbose = args.includes('--verbose') || args.includes('-v');
|
||||
const check = args.includes('--check') || args.includes('-c');
|
||||
|
||||
// Remove flags from args
|
||||
const files = args.filter((arg) => !arg.startsWith('-'));
|
||||
|
||||
const formatter = new WorkflowFormatter({ verbose });
|
||||
let hasChanges = false;
|
||||
let formattedCount = 0;
|
||||
|
||||
// Process files
|
||||
for (const pattern of files) {
|
||||
// For now, treat as direct file path
|
||||
// TODO: Add glob support for patterns
|
||||
if (fs.existsSync(pattern)) {
|
||||
const stat = fs.statSync(pattern);
|
||||
if (stat.isFile()) {
|
||||
const changed = formatter.format(pattern);
|
||||
if (changed) {
|
||||
hasChanges = true;
|
||||
formattedCount++;
|
||||
}
|
||||
} else if (stat.isDirectory()) {
|
||||
console.error(`Error: ${pattern} is a directory. Please specify file paths.`);
|
||||
}
|
||||
} else {
|
||||
console.error(`Error: File not found: ${pattern}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (verbose || formattedCount > 0) {
|
||||
console.log(`\nFormatted ${formattedCount} file(s)`);
|
||||
}
|
||||
|
||||
if (check && hasChanges) {
|
||||
console.error('\n❌ Some files need formatting. Run without --check to format.');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Run if called directly
|
||||
if (require.main === module) {
|
||||
main();
|
||||
}
|
||||
|
||||
module.exports = { WorkflowFormatter };
|
||||
Loading…
Reference in New Issue