ma-agents 3.4.7 → 3.4.9

package/.opencode/skills/bmad-create-prd/data/prd-purpose.md

@@ -0,0 +1,197 @@
+# BMAD PRD Purpose
+
+**The PRD is the top of the required funnel that feeds all subsequent product development work in rhw BMad Method.**
+
+---
+
+## What is a BMAD PRD?
+
+A dual-audience document serving:
+1. **Human Product Managers and builders** - Vision, strategy, stakeholder communication
+2. **LLM Downstream Consumption** - UX Design → Architecture → Epics → Development AI Agents
+
+Each successive document becomes more AI-tailored and granular.
+
+---
+
+## Core Philosophy: Information Density
+
+**High Signal-to-Noise Ratio**
+
+Every sentence must carry information weight. LLMs consume precise, dense content efficiently.
+
+**Anti-Patterns (Eliminate These):**
+- ❌ "The system will allow users to..." → ✅ "Users can..."
+- ❌ "It is important to note that..." → ✅ State the fact directly
+- ❌ "In order to..." → ✅ "To..."
+- ❌ Conversational filler and padding → ✅ Direct, concise statements
+
+**Goal:** Maximum information per word. Zero fluff.
+
+---
+
+## The Traceability Chain
+
+**PRD starts the chain:**
+```
+Vision → Success Criteria → User Journeys → Functional Requirements → (future: User Stories)
+```
+
+**In the PRD, establish:**
+- Vision → Success Criteria alignment
+- Success Criteria → User Journey coverage
+- User Journey → Functional Requirement mapping
+- All requirements traceable to user needs
+
+**Why:** Each downstream artifact (UX, Architecture, Epics, Stories) must trace back to documented user needs and business objectives. This chain ensures we build the right thing.
+
+---
+
+## What Makes Great Functional Requirements?
+
+### FRs are Capabilities, Not Implementation
+
+**Good FR:** "Users can reset their password via email link"
+**Bad FR:** "System sends JWT via email and validates with database" (implementation leakage)
+
+**Good FR:** "Dashboard loads in under 2 seconds for 95th percentile"
+**Bad FR:** "Fast loading time" (subjective, unmeasurable)
+
+### SMART Quality Criteria
+
+**Specific:** Clear, precisely defined capability
+**Measurable:** Quantifiable with test criteria
+**Attainable:** Realistic within constraints
+**Relevant:** Aligns with business objectives
+**Traceable:** Links to source (executive summary or user journey)
+
+### FR Anti-Patterns
+
+**Subjective Adjectives:**
+- ❌ "easy to use", "intuitive", "user-friendly", "fast", "responsive"
+- ✅ Use metrics: "completes task in under 3 clicks", "loads in under 2 seconds"
+
+**Implementation Leakage:**
+- ❌ Technology names, specific libraries, implementation details
+- ✅ Focus on capability and measurable outcomes
+
+**Vague Quantifiers:**
+- ❌ "multiple users", "several options", "various formats"
+- ✅ "up to 100 concurrent users", "3-5 options", "PDF, DOCX, TXT formats"
+
+**Missing Test Criteria:**
+- ❌ "The system shall provide notifications"
+- ✅ "The system shall send email notifications within 30 seconds of trigger event"
+
+---
+
+## What Makes Great Non-Functional Requirements?
+
+### NFRs Must Be Measurable
+
+**Template:**
+```
+"The system shall [metric] [condition] [measurement method]"
+```
+
+**Examples:**
+- ✅ "The system shall respond to API requests in under 200ms for 95th percentile as measured by APM monitoring"
+- ✅ "The system shall maintain 99.9% uptime during business hours as measured by cloud provider SLA"
+- ✅ "The system shall support 10,000 concurrent users as measured by load testing"
+
+### NFR Anti-Patterns
+
+**Unmeasurable Claims:**
+- ❌ "The system shall be scalable" → ✅ "The system shall handle 10x load growth through horizontal scaling"
+- ❌ "High availability required" → ✅ "99.9% uptime as measured by cloud provider SLA"
+
+**Missing Context:**
+- ❌ "Response time under 1 second" → ✅ "API response time under 1 second for 95th percentile under normal load"
+
+---
+
+## Domain-Specific Requirements
+
+**Auto-Detect and Enforce Based on Project Context**
+
+Certain industries have mandatory requirements that must be present:
+
+- **Healthcare:** HIPAA Privacy & Security Rules, PHI encryption, audit logging, MFA
+- **Fintech:** PCI-DSS Level 1, AML/KYC compliance, SOX controls, financial audit trails
+- **GovTech:** NIST framework, Section 508 accessibility (WCAG 2.1 AA), FedRAMP, data residency
+- **E-Commerce:** PCI-DSS for payments, inventory accuracy, tax calculation by jurisdiction
+
+**Why:** Missing these requirements in the PRD means they'll be missed in architecture and implementation, creating expensive rework. During PRD creation there is a step to cover this - during validation we want to make sure it was covered. For this purpose steps will utilize a domain-complexity.csv and project-types.csv.
+
+---
+
+## Document Structure (Markdown, Human-Readable)
+
+### Required Sections
+1. **Executive Summary** - Vision, differentiator, target users
+2. **Success Criteria** - Measurable outcomes (SMART)
+3. **Product Scope** - MVP, Growth, Vision phases
+4. **User Journeys** - Comprehensive coverage
+5. **Domain Requirements** - Industry-specific compliance (if applicable)
+6. **Innovation Analysis** - Competitive differentiation (if applicable)
+7. **Project-Type Requirements** - Platform-specific needs
+8. **Functional Requirements** - Capability contract (FRs)
+9. **Non-Functional Requirements** - Quality attributes (NFRs)
+
+### Formatting for Dual Consumption
+
+**For Humans:**
+- Clear, professional language
+- Logical flow from vision to requirements
+- Easy for stakeholders to review and approve
+
+**For LLMs:**
+- ## Level 2 headers for all main sections (enables extraction)
+- Consistent structure and patterns
+- Precise, testable language
+- High information density
+
+---
+
+## Downstream Impact
+
+**How the PRD Feeds Next Artifacts:**
+
+**UX Design:**
+- User journeys → interaction flows
+- FRs → design requirements
+- Success criteria → UX metrics
+
+**Architecture:**
+- FRs → system capabilities
+- NFRs → architecture decisions
+- Domain requirements → compliance architecture
+- Project-type requirements → platform choices
+
+**Epics & Stories (created after architecture):**
+- FRs → user stories (1 FR could map to 1-3 stories potentially)
+- Acceptance criteria → story acceptance tests
+- Priority → sprint sequencing
+- Traceability → stories map back to vision
+
+**Development AI Agents:**
+- Precise requirements → implementation clarity
+- Test criteria → automated test generation
+- Domain requirements → compliance enforcement
+- Measurable NFRs → performance targets
+
+---
+
+## Summary: What Makes a Great BMAD PRD?
+
+✅ **High Information Density** - Every sentence carries weight, zero fluff
+✅ **Measurable Requirements** - All FRs and NFRs are testable with specific criteria
+✅ **Clear Traceability** - Each requirement links to user need and business objective
+✅ **Domain Awareness** - Industry-specific requirements auto-detected and included
+✅ **Zero Anti-Patterns** - No subjective adjectives, implementation leakage, or vague quantifiers
+✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable
+✅ **Markdown Format** - Professional, clean, accessible to all stakeholders
+
+---
+
+**Remember:** The PRD is the foundation. Quality here ripples through every subsequent phase. A dense, precise, well-traced PRD makes UX design, architecture, epic breakdown, and AI development dramatically more effective.

