pig/pig-farm-controller
1
0
Fork 0
Code Issues 16 Pull Requests Actions Packages Projects Releases Wiki Activity

bmad初始化

Browse Source
This commit is contained in:
huang
2025-11-01 19:22:39 +08:00
parent 5b21dc0bd5
commit 426ae41f54
447 changed files with 80633 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

195
bmad/bmm/workflows/4-implementation/epic-tech-context/README.md Normal file
View File

@@ -0,0 +1,195 @@
# Technical Specification Workflow
## Overview
Generate a comprehensive Technical Specification for a single epic from PRD, Epics file and Architecture to produce a document with full acceptance criteria and traceability mapping. Creates detailed implementation guidance that bridges business requirements with technical execution.
## Key Features
- **PRD-Architecture Integration** - Synthesizes business requirements with technical constraints
- **Traceability Mapping** - Links acceptance criteria to technical components and tests
- **Multi-Input Support** - Leverages PRD, architecture, front-end specs, and brownfield notes
- **Implementation Focus** - Provides concrete technical guidance for development teams
- **Testing Integration** - Includes test strategy aligned with acceptance criteria
- **Validation Ready** - Generates specifications suitable for architectural review
## Usage
### Basic Invocation
```bash
workflow tech-spec
```
### With Input Documents
```bash
# With specific PRD and architecture
workflow tech-spec --input PRD.md --input architecture.md
# With comprehensive inputs
workflow tech-spec --input PRD.md --input architecture.md --input front-end-spec.md
```
### Configuration
- **output_folder**: Location for generated technical specification
- **epic_id**: Used in output filename (extracted from PRD or prompted)
- **recommended_inputs**: PRD, architecture, front-end spec, brownfield notes
## Workflow Structure
### Files Included
```
tech-spec/
├── workflow.yaml # Configuration and metadata
├── instructions.md # Step-by-step execution guide
├── template.md # Technical specification structure
├── checklist.md # Validation criteria
└── README.md # This file
```
## Workflow Process
### Phase 1: Input Collection and Analysis (Steps 1-2)
- **Document Discovery**: Locates PRD and Architecture documents
- **Epic Extraction**: Identifies epic title and ID from PRD content
- **Template Initialization**: Creates tech-spec document from template
- **Context Analysis**: Reviews complete PRD and architecture for alignment
### Phase 2: Technical Design Specification (Step 3)
- **Service Architecture**: Defines services/modules with responsibilities and interfaces
- **Data Modeling**: Specifies entities, schemas, and relationships
- **API Design**: Documents endpoints, request/response models, and error handling
- **Workflow Definition**: Details sequence flows and data processing patterns
### Phase 3: Non-Functional Requirements (Step 4)
- **Performance Specs**: Defines measurable latency, throughput, and scalability targets
- **Security Requirements**: Specifies authentication, authorization, and data protection
- **Reliability Standards**: Documents availability, recovery, and degradation behavior
- **Observability Framework**: Defines logging, metrics, and tracing requirements
### Phase 4: Dependencies and Integration (Step 5)
- **Dependency Analysis**: Scans repository for package manifests and frameworks
- **Integration Mapping**: Identifies external systems and API dependencies
- **Version Management**: Documents version constraints and compatibility requirements
- **Infrastructure Needs**: Specifies deployment and runtime dependencies
### Phase 5: Acceptance and Testing (Step 6)
- **Criteria Normalization**: Extracts and refines acceptance criteria from PRD
- **Traceability Matrix**: Maps acceptance criteria to technical components
- **Test Strategy**: Defines testing approach for each acceptance criterion
- **Component Mapping**: Links requirements to specific APIs and modules
### Phase 6: Risk and Validation (Steps 7-8)
- **Risk Assessment**: Identifies technical risks, assumptions, and open questions
- **Mitigation Planning**: Provides strategies for addressing identified risks
- **Quality Validation**: Ensures specification meets completeness criteria
- **Checklist Verification**: Validates against workflow quality standards
## Output
### Generated Files
- **Primary output**: tech-spec-{epic_id}-{date}.md
- **Traceability data**: Embedded mapping tables linking requirements to implementation
### Output Structure
1. **Overview and Scope** - Project context and boundaries
2. **System Architecture Alignment** - Connection to architecture
3. **Detailed Design** - Services, data models, APIs, and workflows
4. **Non-Functional Requirements** - Performance, security, reliability, observability
5. **Dependencies and Integrations** - External systems and technical dependencies
6. **Acceptance Criteria** - Testable requirements from PRD
7. **Traceability Mapping** - Requirements-to-implementation mapping
8. **Test Strategy** - Testing approach and framework alignment
9. **Risks and Assumptions** - Technical risks and mitigation strategies
## Requirements
- **PRD Document**: Product Requirements Document with clear acceptance criteria
- **Architecture Document**: architecture or technical design
- **Repository Access**: For dependency analysis and framework detection
- **Epic Context**: Clear epic identification and scope definition
## Best Practices
### Before Starting
1. **Validate Inputs**: Ensure PRD and architecture documents are complete and current
2. **Review Requirements**: Confirm acceptance criteria are specific and testable
3. **Check Dependencies**: Verify repository structure supports automated dependency analysis
### During Execution
1. **Maintain Traceability**: Ensure every acceptance criterion maps to implementation
2. **Be Implementation-Specific**: Provide concrete technical guidance, not high-level concepts
3. **Consider Constraints**: Factor in existing system limitations and brownfield challenges
### After Completion
1. **Architect Review**: Have technical lead validate design decisions
2. **Developer Walkthrough**: Ensure implementation team understands specifications
3. **Test Planning**: Use traceability matrix for test case development
## Troubleshooting
### Common Issues
**Issue**: Missing or incomplete technical details
- **Solution**: Review architecture document for implementation specifics
- **Check**: Ensure PRD contains sufficient functional requirements detail
**Issue**: Acceptance criteria don't map cleanly to technical components
- **Solution**: Break down complex criteria into atomic, testable statements
- **Check**: Verify PRD acceptance criteria are properly structured
**Issue**: Dependency analysis fails or is incomplete
- **Solution**: Check repository structure and manifest file locations
- **Check**: Verify repository contains standard dependency files (package.json, etc.)
**Issue**: Non-functional requirements are too vague
- **Solution**: Extract specific performance and quality targets from architecture
- **Check**: Ensure architecture document contains measurable NFR specifications
## Customization
To customize this workflow:
1. **Modify Template**: Update template.md to match organizational technical spec standards
2. **Extend Dependencies**: Add support for additional package managers or frameworks
3. **Enhance Validation**: Extend checklist.md with company-specific technical criteria
4. **Add Sections**: Include additional technical concerns like DevOps or monitoring
## Version History
- **v6.0.0** - Comprehensive technical specification with traceability
- PRD-Architecture integration
- Automated dependency detection
- Traceability mapping
- Test strategy alignment
## Support
For issues or questions:
- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
- Validate output using `checklist.md`
- Ensure PRD and architecture documents are complete before starting
- Consult BMAD documentation for technical specification standards
---
_Part of the BMad Method v6 - BMM (Method) Module_

