zhongwei/gh-adrianpuiu-specification-document-generator-architecture-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 17:50:59 +08:00
commit 7f42d64263
19 changed files with 2908 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "architecture-skills",
"description": "Collection of architectural documentation and specification generation skills",
"version": "0.0.0-2025.11.28",
"author": {
"name": "George A Puiu",
"email": "puiu.adrian@gmail.com"
},
"skills": [
"./skills/specification-architect"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# architecture-skills
Collection of architectural documentation and specification generation skills

104
plugin.lock.json Normal file
View File

@@ -0,0 +1,104 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:adrianpuiu/specification-document-generator:architecture-skills",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "a05ffc0b61bcf2dce213b9e3ba922d1815a65328",
"treeHash": "ea165f6a6b3b2e9cc1e06e1d131635743f7935b17b60aa6112a00b7ecfd31855",
"generatedAt": "2025-11-28T10:13:01.882699Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "architecture-skills",
"description": "Collection of architectural documentation and specification generation skills"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "aa46d2fd2965f0167381040bd508f0bd3fa404410c70c3b6f8bfa641a4925de5"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "ffbef060d9408d45a42636730dcd2a7c0a1fbaa6f793c18b4d7dc3fc314ee92d"
},
{
"path": "skills/specification-architect/validate.bat",
"sha256": "fab04fc5e2cf1a8c0928b6e0cf5c808a211dbf8e206537dfa0f2f6c8a244ab38"
},
{
"path": "skills/specification-architect/validate.sh",
"sha256": "2ba7305a92e7696e0a522e6cbe942b18d3da600ae80c842cba3c0455086da0dd"
},
{
"path": "skills/specification-architect/validate_specifications.py",
"sha256": "429531bd3d64e5d712ad51897564325d6023290a66fb4cff8602d24150df8453"
},
{
"path": "skills/specification-architect/plugin.json",
"sha256": "ac420827bbe164e48f9a663864e55b1b7052f15b0b1343ce2c36b70f0e3ad78d"
},
{
"path": "skills/specification-architect/README.md",
"sha256": "942130a3dc0f15008e125373754bb8984cfcd2a93016c429f2dedc841dc99ffd"
},
{
"path": "skills/specification-architect/SKILL.md",
"sha256": "caa270d54420e9bd0e1d9e7ed590d6c10c7bae07a622e08ace3411a1db5f03ff"
},
{
"path": "skills/specification-architect/VALIDATION_SCRIPTS_README.md",
"sha256": "e23e0d50142625c4b6860691efd0224c71a1cb9be75eb425bd45c0dd3777fa2f"
},
{
"path": "skills/specification-architect/references/document_templates.md",
"sha256": "2b1130d5acb9bc10c23b6d7fc33de89529ebbc55ae2b25a5e5cd709058d7df12"
},
{
"path": "skills/specification-architect/scripts/traceability_validator.py",
"sha256": "8d896f3fd28f47171c4af9c141193ff1b66a4ef591dfaea981a9e6296aef417d"
},
{
"path": "skills/specification-architect/assets/sample_outputs/example_tasks.md",
"sha256": "d23924fbc0b78710d062eb1891391c31575da6d855ac98cfbe265c798828272a"
},
{
"path": "skills/specification-architect/assets/sample_outputs/example_design.md",
"sha256": "c8b76c46cf98eaa08ea04a22206f2c7fdd6b7dc8629f10f432b7f4b53140be4f"
},
{
"path": "skills/specification-architect/assets/sample_outputs/example_requirements.md",
"sha256": "7e56d4ca9196f4caea398ab68f35b995c7d9a663e52c25c4f3ff176319e3dea0"
},
{
"path": "skills/specification-architect/assets/sample_outputs/example_blueprint.md",
"sha256": "03dc691cb51c2d14545d014bf2fa1b15c7b0cfccc5a1cd9033d3423c717cbb49"
},
{
"path": "skills/specification-architect/assets/sample_outputs/example_research.md",
"sha256": "40913d76ad2002b9303d3c52db215c86a72319d0f2f3621de3bba03791d776d2"
},
{
"path": "skills/specification-architect/assets/sample_outputs/example_verifiable_research.md",
"sha256": "5a091a2bd64092b1687bd72bbea705e9ab795aaf5dc0ee79c25ffbc836a2a848"
},
{
"path": "skills/specification-architect/assets/sample_outputs/example_validation.md",
"sha256": "e623b7d38c9dfd3d9ba40fd37787540d4f307f2b1bf707b2e09868b9af497461"
}
],
"dirSha256": "ea165f6a6b3b2e9cc1e06e1d131635743f7935b17b60aa6112a00b7ecfd31855"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

78
skills/specification-architect/README.md Normal file
View File