package/.opencode/skills/bmad-create-prd/data/project-types.csv

@@ -0,0 +1,11 @@
+project_type,detection_signals,key_questions,required_sections,skip_sections,web_search_triggers,innovation_signals
+api_backend,"API,REST,GraphQL,backend,service,endpoints","Endpoints needed?;Authentication method?;Data formats?;Rate limits?;Versioning?;SDK needed?","endpoint_specs;auth_model;data_schemas;error_codes;rate_limits;api_docs","ux_ui;visual_design;user_journeys","framework best practices;OpenAPI standards","API composition;New protocol"
+mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offline needed?;Push notifications?;Device features?;Store compliance?","platform_reqs;device_permissions;offline_mode;push_strategy;store_compliance","desktop_features;cli_commands","app store guidelines;platform requirements","Gesture innovation;AR/VR features"
+saas_b2b,"SaaS,B2B,platform,dashboard,teams,enterprise","Multi-tenant?;Permission model?;Subscription tiers?;Integrations?;Compliance?","tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs","cli_interface;mobile_first","compliance requirements;integration guides","Workflow automation;AI agents"
+developer_tool,"SDK,library,package,npm,pip,framework","Language support?;Package managers?;IDE integration?;Documentation?;Examples?","language_matrix;installation_methods;api_surface;code_examples;migration_guide","visual_design;store_compliance","package manager best practices;API design patterns","New paradigm;DSL creation"
+cli_tool,"CLI,command,terminal,bash,script","Interactive or scriptable?;Output formats?;Config method?;Shell completion?","command_structure;output_formats;config_schema;scripting_support","visual_design;ux_principles;touch_interactions","CLI design patterns;shell integration","Natural language CLI;AI commands"
+web_app,"website,webapp,browser,SPA,PWA","SPA or MPA?;Browser support?;SEO needed?;Real-time?;Accessibility?","browser_matrix;responsive_design;performance_targets;seo_strategy;accessibility_level","native_features;cli_commands","web standards;WCAG guidelines","New interaction;WebAssembly use"
+game,"game,player,gameplay,level,character","REDIRECT TO USE THE BMad Method Game Module Agent and Workflows - HALT","game-brief;GDD","most_sections","game design patterns","Novel mechanics;Genre mixing"
+desktop_app,"desktop,Windows,Mac,Linux,native","Cross-platform?;Auto-update?;System integration?;Offline?","platform_support;system_integration;update_strategy;offline_capabilities","web_seo;mobile_features","desktop guidelines;platform requirements","Desktop AI;System automation"
+iot_embedded,"IoT,embedded,device,sensor,hardware","Hardware specs?;Connectivity?;Power constraints?;Security?;OTA updates?","hardware_reqs;connectivity_protocol;power_profile;security_model;update_mechanism","visual_ui;browser_support","IoT standards;protocol specs","Edge AI;New sensors"
+blockchain_web3,"blockchain,crypto,DeFi,NFT,smart contract","Chain selection?;Wallet integration?;Gas optimization?;Security audit?","chain_specs;wallet_support;smart_contracts;security_audit;gas_optimization","traditional_auth;centralized_db","blockchain standards;security patterns","Novel tokenomics;DAO structure"