17
bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md Normal file
View File

@@ -0,0 +1,17 @@
# Tech Spec Validation Checklist
```xml
<checklist id="bmad/bmm/workflows/4-implementation/epic-tech-context/checklist">
<item>Overview clearly ties to PRD goals</item>
<item>Scope explicitly lists in-scope and out-of-scope</item>
<item>Design lists all services/modules with responsibilities</item>
<item>Data models include entities, fields, and relationships</item>
<item>APIs/interfaces are specified with methods and schemas</item>
<item>NFRs: performance, security, reliability, observability addressed</item>
<item>Dependencies/integrations enumerated with versions where known</item>
<item>Acceptance criteria are atomic and testable</item>
<item>Traceability maps AC → Spec → Components → Tests</item>
<item>Risks/assumptions/questions listed with mitigation/next steps</item>
<item>Test strategy covers all ACs and critical paths</item>
</checklist>
```

160
bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md Normal file
View File

@@ -0,0 +1,160 @@
<!-- BMAD BMM Tech Spec Workflow Instructions (v6) -->
```xml
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
<critical>Communicate all responses in {communication_language}</critical>
<critical>This workflow generates a comprehensive Technical Specification from PRD and Architecture, including detailed design, NFRs, acceptance criteria, and traceability mapping.</critical>
<critical>If required inputs cannot be auto-discovered HALT with a clear message listing missing documents, allow user to provide them to proceed.</critical>
<workflow>
<step n="1" goal="Collect inputs and discover next epic" tag="sprint-status">
<action>Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths.</action>
<ask if="inputs are missing">ask the user for file paths. HALT and wait for docs to proceed</ask>
<!-- Intelligent Epic Discovery -->
<critical>MUST read COMPLETE sprint-status.yaml file to discover next epic</critical>
<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
<action>Read ALL development_status entries</action>
<action>Find all epics with status "backlog" (not yet contexted)</action>
<action>Identify the FIRST backlog epic as the suggested default</action>
<check if="backlog epics found">
<output>📋 **Next Epic Suggested:** Epic {{suggested_epic_id}}: {{suggested_epic_title}}</output>
<ask>Use this epic?
- [y] Yes, use {{suggested_epic_id}}
- [n] No, let me specify a different epic_id
</ask>
<check if="user selects 'n'">
<ask>Enter the epic_id you want to context</ask>
<action>Store user-provided epic_id as {{epic_id}}</action>
</check>
<check if="user selects 'y'">
<action>Use {{suggested_epic_id}} as {{epic_id}}</action>
</check>
</check>
<check if="no backlog epics found">
<output>✅ All epics are already contexted!
No epics with status "backlog" found in sprint-status.yaml.
</output>
<ask>Do you want to re-context an existing epic? Enter epic_id or [q] to quit:</ask>
<check if="user enters epic_id">
<action>Store as {{epic_id}}</action>
</check>
<check if="user enters 'q'">
<action>HALT - No work needed</action>
</check>
</check>
<action>Extract {{epic_title}} from PRD based on {{epic_id}}.</action>
<action>Resolve output file path using workflow variables and initialize by writing the template.</action>
</step>
<step n="2" goal="Validate epic exists in sprint status" tag="sprint-status">
<action>Look for epic key "epic-{{epic_id}}" in development_status (already loaded from step 1)</action>
<action>Get current status value if epic exists</action>
<check if="epic not found">
<output>⚠️ Epic {{epic_id}} not found in sprint-status.yaml
This epic hasn't been registered in the sprint plan yet.
Run sprint-planning workflow to initialize epic tracking.
</output>
<action>HALT</action>
</check>
<check if="epic status == 'contexted'">
<output>ℹ️ Epic {{epic_id}} already marked as contexted
Continuing to regenerate tech spec...
</output>
</check>
</step>
<step n="3" goal="Overview and scope">
<action>Read COMPLETE found {recommended_inputs}.</action>
<template-output file="{default_output_file}">
Replace {{overview}} with a concise 1-2 paragraph summary referencing PRD context and goals
Replace {{objectives_scope}} with explicit in-scope and out-of-scope bullets
Replace {{system_arch_alignment}} with a short alignment summary to the architecture (components referenced, constraints)
</template-output>
</step>
<step n="4" goal="Detailed design">
<action>Derive concrete implementation specifics from all {recommended_inputs} (CRITICAL: NO invention). If a epic tech spec precedes this one and exists, maintain consistency where appropriate.</action>
<template-output file="{default_output_file}">
Replace {{services_modules}} with a table or bullets listing services/modules with responsibilities, inputs/outputs, and owners
Replace {{data_models}} with normalized data model definitions (entities, fields, types, relationships); include schema snippets where available
Replace {{apis_interfaces}} with API endpoint specs or interface signatures (method, path, request/response models, error codes)
Replace {{workflows_sequencing}} with sequence notes or diagrams-as-text (steps, actors, data flow)
</template-output>
</step>
<step n="5" goal="Non-functional requirements">
<template-output file="{default_output_file}">
Replace {{nfr_performance}} with measurable targets (latency, throughput); link to any performance requirements in PRD/Architecture
Replace {{nfr_security}} with authn/z requirements, data handling, threat notes; cite source sections
Replace {{nfr_reliability}} with availability, recovery, and degradation behavior
Replace {{nfr_observability}} with logging, metrics, tracing requirements; name required signals
</template-output>
</step>
<step n="6" goal="Dependencies and integrations">
<action>Scan repository for dependency manifests (e.g., package.json, pyproject.toml, go.mod, Unity Packages/manifest.json).</action>
<template-output file="{default_output_file}">
Replace {{dependencies_integrations}} with a structured list of dependencies and integration points with version or commit constraints when known
</template-output>
</step>
<step n="7" goal="Acceptance criteria and traceability">
<action>Extract acceptance criteria from PRD; normalize into atomic, testable statements.</action>
<template-output file="{default_output_file}">
Replace {{acceptance_criteria}} with a numbered list of testable acceptance criteria
Replace {{traceability_mapping}} with a table mapping: AC → Spec Section(s) → Component(s)/API(s) → Test Idea
</template-output>
</step>
<step n="8" goal="Risks and test strategy">
<template-output file="{default_output_file}">
Replace {{risks_assumptions_questions}} with explicit list (each item labeled as Risk/Assumption/Question) with mitigation or next step
Replace {{test_strategy}} with a brief plan (test levels, frameworks, coverage of ACs, edge cases)
</template-output>
</step>
<step n="9" goal="Validate and mark epic contexted" tag="sprint-status">
<invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
<!-- Mark epic as contexted -->
<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
<action>Find development_status key "epic-{{epic_id}}"</action>
<action>Verify current status is "backlog" (expected previous state)</action>
<action>Update development_status["epic-{{epic_id}}"] = "contexted"</action>
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
<check if="epic key not found in file">
<output>⚠️ Could not update epic status: epic-{{epic_id}} not found</output>
</check>
<output>**✅ Tech Spec Generated Successfully, {user_name}!**
**Epic Details:**
- Epic ID: {{epic_id}}
- Epic Title: {{epic_title}}
- Tech Spec File: {{default_output_file}}
- Epic Status: contexted (was backlog)
**Note:** This is a JIT (Just-In-Time) workflow - run again for other epics as needed.
**Next Steps:**
1. Load SM agent and run `create-story` to begin implementing the first story under this epic.
</output>
</step>
</workflow>
```

