hash file change checking integrated
This commit is contained in:
Brian Madison
@@ -1,195 +0,0 @@
|
||||
# Technical Specification Workflow
|
||||
|
||||
## Overview
|
||||
|
||||
Generate a comprehensive Technical Specification from PRD and Architecture with 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 high-level 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**: High-level 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_
|
||||
@@ -1,17 +0,0 @@
|
||||
# Tech Spec Validation Checklist
|
||||
|
||||
```xml
|
||||
<checklist id="bmad/bmm/workflows/3-solutioning/tech-spec/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>
|
||||
```
|
||||
@@ -1,73 +0,0 @@
|
||||
<!-- BMAD BMM Tech Spec Workflow Instructions (v6) -->
|
||||
|
||||
```xml
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>This workflow generates a comprehensive Technical Specification from PRD and Architecture, including detailed design, NFRs, acceptance criteria, and traceability mapping.</critical>
|
||||
<critical>Default execution mode: #yolo (non-interactive). If required inputs cannot be auto-discovered and {{non_interactive}} == true, HALT with a clear message listing missing documents; do not prompt.</critical>
|
||||
|
||||
<workflow>
|
||||
<step n="1" goal="Collect inputs and initialize">
|
||||
<action>Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths.</action>
|
||||
<ask optional="true" if="{{non_interactive}} == false">If inputs are missing, ask the user for file paths.</ask>
|
||||
<check>If inputs are missing and {{non_interactive}} == true → HALT with a clear message listing missing documents.</check>
|
||||
<action>Extract {{epic_title}} and {{epic_id}} from PRD (or ASK if not present).</action>
|
||||
<action>Resolve output file path using workflow variables and initialize by writing the template.</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Overview and scope">
|
||||
<action>Read COMPLETE PRD and Architecture files.</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="3" goal="Detailed design">
|
||||
<action>Derive concrete implementation specifics from Architecture and PRD (NO invention).</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="4" 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="5" 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="6" 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="7" 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="8" goal="Validate">
|
||||
<invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.md</invoke-task>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
```
|
||||
@@ -1,76 +0,0 @@
|
||||
# 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}}
|
||||
@@ -1,51 +0,0 @@
|
||||
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 (ask user if missing)
|
||||
recommended_inputs:
|
||||
- prd: "{project-root}/docs/prd.md"
|
||||
- architecture: "{project-root}/docs/architecture.md"
|
||||
- frontend_spec: "{project-root}/docs/front-end-spec.md"
|
||||
- brownfield_notes: "{project-root}/docs/brownfield-notes.md"
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning/tech-spec"
|
||||
template: "{installed_path}/template.md"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{project-root}/docs/tech-spec-epic-{{epic_id}}.md"
|
||||
|
||||
# Required tools
|
||||
required_tools:
|
||||
- list_files
|
||||
- file_info
|
||||
- read_file
|
||||
- write_file
|
||||
- search_repo
|
||||
- glob
|
||||
- parse_markdown
|
||||
|
||||
tags:
|
||||
- tech-spec
|
||||
- architecture
|
||||
- planning
|
||||
- bmad-v6
|
||||
|
||||
execution_hints:
|
||||
interactive: false
|
||||
autonomous: true
|
||||
iterative: true
|
||||
|
||||
# Variables
|
||||
variables:
|
||||
non_interactive: true
|
||||
Reference in New Issue
Block a user