@@ -0,0 +1,78 @@
# Specification Architect Skill
An AI skill that generates rigorous, evidence-based architectural documentation with complete traceability.
## Quick Start
### Generate Specification Documents
The skill follows a 6-phase sequential process:
1. **Phase 0: Verifiable Research** (research.md) - Evidence-based technology research with citations
2. **Phase 1: Blueprint** (blueprint.md) - Component architecture and data flow
3. **Phase 2: Requirements** (requirements.md) - Acceptance criteria with component assignments
4. **Phase 3: Design** (design.md) - Detailed component specifications
5. **Phase 4: Tasks** (tasks.md) - Implementation tasks with requirement traceability
6. **Phase 5: Validation** (validation.md) - Automated validation results
### Validation Commands
```bash
# Primary validation - ensures 100% requirements coverage
python validate_specifications.py
# With options
python validate_specifications.py --path ./specs --verbose --generate-validation
# Advanced traceability validation
python scripts/traceability_validator.py
```
### Cross-Platform Helpers
```bash
# Linux/macOS
./validate.sh --verbose --generate
# Windows
validate.bat --verbose --generate
```
## Key Files
- **validate_specifications.py** - Main validation script
- **scripts/traceability_validator.py** - Advanced traceability validation
- **SKILL.md** - Complete skill documentation
- **references/document_templates.md** - Template examples and format specifications
- **assets/sample_outputs/** - Example generated documents
## Validation Exit Codes
- **0**: Success (100% coverage achieved)
- **1**: Failure (missing files, incomplete coverage, format errors)
## Evidence-Based Research Protocol
This skill implements a strict anti-"research slop" protocol:
1. **Search THEN Browse**: Use WebSearch to find sources, then WebFetch to read actual content
2. **Cite Every Claim**: Every factual statement must end with `[cite:INDEX]` citation
3. **Verify Sources**: Read full source content, not just search snippets
4. **Auditable Trail**: Complete citation trail from claim to source
## Quality Assurance
The validation system ensures:
- All required documents exist
- Component names are consistent across documents
- Requirements have 100% task coverage
- Citations follow proper format
- Templates are correctly implemented
## License
MIT
## Author
George A Puiu (puiu.adrian@gmail.com)

328
skills/specification-architect/SKILL.md Normal file
View File

@@ -0,0 +1,328 @@
---
name: specification-architect
description: A rigorous, traceability-first system that generates five interconnected architectural documents (blueprint.md, requirements.md, design.md, tasks.md, and validation.md) with complete requirements-to-implementation traceability. Use this skill when users need to architect systems, create technical specifications, or develop structured project documentation with guaranteed traceability.
---
# Specification Architect AI
## Overview
This skill implements a rigorous, evidence-based system for generating architectural documentation that eliminates "research slop" and prevents AI-generated misinformation. It produces five interconnected markdown documents where every technological decision is backed by verifiable sources and complete traceability from research through implementation tasks.
**Core Principle**: Every claim must be supported by evidence. No AI-generated "facts" without verification.
## When to Use This Skill
Use this skill when users request:
- System architecture documentation
- Technical specifications for software projects
- Requirements analysis and traceability
- Implementation planning with validation
- Project documentation with structured methodology
## Prompt Optimization Guidelines
**The quality of architectural specifications is directly proportional to the clarity of upfront goals and boundaries.**
### For Best Results, Include in Your Request:
1. **Clear Business Objectives**
- What problem are you solving?
- Who are the users/stakeholders?
- What does success look like?
2. **Specific Constraints and Boundaries**
- Technology preferences or restrictions
- Performance requirements
- Security/compliance requirements
- Integration constraints
3. **Scope Definition**
- Must-have features vs. nice-to-haves
- Explicit out-of-scope items
- Timeline and resource constraints
4. **Context and Background**
- Existing systems to integrate with
- Team capabilities and expertise
- Previous attempts or solutions
### Example Effective Prompt:
```
"I need to architect a customer support ticket system for a mid-sized SaaS company.
The system must handle 10,000 tickets/month, integrate with our existing Salesforce CRM,
and comply with GDPR requirements. We need email integration, knowledge base search,
and reporting dashboards. Please do NOT include live chat or phone support features.
Our team specializes in Python/React and we need this deployed on AWS."
```
**Why This Works**:
- ✅ Clear business context (customer support for SaaS)
- ✅ Specific constraints (10k tickets/month, GDPR, AWS)
- ✅ Technology preferences (Python/React)
- ✅ Clear scope boundaries (no live chat/phone)
- ✅ Integration requirements (Salesforce)
- ✅ Success metrics (email, knowledge base, reporting)
## How to Use This Skill
Follow the five-phase process in sequence:
### Phase 0: Verifiable Research and Technology Selection
**GOAL**: To produce a technology proposal where every claim is supported by verifiable, browsed sources, thereby eliminating "research slop" and grounding the architecture in factual evidence.
**CRITICAL**: This phase prevents AI-generated misinformation that could lead to serious professional consequences. **You MUST complete this phase with proper verification before proceeding.**
#### Strict Protocol:
1. **Initial Search**: Use the `WebSearch` tool to gather a list of potential sources relevant to the user's request.
2. **Mandatory Verification**: Use the `WebFetch` tool on the URLs returned by the search. **You MUST NOT rely on search snippets alone.** You must read the content of the pages to confirm the information.
3. **Evidence-Based Synthesis**: For each proposed technology or architectural pattern, you must formulate a claim and support it with a rationale directly derived from the browsed content.
4. **Strict Citation Protocol**: Every sentence containing a factual claim in your rationale **MUST** end with a `[cite:INDEX]` citation corresponding to the browsed source. This creates an auditable trail from claim to evidence.
#### Research Process:
1. **Analyze User Request**
- Identify core domain (e.g., e-commerce, IoT, fintech, healthcare)
- Extract key requirements (scale, performance, security, integrations)
- Note any specific technology constraints or preferences
2. **Execute Research with Verification**
- Use `WebSearch` to find relevant sources for domain architecture patterns
- Use `WebFetch` to browse and verify each source's content
- Research technology options with current best practices
- Investigate integration approaches and deployment strategies
3. **Synthesize Evidence-Based Recommendations**
- Create technology recommendations ONLY from verified sources
- Support every claim with citations from browsed content
- Compare options using evidence, not assumptions
- Justify decisions with specific source references
#### Strict Output Template:
```markdown
# Verifiable Research and Technology Proposal
## 1. Core Problem Analysis
[A brief, 1-2 sentence analysis of the user's request and the primary technical challenges.]
## 2. Verifiable Technology Recommendations
| Technology/Pattern | Rationale & Evidence |
|---|---|
| **[Technology Name]** | [Rationale derived from browsed sources, with every factual claim cited.] |
| **[Pattern Name]** | [Rationale derived from browsed sources, with every factual claim cited.] |
## 3. Browsed Sources
- [1] [URL of browsed source 1]
- [2] [URL of browsed source 2]
- [...]
```
**Citation Requirements**:
- Every factual claim MUST end with `[cite:INDEX]` citation
- Citations must correspond to numbered browsed sources
- No technology recommendations allowed without source evidence
- All rationales must be derived from actual browsed content
**Example of Proper Citation**:
"Node.js excels at real-time applications due to its event-driven, non-blocking I/O model [cite:1]. TypeScript adds static typing that reduces runtime errors by approximately 15% in large codebases [cite:2]."
**Approval Gate**: "Research complete. The technology proposal above is based on [N] verifiable, browsed sources. Every claim is cited and traceable to evidence. Proceed to define the architectural blueprint?"
### Phase 1: Architectural Blueprint (blueprint.md)
**PREREQUISITE**: Approval of the technology stack
**GOAL**: To establish a high-level map of the system, its components, interactions, and boundaries
**CRITICAL SUCCESS FACTORS**:
- **Component Clarity**: Each component must have a single, well-defined responsibility
- **Data Flow Visualization**: Map how data moves through the system from input to output
- **Integration Points**: Clearly define all APIs, protocols, and external system connections
- **Boundaries Setting**: Explicitly define what's in scope vs. out of scope to prevent scope creep
**STRICT TEMPLATE**:
```markdown
# Architectural Blueprint
## 1. Core Objective
[Single paragraph defining the primary goal and what success looks like.]
## 2. System Scope and Boundaries
### In Scope
- [Specific feature 1 that WILL be built]
- [Specific capability 2 that WILL be implemented]
- [Integration 1 that WILL be supported]
### Out of Scope
- [Feature 1 that will NOT be built - prevents scope creep]
- [External system 1 that will NOT be integrated]
- [Technology 1 that will NOT be used]
## 3. Core System Components
| Component Name | Single Responsibility |
|---|---|
| **[ComponentName1]** | [One clear, focused responsibility - what this component DOES] |
| **[ComponentName2]** | [One clear, focused responsibility - what this component DOES] |
| **[ComponentName3]** | [One clear, focused responsibility - what this component DOES] |
## 4. High-Level Data Flow
```mermaid
graph TD
A[External Input/User] --> B[ComponentName1]
B --> C[ComponentName2]
C --> D[ComponentName3]
D --> E[External Output/Result]
%% Style components for clarity
style ComponentName1 fill:#e1f5fe
style ComponentName2 fill:#f3e5f5
style ComponentName3 fill:#e8f5e8
```
## 5. Key Integration Points
- **[ComponentName1] ↔ [ComponentName2]**: [API/Protocol - e.g., REST API, gRPC, message queue]
- **[ComponentName2] ↔ [ComponentName3]**: [API/Protocol - how they communicate]
- **[ComponentName1] ↔ External**: [External system integration - e.g., database, third-party API]
- **Authentication**: [How components authenticate with each other]
- **Data Format**: [Standard data format between components - JSON, protobuf, etc.]
```
**Quality Gates**:
- Are component responsibilities clear and non-overlapping?
- Does the data flow diagram show the complete journey from input to output?
- Are all integration points clearly specified with protocols?
- Are in/out scope boundaries unambiguous?
**Approval Gate**: "Architectural blueprint complete with clear component mapping, data flow visualization, and integration points. The component names defined here will be used consistently across all documents. Proceed to generate requirements?"
### Phase 2: Requirements Generation (requirements.md)
**PREREQUISITE**: Approval of the blueprint
**RULE**: All `[System Component]` placeholders MUST use the exact component names from the blueprint
**STRICT TEMPLATE**:
```markdown
# Requirements Document
[Introduction and Glossary...]
## Requirements
### Requirement 1: [Feature Name]
#### Acceptance Criteria
1. WHEN [trigger], THE **[ComponentName1]** SHALL [specific, testable behavior].
```
**Approval Gate**: "Requirements documented with [N] requirements and [M] acceptance criteria, each assigned to a specific component. Proceed to detailed design?"
### Phase 3: Detailed Design (design.md)
**PREREQUISITE**: Approval of requirements
**GOAL**: To elaborate on the blueprint with detailed specifications for each component
**STRICT TEMPLATE**:
```markdown
# Design Document
[Overview, Principles...]
## Component Specifications
#### Component: [ComponentName1]
**Purpose**: [Responsibility from blueprint]
**Location**: `path/to/component.py`
**Interface**: [Code block with methods and requirement references, e.g., `Implements Req 1.1`]
```
**Approval Gate**: "Detailed design complete. All components from the blueprint have been specified. Proceed to generate implementation tasks?"
### Phase 4: Task Decomposition (tasks.md)
**PREREQUISITE**: Approval of the design
**GOAL**: To create a granular, actionable implementation plan
**STRICT TEMPLATE**:
```markdown
# Implementation Plan
- [ ] 1. Implement the [ComponentName1]
- [ ] 1.1 [Specific action, e.g., "Create class in file.py"]
- [ ] 1.2 [Specific action, e.g., "Implement method_x()"]
- _Requirements: 1.1, 1.2, 2.3_
```
**Approval Gate**: "Implementation plan created with [N] tasks. Proceed to final validation?"
### Phase 5: Validation and Traceability (validation.md)
**PREREQUISITE**: Generation of all previous documents
**GOAL**: To perform a final, automated check that guarantees complete traceability from requirements to implementation tasks
**STRICT TEMPLATE**:
```markdown
# Validation Report
## 1. Requirements to Tasks Traceability Matrix
| Requirement | Acceptance Criterion | Implementing Task(s) | Status |
|---|---|---|---|
| 1. [Name] | 1.1 | Task 2, Task 5 | Covered |
| | 1.2 | Task 2, Task 3 | Covered |
| ... | ... | ... | ... |
| X. [Name] | X.Y | Task Z | Covered |
## 2. Coverage Analysis
### Summary
- **Total Acceptance Criteria**: [M]
- **Criteria Covered by Tasks**: [M]
- **Coverage Percentage**: 100%
### Detailed Status
- **Covered Criteria**: A list of all X.Y references that are successfully mapped to at least one task.
- **Missing Criteria**: A list of any X.Y references from `requirements.md` that were NOT found in any task's `_Requirements_` tag. **This list must be empty to pass validation.**
- **Invalid References**: A list of any task references (e.g., `_Requirements: 9.9_`) that do not correspond to a real acceptance criterion. **This list must be empty to pass validation.**
## 3. Final Validation
All [M] acceptance criteria are fully traced to implementation tasks. The plan is validated and ready for execution.
```
**Final Approval Gate**: "Validation complete. Traceability matrix confirms 100% coverage. Type 'execute' to begin implementation."
## Key Principles
1. **Traceability First**: Every requirement must be traced to implementation tasks
2. **Approval Gates**: Get explicit approval before proceeding to next phase
3. **Template Adherence**: Use the exact document templates provided
4. **Component Consistency**: Use identical component names across all documents
5. **Validation Guarantees**: Ensure 100% coverage before completion
## Research Guidelines
When conducting research in Phase 0:
1. **Identify Core Challenges**: Analyze the user's request to determine technical domains
2. **Search Current Best Practices**: Use `WebSearch` with specific queries about:
- Current architectural patterns for the domain
- Recommended technology stacks
- Industry standards and conventions
- Recent advancements or alternatives
3. **Evaluate Options**: Compare multiple approaches and justify the selected stack
4. **Document Rationale**: Briefly explain why each technology was chosen
## Validation Process
The validation phase ensures:
1. **Complete Coverage**: Every acceptance criterion from requirements.md is referenced in at least one task
2. **Valid References**: All task requirement references correspond to real acceptance criteria
3. **Traceability Matrix**: Clear mapping from requirements through tasks
4. **100% Success Rate**: Validation only passes when coverage is complete
## Files Referenced
- `scripts/traceability_validator.py` - Python script for automated validation
- `references/document_templates.md` - Detailed templates and examples
- `assets/sample_outputs/` - Example of complete specification documents
## Execution Workflow
1. **Phase 0**: Research → Get approval
2. **Phase 1**: Blueprint → Get approval
3. **Phase 2**: Requirements → Get approval
4. **Phase 3**: Design → Get approval
5. **Phase 4**: Tasks → Get approval
6. **Phase 5**: Validation → Get final approval
Each phase must be completed and approved before proceeding to the next phase. The final validation confirms 100% traceability and coverage.

403
skills/specification-architect/VALIDATION_SCRIPTS_README.md Normal file
View File

@@ -0,0 +1,403 @@
# Validation Scripts Documentation
This directory includes automated validation scripts that verify complete traceability across all five specification documents.
## Quick Start
### Linux/macOS
```bash
# Make script executable
chmod +x validate.sh
# Basic validation
./validate.sh
# Validate specific directory
./validate.sh --path ./specs
# Generate validation.md
./validate.sh --generate
# Verbose output
./validate.sh --verbose
```
### Windows
```cmd
# Basic validation
validate.bat
# Validate specific directory
validate.bat --path .\specs
# Generate validation.md
validate.bat --generate
# Verbose output
validate.bat --verbose
```
### Python (Cross-Platform)
```bash
# Basic validation
python validate_specifications.py
# Validate specific directory
python validate_specifications.py --path ./specs
# Generate validation.md
python validate_specifications.py --generate-validation
# JSON output
python validate_specifications.py --json
# Verbose mode
python validate_specifications.py --verbose
```
## What Gets Validated
The scripts perform comprehensive validation checks:
1. **File Presence**
- blueprint.md exists
- requirements.md exists
- design.md exists
- tasks.md exists
2. **Component Consistency**
- All components from blueprint.md are used in requirements.md
- No undefined components are referenced
- Component names match exactly (case-sensitive)
3. **Requirements Format**
- Requirement numbers: "### Requirement N: [Name]"
- Acceptance criteria: "N. WHEN ... THE **ComponentName** SHALL ..."
- Criteria use decimal notation (1.1, 1.2, 2.1, etc.)
4. **Task Requirements Tags**
- All tasks include `_Requirements: X.Y, X.Z, ..._` tags
- All referenced criteria IDs are valid
- Format is correct with underscores and spaces
5. **Traceability Coverage**
- Every acceptance criterion is referenced in at least one task
- No orphaned requirements exist
- No invalid requirement references
6. **Coverage Calculation**
- Total acceptance criteria count
- Number covered by tasks
- Coverage percentage (must be 100%)
## Output Examples
### Success (100% Coverage)
```
================================================================================
SPECIFICATION VALIDATION REPORT
================================================================================
SUMMARY
--------------------------------------------------------------------------------
Total Acceptance Criteria: 12
Criteria Covered by Tasks: 12
Coverage Percentage: 100.0%
COVERAGE STATUS
--------------------------------------------------------------------------------
✓ Covered Criteria: 12
✗ Missing Criteria: 0
! Invalid References: 0
VALIDATION STATUS
--------------------------------------------------------------------------------
✅ VALIDATION PASSED
All acceptance criteria are fully traced to implementation tasks.
```
### Failure (Incomplete Coverage)
```
MISSING CRITERIA (Not covered by any task)
--------------------------------------------------------------------------------
- 3.1
- 4.2
VALIDATION STATUS
--------------------------------------------------------------------------------
❌ VALIDATION FAILED
- 2 acceptance criteria are not covered by tasks
```
## Command Options
### --path DIR
Path to directory containing specification documents.
**Default**: `.` (current directory)
```bash
python validate_specifications.py --path /path/to/specs
```
### --verbose
Enable detailed output showing extraction progress.
```bash
./validate.sh --verbose
```
Shows:
- Components found
- Requirements extracted
- Tasks parsed
- Validation steps
### --generate-validation
Generate or update `validation.md` file with report.
```bash
python validate_specifications.py --generate-validation
```
Creates `validation.md` with:
- Traceability matrix
- Coverage analysis
- Validation status
### --json
Output results as JSON instead of human-readable text.
```bash
python validate_specifications.py --json
```
Output:
```json
{
"total_criteria": 12,
"covered_criteria": 12,
"missing_criteria": [],
"coverage_percentage": 100.0,
"is_valid": true,
"errors": [],
"warnings": []
}
```
## Exit Codes
- **0** = Success (validation passed, 100% coverage)
- **1** = Failure (incomplete coverage or errors)
Use in scripts:
```bash
python validate_specifications.py --path ./specs
if [ $? -eq 0 ]; then
echo "Deployment approved"
./deploy.sh
else
echo "Validation failed - fix requirements first"
exit 1
fi
```
## Document Format Requirements
For validation to work correctly:
### Blueprint.md Format
```markdown
## 3. Core System Components
| Component Name | Responsibility |
|---|---|
| **AuthenticationComponent** | Handles user authentication |
| **DatabaseAdapter** | Manages database connections |
```
### Requirements.md Format
```markdown
### Requirement 1: User Authentication
#### Acceptance Criteria
1. WHEN user submits credentials, THE **AuthenticationComponent** SHALL validate them.
2. WHEN validation succeeds, THE **AuthenticationComponent** SHALL return a session token.
```
### Tasks.md Format
```markdown
## Task 1: Implement AuthenticationComponent
- [ ] 1.1 Create AuthenticationComponent class
- [ ] 1.2 Implement validation method
- [ ] 1.3 Add unit tests
- _Requirements: 1.1, 1.2_
```
## Troubleshooting
### Components not extracted
**Issue**: "No components found in blueprint.md"
**Solution**: Verify format matches exactly:
- `| **ComponentName** | description |`
- Component name must be between `**` markers
- Must be in a markdown table
### Requirements not found
**Issue**: "No requirements found"
**Solution**: Use exact format:
- `### Requirement N: [Name]`
- Criteria: `N. WHEN ... THE **Component** SHALL ...`
- Must have numbers and exact spacing
### Missing criteria list has items
**Issue**: Validation fails with missing criteria
**Solution**: Add `_Requirements:` tags to all tasks:
- Format: `_Requirements: 1.1, 1.2, 3.1_`
- Underscore prefix and suffix
- Space after colon
- IDs separated by commas
### Invalid component names
**Issue**: "Unknown component: ComponentName"
**Solution**: Check spelling and capitalization:
- Use exact names from blueprint
- Names are case-sensitive
- Verify in requirements criteria
## Integration Examples
### GitHub Actions
```yaml
name: Validate Specifications
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
- name: Validate specifications
run: |
python validate_specifications.py \
--path ./specs \
--generate-validation
```
### GitLab CI
```yaml
validate_specs:
image: python:3.9
script:
- python validate_specifications.py --path ./specs --generate-validation
only:
changes:
- specs/**
```
### Local Pre-commit Hook
```bash
#!/bin/bash
python validate_specifications.py --path ./specs
if [ $? -ne 0 ]; then
echo "Specifications validation failed!"
exit 1
fi
```
## Performance
- Validates 100+ requirements in <1 second
- Handles 1000+ tasks efficiently
- Minimal memory usage
- No external dependencies
## Requirements
- **Python**: 3.7 or higher
- **Dependencies**: None (standard library only)
## File Structure
```
specification-architect-skill/
├── validate_specifications.py # Main validation script
├── validate.bat # Windows helper
├── validate.sh # Linux/macOS helper
├── VALIDATION_SCRIPTS_README.md # This file
├── SKILL.md # Full skill documentation
├── TEMPLATE_REFERENCE.md # Document templates
├── USAGE_GUIDE.md # Phase-by-phase guide
└── README.md # Quick start
```
## Complete Validation Workflow
1. **Write Specifications**
- Create blueprint.md
- Create requirements.md
- Create design.md
- Create tasks.md
2. **Run Validation**
```bash
python validate_specifications.py --path ./specs --verbose
```
3. **Review Results**
- Check coverage percentage
- Review missing criteria (if any)
- Review invalid references (if any)
4. **Fix Issues**
- Add missing requirement tags to tasks
- Fix invalid requirement references
- Update requirements if needed
5. **Validate Again**
```bash
python validate_specifications.py --path ./specs
```
6. **Generate Report**
```bash
python validate_specifications.py --path ./specs --generate-validation
```
7. **Ready to Execute**
- validation.md confirms 100% coverage
- Commit all spec files
- Begin implementation
## API Usage (Python)
Use the validator as a Python module:
```python
from validate_specifications import SpecificationValidator
# Create validator
validator = SpecificationValidator("./specs", verbose=True)
# Run validation
result = validator.validate_all()
# Check results
if result.is_valid:
print("✅ Validation passed!")
print(f"Coverage: {result.coverage_percentage}%")
else:
print(f"❌ {len(result.missing_criteria)} missing criteria")
# Generate and save validation.md
validator.save_validation_markdown()
```

60
skills/specification-architect/assets/sample_outputs/example_blueprint.md Normal file
View File

@@ -0,0 +1,60 @@
# Architectural Blueprint
## 1. Core Objective
To create a comprehensive task management system that enables users to create, assign, track, and complete tasks across multiple projects with real-time collaboration features.
## 2. System Scope and Boundaries
### In Scope
- User authentication and authorization
- Task creation, assignment, and management
- Project organization and team collaboration
- Real-time notifications and updates
- Basic reporting and analytics
### Out of Scope
- Advanced project management features (Gantt charts, critical path)
- File attachments and document management
- Integration with third-party project management tools
- Mobile application development
- Advanced workflow automation
## 3. Core System Components
| Component Name | Responsibility |
|---|---|
| **UserAuthenticationService** | Handles user registration, login, and session management |
| **TaskManagementEngine** | Core task CRUD operations and business logic |
| **ProjectOrganizer** | Manages project creation, membership, and permissions |
| **NotificationService** | Handles real-time notifications and email alerts |
| **ReportingModule** | Generates basic reports and analytics dashboards |
## 4. High-Level Data Flow
```mermaid
graph TD
A[User Interface] --> B[UserAuthenticationService]
A --> C[TaskManagementEngine]
A --> D[ProjectOrganizer]
B --> E[User Database]
C --> F[Task Database]
D --> G[Project Database]
C --> H[NotificationService]
H --> I[Email Service]
H --> J[WebSocket Service]
C --> K[ReportingModule]
K --> L[Analytics Database]
style UserAuthenticationService fill:#e1f5fe
style TaskManagementEngine fill:#f3e5f5
style ProjectOrganizer fill:#e8f5e8
style NotificationService fill:#fff3e0
style ReportingModule fill:#fce4ec
```
## 5. Key Integration Points
- **Authentication API**: JWT-based authentication between User Interface and UserAuthenticationService
- **Task API**: RESTful APIs between User Interface and TaskManagementEngine
- **Project API**: RESTful APIs between User Interface and ProjectOrganizer
- **Notification Gateway**: WebSocket connections for real-time updates
- **Email Service**: SMTP integration for email notifications
- **Database Connections**: PostgreSQL connections for all data storage components

393
skills/specification-architect/assets/sample_outputs/example_design.md Normal file
View File

@@ -0,0 +1,393 @@
# Design Document
## Overview
This document provides detailed design specifications for the TaskMaster Pro task management system components.
## Design Principles
- **Single Responsibility**: Each component has a single, well-defined responsibility
- **Loose Coupling**: Components interact through well-defined interfaces
- **High Cohesion**: Related functionality is grouped together
- **Scalability**: Design supports future growth and expansion
- **Security**: All components implement proper authentication and authorization
## Component Specifications
### Component: UserAuthenticationService
**Purpose**: Handles user registration, login, and session management
**Location**: `src/services/auth/UserAuthenticationService.py`
**Interface**:
```python
class UserAuthenticationService:
"""
User authentication and authorization service
Implements: Req 1.1, 1.2, 1.3, 1.4, 7.1, 7.2
"""
def __init__(self, user_repository: UserRepository, email_service: EmailService):
"""Initialize authentication service with dependencies"""
self.user_repository = user_repository
self.email_service = email_service
self.jwt_secret = os.getenv('JWT_SECRET')
self.token_expiry = int(os.getenv('TOKEN_EXPIRY_HOURS', '24'))
def register_user(self, user_data: UserRegistrationData) -> AuthResult:
"""
Register a new user account with email verification
Implements: Req 1.1
"""
pass
def authenticate_user(self, credentials: LoginCredentials) -> AuthResult:
"""
Authenticate user and return JWT token
Implements: Req 1.2
"""
pass
def reset_password(self, email: str) -> PasswordResetResult:
"""
Initiate password reset process
Implements: Req 1.3
"""
pass
def validate_token(self, token: str) -> TokenValidationResult:
"""
Validate JWT token and extract user information
Implements: Req 1.4
"""
pass
def hash_password(self, password: str) -> str:
"""
Hash password using bcrypt
Implements: Req 7.2
"""
pass
```
**Dependencies**:
- UserRepository: Database access for user operations
- EmailService: Email sending functionality
- JWT library: Token generation and validation
- bcrypt: Password hashing
**Data Model**:
```python
from dataclasses import dataclass
from typing import Optional, List
from datetime import datetime
from enum import Enum
class UserRole(Enum):
ADMIN = "admin"
MANAGER = "manager"
MEMBER = "member"
@dataclass
class User:
"""User entity model"""
id: str
email: str
username: str
password_hash: str
role: UserRole
is_active: bool
email_verified: bool
created_at: datetime
last_login: Optional[datetime] = None
@dataclass
class UserRegistrationData:
"""User registration request data"""
email: str
username: str
password: str
confirm_password: str
@dataclass
class LoginCredentials:
"""User login credentials"""
email: str
password: str
@dataclass
class AuthResult:
"""Authentication operation result"""
success: bool
token: Optional[str] = None
user: Optional[User] = None
message: str = ""
```
### Component: TaskManagementEngine
**Purpose**: Core task CRUD operations and business logic
**Location**: `src/services/tasks/TaskManagementEngine.py`
**Interface**:
```python
class TaskManagementEngine:
"""
Task management and business logic engine
Implements: Req 2.1, 2.2, 2.3, 2.4, 6.1, 7.3
"""
def __init__(self, task_repository: TaskRepository,
notification_service: NotificationService,
auth_service: UserAuthenticationService):
"""Initialize task engine with dependencies"""
self.task_repository = task_repository
self.notification_service = notification_service
self.auth_service = auth_service
def create_task(self, task_data: TaskCreationData, user_id: str) -> TaskCreationResult:
"""
Create a new task with validation and assignment
Implements: Req 2.1
"""
pass
def update_task(self, task_id: str, updates: TaskUpdateData, user_id: str) -> TaskUpdateResult:
"""
Update existing task with change tracking
Implements: Req 2.2
"""
pass
def assign_task(self, task_id: str, assignee_id: str, assigner_id: str) -> TaskAssignmentResult:
"""
Assign task to user and send notification
Implements: Req 2.3
"""
pass
def change_task_status(self, task_id: str, new_status: TaskStatus, user_id: str) -> StatusChangeResult:
"""
Change task status and notify relevant users
Implements: Req 2.4
"""
pass
def get_user_tasks(self, user_id: str, filters: TaskFilters) -> List[Task]:
"""
Retrieve tasks for a specific user with filters
Implements: Req 6.1
"""
pass
```
**Dependencies**:
- TaskRepository: Database access for task operations
- NotificationService: Real-time notifications
- UserAuthenticationService: User validation and permissions
**Data Model**:
```python
from dataclasses import dataclass
from typing import Optional, List, Dict, Any
from datetime import datetime
from enum import Enum
class TaskStatus(Enum):
TODO = "todo"
IN_PROGRESS = "in_progress"
IN_REVIEW = "in_review"
COMPLETED = "completed"
CANCELLED = "cancelled"
class TaskPriority(Enum):
LOW = "low"
MEDIUM = "medium"
HIGH = "high"
URGENT = "urgent"
@dataclass
class Task:
"""Task entity model"""
id: str
title: str
description: str
status: TaskStatus
priority: TaskPriority
assignee_id: Optional[str]
creator_id: str
project_id: str
due_date: Optional[datetime]
created_at: datetime
updated_at: datetime
completed_at: Optional[datetime] = None
tags: List[str] = None
custom_fields: Dict[str, Any] = None
@dataclass
class TaskCreationData:
"""Task creation request data"""
title: str
description: str
priority: TaskPriority
assignee_id: Optional[str]
project_id: str
due_date: Optional[datetime]
tags: List[str] = None
@dataclass
class TaskUpdateData:
"""Task update request data"""
title: Optional[str] = None
description: Optional[str] = None
priority: Optional[TaskPriority] = None
assignee_id: Optional[str] = None
due_date: Optional[datetime] = None
tags: Optional[List[str]] = None
```
### Component: NotificationService
**Purpose**: Handles real-time notifications and email alerts
**Location**: `src/services/notifications/NotificationService.py`
**Interface**:
```python
class NotificationService:
"""
Real-time notification and alert service
Implements: Req 4.1, 4.2, 4.3, 4.4, 6.4
"""
def __init__(self, websocket_manager: WebSocketManager,
email_service: EmailService,
notification_repository: NotificationRepository):
"""Initialize notification service with dependencies"""
self.websocket_manager = websocket_manager
self.email_service = email_service
self.notification_repository = notification_repository
def send_task_assignment_notification(self, task_id: str, assignee_id: str) -> NotificationResult:
"""
Send real-time notification for task assignment
Implements: Req 4.1
"""
pass
def send_deadline_reminder(self, task_id: str, assignee_id: str) -> NotificationResult:
"""
Send reminder notification for approaching deadline
Implements: Req 4.2
"""
pass
def broadcast_task_update(self, task_id: str, update_data: Dict[str, Any]) -> BroadcastResult:
"""
Broadcast real-time task updates to prevent conflicts
Implements: Req 4.3
"""
pass
def send_maintenance_notification(self, message: str, scheduled_time: datetime) -> NotificationResult:
"""
Send system maintenance notifications
Implements: Req 4.4
"""
pass
```
**Dependencies**:
- WebSocketManager: Real-time WebSocket connection management
- EmailService: Email notification delivery
- NotificationRepository: Database storage for notifications
## Integration Design
### API Contracts
```python
# REST API between User Interface and TaskManagementEngine
POST /api/tasks
Authorization: Bearer {jwt_token}
Content-Type: application/json
Request:
{
"title": "Complete user authentication",
"description": "Implement JWT-based authentication system",
"priority": "high",
"assignee_id": "user123",
"project_id": "proj456",
"due_date": "2024-01-15T17:00:00Z",
"tags": ["backend", "security"]
}
Response:
{
"id": "task789",
"status": "todo",
"created_at": "2024-01-01T12:00:00Z",
"assigned_at": "2024-01-01T12:00:00Z"
}
```
### Database Schema
```sql
-- Users table for UserAuthenticationService
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
username VARCHAR(100) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
role VARCHAR(20) NOT NULL DEFAULT 'member',
is_active BOOLEAN DEFAULT true,
email_verified BOOLEAN DEFAULT false,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
last_login TIMESTAMP WITH TIME ZONE
);
-- Tasks table for TaskManagementEngine
CREATE TABLE tasks (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
title VARCHAR(255) NOT NULL,
description TEXT,
status VARCHAR(20) NOT NULL DEFAULT 'todo',
priority VARCHAR(10) NOT NULL DEFAULT 'medium',
assignee_id UUID REFERENCES users(id),
creator_id UUID NOT NULL REFERENCES users(id),
project_id UUID NOT NULL REFERENCES projects(id),
due_date TIMESTAMP WITH TIME ZONE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
completed_at TIMESTAMP WITH TIME ZONE
);
-- Projects table for ProjectOrganizer
CREATE TABLE projects (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
description TEXT,
owner_id UUID NOT NULL REFERENCES users(id),
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
```
### Security Implementation
```python
# JWT Token validation middleware
def require_auth(func):
"""Decorator to require JWT authentication"""
def wrapper(*args, **kwargs):
token = request.headers.get('Authorization')
if not token or not token.startswith('Bearer '):
return jsonify({'error': 'Authentication required'}), 401
token = token.split(' ')[1]
try:
payload = jwt.decode(token, JWT_SECRET, algorithms=['HS256'])
request.user_id = payload['user_id']
return func(*args, **kwargs)
except jwt.ExpiredSignatureError:
return jsonify({'error': 'Token expired'}), 401
except jwt.InvalidTokenError:
return jsonify({'error': 'Invalid token'}), 401
return wrapper
```

78
skills/specification-architect/assets/sample_outputs/example_requirements.md Normal file
View File

@@ -0,0 +1,78 @@
# Requirements Document
## Introduction
This document defines the functional and non-functional requirements for the TaskMaster Pro task management system.
## Glossary
- **Task**: A unit of work that can be assigned to a user and tracked through completion
- **Project**: A collection of related tasks organized under a common goal
- **User**: An individual with login credentials who can interact with the system
- **Notification**: A message sent to users about task updates or assignments
- **UserAuthenticationService**: The component responsible for managing user accounts and authentication
## Requirements
### Requirement 1: User Management
**Description**: Users must be able to register, authenticate, and manage their profiles.
#### Acceptance Criteria
1. WHEN a new user provides valid registration information, THE **UserAuthenticationService** SHALL create a new user account and send a verification email.
2. WHEN a registered user provides correct credentials, THE **UserAuthenticationService** SHALL return a valid JWT token for session management.
3. WHEN a user requests password reset, THE **UserAuthenticationService** SHALL send a password reset link to their registered email.
4. WHEN a JWT token expires, THE **UserAuthenticationService** SHALL require re-authentication.
### Requirement 2: Task Creation and Management
**Description**: Users must be able to create, edit, assign, and track tasks.
#### Acceptance Criteria
1. WHEN a user creates a new task with valid information, THE **TaskManagementEngine** SHALL save the task and assign it a unique identifier.
2. WHEN a user edits an existing task, THE **TaskManagementEngine** SHALL update the task and maintain change history.
3. WHEN a task is assigned to a user, THE **TaskManagementEngine** SHALL notify the assigned user via the **NotificationService**.
4. WHEN a task status changes, THE **TaskManagementEngine** SHALL update the task status and notify relevant users.
### Requirement 3: Project Organization
**Description**: Tasks must be organized into projects with proper access control.
#### Acceptance Criteria
1. WHEN a user creates a new project, THE **ProjectOrganizer** SHALL create the project and assign the user as project owner.
2. WHEN a project owner adds team members, THE **ProjectOrganizer** SHALL grant appropriate permissions based on role assignments.
3. WHEN a user accesses project tasks, THE **ProjectOrganizer** SHALL validate that the user has permission to view the project.
4. WHEN a project is deleted, THE **ProjectOrganizer** SHALL archive all associated tasks and notify project members.
### Requirement 4: Real-time Notifications
**Description**: Users must receive real-time notifications about task updates and assignments.
#### Acceptance Criteria
1. WHEN a task is assigned to a user, THE **NotificationService** SHALL send an immediate notification via WebSocket.
2. WHEN a task deadline approaches, THE **NotificationService** SHALL send reminder notifications to assigned users.
3. WHEN multiple users edit the same task, THE **NotificationService** SHALL broadcast real-time updates to prevent conflicts.
4. WHEN system maintenance occurs, THE **NotificationService** SHALL display maintenance notifications to all active users.
### Requirement 5: Reporting and Analytics
**Description**: Users must be able to view reports and analytics about task completion and project progress.
#### Acceptance Criteria
1. WHEN a project owner requests a progress report, THE **ReportingModule** SHALL generate a report showing task completion rates and team productivity.
2. WHEN a manager views analytics dashboard, THE **ReportingModule** SHALL display charts showing task distribution by status and assignee.
3. WHEN tasks are overdue, THE **ReportingModule** SHALL highlight overdue items and calculate impact on project timeline.
4. WHEN a project is completed, THE **ReportingModule** SHALL generate a final performance report with key metrics.
## Non-Functional Requirements
### Requirement 6: Performance
**Description**: System must respond quickly under normal load conditions.
#### Acceptance Criteria
1. WHEN 100 concurrent users access the system, THE **TaskManagementEngine** SHALL respond to task operations within 200 milliseconds.
2. WHEN generating reports, THE **ReportingModule** SHALL complete report generation within 5 seconds for projects with up to 1000 tasks.
3. WHEN users authenticate, THE **UserAuthenticationService** SHALL complete login within 500 milliseconds.
4. WHEN notifications are sent, THE **NotificationService** SHALL deliver notifications within 1 second of trigger events.
### Requirement 7: Security
**Description**: System must protect user data and prevent unauthorized access.
#### Acceptance Criteria
1. WHEN users submit sensitive information, THE **UserAuthenticationService** SHALL encrypt all data in transit using HTTPS.
2. WHEN passwords are stored, THE **UserAuthenticationService** SHALL hash passwords using bcrypt with minimum 12 rounds.
3. WHEN API requests are made, THE **TaskManagementEngine** SHALL validate JWT tokens and enforce role-based access control.
4. WHEN database connections are established, THE system SHALL use SSL/TLS encryption for all database communications.

123
skills/specification-architect/assets/sample_outputs/example_research.md Normal file
View File

@@ -0,0 +1,123 @@
## Research Summary for Task Management System
### Domain Analysis
- **Industry**: Productivity/Project Management Software
- **Scale Requirements**: 1,000+ concurrent users, 10,000+ tasks, real-time collaboration
- **Key Challenges**: Real-time updates, data consistency, user permission management, notification delivery
### Architectural Approaches Considered
1. **Microservices Architecture**
- Description: Decompose system into independent services for users, tasks, projects, notifications
- Pros: Independent scaling, fault isolation, technology diversity, team autonomy
- Cons: Operational complexity, network latency, distributed transactions, higher cost
2. **Monolithic Architecture**
- Description: Single application with modular components within one deployable unit
- Pros: Simpler deployment, easier debugging, lower operational overhead, better performance
- Cons: Scalability limits, technology lock-in, deployment risks, team coordination challenges
3. **Event-Driven Architecture with CQRS**
- Description: Command Query Responsibility Segregation with event sourcing
- Pros: Excellent scalability, audit trails, real-time updates, loose coupling
- Cons: High complexity, eventual consistency, steep learning curve, debugging challenges
### Technology Stack Research
#### Backend Frameworks
- **Node.js + Express**: Excellent for real-time features, large ecosystem, fast development
- **Python + FastAPI**: Strong typing, async support, good for APIs, data science integration
- **Java + Spring Boot**: Enterprise-grade, mature ecosystem, strong consistency
#### Database Options
- **PostgreSQL**: ACID compliance, JSON support, reliability, good for complex queries
- **MongoDB**: Flexible schema, horizontal scaling, good for rapid development
- **MySQL**: Mature, widely used, good performance, familiar to most developers
#### Real-time Communication
- **WebSockets**: Direct communication, low latency, widely supported
- **Server-Sent Events (SSE)**: Simpler than WebSockets, good for one-way updates
- **Message Queues (Redis/RabbitMQ)**: Reliable delivery, scalable, decoupled
### Recommended Technology Stack
- **Architecture Pattern**: **Modular Monolith with Microservice Readiness**
- Start with monolith for speed and simplicity
- Design modules to be easily extractable into microservices later
- Use clear boundaries between functional areas
- **Backend**: **Node.js + TypeScript + Express**
- TypeScript for type safety and better development experience
- Express for mature, well-documented framework
- Excellent ecosystem for real-time features (Socket.io)
- Good performance for I/O-bound applications
- **Database**: **PostgreSQL + Redis**
- PostgreSQL as primary database for ACID compliance and reliability
- Redis for session management, caching, and real-time data
- Both have excellent Node.js support
- **Real-time Communication**: **Socket.io + Redis Adapter**
- Socket.io for WebSocket connections with fallback support
- Redis adapter for multi-instance scaling
- Proven solution for real-time collaboration
- **Authentication**: **JWT + Refresh Tokens**
- JWT for stateless authentication
- Refresh tokens for security and better user experience
- Industry standard with good library support
- **Infrastructure**: **Docker + AWS ECS/RDS**
- Docker for containerization and consistency
- AWS ECS for managed container orchestration
- AWS RDS for managed PostgreSQL with automatic backups
### Research Sources
1. **"Microservices vs Monolith: When to Choose Which"** (Martin Fowler, 2024)
- Key insight: Start with monolith, extract microservices when clear boundaries emerge
- Most successful microservices implementations evolved from monoliths
2. **"Real-time Web Application Architecture Best Practices"** (InfoQ, 2024)
- WebSocket scaling challenges and solutions
- Redis adapter pattern for multi-instance deployments
3. **"PostgreSQL vs MongoDB for Task Management Systems"** (Database Journal, 2024)
- PostgreSQL superior for complex queries and data consistency
- JSON support provides flexibility when needed
4. **"Node.js TypeScript Best Practices for Enterprise Applications"** (Node.js Foundation, 2024)
- Type safety significantly reduces runtime errors
- Better development experience with IDE support
5. **"Authentication Patterns for Modern Web Applications"** (OWASP, 2024)
- JWT + refresh token pattern recommended for SPA applications
- Proper token storage and refresh strategies
### Decision Rationale
**Why Modular Monolith First:**
- Team size (3-5 developers) doesn't warrant microservices complexity
- Faster time-to-market with simpler deployment and debugging
- Clear module boundaries will allow future extraction if needed
- Lower operational cost and complexity for initial launch
**Why Node.js + TypeScript:**
- Real-time features are first-class citizens in Node.js ecosystem
- TypeScript provides enterprise-grade type safety
- Large talent pool and extensive library ecosystem
- Excellent performance for our I/O-bound use case
**Why PostgreSQL + Redis:**
- Data consistency is critical for task management
- PostgreSQL handles complex queries and relationships well
- Redis provides excellent caching and real-time data capabilities
- Both technologies are mature, well-supported, and cost-effective
**Why Socket.io for Real-time:**
- Handles WebSocket connection management complexity
- Provides automatic fallback to other transport methods
- Redis adapter enables horizontal scaling
- Large community and proven track record
This technology stack balances development speed, operational simplicity, and future scalability while leveraging current best practices and well-established patterns.

152
skills/specification-architect/assets/sample_outputs/example_tasks.md Normal file
View File

@@ -0,0 +1,152 @@
# Implementation Plan
## Phase 1: Core Infrastructure
- [ ] 1. Implement the UserAuthenticationService
- [ ] 1.1 Create project structure and setup configuration
- [ ] 1.2 Implement core UserAuthenticationService class in `src/services/auth/UserAuthenticationService.py`
- [ ] 1.3 Add user registration and validation methods
- [ ] 1.4 Implement JWT token generation and validation
- [ ] 1.5 Add password hashing with bcrypt
- [ ] 1.6 Create user repository interface and implementation
- [ ] 1.7 Write unit tests for UserAuthenticationService
- [ ] 1.8 Create integration tests for authentication flow
- _Requirements: 1.1, 1.2, 1.3, 1.4, 7.1, 7.2_
- [ ] 2. Implement the TaskManagementEngine
- [ ] 2.1 Create TaskManagementEngine class in `src/services/tasks/TaskManagementEngine.py`
- [ ] 2.2 Implement task CRUD operations (create, read, update, delete)
- [ ] 2.3 Add task assignment and status change methods
- [ ] 2.4 Implement task filtering and search functionality
- [ ] 2.5 Create task repository interface and implementation
- [ ] 2.6 Add input validation and business rules
- [ ] 2.7 Write unit tests for task operations
- [ ] 2.8 Create performance tests for task queries
- _Requirements: 2.1, 2.2, 2.3, 2.4, 6.1, 7.3_
## Phase 2: Data Layer and Storage
- [ ] 3. Setup Database Infrastructure
- [ ] 3.1 Configure PostgreSQL database connection
- [ ] 3.2 Create database migration scripts for schema
- [ ] 3.3 Implement users table with proper constraints
- [ ] 3.4 Create tasks table with foreign key relationships
- [ ] 3.5 Setup projects table and member relationships
- [ ] 3.6 Add indexes for performance optimization
- [ ] 3.7 Create database backup and recovery procedures
- [ ] 3.8 Write database integration tests
- _Requirements: 1.1, 2.1, 3.1, 3.2, 3.3, 3.4, 7.4_
- [ ] 4. Implement the ProjectOrganizer
- [ ] 4.1 Create ProjectOrganizer class in `src/services/projects/ProjectOrganizer.py`
- [ ] 4.2 Implement project creation and management methods
- [ ] 4.3 Add team member invitation and permission system
- [ ] 4.4 Create project repository interface and implementation
- [ ] 4.5 Implement role-based access control for projects
- [ ] 4.6 Add project archiving and deletion functionality
- [ ] 4.7 Write unit tests for project operations
- [ ] 4.8 Create tests for permission validation
- _Requirements: 3.1, 3.2, 3.3, 3.4_
## Phase 3: Communication Layer
- [ ] 5. Implement the NotificationService
- [ ] 5.1 Create NotificationService class in `src/services/notifications/NotificationService.py`
- [ ] 5.2 Setup WebSocket manager for real-time communications
- [ ] 5.3 Implement email service integration with SMTP
- [ ] 5.4 Create notification templates and formatting
- [ ] 5.5 Add notification queue and retry mechanisms
- [ ] 5.6 Implement notification preferences and filtering
- [ ] 5.7 Write tests for real-time notification delivery
- [ ] 5.8 Create email notification tests
- _Requirements: 4.1, 4.2, 4.3, 4.4, 6.4_
- [ ] 6. REST API Implementation
- [ ] 6.1 Create Flask/FastAPI application structure
- [ ] 6.2 Implement authentication middleware and decorators
- [ ] 6.3 Create user endpoints (register, login, profile)
- [ ] 6.4 Implement task CRUD endpoints with proper validation
- [ ] 6.5 Add project management endpoints
- [ ] 6.6 Create API documentation with OpenAPI/Swagger
- [ ] 6.7 Add rate limiting and request validation
- [ ] 6.8 Write comprehensive API tests
- _Requirements: 1.2, 2.1, 2.2, 3.1, 7.3_
## Phase 4: Business Intelligence
- [ ] 7. Implement the ReportingModule
- [ ] 7.1 Create ReportingModule class in `src/services/reports/ReportingModule.py`
- [ ] 7.2 Implement task completion rate calculations
- [ ] 7.3 Create productivity analytics and dashboards
- [ ] 7.4 Add overdue task identification and impact analysis
- [ ] 7.5 Implement project performance metrics
- [ ] 7.6 Create report generation and export functionality
- [ ] 7.7 Add caching for frequently accessed reports
- [ ] 7.8 Write tests for report accuracy and performance
- _Requirements: 5.1, 5.2, 5.3, 5.4, 6.2_
## Phase 5: Testing and Quality Assurance
- [ ] 8. Comprehensive Testing Suite
- [ ] 8.1 Complete unit test coverage for all components (target: 90%+)
- [ ] 8.2 Create integration tests for component interactions
- [ ] 8.3 Implement end-to-end tests for critical user flows
- [ ] 8.4 Add performance testing and load testing
- [ ] 8.5 Create security testing and vulnerability scanning
- [ ] 8.6 Implement automated testing in CI/CD pipeline
- [ ] 8.7 Add user acceptance testing scenarios
- [ ] 8.8 Create test data management and cleanup procedures
- _Requirements: 6.1, 6.2, 6.3, 6.4_
- [ ] 9. Security Implementation
- [ ] 9.1 Configure HTTPS/TLS for all communications
- [ ] 9.2 Implement secure password storage and hashing
- [ ] 9.3 Add input validation and sanitization
- [ ] 9.4 Create security headers and CSP policies
- [ ] 9.5 Implement audit logging for sensitive operations
- [ ] 9.6 Add rate limiting and DDoS protection
- [ ] 9.7 Create security monitoring and alerting
- [ ] 9.8 Write security tests and penetration testing
- _Requirements: 7.1, 7.2, 7.3, 7.4_
## Phase 6: Deployment and Operations
- [ ] 10. Production Deployment
- [ ] 10.1 Setup production environment and infrastructure
- [ ] 10.2 Configure application servers and load balancers
- [ ] 10.3 Implement database clustering and backup strategies
- [ ] 10.4 Setup monitoring and logging infrastructure
- [ ] 10.5 Create deployment scripts and CI/CD pipeline
- [ ] 10.6 Configure environment-specific settings
- [ ] 10.7 Implement health checks and monitoring alerts
- [ ] 10.8 Create disaster recovery and rollback procedures
- _Requirements: 5.1, 5.2_
- [ ] 11. Documentation and Training
- [ ] 11.1 Create comprehensive API documentation
- [ ] 11.2 Write user guides and documentation
- [ ] 11.3 Create administrator and deployment guides
- [ ] 11.4 Document system architecture and design decisions
- [ ] 11.5 Create troubleshooting and maintenance guides
- [ ] 11.6 Develop training materials for end users
- [ ] 11.7 Record video tutorials and walkthroughs
- [ ] 11.8 Create knowledge base and FAQ resources
- _Requirements: 5.1, 5.2_
## Phase 7: Performance Optimization
- [ ] 12. Performance Tuning
- [ ] 12.1 Optimize database queries and add query caching
- [ ] 12.2 Implement Redis caching for frequently accessed data
- [ ] 12.3 Add connection pooling and optimize resource usage
- [ ] 12.4 Optimize API response times and implement pagination
- [ ] 12.5 Add asynchronous processing for long-running tasks
- [ ] 12.6 Implement content delivery network for static assets
- [ ] 12.7 Monitor and optimize memory usage
- [ ] 12.8 Create performance benchmarks and monitoring
- _Requirements: 6.1, 6.2, 6.3, 6.4_
## Final Acceptance Criteria
- [ ] 13. System Integration and Validation
- [ ] 13.1 Validate all acceptance criteria from requirements document
- [ ] 13.2 Run complete traceability validation using automated script
- [ ] 13.3 Perform full system integration testing
- [ ] 13.4 Conduct security audit and penetration testing
- [ ] 13.5 Validate performance under expected load
- [ ] 13.6 Confirm all user workflows function correctly
- [ ] 13.7 Complete user acceptance testing with stakeholders
- [ ] 13.8 Finalize documentation and prepare for launch
- _Requirements: 1.1, 1.2, 1.3, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 4.4, 5.1, 5.2, 5.3, 5.4, 6.1, 6.2, 6.3, 6.4, 7.1, 7.2, 7.3, 7.4_

110
skills/specification-architect/assets/sample_outputs/example_validation.md Normal file
View File

@@ -0,0 +1,110 @@
# Validation Report
## 1. Requirements to Tasks Traceability Matrix
| Requirement | Acceptance Criterion | Implementing Task(s) | Status |
|---|---|---|---|
| 1. User Management | 1.1 | Task 1, Task 8 | Covered |
| | 1.2 | Task 1, Task 6 | Covered |
| | 1.3 | Task 1, Task 8 | Covered |
| | 1.4 | Task 1, Task 6 | Covered |
| 2. Task Creation and Management | 2.1 | Task 2, Task 6 | Covered |
| | 2.2 | Task 2, Task 6 | Covered |
| | 2.3 | Task 2, Task 5 | Covered |
| | 2.4 | Task 2, Task 5 | Covered |
| 3. Project Organization | 3.1 | Task 4, Task 6 | Covered |
| | 3.2 | Task 4, Task 8 | Covered |
| | 3.3 | Task 4, Task 8 | Covered |
| | 3.4 | Task 4, Task 8 | Covered |
| 4. Real-time Notifications | 4.1 | Task 5, Task 8 | Covered |
| | 4.2 | Task 5, Task 8 | Covered |
| | 4.3 | Task 5, Task 8 | Covered |
| | 4.4 | Task 5, Task 8 | Covered |
| 5. Reporting and Analytics | 5.1 | Task 7, Task 10 | Covered |
| | 5.2 | Task 7, Task 8 | Covered |
| | 5.3 | Task 7, Task 8 | Covered |
| | 5.4 | Task 7, Task 10 | Covered |
| 6. Performance | 6.1 | Task 2, Task 12 | Covered |
| | 6.2 | Task 7, Task 12 | Covered |
| | 6.3 | Task 8, Task 12 | Covered |
| | 6.4 | Task 5, Task 12 | Covered |
| 7. Security | 7.1 | Task 1, Task 9 | Covered |
| | 7.2 | Task 1, Task 9 | Covered |
| | 7.3 | Task 2, Task 9 | Covered |
| | 7.4 | Task 3, Task 9 | Covered |
## 2. Coverage Analysis
### Summary
- **Total Acceptance Criteria**: 28
- **Criteria Covered by Tasks**: 28
- **Coverage Percentage**: 100%
### Detailed Status
- **Covered Criteria**: 1.1, 1.2, 1.3, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 4.4, 5.1, 5.2, 5.3, 5.4, 6.1, 6.2, 6.3, 6.4, 7.1, 7.2, 7.3, 7.4
- **Missing Criteria**: None
- **Invalid References**: None
## 3. Validation Summary
### Component Coverage Analysis
- **UserAuthenticationService**: All 6 acceptance criteria covered across tasks 1, 6, 8, 9
- **TaskManagementEngine**: All 4 acceptance criteria covered across tasks 2, 5, 6, 9, 12
- **ProjectOrganizer**: All 4 acceptance criteria covered across tasks 4, 6, 8
- **NotificationService**: All 4 acceptance criteria covered across tasks 5, 8, 12
- **ReportingModule**: All 4 acceptance criteria covered across tasks 7, 8, 10, 12
- **Infrastructure Components**: All 6 security and performance criteria covered across tasks 3, 9, 12
### Task Distribution Analysis
- **Phase 1 (Infrastructure)**: Tasks 1-2 cover 10 acceptance criteria
- **Phase 2 (Data Layer)**: Tasks 3-4 cover 8 acceptance criteria
- **Phase 3 (Communication)**: Tasks 5-6 cover 8 acceptance criteria
- **Phase 4 (Business Intelligence)**: Task 7 covers 4 acceptance criteria
- **Phase 5 (Testing)**: Tasks 8-9 cover 16 acceptance criteria
- **Phase 6 (Deployment)**: Task 10 covers 2 acceptance criteria
- **Phase 7 (Performance)**: Task 12 covers 4 acceptance criteria
### Cross-Cutting Concerns
- **Security Requirements**: All 4 criteria (7.1-7.4) addressed in tasks 1, 2, 3, 9
- **Performance Requirements**: All 4 criteria (6.1-6.4) addressed in tasks 2, 5, 7, 12
- **Authentication/Authorization**: Integrated throughout tasks 1, 2, 4, 6
- **Data Validation**: Covered in tasks 1, 2, 4, 6, 9
- **Error Handling**: Addressed in tasks 1, 2, 4, 5, 7, 9
## 4. Final Validation
All 28 acceptance criteria are fully traced to implementation tasks. The plan is validated and ready for execution.
### Validation Results:
- ✅ **Requirements Coverage**: 100% (28/28 criteria covered)
- ✅ **Task Traceability**: All 13 major tasks have proper requirement references
- ✅ **Component Consistency**: All component names used consistently across documents
- ✅ **Template Adherence**: All documents follow the specified templates
- ✅ **Reference Validity**: No invalid requirement references found in tasks
### Readiness Assessment:
- ✅ **Architecture**: Complete and validated
- ✅ **Requirements**: Fully specified and testable
- ✅ **Design**: Detailed and comprehensive
- ✅ **Implementation Plan**: Granular and actionable
- ✅ **Validation**: Automated and verified
## 5. Next Steps
The specification is now complete and validated. The following actions are recommended:
1. **Begin Implementation**: Start with Phase 1 tasks as outlined in the implementation plan
2. **Setup Development Environment**: Configure tools, databases, and repositories
3. **Establish Quality Gates**: Implement the traceability validator in CI/CD pipeline
4. **Regular Validation**: Run validation checks after each major milestone
5. **Stakeholder Review**: Conduct final review with all project stakeholders
## 6. Validation Command
To re-run validation during implementation:
```bash
python scripts/traceability_validator.py --path . --requirements requirements.md --tasks tasks.md
```
This command will verify that all requirements remain covered throughout the development process.

25
skills/specification-architect/assets/sample_outputs/example_verifiable_research.md Normal file
View File

@@ -0,0 +1,25 @@
# Verifiable Research and Technology Proposal
## 1. Core Problem Analysis
The user requires a task management system for a growing SaaS company that must handle real-time collaboration, support 1,000+ concurrent users, integrate with existing tools, and scale horizontally. The primary technical challenges include real-time data synchronization, conflict resolution, and maintaining performance under high load.
## 2. Verifiable Technology Recommendations
| Technology/Pattern | Rationale & Evidence |
|---|---|
| **Node.js + TypeScript** | Node.js excels at real-time applications due to its event-driven, non-blocking I/O model that can handle thousands of concurrent connections efficiently [cite:1]. TypeScript adds static typing that reduces runtime errors by approximately 15% in large codebases while providing better IDE support and documentation [cite:2]. |
| **Modular Monolith Architecture** | A modular monolith approach is recommended over microservices for teams of 3-5 developers because it provides clear module boundaries that can be extracted into microservices later, while avoiding the operational complexity of distributed systems [cite:3]. This approach has been successfully used by companies like Basecamp and GitHub before scaling to microservices. |
| **PostgreSQL + Redis** | PostgreSQL provides ACID compliance and has been proven reliable for financial applications with 99.99% uptime, making it ideal for critical task data [cite:4]. Redis offers sub-millisecond latency for real-time features like notifications and presence detection, with proven scalability for millions of concurrent connections [cite:5]. |
| **Socket.io for Real-time Communication** | Socket.io provides automatic fallback from WebSockets to other transport methods, ensuring compatibility across all network environments including restrictive corporate firewalls [cite:6]. The library handles connection management, reconnection logic, and room-based messaging out of the box. |
| **Docker + Kubernetes Deployment** | Containerization with Docker provides consistent environments across development, testing, and production, eliminating "it works on my machine" issues [cite:7]. Kubernetes enables horizontal scaling with automatic load balancing and self-healing capabilities that have been proven to reduce infrastructure costs by 30-40% for SaaS applications [cite:8]. |
## 3. Browsed Sources
- [1] https://nodejs.org/en/docs/guides/blocking-vs-non-blocking/ - Official Node.js documentation explaining event-driven, non-blocking I/O architecture and its benefits for concurrent applications
- [2] https://www.typescriptlang.org/docs/handbook/intro.html - TypeScript documentation showing how static typing reduces runtime errors and improves development experience
- [3] https://martinfowler.com/articles/monoliths.html - Martin Fowler's analysis of modular monolith architecture, including successful case studies from Basecamp and GitHub
- [4] https://www.postgresql.org/about/ - PostgreSQL official documentation highlighting ACID compliance, reliability statistics, and financial industry adoption
- [5] https://redis.io/topics/introduction - Redis documentation showing performance benchmarks and scalability for real-time applications
- [6] https://socket.io/docs/ - Socket.io documentation demonstrating fallback mechanisms and compatibility features
- [7] https://www.docker.com/why-docker/ - Docker documentation showing containerization benefits and environment consistency
- [8] https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/ - Kubernetes documentation detailing scaling capabilities and cost reduction studies

25
skills/specification-architect/plugin.json Normal file
View File

@@ -0,0 +1,25 @@
{
"name": "specification-architect",
"version": "1.0.0",
"description": "A rigorous, evidence-based system that generates six interconnected architectural documents (research.md, blueprint.md, requirements.md, design.md, tasks.md, validation.md) with complete traceability. Implements a 6-phase process that eliminates AI-generated misinformation by mandating verification of all claims through web browsing and citations.",
"author": {
"name": "George A Puiu",
"email": "puiu.adrian@gmail.com"
},
"license": "MIT",
"keywords": [
"architecture",
"specification",
"documentation",
"traceability",
"requirements",
"design",
"evidence-based",
"validation"
],
"category": "productivity",
"commands": "./SKILL.md",
"strict": false,
"repository": "https://github.com/adrianpuiu/specification-document-generator",
"homepage": "https://github.com/adrianpuiu/specification-document-generator"
}

448
skills/specification-architect/references/document_templates.md Normal file
View File

@@ -0,0 +1,448 @@
# Document Templates
This document provides detailed templates and examples for each of the five specification architect documents.
## Phase 0: Verifiable Research Template
### Strict Protocol - NO "RESEARCH SLOP"
**CRITICAL**: This phase prevents AI-generated misinformation that could lead to serious professional consequences. Every claim MUST be verified with browsed sources.
### Evidence-Based Research Template
```markdown
# Verifiable Research and Technology Proposal
## 1. Core Problem Analysis
[A brief, 1-2 sentence analysis of the user's request and the primary technical challenges.]
## 2. Verifiable Technology Recommendations
| Technology/Pattern | Rationale & Evidence |
|---|---|
| **[Technology Name]** | [Rationale derived from browsed sources, with every factual claim cited.] |
| **[Pattern Name]** | [Rationale derived from browsed sources, with every factual claim cited.] |
| **[Framework]** | [Specific capabilities and limitations supported by sources.] |
| **[Database]** | [Performance characteristics and use case suitability with citations.] |
## 3. Browsed Sources
- [1] [Complete URL of browsed source 1] - [Brief description of content]
- [2] [Complete URL of browsed source 2] - [Brief description of content]
- [3] [Complete URL of browsed source 3] - [Brief description of content]
- [...]
```
### Citation Requirements - MANDATORY
**Every factual claim MUST end with `[cite:INDEX]` citation:**
**Examples of Proper Citations:**
- ❌ "Node.js is great for real-time applications" (NO CITATION - RESEARCH SLOP)
- ✅ "Node.js excels at real-time applications due to its event-driven, non-blocking I/O model [cite:1]."
- ❌ "TypeScript reduces errors" (NO CITATION - RESEARCH SLOP)
- ✅ "TypeScript adds static typing that reduces runtime errors by approximately 15% in large codebases [cite:2]."
- ❌ "PostgreSQL is reliable" (NO CITATION - RESEARCH SLOP)
- ✅ "PostgreSQL provides ACID compliance and has been proven reliable for financial applications with 99.99% uptime [cite:3]."
### Mandatory Research Process
1. **Search THEN Browse**: Use WebSearch to find sources, then WebFetch to read the actual content
2. **NO Search Snippets**: You MUST read the full content of sources, not just search results
3. **Verify Claims**: Every technology claim must be supported by actual browsed content
4. **Cite Everything**: All factual statements must have corresponding citations
5. **Source Listing**: All browsed URLs must be listed with index numbers
### Quality Assurance Checklist
**Before proceeding to Phase 1, verify:**
- [ ] Every technology recommendation has citations
- [ ] All citations correspond to browsed sources
- [ ] No claims made without source evidence
- [ ] Source URLs are complete and accessible
- [ ] Rationales are derived from actual source content
- [ ] No "research slop" or AI-generated assumptions
**Professional Standards Compliance:**
This research process prevents the types of errors that have led to legal sanctions, financial penalties, and professional ruin when relying on unverified AI-generated content.
**Quality Gate**: Do not proceed to Phase 1 until ALL claims are cited and verified with browsed sources.
## Blueprint Template
### Complete Template
```markdown
# Architectural Blueprint
## 1. Core Objective
[Single paragraph defining the primary goal and purpose of the system.]
## 2. System Scope and Boundaries
### In Scope
- [Feature 1 that will be implemented]
- [Feature 2 that will be implemented]
- [Component 1 that will be developed]
### Out of Scope
- [Feature 1 that will NOT be implemented]
- [External system 1 that will NOT be integrated]
- [Technology 1 that will NOT be used]
## 3. Core System Components
| Component Name | Responsibility |
|---|---|
| **[ComponentName1]** | [Concise function description explaining what this component does.] |
| **[ComponentName2]** | [Concise function description explaining what this component does.] |
| **[ComponentName3]** | [Concise function description explaining what this component does.] |
## 4. High-Level Data Flow
```mermaid
graph TD
A[External Input] --> B[ComponentName1]
B --> C[ComponentName2]
C --> D[ComponentName3]
D --> E[External Output]
style ComponentName1 fill:#e1f5fe
style ComponentName2 fill:#f3e5f5
style ComponentName3 fill:#e8f5e8
```
## 5. Key Integration Points
- **API Gateway**: RESTful APIs between [ComponentName1] and [ComponentName2]
- **Database Connection**: [ComponentName2] connects to PostgreSQL database
- **External Service**: [ComponentName3] integrates with [External Service Name] via [Protocol]
- **Authentication**: JWT-based authentication between all components
```
### Blueprint Guidelines
**CRITICAL: Upfront Planning Quality Determines Everything**
- **Component Names**: Use clear, descriptive names (e.g., "UserAuthenticationService", "DataProcessingEngine")
- Names should clearly indicate what the component DOES
- Use consistent naming conventions (Service, Engine, Manager, Repository, etc.)
- Avoid ambiguous names like "Helper" or "Utilities"
- **Single Responsibility Principle**: Each component should have ONE clear purpose
- If you find yourself saying "and also", split into multiple components
- Clear responsibilities prevent confusion and enable independent testing
- **Data Flow Visualization**: The Mermaid diagram is CRITICAL for understanding
- Show the complete journey from external input to external output
- Include all decision points and data transformations
- Use colors/styles to make component boundaries obvious
- **Integration Points**: Be explicit about how components communicate
- Specify protocols (REST, gRPC, message queues, events)
- Define data formats (JSON, protobuf, XML)
- Include authentication and error handling strategies
- **Boundaries Setting**: The In Scope/Out of Scope section prevents scope creep
- Be specific about what you WILL NOT build
- This protects against "while you're at it" additions
- Clear boundaries enable accurate estimation and planning
## Requirements Template
### Complete Template
```markdown
# Requirements Document
## Introduction
This document defines the functional and non-functional requirements for the [System Name] system.
## Glossary
- **Term1**: Definition of term1
- **Term2**: Definition of term2
- **[ComponentName1]**: The component responsible for [function]
## Requirements
### Requirement 1: [Feature Name]
**Description**: [Brief description of what this requirement accomplishes.]
#### Acceptance Criteria
1. WHEN [trigger condition], THE **[ComponentName1]** SHALL [specific, testable behavior].
2. WHEN [another trigger condition], THE **[ComponentName2]** SHALL [specific, testable behavior].
3. GIVEN [precondition], WHEN [action], THEN **[ComponentName3]** SHALL [expected outcome].
### Requirement 2: [Another Feature Name]
**Description**: [Brief description of what this requirement accomplishes.]
#### Acceptance Criteria
1. WHEN [trigger condition], THE **[ComponentName1]** SHALL [specific, testable behavior].
2. WHEN [trigger condition], THE **[ComponentName2]** SHALL [specific, testable behavior].
## Non-Functional Requirements
### Requirement 3: Performance
**Description**: System must meet performance requirements.
#### Acceptance Criteria
1. WHEN [load condition], THE **[ComponentName1]** SHALL [response time requirement].
2. WHEN [concurrent users condition], THE **[ComponentName2]** SHALL [throughput requirement].
```
### Requirements Guidelines
- **Component References**: MUST use exact component names from blueprint (copy-paste to avoid errors)
- **Testable Criteria**: Each acceptance criterion must be measurable and testable
- **WHEN-THEN Format**: Use the format "WHEN [condition], THE **[Component]** SHALL [behavior]"
- **Requirement Numbering**: Use sequential numbering (1, 2, 3...)
- **Criteria Numbering**: Use decimal numbering (1.1, 1.2, 2.1, 2.2...)
## Design Template
### Complete Template
```markdown
# Design Document
## Overview
This document provides detailed design specifications for the [System Name] system components.
## Design Principles
- **Single Responsibility**: Each component has a single, well-defined responsibility
- **Loose Coupling**: Components interact through well-defined interfaces
- **High Cohesion**: Related functionality is grouped together
- **Scalability**: Design supports future growth and expansion
## Component Specifications
### Component: [ComponentName1]
**Purpose**: [Responsibility from blueprint - copy exactly]
**Location**: `src/components/[ComponentName1].py`
**Interface**:
```python
class [ComponentName1]:
"""
[Brief description of component purpose]
Implements: Req 1.1, Req 1.2
"""
def __init__(self, dependency: [DependencyType]):
"""Initialize component with required dependencies"""
pass
def process_data(self, input: InputType) -> OutputType:
"""
Process input data and return results
Implements: Req 1.1
"""
pass
def validate_input(self, data: Any) -> bool:
"""
Validate input data format and constraints
Implements: Req 1.2
"""
pass
```
**Dependencies**:
- [Dependency1]: [Description of dependency]
- [Dependency2]: [Description of dependency]
**Data Model**:
```python
from dataclasses import dataclass
from typing import List, Optional
@dataclass
class [DataModelName]:
"""Data structure for [ComponentName1]"""
field1: str
field2: int
field3: Optional[List[str]] = None
```
### Component: [ComponentName2]
**Purpose**: [Responsibility from blueprint - copy exactly]
**Location**: `src/services/[ComponentName2].py`
**Interface**:
```python
class [ComponentName2]:
"""
[Brief description of component purpose]
Implements: Req 2.1, Req 2.2, Req 3.1
"""
def __init__(self, config: ConfigType):
"""Initialize component with configuration"""
pass
def execute_service(self, request: RequestType) -> ResponseType:
"""
Execute main service functionality
Implements: Req 2.1
"""
pass
def handle_error(self, error: Exception) -> ErrorResponseType:
"""
Handle and log service errors
Implements: Req 2.2
"""
pass
```
## Integration Design
### API Contracts
```python
# REST API between [ComponentName1] and [ComponentName2]
POST /api/process
Content-Type: application/json
Request:
{
"data": "input_data",
"options": {
"validate": true,
"format": "json"
}
}
Response:
{
"status": "success",
"result": "processed_data",
"metadata": {
"processing_time": 150,
"timestamp": "2024-01-01T12:00:00Z"
}
}
```
### Database Schema
```sql
-- Table for [ComponentName2] data storage
CREATE TABLE processed_data (
id SERIAL PRIMARY KEY,
input_data TEXT NOT NULL,
output_data TEXT NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
processed_by VARCHAR(100) NOT NULL
);
```
```
### Design Guidelines
- **Purpose**: Copy the responsibility exactly from the blueprint
- **Location**: Specify the exact file path where the component will be implemented
- **Requirement References**: Include "Implements: Req X.Y" comments for each method
- **Dependencies**: List all external dependencies and services
- **Data Models**: Define data structures used by the component
## Tasks Template
### Complete Template
```markdown
# Implementation Plan
## Phase 1: Core Infrastructure
- [ ] 1. Implement the [ComponentName1]
- [ ] 1.1 Create project structure and setup
- [ ] 1.2 Implement core [ComponentName1] class in `src/components/[ComponentName1].py`
- [ ] 1.3 Add input validation methods
- [ ] 1.4 Write unit tests for [ComponentName1]
- [ ] 1.5 Create integration tests
- _Requirements: 1.1, 1.2_
- [ ] 2. Implement the [ComponentName2]
- [ ] 2.1 Create [ComponentName2] service class
- [ ] 2.2 Implement main service methods
- [ ] 2.3 Add error handling and logging
- [ ] 2.4 Configure service dependencies
- [ ] 2.5 Write service tests
- _Requirements: 2.1, 2.2, 3.1_
## Phase 2: Data Layer
- [ ] 3. Implement the [ComponentName3]
- [ ] 3.1 Setup database connection and schema
- [ ] 3.2 Implement data access methods
- [ ] 3.3 Add data validation and transformation
- [ ] 3.4 Create database migration scripts
- [ ] 3.5 Write database tests
- _Requirements: 3.1, 3.2_
## Phase 3: Integration
- [ ] 4. API Integration
- [ ] 4.1 Implement REST API endpoints
- [ ] 4.2 Add request/response validation
- [ ] 4.3 Configure API security and authentication
- [ ] 4.4 Add API documentation
- [ ] 4.5 Write API integration tests
- _Requirements: 2.1, 4.1_
## Phase 4: Testing and Deployment
- [ ] 5. Testing
- [ ] 5.1 Complete end-to-end test suite
- [ ] 5.2 Performance testing and optimization
- [ ] 5.3 Security testing and vulnerability scanning
- [ ] 5.4 User acceptance testing
- _Requirements: 3.1, 5.1_
- [ ] 6. Deployment
- [ ] 6.1 Setup production environment
- [ ] 6.2 Configure monitoring and logging
- [ ] 6.3 Create deployment scripts
- [ ] 6.4 Implement rollback procedures
- _Requirements: 5.1, 5.2_
```
### Tasks Guidelines
- **Component Names**: Use exact component names from blueprint
- **Task Numbering**: Use sequential numbering (1, 2, 3...)
- **Sub-tasks**: Use decimal numbering (1.1, 1.2, 1.3...)
- **Requirement Tags**: Each main task must include `_Requirements: X.Y, Z.W_` tags
- **Actionable Tasks**: Each sub-task should be a specific, actionable item
- **Complete Coverage**: Every acceptance criterion from requirements must be referenced
## Validation Template
### Complete Template
```markdown
# Validation Report
## 1. Requirements to Tasks Traceability Matrix
| Requirement | Acceptance Criterion | Implementing Task(s) | Status |
|---|---|---|---|
| 1. User Authentication | 1.1 | Task 1, Task 2 | Covered |
| | 1.2 | Task 1, Task 3 | Covered |
| 2. Data Processing | 2.1 | Task 4, Task 5 | Covered |
| | 2.2 | Task 4 | Covered |
| | 2.3 | Task 6 | Covered |
| 3. Performance | 3.1 | Task 7, Task 8 | Covered |
| ... | ... | ... | ... |
| X. [Final Requirement] | X.Y | Task Z | Covered |
## 2. Coverage Analysis
### Summary
- **Total Acceptance Criteria**: [M]
- **Criteria Covered by Tasks**: [M]
- **Coverage Percentage**: 100%
### Detailed Status
- **Covered Criteria**: 1.1, 1.2, 2.1, 2.2, 2.3, 3.1, ..., X.Y
- **Missing Criteria**: None
- **Invalid References**: None
## 3. Final Validation
All [M] acceptance criteria are fully traced to implementation tasks. The plan is validated and ready for execution.
```
### Validation Guidelines
- **Matrix Generation**: Create a row for each acceptance criterion
- **Task Mapping**: List all tasks that implement each criterion
- **Status Indicators**: Use "Covered" for implemented criteria, "Missing" for gaps
- **Coverage Analysis**: Provide summary statistics and detailed status
- **Final Statement**: Confirm 100% coverage or identify gaps
## Template Usage Tips
1. **Copy-Paste Accuracy**: Copy component names exactly between documents to avoid traceability errors
2. **Sequential Numbering**: Maintain consistent numbering schemes across all documents
3. **Requirement References**: Double-check that all task requirement references exist in the requirements document
4. **Template Strictness**: Follow the templates exactly - the validation script depends on the specific format
5. **Validation First**: Run the traceability validator before considering the specification complete

340
skills/specification-architect/scripts/traceability_validator.py Normal file
View File

@@ -0,0 +1,340 @@
#!/usr/bin/env python3
"""
Traceability validator for specification architect skill.
Validates that all requirements are covered by implementation tasks.
"""
import re
import sys
from pathlib import Path
from typing import Dict, List, Tuple, Set
class TraceabilityValidator:
def __init__(self, base_path: str):
self.base_path = Path(base_path)
self.requirements = {}
self.tasks = []
self.research_citations = {}
def parse_requirements(self, requirements_file: str) -> Dict:
"""Parse requirements.md to extract requirements and acceptance criteria."""
req_file = self.base_path / requirements_file
if not req_file.exists():
raise FileNotFoundError(f"Requirements file not found: {requirements_file}")
content = req_file.read_text(encoding='utf-8')
# Split content by requirement headers and capture requirement numbers
pattern = r'\n### Requirement (\d+): ([^\n]+)'
matches = list(re.finditer(pattern, content))
requirements = {}
for match in matches:
req_num = match.group(1).strip()
req_title = match.group(2).strip()
# Find the start and end of this requirement section
start_pos = match.start()
end_pos = content.find('\n### Requirement', start_pos + 1)
if end_pos == -1:
end_pos = len(content)
# Extract this requirement's content
section_content = content[start_pos:end_pos]
# Find acceptance criteria within this section
ac_match = re.search(r'#### Acceptance Criteria\n(.*?)(?=\n###|\n##|\Z)', section_content, re.DOTALL)
if not ac_match:
continue
ac_text = ac_match.group(1).strip()
# Parse acceptance criteria
requirements[req_num] = {
"title": req_title,
"acceptance_criteria": {}
}
ac_pattern = r"(\d+)\.\s+(.+)"
ac_matches = re.findall(ac_pattern, ac_text)
for ac_num, ac_text in ac_matches:
requirements[req_num]["acceptance_criteria"][f"{req_num}.{ac_num}"] = ac_text.strip()
self.requirements = requirements
return requirements
def parse_tasks(self, tasks_file: str) -> List[Dict]:
"""Parse tasks.md to extract tasks and their requirement references."""
task_file = self.base_path / tasks_file
if not task_file.exists():
raise FileNotFoundError(f"Tasks file not found: {tasks_file}")
content = task_file.read_text(encoding='utf-8')
# Parse tasks and requirement references
task_pattern = r"- \[ \] (\d+).+?_Requirements: (.+?)_"
matches = re.findall(task_pattern, content, re.MULTILINE | re.DOTALL)
tasks = []
for task_num, req_refs in matches:
# Parse requirement references
req_refs = [ref.strip() for ref in req_refs.split(",")]
tasks.append({
"task_id": task_num,
"requirement_references": req_refs
})
self.tasks = tasks
return tasks
def validate_traceability(self) -> Tuple[Dict, List[str], List[str]]:
"""Validate that all requirements are covered by tasks."""
all_criteria = set()
for req_num, req_data in self.requirements.items():
for ac_ref in req_data["acceptance_criteria"]:
all_criteria.add(ac_ref)
covered_criteria = set()
invalid_references = set()
for task in self.tasks:
for req_ref in task["requirement_references"]:
if req_ref in all_criteria:
covered_criteria.add(req_ref)
else:
invalid_references.add(req_ref)
missing_criteria = all_criteria - covered_criteria
return {
"total_criteria": len(all_criteria),
"covered_criteria": len(covered_criteria),
"coverage_percentage": (len(covered_criteria) / len(all_criteria) * 100) if all_criteria else 100
}, list(missing_criteria), list(invalid_references)
def validate_research_evidence(self, research_file: str = "example_research.md") -> Dict:
"""Validate research document for proper citations and evidence."""
research_path = self.base_path / research_file
if not research_path.exists():
return {"valid": False, "error": f"Research file not found: {research_file}"}
content = research_path.read_text(encoding='utf-8')
validation_results = {
"valid": True,
"citation_errors": [],
"missing_sources": [],
"uncited_claims": [],
"total_sources": 0,
"total_citations": 0
}
# Extract source list (## 3. Browsed Sources section)
source_pattern = r'## 3\. Browsed Sources\n(.*?)(?=\n##|\Z)'
source_match = re.search(source_pattern, content, re.DOTALL)
if not source_match:
validation_results["valid"] = False
validation_results["citation_errors"].append("Missing 'Browsed Sources' section")
return validation_results
sources_text = source_match.group(1)
source_lines = [line.strip() for line in sources_text.split('\n') if line.strip()]
# Extract source URLs and indices
sources = {}
for line in source_lines:
source_match = re.match(r'- \[(\d+)\] (https?://\S+)', line)
if source_match:
index = source_match.group(1)
url = source_match.group(2)
sources[index] = url
validation_results["total_sources"] = len(sources)
# Check for citations in rationale section
rationale_pattern = r'\| \*\*(.+?)\*\* \| (.+?) \|'
rationale_matches = re.findall(rationale_pattern, content, re.DOTALL)
total_citations = 0
for technology, rationale in rationale_matches:
# Find all citations in rationale
citations = re.findall(r'\[cite:(\d+)\]', rationale)
total_citations += len(citations)
# Check each citation has corresponding source
for citation in citations:
if citation not in sources:
validation_results["citation_errors"].append(f"Citation [cite:{citation}] references non-existent source")
validation_results["valid"] = False
validation_results["total_citations"] = total_citations
# Check for factual claims without citations (simplified detection)
# Look for sentences with specific numbers, percentages, or strong claims
factual_claims = re.findall(r'[^.!?]*\d+(?:\.\d+)?%?[^.!?]*\.|[^.!?]*?(excellent|proven|ideal|best|optimal)[^.!?]*\.', content)
for claim in factual_claims:
if not re.search(r'\[cite:\d+\]', claim):
validation_results["uncited_claims"].append(claim.strip())
# Validate that we have both sources and citations
if len(sources) == 0:
validation_results["valid"] = False
validation_results["citation_errors"].append("No sources found in research document")
if total_citations == 0:
validation_results["valid"] = False
validation_results["citation_errors"].append("No citations found in technology rationales")
# Check citation to source ratio (should have reasonable coverage)
if total_citations < len(sources):
validation_results["citation_errors"].append(f"Too few citations ({total_citations}) for number of sources ({len(sources)})")
return validation_results
def generate_validation_report(self, requirements_file: str = "requirements.md",
tasks_file: str = "tasks.md",
research_file: str = "example_research.md") -> str:
"""Generate a complete validation report."""
self.parse_requirements(requirements_file)
self.parse_tasks(tasks_file)
validation_result, missing, invalid = self.validate_traceability()
research_validation = self.validate_research_evidence(research_file)
report = f"""# Validation Report
## 1. Requirements to Tasks Traceability Matrix
| Requirement | Acceptance Criterion | Implementing Task(s) | Status |
|---|---|---|---|"""
# Generate traceability matrix
for req_num, req_data in self.requirements.items():
for ac_ref, ac_text in req_data["acceptance_criteria"].items():
# Find tasks implementing this criterion
implementing_tasks = []
for task in self.tasks:
if ac_ref in task["requirement_references"]:
implementing_tasks.append(f"Task {task['task_id']}")
status = "Covered" if implementing_tasks else "Missing"
tasks_str = ", ".join(implementing_tasks) if implementing_tasks else "None"
report += f"\n| {req_num} | {ac_ref} | {tasks_str} | {status} |"
report += f"""
## 2. Coverage Analysis
### Summary
- **Total Acceptance Criteria**: {validation_result['total_criteria']}
- **Criteria Covered by Tasks**: {validation_result['covered_criteria']}
- **Coverage Percentage**: {validation_result['coverage_percentage']:.1f}%
### Detailed Status
- **Covered Criteria**: {[ref for ref in self._get_all_criteria() if ref in self._get_covered_criteria()]}
- **Missing Criteria**: {missing if missing else 'None'}
- **Invalid References**: {invalid if invalid else 'None'}
## 3. Research Evidence Validation
### Summary
- **Total Sources**: {research_validation['total_sources']}
- **Total Citations**: {research_validation['total_citations']}
- **Research Validation**: {'PASSED' if research_validation['valid'] else 'FAILED'}
### Evidence Quality
- **Citation Errors**: {len(research_validation['citation_errors'])}
- **Uncited Claims**: {len(research_validation['uncited_claims'])}
"""
if research_validation['citation_errors']:
report += "\n#### Citation Issues:\n"
for error in research_validation['citation_errors']:
report += f"- {error}\n"
if research_validation['uncited_claims']:
report += "\n#### Uncited Factual Claims:\n"
for claim in research_validation['uncited_claims'][:5]: # Limit to first 5
report += f"- {claim}\n"
if len(research_validation['uncited_claims']) > 5:
report += f"- ... and {len(research_validation['uncited_claims']) - 5} more\n"
report += """
## 4. Final Validation
"""
requirements_valid = validation_result['coverage_percentage'] == 100 and not invalid
research_valid = research_validation['valid']
if requirements_valid and research_valid:
report += f"[PASS] **VALIDATION PASSED**\n\nAll {validation_result['total_criteria']} acceptance criteria are fully traced to implementation tasks AND all research claims are properly cited with verifiable sources. The plan is validated and ready for execution."
elif not requirements_valid and research_valid:
report += f"[FAIL] **VALIDATION FAILED** - Requirements Issues\n\n{len(missing)} criteria not covered, {len(invalid)} invalid references. Research evidence is properly cited, but requirements traceability needs attention."
elif requirements_valid and not research_valid:
report += f"[FAIL] **VALIDATION FAILED** - Research Evidence Issues\n\nRequirements traceability is complete, but research evidence has {len(research_validation['citation_errors'])} citation errors and {len(research_validation['uncited_claims'])} uncited claims. This violates the evidence-based protocol and prevents professional use."
else:
report += f"[FAIL] **VALIDATION FAILED** - Multiple Issues\n\nRequirements: {len(missing)} criteria not covered, {len(invalid)} invalid references. Research: {len(research_validation['citation_errors'])} citation errors, {len(research_validation['uncited_claims'])} uncited claims."
return report
def _get_all_criteria(self) -> Set[str]:
"""Get all acceptance criteria references."""
all_criteria = set()
for req_num, req_data in self.requirements.items():
for ac_ref in req_data["acceptance_criteria"]:
all_criteria.add(ac_ref)
return all_criteria
def _get_covered_criteria(self) -> Set[str]:
"""Get all covered acceptance criteria references."""
covered_criteria = set()
all_criteria = self._get_all_criteria()
for task in self.tasks:
for req_ref in task["requirement_references"]:
if req_ref in all_criteria:
covered_criteria.add(req_ref)
return covered_criteria
if __name__ == "__main__":
import argparse
parser = argparse.ArgumentParser(description="Validate specification architect traceability")
parser.add_argument("--path", default=".", help="Base path containing specification files")
parser.add_argument("--requirements", default="requirements.md", help="Requirements file name")
parser.add_argument("--tasks", default="tasks.md", help="Tasks file name")
parser.add_argument("--research", default="example_research.md", help="Research file name")
args = parser.parse_args()
try:
validator = TraceabilityValidator(args.path)
report = validator.generate_validation_report(args.requirements, args.tasks, args.research)
print(report)
# Exit with error code if validation fails
validation_result, missing, invalid = validator.validate_traceability()
research_validation = validator.validate_research_evidence(args.research)
requirements_valid = validation_result['coverage_percentage'] == 100 and not invalid
research_valid = research_validation['valid']
if not requirements_valid or not research_valid:
sys.exit(1)
else:
sys.exit(0)
except FileNotFoundError as e:
print(f"Error: {e}")
sys.exit(1)
except Exception as e:
print(f"Unexpected error: {e}")
sys.exit(1)

24
skills/specification-architect/validate.bat Normal file
View File

@@ -0,0 +1,24 @@
@echo off
REM Specification Architect Validation Helper
setlocal enabledelayedexpansion
set SCRIPT_DIR=%~dp0
set SPEC_DIR=.
set VERBOSE=
set GENERATE=
:parse_args
if "%1"=="" goto run
if "%1"=="-p" (set SPEC_DIR=%2 & shift & shift & goto parse_args)
if "%1"=="--path" (set SPEC_DIR=%2 & shift & shift & goto parse_args)
if "%1"=="-v" (set VERBOSE=--verbose & shift & goto parse_args)
if "%1"=="--verbose" (set VERBOSE=--verbose & shift & goto parse_args)
if "%1"=="-g" (set GENERATE=--generate-validation & shift & goto parse_args)
if "%1"=="--generate" (set GENERATE=--generate-validation & shift & goto parse_args)
shift
goto parse_args
:run
echo Running specification validation...
python "%SCRIPT_DIR%validate_specifications.py" --path "%SPEC_DIR%" %VERBOSE% %GENERATE%
exit /b %ERRORLEVEL%

38
skills/specification-architect/validate.sh Normal file
View File

@@ -0,0 +1,38 @@
#!/bin/bash
# Specification Architect Validation Helper
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
SPEC_DIR="."
VERBOSE=""
GENERATE=""
while [[ $# -gt 0 ]]; do
case $1 in
-p|--path)
SPEC_DIR="$2"
shift 2
;;
-v|--verbose)
VERBOSE="--verbose"
shift
;;
-g|--generate)
GENERATE="--generate-validation"
shift
;;
-h|--help)
echo "Usage: ./validate.sh [options]"
echo "Options:"
echo " -p, --path DIR Path to spec directory"
echo " -v, --verbose Verbose output"
echo " -g, --generate Generate validation.md"
exit 0
;;
*)
shift
;;
esac
done
python3 "$SCRIPT_DIR/validate_specifications.py" --path "$SPEC_DIR" $VERBOSE $GENERATE
exit $?

164
skills/specification-architect/validate_specifications.py Normal file
View File

@@ -0,0 +1,164 @@
#!/usr/bin/env python3
"""Specification Architect Validation Script"""
import re, sys, json, argparse
from pathlib import Path
from dataclasses import dataclass, field
from typing import Dict, Set, List
@dataclass
class Result:
total: int = 0
covered: Set[str] = field(default_factory=set)
missing: Set[str] = field(default_factory=set)
coverage: float = 0.0
valid: bool = False
errors: List[str] = field(default_factory=list)
class Validator:
def __init__(self, spec_dir: str, verbose=False):
self.dir = Path(spec_dir)
self.verbose = verbose
self.result = Result()
self.components = set()
self.requirements = {}
self.task_reqs = set()
def log(self, msg, level="INFO"):
if self.verbose or level=="ERROR":
print(f"[{level}] {msg}")
def validate(self) -> Result:
self.log("Starting validation...")
if not self._files_exist():
return self.result
if not self._extract_components():
return self.result
if not self._extract_requirements():
return self.result
if not self._extract_tasks():
return self.result
self._calculate()
self._report()
return self.result
def _files_exist(self) -> bool:
for name in ["blueprint.md", "requirements.md", "tasks.md"]:
if not (self.dir / name).exists():
self.result.errors.append(f"Missing: {name}")
return len(self.result.errors) == 0
def _extract_components(self) -> bool:
try:
content = (self.dir / "blueprint.md").read_text()
self.components = set(re.findall(r'\|\s*\*\*([A-Za-z0-9_]+)\*\*\s*\|', content))
if not self.components:
self.log("No components found", "WARNING")
return False
self.log(f"Found {len(self.components)} components")
return True
except Exception as e:
self.log(f"Error: {e}", "ERROR")
return False
def _extract_requirements(self) -> bool:
try:
content = (self.dir / "requirements.md").read_text()
for match in re.finditer(r'### Requirement (\d+):', content):
req_num = match.group(1)
start = match.end()
end = len(content)
text = content[start:end]
criteria = [f"{req_num}.{c}" for c, _ in re.findall(
r'(\d+)\.\s+WHEN.*?THE\s+\*\*([A-Za-z0-9_]+)\*\*\s+SHALL',
text, re.DOTALL)]
if criteria:
self.requirements[req_num] = criteria
self.result.total = sum(len(v) for v in self.requirements.values())
self.log(f"Found {self.result.total} criteria")
return self.result.total > 0
except Exception as e:
self.log(f"Error: {e}", "ERROR")
return False
def _extract_tasks(self) -> bool:
try:
content = (self.dir / "tasks.md").read_text()
for match in re.findall(r'_Requirements:\s*([\d., ]+)_', content):
for c in match.split(','):
self.task_reqs.add(c.strip())
if not self.task_reqs:
self.log("No requirement tags found", "WARNING")
return False
self.log(f"Found {len(self.task_reqs)} covered criteria")
return True
except Exception as e:
self.log(f"Error: {e}", "ERROR")
return False
def _calculate(self):
all_crit = set()
for crit_list in self.requirements.values():
all_crit.update(crit_list)
self.result.covered = self.task_reqs & all_crit
self.result.missing = all_crit - self.task_reqs
if all_crit:
self.result.coverage = (len(self.result.covered) / len(all_crit)) * 100
self.result.valid = self.result.coverage == 100.0
def _report(self):
print("\n" + "="*80)
print("SPECIFICATION VALIDATION REPORT")
print("="*80 + "\n")
print("SUMMARY")
print("-"*80)
print(f"Total Criteria: {self.result.total}")
print(f"Covered by Tasks: {len(self.result.covered)}")
print(f"Coverage: {self.result.coverage:.1f}%\n")
if self.result.missing:
print("MISSING CRITERIA")
print("-"*80)
for c in sorted(self.result.missing, key=lambda x: tuple(map(int, x.split('.')))):
print(f" - {c}")
print()
print("VALIDATION STATUS")
print("-"*80)
if self.result.valid:
print("✅ PASSED - All criteria covered\n")
else:
print(f"❌ FAILED - {len(self.result.missing)} uncovered\n")
print("="*80 + "\n")
def main():
parser = argparse.ArgumentParser(description="Validate specifications")
parser.add_argument("--path", default=".", help="Spec directory")
parser.add_argument("--verbose", action="store_true", help="Verbose")
parser.add_argument("--json", action="store_true", help="JSON output")
args = parser.parse_args()
v = Validator(args.path, args.verbose)
result = v.validate()
if args.json:
print(json.dumps({
"total": result.total,
"covered": len(result.covered),
"missing": list(result.missing),
"coverage": result.coverage,
"valid": result.valid,
}, indent=2))
sys.exit(0 if result.valid else 1)
if __name__ == "__main__":
main()