76
bmad/bmm/workflows/4-implementation/epic-tech-context/template.md Normal file
View File

@@ -0,0 +1,76 @@
# Epic Technical Specification: {{epic_title}}
Date: {{date}}
Author: {{user_name}}
Epic ID: {{epic_id}}
Status: Draft
---
## Overview
{{overview}}
## Objectives and Scope
{{objectives_scope}}
## System Architecture Alignment
{{system_arch_alignment}}
## Detailed Design
### Services and Modules
{{services_modules}}
### Data Models and Contracts
{{data_models}}
### APIs and Interfaces
{{apis_interfaces}}
### Workflows and Sequencing
{{workflows_sequencing}}
## Non-Functional Requirements
### Performance
{{nfr_performance}}
### Security
{{nfr_security}}
### Reliability/Availability
{{nfr_reliability}}
### Observability
{{nfr_observability}}
## Dependencies and Integrations
{{dependencies_integrations}}
## Acceptance Criteria (Authoritative)
{{acceptance_criteria}}
## Traceability Mapping
{{traceability_mapping}}
## Risks, Assumptions, Open Questions
{{risks_assumptions_questions}}
## Test Strategy Summary
{{test_strategy}}

32
bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml Normal file
View File

@@ -0,0 +1,32 @@
name: tech-spec
description: "Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping"
author: "BMAD BMM"
# Critical 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
# Inputs expected ( check output_folder or ask user if missing)
recommended_inputs:
- prd
- gdd
- spec
- architecture
- ux_spec
- ux-design
- if there is an index.md then read the index.md to find other related docs that could be relevant
- prior epic tech-specs for model, style and consistency reference
# Workflow components
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context"
template: "{installed_path}/template.md"
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
# Output configuration
default_output_file: "{output_folder}/tech-spec-epic-{{epic_id}}.md"
standalone: true