package/.opencode/skills/bmad-create-prd/steps-c/step-01-init.md

@@ -0,0 +1,178 @@
+# Step 1: Workflow Initialization
+
+**Progress: Step 1 of 11** - Next: Project Discovery
+
+## STEP GOAL:
+
+Initialize the PRD workflow by detecting continuation state, discovering input documents, and setting up the document structure for collaborative product requirement discovery.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on initialization and setup - no content generation yet
+- 🚫 FORBIDDEN to look ahead to future steps or assume knowledge from them
+- 💬 Approach: Systematic setup with clear reporting to user
+- 🚪 Detect existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis of current state before taking any action
+- 💾 Initialize document structure and update frontmatter appropriately
+- Update frontmatter: add this step name to the end of the steps completed array (it should be the first entry in the steps array since this is step 1)
+- 🚫 FORBIDDEN to load next step until user selects 'C' (Continue)
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Variables from workflow.md are available in memory
+- Focus: Workflow initialization and document setup only
+- Limits: Don't assume knowledge from other steps or create content yet
+- Dependencies: Configuration loaded from workflow.md initialization
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Check for Existing Workflow State
+
+First, check if the output document already exists:
+
+**Workflow State Detection:**
+
+- Look for file at `{outputFile}`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted` BUT `step-12-complete` is NOT in the list, follow the Continuation Protocol since the document is incomplete:
+
+**Continuation Protocol:**
+
+- **STOP immediately** and load `./step-01b-continue.md`
+- Do not proceed with any initialization tasks
+- Let step-01b handle all continuation logic
+- This is an auto-proceed situation - no user choice needed
+
+### 3. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+Discover and load context documents using smart discovery. Documents can be in the following locations:
+- {planning_artifacts}/**
+- {output_folder}/**
+- {project_knowledge}/**
+- docs/**
+
+Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content)
+
+Try to discover the following:
+- Product Brief (`*brief*.md`)
+- Research Documents (`/*research*.md`)
+- Project Documentation (generally multiple documents might be found for this in the `{project_knowledge}` or `docs` folder.)
+- Project Context (`**/project-context.md`)
+
+<critical>Confirm what you have found with the user, along with asking if the user wants to provide anything else. Only after this confirmation will you proceed to follow the loading rules</critical>
+
+**Loading Rules:**
+
+- Load ALL discovered files completely that the user confirmed or provided (no offset/limit)
+- If there is a project context, whatever is relevant should try to be biased in the remainder of this whole workflow process
+- For sharded folders, load ALL files to get complete picture, using the index first to potentially know the potential of each document
+- index.md is a guide to what's relevant whenever available
+- Track all successfully loaded files in frontmatter `inputDocuments` array
+
+#### B. Create Initial Document
+
+**Document Setup:**
+
+- Copy the template from `../templates/prd-template.md` to `{outputFile}`
+- Initialize frontmatter with proper structure including inputDocuments array.
+
+#### C. Present Initialization Results
+
+**Setup Report to User:**
+
+"Welcome {{user_name}}! I've set up your PRD workspace for {{project_name}}.
+
+**Document Setup:**
+
+- Created: `{outputFile}` from template
+- Initialized frontmatter with workflow state
+
+**Input Documents Discovered:**
+
+- Product briefs: {{briefCount}} files {if briefCount > 0}✓ loaded{else}(none found){/if}
+- Research: {{researchCount}} files {if researchCount > 0}✓ loaded{else}(none found){/if}
+- Brainstorming: {{brainstormingCount}} files {if brainstormingCount > 0}✓ loaded{else}(none found){/if}
+- Project docs: {{projectDocsCount}} files {if projectDocsCount > 0}✓ loaded (brownfield project){else}(none found - greenfield project){/if}
+
+**Files loaded:** {list of specific file names or "No additional documents found"}
+
+{if projectDocsCount > 0}
+📋 **Note:** This is a **brownfield project**. Your existing project documentation has been loaded. In the next step, I'll ask specifically about what new features or changes you want to add to your existing system.
+{/if}
+
+Do you have any other documents you'd like me to include, or shall we continue to the next step?"
+
+### 4. Present MENU OPTIONS
+
+Display menu after setup report:
+
+"[C] Continue - Save this and move to Project Discovery (Step 2 of 11)"
+
+#### Menu Handling Logic:
+
+- IF C: Update output file frontmatter, adding this step name to the end of the list of stepsCompleted, then read fully and follow: ./step-02-discovery.md
+- IF user provides additional files: Load them, update inputDocuments and documentCounts, redisplay report
+- IF user asks questions: Answer and redisplay menu
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [frontmatter properly updated with this step added to stepsCompleted and documentCounts], will you then read fully and follow: `./step-02-discovery.md` to begin project discovery.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Existing workflow detected and properly handed off to step-01b
+- Fresh workflow initialized with template and proper frontmatter
+- Input documents discovered and loaded using sharded-first logic
+- All discovered files tracked in frontmatter `inputDocuments`
+- User clearly informed of brownfield vs greenfield status
+- Menu presented and user input handled correctly
+- Frontmatter updated with this step name added to stepsCompleted before proceeding
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with fresh initialization when existing workflow exists
+- Not updating frontmatter with discovered input documents
+- **Not storing document counts in frontmatter**
+- Creating document without proper template structure
+- Not checking sharded folders first before whole files
+- Not reporting discovered documents to user clearly
+- Proceeding without user selecting 'C' (Continue)
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/.opencode/skills/bmad-create-prd/steps-c/step-01b-continue.md

@@ -0,0 +1,161 @@
+# Step 1B: Workflow Continuation
+
+## STEP GOAL:
+
+Resume the PRD workflow from where it was left off, ensuring smooth continuation with full context restoration.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ Resume workflow from exact point where it was interrupted
+
+### Step-Specific Rules:
+
+- 💬 FOCUS on understanding where we left off and continuing appropriately
+- 🚫 FORBIDDEN to modify content completed in previous steps
+- 📖 Only reload documents that were already tracked in `inputDocuments`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis of current state before taking action
+- Update frontmatter: add this step name to the end of the steps completed array
+- 📖 Only load documents that were already tracked in `inputDocuments`
+- 🚫 FORBIDDEN to discover new input documents during continuation
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Current document and frontmatter are already loaded
+- Focus: Workflow state analysis and continuation logic only
+- Limits: Don't assume knowledge beyond what's in the document
+- Dependencies: Existing workflow state from previous session
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Analyze Current State
+
+**State Assessment:**
+Review the frontmatter to understand:
+
+- `stepsCompleted`: Array of completed step filenames
+- Last element of `stepsCompleted` array: The most recently completed step
+- `inputDocuments`: What context was already loaded
+- All other frontmatter variables
+
+### 2. Restore Context Documents
+
+**Context Reloading:**
+
+- For each document in `inputDocuments`, load the complete file
+- This ensures you have full context for continuation
+- Don't discover new documents - only reload what was previously processed
+
+### 3. Determine Next Step
+
+**Step Sequence Lookup:**
+
+Use the following ordered sequence to determine the next step from the last completed step:
+
+| Last Completed | Next Step |
+|---|---|
+| step-01-init.md | step-02-discovery.md |
+| step-02-discovery.md | step-02b-vision.md |
+| step-02b-vision.md | step-02c-executive-summary.md |
+| step-02c-executive-summary.md | step-03-success.md |
+| step-03-success.md | step-04-journeys.md |
+| step-04-journeys.md | step-05-domain.md |
+| step-05-domain.md | step-06-innovation.md |
+| step-06-innovation.md | step-07-project-type.md |
+| step-07-project-type.md | step-08-scoping.md |
+| step-08-scoping.md | step-09-functional.md |
+| step-09-functional.md | step-10-nonfunctional.md |
+| step-10-nonfunctional.md | step-11-polish.md |
+| step-11-polish.md | step-12-complete.md |
+
+1. Get the last element from the `stepsCompleted` array
+2. Look it up in the table above to find the next step
+3. That's the next step to load!
+
+**Example:**
+- If `stepsCompleted = ["step-01-init.md", "step-02-discovery.md", "step-03-success.md"]`
+- Last element is `"step-03-success.md"`
+- Table lookup → next step is `./step-04-journeys.md`
+
+### 4. Handle Workflow Completion
+
+**If `stepsCompleted` array contains `"step-12-complete.md"`:**
+"Great news! It looks like we've already completed the PRD workflow for {{project_name}}.
+
+The final document is ready at `{outputFile}` with all sections completed.
+
+Would you like me to:
+
+- Review the completed PRD with you
+- Suggest next workflow steps (like architecture or epic creation)
+- Start a new PRD revision
+
+What would be most helpful?"
+
+### 5. Present Current Progress
+
+**If workflow not complete:**
+"Welcome back {{user_name}}! I'm resuming our PRD collaboration for {{project_name}}.
+
+**Current Progress:**
+- Last completed: {last step filename from stepsCompleted array}
+- Next up: {next step from lookup table}
+- Context documents available: {len(inputDocuments)} files
+
+**Document Status:**
+- Current PRD document is ready with all completed sections
+- Ready to continue from where we left off
+
+Does this look right, or do you want to make any adjustments before we proceed?"
+
+### 6. Present MENU OPTIONS
+
+Display: "**Select an Option:** [C] Continue to {next step name}"
+
+#### Menu Handling Logic:
+
+- IF C: Read fully and follow the next step determined from the lookup table in step 3
+- IF Any other comments or queries: respond and redisplay menu
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [current state confirmed], will you then read fully and follow the next step (from the lookup table) to resume the workflow.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All previous input documents successfully reloaded
+- Current workflow state accurately analyzed and presented
+- User confirms understanding of progress before continuation
+- Correct next step identified and prepared for loading
+
+### ❌ SYSTEM FAILURE:
+
+- Discovering new input documents instead of reloading existing ones
+- Modifying content from already completed steps
+- Failing to determine the next step from the lookup table
+- Proceeding without user confirmation of current state
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.