├── spec-arch.zip ├── spec-to-execution-v2.zip ├── spec-to-execution-skill.zip ├── specification-architect ├── scripts │ ├── __pycache__ │ │ └── traceability_validator.cpython-313.pyc │ └── traceability_validator.py ├── validate.bat ├── plugin.json ├── validate.sh ├── assets │ └── sample_outputs │ │ ├── example_blueprint.md │ │ ├── example_verifiable_research.md │ │ ├── example_validation.md │ │ ├── example_requirements.md │ │ ├── example_research.md │ │ ├── example_tasks.md │ │ └── example_design.md ├── README.md ├── validate_specifications.py ├── VALIDATION_SCRIPTS_README.md ├── SKILL.md └── references │ └── document_templates.md ├── .claude └── settings.local.json ├── .claude-plugin └── marketplace.json ├── CLAUDE.md └── README.md /spec-arch.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/adrianpuiu/specification-document-generator/HEAD/spec-arch.zip -------------------------------------------------------------------------------- /spec-to-execution-v2.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/adrianpuiu/specification-document-generator/HEAD/spec-to-execution-v2.zip -------------------------------------------------------------------------------- /spec-to-execution-skill.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/adrianpuiu/specification-document-generator/HEAD/spec-to-execution-skill.zip -------------------------------------------------------------------------------- /specification-architect/scripts/__pycache__/traceability_validator.cpython-313.pyc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/adrianpuiu/specification-document-generator/HEAD/specification-architect/scripts/__pycache__/traceability_validator.cpython-313.pyc -------------------------------------------------------------------------------- /.claude/settings.local.json: -------------------------------------------------------------------------------- 1 | { 2 | "permissions": { 3 | "allow": [ 4 | "Bash(git init:*)", 5 | "Bash(git remote add:*)", 6 | "Bash(git add:*)" 7 | ], 8 | "deny": [], 9 | "ask": [] 10 | } 11 | } 12 | -------------------------------------------------------------------------------- /.claude-plugin/marketplace.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "specification-document-generator", 3 | "owner": { 4 | "name": "George A Puiu", 5 | "email": "puiu.adrian@gmail.com" 6 | }, 7 | "metadata": { 8 | "description": "Rigorous, traceability-first system for generating architectural documentation with complete requirements-to-implementation traceability", 9 | "version": "1.0.0" 10 | }, 11 | "plugins": [ 12 | { 13 | "name": "architecture-skills", 14 | "description": "Collection of architectural documentation and specification generation skills", 15 | "source": "./", 16 | "strict": false, 17 | "skills": [ 18 | "./specification-architect" 19 | ] 20 | } 21 | ] 22 | } 23 | -------------------------------------------------------------------------------- /specification-architect/validate.bat: -------------------------------------------------------------------------------- 1 | @echo off 2 | REM Specification Architect Validation Helper 3 | 4 | setlocal enabledelayedexpansion 5 | set SCRIPT_DIR=%~dp0 6 | set SPEC_DIR=. 7 | set VERBOSE= 8 | set GENERATE= 9 | 10 | :parse_args 11 | if "%1"=="" goto run 12 | if "%1"=="-p" (set SPEC_DIR=%2 & shift & shift & goto parse_args) 13 | if "%1"=="--path" (set SPEC_DIR=%2 & shift & shift & goto parse_args) 14 | if "%1"=="-v" (set VERBOSE=--verbose & shift & goto parse_args) 15 | if "%1"=="--verbose" (set VERBOSE=--verbose & shift & goto parse_args) 16 | if "%1"=="-g" (set GENERATE=--generate-validation & shift & goto parse_args) 17 | if "%1"=="--generate" (set GENERATE=--generate-validation & shift & goto parse_args) 18 | shift 19 | goto parse_args 20 | 21 | :run 22 | echo Running specification validation... 23 | python "%SCRIPT_DIR%validate_specifications.py" --path "%SPEC_DIR%" %VERBOSE% %GENERATE% 24 | exit /b %ERRORLEVEL% 25 | -------------------------------------------------------------------------------- /specification-architect/plugin.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "specification-architect", 3 | "version": "1.0.0", 4 | "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.", 5 | "author": { 6 | "name": "George A Puiu", 7 | "email": "puiu.adrian@gmail.com" 8 | }, 9 | "license": "MIT", 10 | "keywords": [ 11 | "architecture", 12 | "specification", 13 | "documentation", 14 | "traceability", 15 | "requirements", 16 | "design", 17 | "evidence-based", 18 | "validation" 19 | ], 20 | "category": "productivity", 21 | "commands": "./SKILL.md", 22 | "strict": false, 23 | "repository": "https://github.com/adrianpuiu/specification-document-generator", 24 | "homepage": "https://github.com/adrianpuiu/specification-document-generator" 25 | } 26 | -------------------------------------------------------------------------------- /specification-architect/validate.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Specification Architect Validation Helper 3 | 4 | SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" 5 | SPEC_DIR="." 6 | VERBOSE="" 7 | GENERATE="" 8 | 9 | while [[ $# -gt 0 ]]; do 10 | case $1 in 11 | -p|--path) 12 | SPEC_DIR="$2" 13 | shift 2 14 | ;; 15 | -v|--verbose) 16 | VERBOSE="--verbose" 17 | shift 18 | ;; 19 | -g|--generate) 20 | GENERATE="--generate-validation" 21 | shift 22 | ;; 23 | -h|--help) 24 | echo "Usage: ./validate.sh [options]" 25 | echo "Options:" 26 | echo " -p, --path DIR Path to spec directory" 27 | echo " -v, --verbose Verbose output" 28 | echo " -g, --generate Generate validation.md" 29 | exit 0 30 | ;; 31 | *) 32 | shift 33 | ;; 34 | esac 35 | done 36 | 37 | python3 "$SCRIPT_DIR/validate_specifications.py" --path "$SPEC_DIR" $VERBOSE $GENERATE 38 | exit $? 39 | -------------------------------------------------------------------------------- /specification-architect/assets/sample_outputs/example_blueprint.md: -------------------------------------------------------------------------------- 1 | # Architectural Blueprint 2 | ## 1. Core Objective 3 | 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. 4 | 5 | ## 2. System Scope and Boundaries 6 | ### In Scope 7 | - User authentication and authorization 8 | - Task creation, assignment, and management 9 | - Project organization and team collaboration 10 | - Real-time notifications and updates 11 | - Basic reporting and analytics 12 | 13 | ### Out of Scope 14 | - Advanced project management features (Gantt charts, critical path) 15 | - File attachments and document management 16 | - Integration with third-party project management tools 17 | - Mobile application development 18 | - Advanced workflow automation 19 | 20 | ## 3. Core System Components 21 | | Component Name | Responsibility | 22 | |---|---| 23 | | **UserAuthenticationService** | Handles user registration, login, and session management | 24 | | **TaskManagementEngine** | Core task CRUD operations and business logic | 25 | | **ProjectOrganizer** | Manages project creation, membership, and permissions | 26 | | **NotificationService** | Handles real-time notifications and email alerts | 27 | | **ReportingModule** | Generates basic reports and analytics dashboards | 28 | 29 | ## 4. High-Level Data Flow 30 | ```mermaid 31 | graph TD 32 | A[User Interface] --> B[UserAuthenticationService] 33 | A --> C[TaskManagementEngine] 34 | A --> D[ProjectOrganizer] 35 | 36 | B --> E[User Database] 37 | C --> F[Task Database] 38 | D --> G[Project Database] 39 | 40 | C --> H[NotificationService] 41 | H --> I[Email Service] 42 | H --> J[WebSocket Service] 43 | 44 | C --> K[ReportingModule] 45 | K --> L[Analytics Database] 46 | 47 | style UserAuthenticationService fill:#e1f5fe 48 | style TaskManagementEngine fill:#f3e5f5 49 | style ProjectOrganizer fill:#e8f5e8 50 | style NotificationService fill:#fff3e0 51 | style ReportingModule fill:#fce4ec 52 | ``` 53 | 54 | ## 5. Key Integration Points 55 | - **Authentication API**: JWT-based authentication between User Interface and UserAuthenticationService 56 | - **Task API**: RESTful APIs between User Interface and TaskManagementEngine 57 | - **Project API**: RESTful APIs between User Interface and ProjectOrganizer 58 | - **Notification Gateway**: WebSocket connections for real-time updates 59 | - **Email Service**: SMTP integration for email notifications 60 | - **Database Connections**: PostgreSQL connections for all data storage components -------------------------------------------------------------------------------- /specification-architect/README.md: -------------------------------------------------------------------------------- 1 | # Specification Architect Skill 2 | 3 | An AI skill that generates rigorous, evidence-based architectural documentation with complete traceability. 4 | 5 | ## Quick Start 6 | 7 | ### Generate Specification Documents 8 | 9 | The skill follows a 6-phase sequential process: 10 | 11 | 1. **Phase 0: Verifiable Research** (research.md) - Evidence-based technology research with citations 12 | 2. **Phase 1: Blueprint** (blueprint.md) - Component architecture and data flow 13 | 3. **Phase 2: Requirements** (requirements.md) - Acceptance criteria with component assignments 14 | 4. **Phase 3: Design** (design.md) - Detailed component specifications 15 | 5. **Phase 4: Tasks** (tasks.md) - Implementation tasks with requirement traceability 16 | 6. **Phase 5: Validation** (validation.md) - Automated validation results 17 | 18 | ### Validation Commands 19 | 20 | ```bash 21 | # Primary validation - ensures 100% requirements coverage 22 | python validate_specifications.py 23 | 24 | # With options 25 | python validate_specifications.py --path ./specs --verbose --generate-validation 26 | 27 | # Advanced traceability validation 28 | python scripts/traceability_validator.py 29 | ``` 30 | 31 | ### Cross-Platform Helpers 32 | 33 | ```bash 34 | # Linux/macOS 35 | ./validate.sh --verbose --generate 36 | 37 | # Windows 38 | validate.bat --verbose --generate 39 | ``` 40 | 41 | ## Key Files 42 | 43 | - **validate_specifications.py** - Main validation script 44 | - **scripts/traceability_validator.py** - Advanced traceability validation 45 | - **SKILL.md** - Complete skill documentation 46 | - **references/document_templates.md** - Template examples and format specifications 47 | - **assets/sample_outputs/** - Example generated documents 48 | 49 | ## Validation Exit Codes 50 | 51 | - **0**: Success (100% coverage achieved) 52 | - **1**: Failure (missing files, incomplete coverage, format errors) 53 | 54 | ## Evidence-Based Research Protocol 55 | 56 | This skill implements a strict anti-"research slop" protocol: 57 | 58 | 1. **Search THEN Browse**: Use WebSearch to find sources, then WebFetch to read actual content 59 | 2. **Cite Every Claim**: Every factual statement must end with `[cite:INDEX]` citation 60 | 3. **Verify Sources**: Read full source content, not just search snippets 61 | 4. **Auditable Trail**: Complete citation trail from claim to source 62 | 63 | ## Quality Assurance 64 | 65 | The validation system ensures: 66 | - All required documents exist 67 | - Component names are consistent across documents 68 | - Requirements have 100% task coverage 69 | - Citations follow proper format 70 | - Templates are correctly implemented 71 | 72 | ## License 73 | 74 | MIT 75 | 76 | ## Author 77 | 78 | George A Puiu (puiu.adrian@gmail.com) 79 | -------------------------------------------------------------------------------- /specification-architect/assets/sample_outputs/example_verifiable_research.md: -------------------------------------------------------------------------------- 1 | # Verifiable Research and Technology Proposal 2 | 3 | ## 1. Core Problem Analysis 4 | 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. 5 | 6 | ## 2. Verifiable Technology Recommendations 7 | 8 | | Technology/Pattern | Rationale & Evidence | 9 | |---|---| 10 | | **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]. | 11 | | **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. | 12 | | **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]. | 13 | | **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. | 14 | | **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]. | 15 | 16 | ## 3. Browsed Sources 17 | 18 | - [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 19 | - [2] https://www.typescriptlang.org/docs/handbook/intro.html - TypeScript documentation showing how static typing reduces runtime errors and improves development experience 20 | - [3] https://martinfowler.com/articles/monoliths.html - Martin Fowler's analysis of modular monolith architecture, including successful case studies from Basecamp and GitHub 21 | - [4] https://www.postgresql.org/about/ - PostgreSQL official documentation highlighting ACID compliance, reliability statistics, and financial industry adoption 22 | - [5] https://redis.io/topics/introduction - Redis documentation showing performance benchmarks and scalability for real-time applications 23 | - [6] https://socket.io/docs/ - Socket.io documentation demonstrating fallback mechanisms and compatibility features 24 | - [7] https://www.docker.com/why-docker/ - Docker documentation showing containerization benefits and environment consistency 25 | - [8] https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/ - Kubernetes documentation detailing scaling capabilities and cost reduction studies -------------------------------------------------------------------------------- /CLAUDE.md: -------------------------------------------------------------------------------- 1 | # CLAUDE.md 2 | 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. 4 | 5 | ## Project Overview 6 | 7 | This is the **Specification Architect** - an AI skill that generates rigorous, evidence-based architectural documentation with complete traceability. It implements a 6-phase process that eliminates "research slop" by mandating verification of all claims through web browsing and citations. 8 | 9 | ## Core Commands 10 | 11 | ### Validation (Most Common) 12 | ```bash 13 | # Primary validation - ensures 100% requirements coverage 14 | python specification-architect/validate_specifications.py 15 | 16 | # With options 17 | python specification-architect/validate_specifications.py --path ./specs --verbose --generate-validation 18 | 19 | # Advanced traceability validation 20 | python specification-architect/scripts/traceability_validator.py 21 | ``` 22 | 23 | ### Cross-Platform Helpers 24 | ```bash 25 | # Linux/macOS 26 | specification-architect/validate.sh --verbose --generate 27 | 28 | # Windows 29 | specification-architect\validate.bat --verbose --generate 30 | ``` 31 | 32 | ## Critical Methodology Rules 33 | 34 | ### 1. Evidence-Based Research (Phase 0) 35 | - **MANDATORY**: Use WebSearch THEN WebFetch - never rely on search snippets 36 | - **CITATION FORMAT**: Every factual claim must end with `[cite:INDEX]` 37 | - **VERIFICATION**: Read full source content before making claims 38 | - **EVIDENCE TRAIL**: Create auditable trail from claim to source 39 | 40 | ### 2. Document Generation Sequence 41 | 1. **research.md** - Verified research with citations (NEW anti-slop phase) 42 | 2. **blueprint.md** - Component architecture and data flow 43 | 3. **requirements.md** - Acceptance criteria with component assignments 44 | 4. **design.md** - Detailed component specifications 45 | 5. **tasks.md** - Implementation tasks with requirement traceability 46 | 6. **validation.md** - Automated validation results 47 | 48 | ### 3. Quality Gates 49 | - Each phase requires explicit approval before proceeding 50 | - Component names must match EXACTLY across all documents 51 | - 100% requirements coverage is mandatory for validation success 52 | - Template format must be followed precisely 53 | 54 | ## Architecture Understanding 55 | 56 | ### Core Components 57 | - **Validation Engine**: Python-based multi-layer validation system 58 | - **Template System**: Enforces consistent document structure 59 | - **Traceability Matrix**: Maps requirements to implementation tasks 60 | - **Evidence Protocol**: Prevents AI-generated misinformation 61 | 62 | ### Key Files 63 | - `specification-architect/validate_specifications.py` - Main validation script (165 lines) 64 | - `specification-architect/scripts/traceability_validator.py` - Advanced validation (340 lines) 65 | - `specification-architect/SKILL.md` - Complete skill documentation (328 lines) 66 | - `specification-architect/references/document_templates.md` - Template examples (448 lines) 67 | 68 | ### Validation Exit Codes 69 | - **0**: Success (100% coverage achieved) 70 | - **1**: Failure (missing files, incomplete coverage, format errors) 71 | 72 | ## Professional Standards 73 | 74 | This system prevents: 75 | - **Legal sanctions** from fabricated citations 76 | - **Financial penalties** from incorrect statistics 77 | - **Professional ruin** from AI-generated misinformation 78 | 79 | ### Anti-"Research Slop" Protocol 80 | 1. Search for sources 81 | 2. Browse and read full content 82 | 3. Cite every factual claim 83 | 4. Create auditable evidence trail 84 | 5. Never generate "facts" without verification 85 | 86 | ## Development Workflow 87 | 88 | When working with this repository: 89 | 90 | 1. **Always run validation** after document changes: `python specification-architect/validate_specifications.py` 91 | 2. **Check sample outputs** in `specification-architect/assets/sample_outputs/` for format examples 92 | 3. **Follow templates** strictly from `specification-architect/references/document_templates.md` 93 | 4. **Verify research claims** with proper citation format 94 | 5. **Maintain traceability** - every requirement must map to tasks 95 | 96 | ## Quality Assurance 97 | 98 | The validation system ensures: 99 | - All required documents exist 100 | - Component names are consistent across documents 101 | - Requirements have 100% task coverage 102 | - Citations follow proper format 103 | - Templates are correctly implemented 104 | 105 | **Remember**: This system prioritizes verifiable accuracy over polished but unverified content. When in doubt, find sources and cite them properly. -------------------------------------------------------------------------------- /specification-architect/assets/sample_outputs/example_validation.md: -------------------------------------------------------------------------------- 1 | # Validation Report 2 | 3 | ## 1. Requirements to Tasks Traceability Matrix 4 | 5 | | Requirement | Acceptance Criterion | Implementing Task(s) | Status | 6 | |---|---|---|---| 7 | | 1. User Management | 1.1 | Task 1, Task 8 | Covered | 8 | | | 1.2 | Task 1, Task 6 | Covered | 9 | | | 1.3 | Task 1, Task 8 | Covered | 10 | | | 1.4 | Task 1, Task 6 | Covered | 11 | | 2. Task Creation and Management | 2.1 | Task 2, Task 6 | Covered | 12 | | | 2.2 | Task 2, Task 6 | Covered | 13 | | | 2.3 | Task 2, Task 5 | Covered | 14 | | | 2.4 | Task 2, Task 5 | Covered | 15 | | 3. Project Organization | 3.1 | Task 4, Task 6 | Covered | 16 | | | 3.2 | Task 4, Task 8 | Covered | 17 | | | 3.3 | Task 4, Task 8 | Covered | 18 | | | 3.4 | Task 4, Task 8 | Covered | 19 | | 4. Real-time Notifications | 4.1 | Task 5, Task 8 | Covered | 20 | | | 4.2 | Task 5, Task 8 | Covered | 21 | | | 4.3 | Task 5, Task 8 | Covered | 22 | | | 4.4 | Task 5, Task 8 | Covered | 23 | | 5. Reporting and Analytics | 5.1 | Task 7, Task 10 | Covered | 24 | | | 5.2 | Task 7, Task 8 | Covered | 25 | | | 5.3 | Task 7, Task 8 | Covered | 26 | | | 5.4 | Task 7, Task 10 | Covered | 27 | | 6. Performance | 6.1 | Task 2, Task 12 | Covered | 28 | | | 6.2 | Task 7, Task 12 | Covered | 29 | | | 6.3 | Task 8, Task 12 | Covered | 30 | | | 6.4 | Task 5, Task 12 | Covered | 31 | | 7. Security | 7.1 | Task 1, Task 9 | Covered | 32 | | | 7.2 | Task 1, Task 9 | Covered | 33 | | | 7.3 | Task 2, Task 9 | Covered | 34 | | | 7.4 | Task 3, Task 9 | Covered | 35 | 36 | ## 2. Coverage Analysis 37 | 38 | ### Summary 39 | - **Total Acceptance Criteria**: 28 40 | - **Criteria Covered by Tasks**: 28 41 | - **Coverage Percentage**: 100% 42 | 43 | ### Detailed Status 44 | - **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 45 | - **Missing Criteria**: None 46 | - **Invalid References**: None 47 | 48 | ## 3. Validation Summary 49 | 50 | ### Component Coverage Analysis 51 | - **UserAuthenticationService**: All 6 acceptance criteria covered across tasks 1, 6, 8, 9 52 | - **TaskManagementEngine**: All 4 acceptance criteria covered across tasks 2, 5, 6, 9, 12 53 | - **ProjectOrganizer**: All 4 acceptance criteria covered across tasks 4, 6, 8 54 | - **NotificationService**: All 4 acceptance criteria covered across tasks 5, 8, 12 55 | - **ReportingModule**: All 4 acceptance criteria covered across tasks 7, 8, 10, 12 56 | - **Infrastructure Components**: All 6 security and performance criteria covered across tasks 3, 9, 12 57 | 58 | ### Task Distribution Analysis 59 | - **Phase 1 (Infrastructure)**: Tasks 1-2 cover 10 acceptance criteria 60 | - **Phase 2 (Data Layer)**: Tasks 3-4 cover 8 acceptance criteria 61 | - **Phase 3 (Communication)**: Tasks 5-6 cover 8 acceptance criteria 62 | - **Phase 4 (Business Intelligence)**: Task 7 covers 4 acceptance criteria 63 | - **Phase 5 (Testing)**: Tasks 8-9 cover 16 acceptance criteria 64 | - **Phase 6 (Deployment)**: Task 10 covers 2 acceptance criteria 65 | - **Phase 7 (Performance)**: Task 12 covers 4 acceptance criteria 66 | 67 | ### Cross-Cutting Concerns 68 | - **Security Requirements**: All 4 criteria (7.1-7.4) addressed in tasks 1, 2, 3, 9 69 | - **Performance Requirements**: All 4 criteria (6.1-6.4) addressed in tasks 2, 5, 7, 12 70 | - **Authentication/Authorization**: Integrated throughout tasks 1, 2, 4, 6 71 | - **Data Validation**: Covered in tasks 1, 2, 4, 6, 9 72 | - **Error Handling**: Addressed in tasks 1, 2, 4, 5, 7, 9 73 | 74 | ## 4. Final Validation 75 | 76 | All 28 acceptance criteria are fully traced to implementation tasks. The plan is validated and ready for execution. 77 | 78 | ### Validation Results: 79 | - ✅ **Requirements Coverage**: 100% (28/28 criteria covered) 80 | - ✅ **Task Traceability**: All 13 major tasks have proper requirement references 81 | - ✅ **Component Consistency**: All component names used consistently across documents 82 | - ✅ **Template Adherence**: All documents follow the specified templates 83 | - ✅ **Reference Validity**: No invalid requirement references found in tasks 84 | 85 | ### Readiness Assessment: 86 | - ✅ **Architecture**: Complete and validated 87 | - ✅ **Requirements**: Fully specified and testable 88 | - ✅ **Design**: Detailed and comprehensive 89 | - ✅ **Implementation Plan**: Granular and actionable 90 | - ✅ **Validation**: Automated and verified 91 | 92 | ## 5. Next Steps 93 | 94 | The specification is now complete and validated. The following actions are recommended: 95 | 96 | 1. **Begin Implementation**: Start with Phase 1 tasks as outlined in the implementation plan 97 | 2. **Setup Development Environment**: Configure tools, databases, and repositories 98 | 3. **Establish Quality Gates**: Implement the traceability validator in CI/CD pipeline 99 | 4. **Regular Validation**: Run validation checks after each major milestone 100 | 5. **Stakeholder Review**: Conduct final review with all project stakeholders 101 | 102 | ## 6. Validation Command 103 | 104 | To re-run validation during implementation: 105 | 106 | ```bash 107 | python scripts/traceability_validator.py --path . --requirements requirements.md --tasks tasks.md 108 | ``` 109 | 110 | This command will verify that all requirements remain covered throughout the development process. -------------------------------------------------------------------------------- /specification-architect/assets/sample_outputs/example_requirements.md: -------------------------------------------------------------------------------- 1 | # Requirements Document 2 | 3 | ## Introduction 4 | This document defines the functional and non-functional requirements for the TaskMaster Pro task management system. 5 | 6 | ## Glossary 7 | - **Task**: A unit of work that can be assigned to a user and tracked through completion 8 | - **Project**: A collection of related tasks organized under a common goal 9 | - **User**: An individual with login credentials who can interact with the system 10 | - **Notification**: A message sent to users about task updates or assignments 11 | - **UserAuthenticationService**: The component responsible for managing user accounts and authentication 12 | 13 | ## Requirements 14 | 15 | ### Requirement 1: User Management 16 | **Description**: Users must be able to register, authenticate, and manage their profiles. 17 | 18 | #### Acceptance Criteria 19 | 1. WHEN a new user provides valid registration information, THE **UserAuthenticationService** SHALL create a new user account and send a verification email. 20 | 2. WHEN a registered user provides correct credentials, THE **UserAuthenticationService** SHALL return a valid JWT token for session management. 21 | 3. WHEN a user requests password reset, THE **UserAuthenticationService** SHALL send a password reset link to their registered email. 22 | 4. WHEN a JWT token expires, THE **UserAuthenticationService** SHALL require re-authentication. 23 | 24 | ### Requirement 2: Task Creation and Management 25 | **Description**: Users must be able to create, edit, assign, and track tasks. 26 | 27 | #### Acceptance Criteria 28 | 1. WHEN a user creates a new task with valid information, THE **TaskManagementEngine** SHALL save the task and assign it a unique identifier. 29 | 2. WHEN a user edits an existing task, THE **TaskManagementEngine** SHALL update the task and maintain change history. 30 | 3. WHEN a task is assigned to a user, THE **TaskManagementEngine** SHALL notify the assigned user via the **NotificationService**. 31 | 4. WHEN a task status changes, THE **TaskManagementEngine** SHALL update the task status and notify relevant users. 32 | 33 | ### Requirement 3: Project Organization 34 | **Description**: Tasks must be organized into projects with proper access control. 35 | 36 | #### Acceptance Criteria 37 | 1. WHEN a user creates a new project, THE **ProjectOrganizer** SHALL create the project and assign the user as project owner. 38 | 2. WHEN a project owner adds team members, THE **ProjectOrganizer** SHALL grant appropriate permissions based on role assignments. 39 | 3. WHEN a user accesses project tasks, THE **ProjectOrganizer** SHALL validate that the user has permission to view the project. 40 | 4. WHEN a project is deleted, THE **ProjectOrganizer** SHALL archive all associated tasks and notify project members. 41 | 42 | ### Requirement 4: Real-time Notifications 43 | **Description**: Users must receive real-time notifications about task updates and assignments. 44 | 45 | #### Acceptance Criteria 46 | 1. WHEN a task is assigned to a user, THE **NotificationService** SHALL send an immediate notification via WebSocket. 47 | 2. WHEN a task deadline approaches, THE **NotificationService** SHALL send reminder notifications to assigned users. 48 | 3. WHEN multiple users edit the same task, THE **NotificationService** SHALL broadcast real-time updates to prevent conflicts. 49 | 4. WHEN system maintenance occurs, THE **NotificationService** SHALL display maintenance notifications to all active users. 50 | 51 | ### Requirement 5: Reporting and Analytics 52 | **Description**: Users must be able to view reports and analytics about task completion and project progress. 53 | 54 | #### Acceptance Criteria 55 | 1. WHEN a project owner requests a progress report, THE **ReportingModule** SHALL generate a report showing task completion rates and team productivity. 56 | 2. WHEN a manager views analytics dashboard, THE **ReportingModule** SHALL display charts showing task distribution by status and assignee. 57 | 3. WHEN tasks are overdue, THE **ReportingModule** SHALL highlight overdue items and calculate impact on project timeline. 58 | 4. WHEN a project is completed, THE **ReportingModule** SHALL generate a final performance report with key metrics. 59 | 60 | ## Non-Functional Requirements 61 | 62 | ### Requirement 6: Performance 63 | **Description**: System must respond quickly under normal load conditions. 64 | 65 | #### Acceptance Criteria 66 | 1. WHEN 100 concurrent users access the system, THE **TaskManagementEngine** SHALL respond to task operations within 200 milliseconds. 67 | 2. WHEN generating reports, THE **ReportingModule** SHALL complete report generation within 5 seconds for projects with up to 1000 tasks. 68 | 3. WHEN users authenticate, THE **UserAuthenticationService** SHALL complete login within 500 milliseconds. 69 | 4. WHEN notifications are sent, THE **NotificationService** SHALL deliver notifications within 1 second of trigger events. 70 | 71 | ### Requirement 7: Security 72 | **Description**: System must protect user data and prevent unauthorized access. 73 | 74 | #### Acceptance Criteria 75 | 1. WHEN users submit sensitive information, THE **UserAuthenticationService** SHALL encrypt all data in transit using HTTPS. 76 | 2. WHEN passwords are stored, THE **UserAuthenticationService** SHALL hash passwords using bcrypt with minimum 12 rounds. 77 | 3. WHEN API requests are made, THE **TaskManagementEngine** SHALL validate JWT tokens and enforce role-based access control. 78 | 4. WHEN database connections are established, THE system SHALL use SSL/TLS encryption for all database communications. -------------------------------------------------------------------------------- /specification-architect/assets/sample_outputs/example_research.md: -------------------------------------------------------------------------------- 1 | ## Research Summary for Task Management System 2 | 3 | ### Domain Analysis 4 | - **Industry**: Productivity/Project Management Software 5 | - **Scale Requirements**: 1,000+ concurrent users, 10,000+ tasks, real-time collaboration 6 | - **Key Challenges**: Real-time updates, data consistency, user permission management, notification delivery 7 | 8 | ### Architectural Approaches Considered 9 | 10 | 1. **Microservices Architecture** 11 | - Description: Decompose system into independent services for users, tasks, projects, notifications 12 | - Pros: Independent scaling, fault isolation, technology diversity, team autonomy 13 | - Cons: Operational complexity, network latency, distributed transactions, higher cost 14 | 15 | 2. **Monolithic Architecture** 16 | - Description: Single application with modular components within one deployable unit 17 | - Pros: Simpler deployment, easier debugging, lower operational overhead, better performance 18 | - Cons: Scalability limits, technology lock-in, deployment risks, team coordination challenges 19 | 20 | 3. **Event-Driven Architecture with CQRS** 21 | - Description: Command Query Responsibility Segregation with event sourcing 22 | - Pros: Excellent scalability, audit trails, real-time updates, loose coupling 23 | - Cons: High complexity, eventual consistency, steep learning curve, debugging challenges 24 | 25 | ### Technology Stack Research 26 | 27 | #### Backend Frameworks 28 | - **Node.js + Express**: Excellent for real-time features, large ecosystem, fast development 29 | - **Python + FastAPI**: Strong typing, async support, good for APIs, data science integration 30 | - **Java + Spring Boot**: Enterprise-grade, mature ecosystem, strong consistency 31 | 32 | #### Database Options 33 | - **PostgreSQL**: ACID compliance, JSON support, reliability, good for complex queries 34 | - **MongoDB**: Flexible schema, horizontal scaling, good for rapid development 35 | - **MySQL**: Mature, widely used, good performance, familiar to most developers 36 | 37 | #### Real-time Communication 38 | - **WebSockets**: Direct communication, low latency, widely supported 39 | - **Server-Sent Events (SSE)**: Simpler than WebSockets, good for one-way updates 40 | - **Message Queues (Redis/RabbitMQ)**: Reliable delivery, scalable, decoupled 41 | 42 | ### Recommended Technology Stack 43 | 44 | - **Architecture Pattern**: **Modular Monolith with Microservice Readiness** 45 | - Start with monolith for speed and simplicity 46 | - Design modules to be easily extractable into microservices later 47 | - Use clear boundaries between functional areas 48 | 49 | - **Backend**: **Node.js + TypeScript + Express** 50 | - TypeScript for type safety and better development experience 51 | - Express for mature, well-documented framework 52 | - Excellent ecosystem for real-time features (Socket.io) 53 | - Good performance for I/O-bound applications 54 | 55 | - **Database**: **PostgreSQL + Redis** 56 | - PostgreSQL as primary database for ACID compliance and reliability 57 | - Redis for session management, caching, and real-time data 58 | - Both have excellent Node.js support 59 | 60 | - **Real-time Communication**: **Socket.io + Redis Adapter** 61 | - Socket.io for WebSocket connections with fallback support 62 | - Redis adapter for multi-instance scaling 63 | - Proven solution for real-time collaboration 64 | 65 | - **Authentication**: **JWT + Refresh Tokens** 66 | - JWT for stateless authentication 67 | - Refresh tokens for security and better user experience 68 | - Industry standard with good library support 69 | 70 | - **Infrastructure**: **Docker + AWS ECS/RDS** 71 | - Docker for containerization and consistency 72 | - AWS ECS for managed container orchestration 73 | - AWS RDS for managed PostgreSQL with automatic backups 74 | 75 | ### Research Sources 76 | 77 | 1. **"Microservices vs Monolith: When to Choose Which"** (Martin Fowler, 2024) 78 | - Key insight: Start with monolith, extract microservices when clear boundaries emerge 79 | - Most successful microservices implementations evolved from monoliths 80 | 81 | 2. **"Real-time Web Application Architecture Best Practices"** (InfoQ, 2024) 82 | - WebSocket scaling challenges and solutions 83 | - Redis adapter pattern for multi-instance deployments 84 | 85 | 3. **"PostgreSQL vs MongoDB for Task Management Systems"** (Database Journal, 2024) 86 | - PostgreSQL superior for complex queries and data consistency 87 | - JSON support provides flexibility when needed 88 | 89 | 4. **"Node.js TypeScript Best Practices for Enterprise Applications"** (Node.js Foundation, 2024) 90 | - Type safety significantly reduces runtime errors 91 | - Better development experience with IDE support 92 | 93 | 5. **"Authentication Patterns for Modern Web Applications"** (OWASP, 2024) 94 | - JWT + refresh token pattern recommended for SPA applications 95 | - Proper token storage and refresh strategies 96 | 97 | ### Decision Rationale 98 | 99 | **Why Modular Monolith First:** 100 | - Team size (3-5 developers) doesn't warrant microservices complexity 101 | - Faster time-to-market with simpler deployment and debugging 102 | - Clear module boundaries will allow future extraction if needed 103 | - Lower operational cost and complexity for initial launch 104 | 105 | **Why Node.js + TypeScript:** 106 | - Real-time features are first-class citizens in Node.js ecosystem 107 | - TypeScript provides enterprise-grade type safety 108 | - Large talent pool and extensive library ecosystem 109 | - Excellent performance for our I/O-bound use case 110 | 111 | **Why PostgreSQL + Redis:** 112 | - Data consistency is critical for task management 113 | - PostgreSQL handles complex queries and relationships well 114 | - Redis provides excellent caching and real-time data capabilities 115 | - Both technologies are mature, well-supported, and cost-effective 116 | 117 | **Why Socket.io for Real-time:** 118 | - Handles WebSocket connection management complexity 119 | - Provides automatic fallback to other transport methods 120 | - Redis adapter enables horizontal scaling 121 | - Large community and proven track record 122 | 123 | This technology stack balances development speed, operational simplicity, and future scalability while leveraging current best practices and well-established patterns. -------------------------------------------------------------------------------- /specification-architect/validate_specifications.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """Specification Architect Validation Script""" 3 | import re, sys, json, argparse 4 | from pathlib import Path 5 | from dataclasses import dataclass, field 6 | from typing import Dict, Set, List 7 | 8 | @dataclass 9 | class Result: 10 | total: int = 0 11 | covered: Set[str] = field(default_factory=set) 12 | missing: Set[str] = field(default_factory=set) 13 | coverage: float = 0.0 14 | valid: bool = False 15 | errors: List[str] = field(default_factory=list) 16 | 17 | class Validator: 18 | def __init__(self, spec_dir: str, verbose=False): 19 | self.dir = Path(spec_dir) 20 | self.verbose = verbose 21 | self.result = Result() 22 | self.components = set() 23 | self.requirements = {} 24 | self.task_reqs = set() 25 | 26 | def log(self, msg, level="INFO"): 27 | if self.verbose or level=="ERROR": 28 | print(f"[{level}] {msg}") 29 | 30 | def validate(self) -> Result: 31 | self.log("Starting validation...") 32 | 33 | if not self._files_exist(): 34 | return self.result 35 | if not self._extract_components(): 36 | return self.result 37 | if not self._extract_requirements(): 38 | return self.result 39 | if not self._extract_tasks(): 40 | return self.result 41 | 42 | self._calculate() 43 | self._report() 44 | return self.result 45 | 46 | def _files_exist(self) -> bool: 47 | for name in ["blueprint.md", "requirements.md", "tasks.md"]: 48 | if not (self.dir / name).exists(): 49 | self.result.errors.append(f"Missing: {name}") 50 | return len(self.result.errors) == 0 51 | 52 | def _extract_components(self) -> bool: 53 | try: 54 | content = (self.dir / "blueprint.md").read_text() 55 | self.components = set(re.findall(r'\|\s*\*\*([A-Za-z0-9_]+)\*\*\s*\|', content)) 56 | if not self.components: 57 | self.log("No components found", "WARNING") 58 | return False 59 | self.log(f"Found {len(self.components)} components") 60 | return True 61 | except Exception as e: 62 | self.log(f"Error: {e}", "ERROR") 63 | return False 64 | 65 | def _extract_requirements(self) -> bool: 66 | try: 67 | content = (self.dir / "requirements.md").read_text() 68 | for match in re.finditer(r'### Requirement (\d+):', content): 69 | req_num = match.group(1) 70 | start = match.end() 71 | end = len(content) 72 | text = content[start:end] 73 | 74 | criteria = [f"{req_num}.{c}" for c, _ in re.findall( 75 | r'(\d+)\.\s+WHEN.*?THE\s+\*\*([A-Za-z0-9_]+)\*\*\s+SHALL', 76 | text, re.DOTALL)] 77 | if criteria: 78 | self.requirements[req_num] = criteria 79 | 80 | self.result.total = sum(len(v) for v in self.requirements.values()) 81 | self.log(f"Found {self.result.total} criteria") 82 | return self.result.total > 0 83 | except Exception as e: 84 | self.log(f"Error: {e}", "ERROR") 85 | return False 86 | 87 | def _extract_tasks(self) -> bool: 88 | try: 89 | content = (self.dir / "tasks.md").read_text() 90 | for match in re.findall(r'_Requirements:\s*([\d., ]+)_', content): 91 | for c in match.split(','): 92 | self.task_reqs.add(c.strip()) 93 | if not self.task_reqs: 94 | self.log("No requirement tags found", "WARNING") 95 | return False 96 | self.log(f"Found {len(self.task_reqs)} covered criteria") 97 | return True 98 | except Exception as e: 99 | self.log(f"Error: {e}", "ERROR") 100 | return False 101 | 102 | def _calculate(self): 103 | all_crit = set() 104 | for crit_list in self.requirements.values(): 105 | all_crit.update(crit_list) 106 | 107 | self.result.covered = self.task_reqs & all_crit 108 | self.result.missing = all_crit - self.task_reqs 109 | 110 | if all_crit: 111 | self.result.coverage = (len(self.result.covered) / len(all_crit)) * 100 112 | 113 | self.result.valid = self.result.coverage == 100.0 114 | 115 | def _report(self): 116 | print("\n" + "="*80) 117 | print("SPECIFICATION VALIDATION REPORT") 118 | print("="*80 + "\n") 119 | 120 | print("SUMMARY") 121 | print("-"*80) 122 | print(f"Total Criteria: {self.result.total}") 123 | print(f"Covered by Tasks: {len(self.result.covered)}") 124 | print(f"Coverage: {self.result.coverage:.1f}%\n") 125 | 126 | if self.result.missing: 127 | print("MISSING CRITERIA") 128 | print("-"*80) 129 | for c in sorted(self.result.missing, key=lambda x: tuple(map(int, x.split('.')))): 130 | print(f" - {c}") 131 | print() 132 | 133 | print("VALIDATION STATUS") 134 | print("-"*80) 135 | if self.result.valid: 136 | print("✅ PASSED - All criteria covered\n") 137 | else: 138 | print(f"❌ FAILED - {len(self.result.missing)} uncovered\n") 139 | 140 | print("="*80 + "\n") 141 | 142 | def main(): 143 | parser = argparse.ArgumentParser(description="Validate specifications") 144 | parser.add_argument("--path", default=".", help="Spec directory") 145 | parser.add_argument("--verbose", action="store_true", help="Verbose") 146 | parser.add_argument("--json", action="store_true", help="JSON output") 147 | args = parser.parse_args() 148 | 149 | v = Validator(args.path, args.verbose) 150 | result = v.validate() 151 | 152 | if args.json: 153 | print(json.dumps({ 154 | "total": result.total, 155 | "covered": len(result.covered), 156 | "missing": list(result.missing), 157 | "coverage": result.coverage, 158 | "valid": result.valid, 159 | }, indent=2)) 160 | 161 | sys.exit(0 if result.valid else 1) 162 | 163 | if __name__ == "__main__": 164 | main() 165 | -------------------------------------------------------------------------------- /specification-architect/assets/sample_outputs/example_tasks.md: -------------------------------------------------------------------------------- 1 | # Implementation Plan 2 | 3 | ## Phase 1: Core Infrastructure 4 | - [ ] 1. Implement the UserAuthenticationService 5 | - [ ] 1.1 Create project structure and setup configuration 6 | - [ ] 1.2 Implement core UserAuthenticationService class in `src/services/auth/UserAuthenticationService.py` 7 | - [ ] 1.3 Add user registration and validation methods 8 | - [ ] 1.4 Implement JWT token generation and validation 9 | - [ ] 1.5 Add password hashing with bcrypt 10 | - [ ] 1.6 Create user repository interface and implementation 11 | - [ ] 1.7 Write unit tests for UserAuthenticationService 12 | - [ ] 1.8 Create integration tests for authentication flow 13 | - _Requirements: 1.1, 1.2, 1.3, 1.4, 7.1, 7.2_ 14 | 15 | - [ ] 2. Implement the TaskManagementEngine 16 | - [ ] 2.1 Create TaskManagementEngine class in `src/services/tasks/TaskManagementEngine.py` 17 | - [ ] 2.2 Implement task CRUD operations (create, read, update, delete) 18 | - [ ] 2.3 Add task assignment and status change methods 19 | - [ ] 2.4 Implement task filtering and search functionality 20 | - [ ] 2.5 Create task repository interface and implementation 21 | - [ ] 2.6 Add input validation and business rules 22 | - [ ] 2.7 Write unit tests for task operations 23 | - [ ] 2.8 Create performance tests for task queries 24 | - _Requirements: 2.1, 2.2, 2.3, 2.4, 6.1, 7.3_ 25 | 26 | ## Phase 2: Data Layer and Storage 27 | - [ ] 3. Setup Database Infrastructure 28 | - [ ] 3.1 Configure PostgreSQL database connection 29 | - [ ] 3.2 Create database migration scripts for schema 30 | - [ ] 3.3 Implement users table with proper constraints 31 | - [ ] 3.4 Create tasks table with foreign key relationships 32 | - [ ] 3.5 Setup projects table and member relationships 33 | - [ ] 3.6 Add indexes for performance optimization 34 | - [ ] 3.7 Create database backup and recovery procedures 35 | - [ ] 3.8 Write database integration tests 36 | - _Requirements: 1.1, 2.1, 3.1, 3.2, 3.3, 3.4, 7.4_ 37 | 38 | - [ ] 4. Implement the ProjectOrganizer 39 | - [ ] 4.1 Create ProjectOrganizer class in `src/services/projects/ProjectOrganizer.py` 40 | - [ ] 4.2 Implement project creation and management methods 41 | - [ ] 4.3 Add team member invitation and permission system 42 | - [ ] 4.4 Create project repository interface and implementation 43 | - [ ] 4.5 Implement role-based access control for projects 44 | - [ ] 4.6 Add project archiving and deletion functionality 45 | - [ ] 4.7 Write unit tests for project operations 46 | - [ ] 4.8 Create tests for permission validation 47 | - _Requirements: 3.1, 3.2, 3.3, 3.4_ 48 | 49 | ## Phase 3: Communication Layer 50 | - [ ] 5. Implement the NotificationService 51 | - [ ] 5.1 Create NotificationService class in `src/services/notifications/NotificationService.py` 52 | - [ ] 5.2 Setup WebSocket manager for real-time communications 53 | - [ ] 5.3 Implement email service integration with SMTP 54 | - [ ] 5.4 Create notification templates and formatting 55 | - [ ] 5.5 Add notification queue and retry mechanisms 56 | - [ ] 5.6 Implement notification preferences and filtering 57 | - [ ] 5.7 Write tests for real-time notification delivery 58 | - [ ] 5.8 Create email notification tests 59 | - _Requirements: 4.1, 4.2, 4.3, 4.4, 6.4_ 60 | 61 | - [ ] 6. REST API Implementation 62 | - [ ] 6.1 Create Flask/FastAPI application structure 63 | - [ ] 6.2 Implement authentication middleware and decorators 64 | - [ ] 6.3 Create user endpoints (register, login, profile) 65 | - [ ] 6.4 Implement task CRUD endpoints with proper validation 66 | - [ ] 6.5 Add project management endpoints 67 | - [ ] 6.6 Create API documentation with OpenAPI/Swagger 68 | - [ ] 6.7 Add rate limiting and request validation 69 | - [ ] 6.8 Write comprehensive API tests 70 | - _Requirements: 1.2, 2.1, 2.2, 3.1, 7.3_ 71 | 72 | ## Phase 4: Business Intelligence 73 | - [ ] 7. Implement the ReportingModule 74 | - [ ] 7.1 Create ReportingModule class in `src/services/reports/ReportingModule.py` 75 | - [ ] 7.2 Implement task completion rate calculations 76 | - [ ] 7.3 Create productivity analytics and dashboards 77 | - [ ] 7.4 Add overdue task identification and impact analysis 78 | - [ ] 7.5 Implement project performance metrics 79 | - [ ] 7.6 Create report generation and export functionality 80 | - [ ] 7.7 Add caching for frequently accessed reports 81 | - [ ] 7.8 Write tests for report accuracy and performance 82 | - _Requirements: 5.1, 5.2, 5.3, 5.4, 6.2_ 83 | 84 | ## Phase 5: Testing and Quality Assurance 85 | - [ ] 8. Comprehensive Testing Suite 86 | - [ ] 8.1 Complete unit test coverage for all components (target: 90%+) 87 | - [ ] 8.2 Create integration tests for component interactions 88 | - [ ] 8.3 Implement end-to-end tests for critical user flows 89 | - [ ] 8.4 Add performance testing and load testing 90 | - [ ] 8.5 Create security testing and vulnerability scanning 91 | - [ ] 8.6 Implement automated testing in CI/CD pipeline 92 | - [ ] 8.7 Add user acceptance testing scenarios 93 | - [ ] 8.8 Create test data management and cleanup procedures 94 | - _Requirements: 6.1, 6.2, 6.3, 6.4_ 95 | 96 | - [ ] 9. Security Implementation 97 | - [ ] 9.1 Configure HTTPS/TLS for all communications 98 | - [ ] 9.2 Implement secure password storage and hashing 99 | - [ ] 9.3 Add input validation and sanitization 100 | - [ ] 9.4 Create security headers and CSP policies 101 | - [ ] 9.5 Implement audit logging for sensitive operations 102 | - [ ] 9.6 Add rate limiting and DDoS protection 103 | - [ ] 9.7 Create security monitoring and alerting 104 | - [ ] 9.8 Write security tests and penetration testing 105 | - _Requirements: 7.1, 7.2, 7.3, 7.4_ 106 | 107 | ## Phase 6: Deployment and Operations 108 | - [ ] 10. Production Deployment 109 | - [ ] 10.1 Setup production environment and infrastructure 110 | - [ ] 10.2 Configure application servers and load balancers 111 | - [ ] 10.3 Implement database clustering and backup strategies 112 | - [ ] 10.4 Setup monitoring and logging infrastructure 113 | - [ ] 10.5 Create deployment scripts and CI/CD pipeline 114 | - [ ] 10.6 Configure environment-specific settings 115 | - [ ] 10.7 Implement health checks and monitoring alerts 116 | - [ ] 10.8 Create disaster recovery and rollback procedures 117 | - _Requirements: 5.1, 5.2_ 118 | 119 | - [ ] 11. Documentation and Training 120 | - [ ] 11.1 Create comprehensive API documentation 121 | - [ ] 11.2 Write user guides and documentation 122 | - [ ] 11.3 Create administrator and deployment guides 123 | - [ ] 11.4 Document system architecture and design decisions 124 | - [ ] 11.5 Create troubleshooting and maintenance guides 125 | - [ ] 11.6 Develop training materials for end users 126 | - [ ] 11.7 Record video tutorials and walkthroughs 127 | - [ ] 11.8 Create knowledge base and FAQ resources 128 | - _Requirements: 5.1, 5.2_ 129 | 130 | ## Phase 7: Performance Optimization 131 | - [ ] 12. Performance Tuning 132 | - [ ] 12.1 Optimize database queries and add query caching 133 | - [ ] 12.2 Implement Redis caching for frequently accessed data 134 | - [ ] 12.3 Add connection pooling and optimize resource usage 135 | - [ ] 12.4 Optimize API response times and implement pagination 136 | - [ ] 12.5 Add asynchronous processing for long-running tasks 137 | - [ ] 12.6 Implement content delivery network for static assets 138 | - [ ] 12.7 Monitor and optimize memory usage 139 | - [ ] 12.8 Create performance benchmarks and monitoring 140 | - _Requirements: 6.1, 6.2, 6.3, 6.4_ 141 | 142 | ## Final Acceptance Criteria 143 | - [ ] 13. System Integration and Validation 144 | - [ ] 13.1 Validate all acceptance criteria from requirements document 145 | - [ ] 13.2 Run complete traceability validation using automated script 146 | - [ ] 13.3 Perform full system integration testing 147 | - [ ] 13.4 Conduct security audit and penetration testing 148 | - [ ] 13.5 Validate performance under expected load 149 | - [ ] 13.6 Confirm all user workflows function correctly 150 | - [ ] 13.7 Complete user acceptance testing with stakeholders 151 | - [ ] 13.8 Finalize documentation and prepare for launch 152 | - _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_ -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Specification Architect AI Skill 2 | 3 | ## 📦 Installation 4 | 5 | ### Prerequisites 6 | 7 | - [Claude Code](https://docs.claude.com/en/docs/claude-code) installed and running 8 | 9 | ### Quick Start (Choose Your Method) 10 | 11 | **Method 1: Using Claude Code Chat Interface** 12 | 13 | Inside Claude Code's chat, run these commands: 14 | 15 | ``` 16 | /plugin marketplace add adrianpuiu/specification-document-generator 17 | /plugin install architecture-skills@specification-document-generator 18 | ``` 19 | 20 | **Method 2: Using Terminal/CLI** 21 | 22 | In your terminal, run: 23 | 24 | ```bash 25 | claude plugin marketplace add adrianpuiu/specification-document-generator 26 | claude plugin install architecture-skills@specification-document-generator 27 | ``` 28 | 29 | **What this does:** 30 | - Claude Code fetches `.claude-plugin/marketplace.json` from this GitHub repository 31 | - Discovers the `architecture-skills` plugin (which includes the `specification-architect` skill) 32 | - Installs the plugin and makes all skills available in your session 33 | 34 | ### Alternative Installation Options 35 | 36 | **Option 2: Install from Central Skills Marketplace** 37 | 38 | Claude Code chat: 39 | ``` 40 | /plugin marketplace add adrianpuiu/claude-skills-marketplace 41 | /plugin install architecture-skills@claude-skills-marketplace 42 | ``` 43 | 44 | Terminal: 45 | ```bash 46 | claude plugin marketplace add adrianpuiu/claude-skills-marketplace 47 | claude plugin install architecture-skills@claude-skills-marketplace 48 | ``` 49 | 50 | **Option 3: Local Development Installation** 51 | 52 | Clone the repository: 53 | ```bash 54 | git clone https://github.com/adrianpuiu/specification-document-generator.git 55 | cd specification-document-generator 56 | ``` 57 | 58 | Then install via CLI: 59 | ```bash 60 | claude plugin marketplace add adrianpuiu/specification-document-generator 61 | claude plugin install architecture-skills@specification-document-generator 62 | ``` 63 | 64 | Or via Claude Code chat: 65 | ``` 66 | /plugin marketplace add /absolute/path/to/specification-document-generator 67 | /plugin install architecture-skills@specification-document-generator 68 | ``` 69 | 70 | ### Verify Installation 71 | 72 | **Claude Code chat:** 73 | ``` 74 | /plugin list 75 | ``` 76 | 77 | **Terminal:** 78 | ```bash 79 | claude plugin list 80 | ``` 81 | 82 | You should see `architecture-skills` in the list of installed plugins. 83 | 84 | ### Using the Skill 85 | 86 | Once installed, you can use the `specification-architect` skill in Claude Code. Simply provide your project requirements and the skill will guide you through the 6-phase documentation generation process. 87 | 88 | ## Overview 89 | 90 | A rigorous, evidence-based system that generates six interconnected architectural documents while **eliminating "research slop"** and preventing AI-generated misinformation. Every technological decision is backed by verifiable sources with complete traceability from research through implementation. 91 | 92 | ## 🚨 CRITICAL: Preventing "Research Slop" 93 | 94 | **The Problem**: AI generates content that is polished, articulate, and inspires "faith-like confidence," yet is often unverified and factually incorrect. This has led to: 95 | - **Legal sanctions** for law firms submitting fabricated citations 96 | - **Financial penalties** for consulting firms providing incorrect statistics 97 | - **Professional ruin** from relying on plausible-sounding falsehoods 98 | 99 | **Our Solution**: **Mandatory verification protocol** that transforms AI from "confident author" to "diligent research assistant" with auditable evidence trails. 100 | 101 | ## 🎯 Evidence-Based Architecture 102 | 103 | **The quality of your architectural specification is directly proportional to the verifiability of your research evidence.** 104 | 105 | ### What This Skill Does 106 | 107 | 1. **Phase 0**: 🔍 **Verifiable Research** (Mandatory Web Search + Browsing + Citations) 108 | 2. **Phase 1**: Architectural Blueprint (Evidence-Based Component Mapping) 109 | 3. **Phase 2**: Requirements Generation (Research-Backed Acceptance Criteria) 110 | 4. **Phase 3**: Detailed Design (Source-Validated Specifications) 111 | 5. **Phase 4**: Task Decomposition (Traceable Implementation Plan) 112 | 6. **Phase 5**: Validation & Traceability (100% Coverage + Evidence Verification) 113 | 114 | ## 🚀 Example: Clear Input = Clear Output 115 | 116 | ### User Prompt (High Quality): 117 | ``` 118 | "I need to architect an inventory management system for a growing e-commerce business. 119 | The system must handle 50,000 SKUs, integrate with our existing Shopify store, 120 | and provide real-time stock updates. We need barcode scanning, low-stock alerts, 121 | and supplier management. Please do NOT include POS functionality or customer-facing 122 | features. Our team uses Node.js/React and we need cloud deployment with automatic backups." 123 | ``` 124 | 125 | ### What This Prompt Provides: 126 | ✅ **Clear Business Context**: E-commerce inventory management 127 | ✅ **Specific Constraints**: 50,000 SKUs, Shopify integration, real-time updates 128 | ✅ **Technology Stack**: Node.js/React, cloud deployment 129 | ✅ **Clear Scope Boundaries**: No POS, no customer-facing features 130 | ✅ **Success Metrics**: Barcode scanning, stock alerts, supplier management 131 | 132 | ### Resulting Architecture Quality: 133 | 🎯 **Clear Component Boundaries**: Each service has single responsibility 134 | 🎯 **Explicit Data Flow**: Complete journey from barcode scan to inventory update 135 | 🎯 **Defined Integration Points**: Shopify API, backup systems, cloud infrastructure 136 | 🎯 **Traceable Requirements**: Every feature traced to implementation tasks 137 | 🎯 **No Scope Creep**: Clear boundaries prevent "feature additions" 138 | 139 | ## 📋 Generated Documents 140 | 141 | 1. **research.md** - Web search findings, technology comparison, stack selection (NEW!) 142 | 2. **blueprint.md** - Component mapping, data flow diagrams, integration points 143 | 3. **requirements.md** - Testable acceptance criteria with component assignments 144 | 4. **design.md** - Detailed component specifications and interfaces 145 | 5. **tasks.md** - Implementation plan with requirement traceability 146 | 6. **validation.md** - Automated validation confirming 100% coverage 147 | 148 | ## ✨ Key Features 149 | 150 | - **🚫 Research Slop Prevention**: Mandatory verification eliminates AI-generated misinformation 151 | - **🔍 Evidence-Based Research**: Every claim supported by browsed sources with citations 152 | - **📋 Citation Protocol**: Strict `[cite:INDEX]` format creates auditable evidence trails 153 | - **🛡️ Professional Standards**: Prevents legal sanctions, financial penalties, and professional ruin 154 | - **Automated Validation**: Python script ensures 100% requirements coverage + evidence verification 155 | - **Source Verification**: Mandatory browsing of sources, not just search snippets 156 | - **Template Enforcement**: Guarantees consistency and completeness 157 | - **Component Consistency**: Exact name matching across all documents 158 | - **Traceability Matrix**: Complete mapping from requirements to tasks 159 | - **Quality Gates**: Sequential approval process with evidence verification 160 | 161 | ## 🔍 Phase 0: VERIFIABLE Research - ANTI-SLOP PROTOCOL 162 | 163 | **CRITICAL**: This phase prevents the exact types of AI errors that cause legal sanctions and professional ruin. 164 | 165 | ### Mandatory Verification Process: 166 | 1. **Search THEN Browse**: Use WebSearch to find sources, then WebFetch to read actual content 167 | 2. **NO Search Snippets**: You MUST read full source content, not just search results 168 | 3. **Cite Every Claim**: Every factual statement MUST end with `[cite:INDEX]` citation 169 | 4. **Evidence-Based Decisions**: Technology choices only from verified sources 170 | 5. **Auditable Trail**: Complete citation trail from claim to source 171 | 172 | ### Examples of What We Prevent: 173 | ❌ **Research Slop**: "Node.js is great for real-time apps" 174 | ✅ **Evidence-Based**: "Node.js excels at real-time applications due to its event-driven, non-blocking I/O model [cite:1]" 175 | 176 | ❌ **Research Slop**: "TypeScript reduces errors" 177 | ✅ **Evidence-Based**: "TypeScript adds static typing that reduces runtime errors by approximately 15% in large codebases [cite:2]" 178 | 179 | ### Professional Impact: 180 | This protocol prevents the types of errors that have led to: 181 | - **Legal sanctions** for law firms (fabricated citations) 182 | - **Financial penalties** for consulting firms (incorrect statistics) 183 | - **Professional ruin** from AI-generated misinformation 184 | 185 | ## 🎖️ Critical Success Factors 186 | 187 | ### 1. Research-Driven Decisions 188 | Never skip Phase 0! Web research ensures: 189 | - Current best practices and patterns 190 | - Proven technology stacks 191 | - Industry-specific considerations 192 | - Avoidance of outdated approaches 193 | 194 | ### 2. Component Clarity 195 | Each component must have a single, well-defined responsibility. If you find yourself saying "and also," split into multiple components. 196 | 197 | ### 2. Data Flow Visualization 198 | Map how data moves through the system from input to output. The Mermaid diagram should show the complete journey. 199 | 200 | ### 3. Integration Points 201 | Clearly define all APIs, protocols, and external system connections. Specify data formats, authentication, and error handling. 202 | 203 | ### 4. Boundaries Setting 204 | Explicitly define what's in scope vs. out of scope to prevent scope creep and enable accurate estimation. 205 | 206 | ## 🔧 Usage 207 | 208 | 1. **Provide Clear Requirements**: Include business objectives, constraints, and scope boundaries 209 | 2. **Follow Sequential Phases**: Each phase builds upon the previous one 210 | 3. **Review Quality Gates**: Ensure each phase meets quality criteria before proceeding 211 | 4. **Validate Traceability**: Use the automated validator to confirm complete coverage 212 | 213 | ## 📊 Validation Example 214 | 215 | ``` 216 | Validation Report: 217 | - Total Acceptance Criteria: 28 218 | - Criteria Covered by Tasks: 28 219 | - Coverage Percentage: 100% 220 | - Invalid References: 0 221 | ✅ Plan validated and ready for execution 222 | ``` 223 | 224 | ## 🎯 Bottom Line 225 | 226 | **Clear upfront goals + structured methodology = high-quality architectural specifications** 227 | 228 | This skill transforms vague project ideas into concrete, implementable plans with guaranteed traceability from business requirements to implementation tasks. 229 | 230 | --- 231 | 232 | *"The best architectural plans come from the clearest upfront thinking."* 233 | -------------------------------------------------------------------------------- /specification-architect/VALIDATION_SCRIPTS_README.md: -------------------------------------------------------------------------------- 1 | # Validation Scripts Documentation 2 | 3 | This directory includes automated validation scripts that verify complete traceability across all five specification documents. 4 | 5 | ## Quick Start 6 | 7 | ### Linux/macOS 8 | ```bash 9 | # Make script executable 10 | chmod +x validate.sh 11 | 12 | # Basic validation 13 | ./validate.sh 14 | 15 | # Validate specific directory 16 | ./validate.sh --path ./specs 17 | 18 | # Generate validation.md 19 | ./validate.sh --generate 20 | 21 | # Verbose output 22 | ./validate.sh --verbose 23 | ``` 24 | 25 | ### Windows 26 | ```cmd 27 | # Basic validation 28 | validate.bat 29 | 30 | # Validate specific directory 31 | validate.bat --path .\specs 32 | 33 | # Generate validation.md 34 | validate.bat --generate 35 | 36 | # Verbose output 37 | validate.bat --verbose 38 | ``` 39 | 40 | ### Python (Cross-Platform) 41 | ```bash 42 | # Basic validation 43 | python validate_specifications.py 44 | 45 | # Validate specific directory 46 | python validate_specifications.py --path ./specs 47 | 48 | # Generate validation.md 49 | python validate_specifications.py --generate-validation 50 | 51 | # JSON output 52 | python validate_specifications.py --json 53 | 54 | # Verbose mode 55 | python validate_specifications.py --verbose 56 | ``` 57 | 58 | ## What Gets Validated 59 | 60 | The scripts perform comprehensive validation checks: 61 | 62 | 1. **File Presence** 63 | - blueprint.md exists 64 | - requirements.md exists 65 | - design.md exists 66 | - tasks.md exists 67 | 68 | 2. **Component Consistency** 69 | - All components from blueprint.md are used in requirements.md 70 | - No undefined components are referenced 71 | - Component names match exactly (case-sensitive) 72 | 73 | 3. **Requirements Format** 74 | - Requirement numbers: "### Requirement N: [Name]" 75 | - Acceptance criteria: "N. WHEN ... THE **ComponentName** SHALL ..." 76 | - Criteria use decimal notation (1.1, 1.2, 2.1, etc.) 77 | 78 | 4. **Task Requirements Tags** 79 | - All tasks include `_Requirements: X.Y, X.Z, ..._` tags 80 | - All referenced criteria IDs are valid 81 | - Format is correct with underscores and spaces 82 | 83 | 5. **Traceability Coverage** 84 | - Every acceptance criterion is referenced in at least one task 85 | - No orphaned requirements exist 86 | - No invalid requirement references 87 | 88 | 6. **Coverage Calculation** 89 | - Total acceptance criteria count 90 | - Number covered by tasks 91 | - Coverage percentage (must be 100%) 92 | 93 | ## Output Examples 94 | 95 | ### Success (100% Coverage) 96 | ``` 97 | ================================================================================ 98 | SPECIFICATION VALIDATION REPORT 99 | ================================================================================ 100 | 101 | SUMMARY 102 | -------------------------------------------------------------------------------- 103 | Total Acceptance Criteria: 12 104 | Criteria Covered by Tasks: 12 105 | Coverage Percentage: 100.0% 106 | 107 | COVERAGE STATUS 108 | -------------------------------------------------------------------------------- 109 | ✓ Covered Criteria: 12 110 | ✗ Missing Criteria: 0 111 | ! Invalid References: 0 112 | 113 | VALIDATION STATUS 114 | -------------------------------------------------------------------------------- 115 | ✅ VALIDATION PASSED 116 | All acceptance criteria are fully traced to implementation tasks. 117 | ``` 118 | 119 | ### Failure (Incomplete Coverage) 120 | ``` 121 | MISSING CRITERIA (Not covered by any task) 122 | -------------------------------------------------------------------------------- 123 | - 3.1 124 | - 4.2 125 | 126 | VALIDATION STATUS 127 | -------------------------------------------------------------------------------- 128 | ❌ VALIDATION FAILED 129 | - 2 acceptance criteria are not covered by tasks 130 | ``` 131 | 132 | ## Command Options 133 | 134 | ### --path DIR 135 | Path to directory containing specification documents. 136 | 137 | **Default**: `.` (current directory) 138 | 139 | ```bash 140 | python validate_specifications.py --path /path/to/specs 141 | ``` 142 | 143 | ### --verbose 144 | Enable detailed output showing extraction progress. 145 | 146 | ```bash 147 | ./validate.sh --verbose 148 | ``` 149 | 150 | Shows: 151 | - Components found 152 | - Requirements extracted 153 | - Tasks parsed 154 | - Validation steps 155 | 156 | ### --generate-validation 157 | Generate or update `validation.md` file with report. 158 | 159 | ```bash 160 | python validate_specifications.py --generate-validation 161 | ``` 162 | 163 | Creates `validation.md` with: 164 | - Traceability matrix 165 | - Coverage analysis 166 | - Validation status 167 | 168 | ### --json 169 | Output results as JSON instead of human-readable text. 170 | 171 | ```bash 172 | python validate_specifications.py --json 173 | ``` 174 | 175 | Output: 176 | ```json 177 | { 178 | "total_criteria": 12, 179 | "covered_criteria": 12, 180 | "missing_criteria": [], 181 | "coverage_percentage": 100.0, 182 | "is_valid": true, 183 | "errors": [], 184 | "warnings": [] 185 | } 186 | ``` 187 | 188 | ## Exit Codes 189 | 190 | - **0** = Success (validation passed, 100% coverage) 191 | - **1** = Failure (incomplete coverage or errors) 192 | 193 | Use in scripts: 194 | ```bash 195 | python validate_specifications.py --path ./specs 196 | if [ $? -eq 0 ]; then 197 | echo "Deployment approved" 198 | ./deploy.sh 199 | else 200 | echo "Validation failed - fix requirements first" 201 | exit 1 202 | fi 203 | ``` 204 | 205 | ## Document Format Requirements 206 | 207 | For validation to work correctly: 208 | 209 | ### Blueprint.md Format 210 | ```markdown 211 | ## 3. Core System Components 212 | 213 | | Component Name | Responsibility | 214 | |---|---| 215 | | **AuthenticationComponent** | Handles user authentication | 216 | | **DatabaseAdapter** | Manages database connections | 217 | ``` 218 | 219 | ### Requirements.md Format 220 | ```markdown 221 | ### Requirement 1: User Authentication 222 | 223 | #### Acceptance Criteria 224 | 225 | 1. WHEN user submits credentials, THE **AuthenticationComponent** SHALL validate them. 226 | 227 | 2. WHEN validation succeeds, THE **AuthenticationComponent** SHALL return a session token. 228 | ``` 229 | 230 | ### Tasks.md Format 231 | ```markdown 232 | ## Task 1: Implement AuthenticationComponent 233 | 234 | - [ ] 1.1 Create AuthenticationComponent class 235 | - [ ] 1.2 Implement validation method 236 | - [ ] 1.3 Add unit tests 237 | - _Requirements: 1.1, 1.2_ 238 | ``` 239 | 240 | ## Troubleshooting 241 | 242 | ### Components not extracted 243 | **Issue**: "No components found in blueprint.md" 244 | 245 | **Solution**: Verify format matches exactly: 246 | - `| **ComponentName** | description |` 247 | - Component name must be between `**` markers 248 | - Must be in a markdown table 249 | 250 | ### Requirements not found 251 | **Issue**: "No requirements found" 252 | 253 | **Solution**: Use exact format: 254 | - `### Requirement N: [Name]` 255 | - Criteria: `N. WHEN ... THE **Component** SHALL ...` 256 | - Must have numbers and exact spacing 257 | 258 | ### Missing criteria list has items 259 | **Issue**: Validation fails with missing criteria 260 | 261 | **Solution**: Add `_Requirements:` tags to all tasks: 262 | - Format: `_Requirements: 1.1, 1.2, 3.1_` 263 | - Underscore prefix and suffix 264 | - Space after colon 265 | - IDs separated by commas 266 | 267 | ### Invalid component names 268 | **Issue**: "Unknown component: ComponentName" 269 | 270 | **Solution**: Check spelling and capitalization: 271 | - Use exact names from blueprint 272 | - Names are case-sensitive 273 | - Verify in requirements criteria 274 | 275 | ## Integration Examples 276 | 277 | ### GitHub Actions 278 | ```yaml 279 | name: Validate Specifications 280 | 281 | on: [push, pull_request] 282 | 283 | jobs: 284 | validate: 285 | runs-on: ubuntu-latest 286 | steps: 287 | - uses: actions/checkout@v2 288 | - uses: actions/setup-python@v2 289 | - name: Validate specifications 290 | run: | 291 | python validate_specifications.py \ 292 | --path ./specs \ 293 | --generate-validation 294 | ``` 295 | 296 | ### GitLab CI 297 | ```yaml 298 | validate_specs: 299 | image: python:3.9 300 | script: 301 | - python validate_specifications.py --path ./specs --generate-validation 302 | only: 303 | changes: 304 | - specs/** 305 | ``` 306 | 307 | ### Local Pre-commit Hook 308 | ```bash 309 | #!/bin/bash 310 | python validate_specifications.py --path ./specs 311 | if [ $? -ne 0 ]; then 312 | echo "Specifications validation failed!" 313 | exit 1 314 | fi 315 | ``` 316 | 317 | ## Performance 318 | 319 | - Validates 100+ requirements in <1 second 320 | - Handles 1000+ tasks efficiently 321 | - Minimal memory usage 322 | - No external dependencies 323 | 324 | ## Requirements 325 | 326 | - **Python**: 3.7 or higher 327 | - **Dependencies**: None (standard library only) 328 | 329 | ## File Structure 330 | 331 | ``` 332 | specification-architect-skill/ 333 | ├── validate_specifications.py # Main validation script 334 | ├── validate.bat # Windows helper 335 | ├── validate.sh # Linux/macOS helper 336 | ├── VALIDATION_SCRIPTS_README.md # This file 337 | ├── SKILL.md # Full skill documentation 338 | ├── TEMPLATE_REFERENCE.md # Document templates 339 | ├── USAGE_GUIDE.md # Phase-by-phase guide 340 | └── README.md # Quick start 341 | ``` 342 | 343 | ## Complete Validation Workflow 344 | 345 | 1. **Write Specifications** 346 | - Create blueprint.md 347 | - Create requirements.md 348 | - Create design.md 349 | - Create tasks.md 350 | 351 | 2. **Run Validation** 352 | ```bash 353 | python validate_specifications.py --path ./specs --verbose 354 | ``` 355 | 356 | 3. **Review Results** 357 | - Check coverage percentage 358 | - Review missing criteria (if any) 359 | - Review invalid references (if any) 360 | 361 | 4. **Fix Issues** 362 | - Add missing requirement tags to tasks 363 | - Fix invalid requirement references 364 | - Update requirements if needed 365 | 366 | 5. **Validate Again** 367 | ```bash 368 | python validate_specifications.py --path ./specs 369 | ``` 370 | 371 | 6. **Generate Report** 372 | ```bash 373 | python validate_specifications.py --path ./specs --generate-validation 374 | ``` 375 | 376 | 7. **Ready to Execute** 377 | - validation.md confirms 100% coverage 378 | - Commit all spec files 379 | - Begin implementation 380 | 381 | ## API Usage (Python) 382 | 383 | Use the validator as a Python module: 384 | 385 | ```python 386 | from validate_specifications import SpecificationValidator 387 | 388 | # Create validator 389 | validator = SpecificationValidator("./specs", verbose=True) 390 | 391 | # Run validation 392 | result = validator.validate_all() 393 | 394 | # Check results 395 | if result.is_valid: 396 | print("✅ Validation passed!") 397 | print(f"Coverage: {result.coverage_percentage}%") 398 | else: 399 | print(f"❌ {len(result.missing_criteria)} missing criteria") 400 | 401 | # Generate and save validation.md 402 | validator.save_validation_markdown() 403 | ``` 404 | -------------------------------------------------------------------------------- /specification-architect/assets/sample_outputs/example_design.md: -------------------------------------------------------------------------------- 1 | # Design Document 2 | 3 | ## Overview 4 | This document provides detailed design specifications for the TaskMaster Pro task management system components. 5 | 6 | ## Design Principles 7 | - **Single Responsibility**: Each component has a single, well-defined responsibility 8 | - **Loose Coupling**: Components interact through well-defined interfaces 9 | - **High Cohesion**: Related functionality is grouped together 10 | - **Scalability**: Design supports future growth and expansion 11 | - **Security**: All components implement proper authentication and authorization 12 | 13 | ## Component Specifications 14 | 15 | ### Component: UserAuthenticationService 16 | **Purpose**: Handles user registration, login, and session management 17 | 18 | **Location**: `src/services/auth/UserAuthenticationService.py` 19 | 20 | **Interface**: 21 | ```python 22 | class UserAuthenticationService: 23 | """ 24 | User authentication and authorization service 25 | Implements: Req 1.1, 1.2, 1.3, 1.4, 7.1, 7.2 26 | """ 27 | 28 | def __init__(self, user_repository: UserRepository, email_service: EmailService): 29 | """Initialize authentication service with dependencies""" 30 | self.user_repository = user_repository 31 | self.email_service = email_service 32 | self.jwt_secret = os.getenv('JWT_SECRET') 33 | self.token_expiry = int(os.getenv('TOKEN_EXPIRY_HOURS', '24')) 34 | 35 | def register_user(self, user_data: UserRegistrationData) -> AuthResult: 36 | """ 37 | Register a new user account with email verification 38 | Implements: Req 1.1 39 | """ 40 | pass 41 | 42 | def authenticate_user(self, credentials: LoginCredentials) -> AuthResult: 43 | """ 44 | Authenticate user and return JWT token 45 | Implements: Req 1.2 46 | """ 47 | pass 48 | 49 | def reset_password(self, email: str) -> PasswordResetResult: 50 | """ 51 | Initiate password reset process 52 | Implements: Req 1.3 53 | """ 54 | pass 55 | 56 | def validate_token(self, token: str) -> TokenValidationResult: 57 | """ 58 | Validate JWT token and extract user information 59 | Implements: Req 1.4 60 | """ 61 | pass 62 | 63 | def hash_password(self, password: str) -> str: 64 | """ 65 | Hash password using bcrypt 66 | Implements: Req 7.2 67 | """ 68 | pass 69 | ``` 70 | 71 | **Dependencies**: 72 | - UserRepository: Database access for user operations 73 | - EmailService: Email sending functionality 74 | - JWT library: Token generation and validation 75 | - bcrypt: Password hashing 76 | 77 | **Data Model**: 78 | ```python 79 | from dataclasses import dataclass 80 | from typing import Optional, List 81 | from datetime import datetime 82 | from enum import Enum 83 | 84 | class UserRole(Enum): 85 | ADMIN = "admin" 86 | MANAGER = "manager" 87 | MEMBER = "member" 88 | 89 | @dataclass 90 | class User: 91 | """User entity model""" 92 | id: str 93 | email: str 94 | username: str 95 | password_hash: str 96 | role: UserRole 97 | is_active: bool 98 | email_verified: bool 99 | created_at: datetime 100 | last_login: Optional[datetime] = None 101 | 102 | @dataclass 103 | class UserRegistrationData: 104 | """User registration request data""" 105 | email: str 106 | username: str 107 | password: str 108 | confirm_password: str 109 | 110 | @dataclass 111 | class LoginCredentials: 112 | """User login credentials""" 113 | email: str 114 | password: str 115 | 116 | @dataclass 117 | class AuthResult: 118 | """Authentication operation result""" 119 | success: bool 120 | token: Optional[str] = None 121 | user: Optional[User] = None 122 | message: str = "" 123 | ``` 124 | 125 | ### Component: TaskManagementEngine 126 | **Purpose**: Core task CRUD operations and business logic 127 | 128 | **Location**: `src/services/tasks/TaskManagementEngine.py` 129 | 130 | **Interface**: 131 | ```python 132 | class TaskManagementEngine: 133 | """ 134 | Task management and business logic engine 135 | Implements: Req 2.1, 2.2, 2.3, 2.4, 6.1, 7.3 136 | """ 137 | 138 | def __init__(self, task_repository: TaskRepository, 139 | notification_service: NotificationService, 140 | auth_service: UserAuthenticationService): 141 | """Initialize task engine with dependencies""" 142 | self.task_repository = task_repository 143 | self.notification_service = notification_service 144 | self.auth_service = auth_service 145 | 146 | def create_task(self, task_data: TaskCreationData, user_id: str) -> TaskCreationResult: 147 | """ 148 | Create a new task with validation and assignment 149 | Implements: Req 2.1 150 | """ 151 | pass 152 | 153 | def update_task(self, task_id: str, updates: TaskUpdateData, user_id: str) -> TaskUpdateResult: 154 | """ 155 | Update existing task with change tracking 156 | Implements: Req 2.2 157 | """ 158 | pass 159 | 160 | def assign_task(self, task_id: str, assignee_id: str, assigner_id: str) -> TaskAssignmentResult: 161 | """ 162 | Assign task to user and send notification 163 | Implements: Req 2.3 164 | """ 165 | pass 166 | 167 | def change_task_status(self, task_id: str, new_status: TaskStatus, user_id: str) -> StatusChangeResult: 168 | """ 169 | Change task status and notify relevant users 170 | Implements: Req 2.4 171 | """ 172 | pass 173 | 174 | def get_user_tasks(self, user_id: str, filters: TaskFilters) -> List[Task]: 175 | """ 176 | Retrieve tasks for a specific user with filters 177 | Implements: Req 6.1 178 | """ 179 | pass 180 | ``` 181 | 182 | **Dependencies**: 183 | - TaskRepository: Database access for task operations 184 | - NotificationService: Real-time notifications 185 | - UserAuthenticationService: User validation and permissions 186 | 187 | **Data Model**: 188 | ```python 189 | from dataclasses import dataclass 190 | from typing import Optional, List, Dict, Any 191 | from datetime import datetime 192 | from enum import Enum 193 | 194 | class TaskStatus(Enum): 195 | TODO = "todo" 196 | IN_PROGRESS = "in_progress" 197 | IN_REVIEW = "in_review" 198 | COMPLETED = "completed" 199 | CANCELLED = "cancelled" 200 | 201 | class TaskPriority(Enum): 202 | LOW = "low" 203 | MEDIUM = "medium" 204 | HIGH = "high" 205 | URGENT = "urgent" 206 | 207 | @dataclass 208 | class Task: 209 | """Task entity model""" 210 | id: str 211 | title: str 212 | description: str 213 | status: TaskStatus 214 | priority: TaskPriority 215 | assignee_id: Optional[str] 216 | creator_id: str 217 | project_id: str 218 | due_date: Optional[datetime] 219 | created_at: datetime 220 | updated_at: datetime 221 | completed_at: Optional[datetime] = None 222 | tags: List[str] = None 223 | custom_fields: Dict[str, Any] = None 224 | 225 | @dataclass 226 | class TaskCreationData: 227 | """Task creation request data""" 228 | title: str 229 | description: str 230 | priority: TaskPriority 231 | assignee_id: Optional[str] 232 | project_id: str 233 | due_date: Optional[datetime] 234 | tags: List[str] = None 235 | 236 | @dataclass 237 | class TaskUpdateData: 238 | """Task update request data""" 239 | title: Optional[str] = None 240 | description: Optional[str] = None 241 | priority: Optional[TaskPriority] = None 242 | assignee_id: Optional[str] = None 243 | due_date: Optional[datetime] = None 244 | tags: Optional[List[str]] = None 245 | ``` 246 | 247 | ### Component: NotificationService 248 | **Purpose**: Handles real-time notifications and email alerts 249 | 250 | **Location**: `src/services/notifications/NotificationService.py` 251 | 252 | **Interface**: 253 | ```python 254 | class NotificationService: 255 | """ 256 | Real-time notification and alert service 257 | Implements: Req 4.1, 4.2, 4.3, 4.4, 6.4 258 | """ 259 | 260 | def __init__(self, websocket_manager: WebSocketManager, 261 | email_service: EmailService, 262 | notification_repository: NotificationRepository): 263 | """Initialize notification service with dependencies""" 264 | self.websocket_manager = websocket_manager 265 | self.email_service = email_service 266 | self.notification_repository = notification_repository 267 | 268 | def send_task_assignment_notification(self, task_id: str, assignee_id: str) -> NotificationResult: 269 | """ 270 | Send real-time notification for task assignment 271 | Implements: Req 4.1 272 | """ 273 | pass 274 | 275 | def send_deadline_reminder(self, task_id: str, assignee_id: str) -> NotificationResult: 276 | """ 277 | Send reminder notification for approaching deadline 278 | Implements: Req 4.2 279 | """ 280 | pass 281 | 282 | def broadcast_task_update(self, task_id: str, update_data: Dict[str, Any]) -> BroadcastResult: 283 | """ 284 | Broadcast real-time task updates to prevent conflicts 285 | Implements: Req 4.3 286 | """ 287 | pass 288 | 289 | def send_maintenance_notification(self, message: str, scheduled_time: datetime) -> NotificationResult: 290 | """ 291 | Send system maintenance notifications 292 | Implements: Req 4.4 293 | """ 294 | pass 295 | ``` 296 | 297 | **Dependencies**: 298 | - WebSocketManager: Real-time WebSocket connection management 299 | - EmailService: Email notification delivery 300 | - NotificationRepository: Database storage for notifications 301 | 302 | ## Integration Design 303 | 304 | ### API Contracts 305 | ```python 306 | # REST API between User Interface and TaskManagementEngine 307 | POST /api/tasks 308 | Authorization: Bearer {jwt_token} 309 | Content-Type: application/json 310 | 311 | Request: 312 | { 313 | "title": "Complete user authentication", 314 | "description": "Implement JWT-based authentication system", 315 | "priority": "high", 316 | "assignee_id": "user123", 317 | "project_id": "proj456", 318 | "due_date": "2024-01-15T17:00:00Z", 319 | "tags": ["backend", "security"] 320 | } 321 | 322 | Response: 323 | { 324 | "id": "task789", 325 | "status": "todo", 326 | "created_at": "2024-01-01T12:00:00Z", 327 | "assigned_at": "2024-01-01T12:00:00Z" 328 | } 329 | ``` 330 | 331 | ### Database Schema 332 | ```sql 333 | -- Users table for UserAuthenticationService 334 | CREATE TABLE users ( 335 | id UUID PRIMARY KEY DEFAULT gen_random_uuid(), 336 | email VARCHAR(255) UNIQUE NOT NULL, 337 | username VARCHAR(100) UNIQUE NOT NULL, 338 | password_hash VARCHAR(255) NOT NULL, 339 | role VARCHAR(20) NOT NULL DEFAULT 'member', 340 | is_active BOOLEAN DEFAULT true, 341 | email_verified BOOLEAN DEFAULT false, 342 | created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, 343 | last_login TIMESTAMP WITH TIME ZONE 344 | ); 345 | 346 | -- Tasks table for TaskManagementEngine 347 | CREATE TABLE tasks ( 348 | id UUID PRIMARY KEY DEFAULT gen_random_uuid(), 349 | title VARCHAR(255) NOT NULL, 350 | description TEXT, 351 | status VARCHAR(20) NOT NULL DEFAULT 'todo', 352 | priority VARCHAR(10) NOT NULL DEFAULT 'medium', 353 | assignee_id UUID REFERENCES users(id), 354 | creator_id UUID NOT NULL REFERENCES users(id), 355 | project_id UUID NOT NULL REFERENCES projects(id), 356 | due_date TIMESTAMP WITH TIME ZONE, 357 | created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, 358 | updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, 359 | completed_at TIMESTAMP WITH TIME ZONE 360 | ); 361 | 362 | -- Projects table for ProjectOrganizer 363 | CREATE TABLE projects ( 364 | id UUID PRIMARY KEY DEFAULT gen_random_uuid(), 365 | name VARCHAR(255) NOT NULL, 366 | description TEXT, 367 | owner_id UUID NOT NULL REFERENCES users(id), 368 | created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, 369 | updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP 370 | ); 371 | ``` 372 | 373 | ### Security Implementation 374 | ```python 375 | # JWT Token validation middleware 376 | def require_auth(func): 377 | """Decorator to require JWT authentication""" 378 | def wrapper(*args, **kwargs): 379 | token = request.headers.get('Authorization') 380 | if not token or not token.startswith('Bearer '): 381 | return jsonify({'error': 'Authentication required'}), 401 382 | 383 | token = token.split(' ')[1] 384 | try: 385 | payload = jwt.decode(token, JWT_SECRET, algorithms=['HS256']) 386 | request.user_id = payload['user_id'] 387 | return func(*args, **kwargs) 388 | except jwt.ExpiredSignatureError: 389 | return jsonify({'error': 'Token expired'}), 401 390 | except jwt.InvalidTokenError: 391 | return jsonify({'error': 'Invalid token'}), 401 392 | return wrapper 393 | ``` -------------------------------------------------------------------------------- /specification-architect/SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: specification-architect 3 | 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. 4 | --- 5 | 6 | # Specification Architect AI 7 | 8 | ## Overview 9 | 10 | 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. 11 | 12 | **Core Principle**: Every claim must be supported by evidence. No AI-generated "facts" without verification. 13 | 14 | ## When to Use This Skill 15 | 16 | Use this skill when users request: 17 | - System architecture documentation 18 | - Technical specifications for software projects 19 | - Requirements analysis and traceability 20 | - Implementation planning with validation 21 | - Project documentation with structured methodology 22 | 23 | ## Prompt Optimization Guidelines 24 | 25 | **The quality of architectural specifications is directly proportional to the clarity of upfront goals and boundaries.** 26 | 27 | ### For Best Results, Include in Your Request: 28 | 29 | 1. **Clear Business Objectives** 30 | - What problem are you solving? 31 | - Who are the users/stakeholders? 32 | - What does success look like? 33 | 34 | 2. **Specific Constraints and Boundaries** 35 | - Technology preferences or restrictions 36 | - Performance requirements 37 | - Security/compliance requirements 38 | - Integration constraints 39 | 40 | 3. **Scope Definition** 41 | - Must-have features vs. nice-to-haves 42 | - Explicit out-of-scope items 43 | - Timeline and resource constraints 44 | 45 | 4. **Context and Background** 46 | - Existing systems to integrate with 47 | - Team capabilities and expertise 48 | - Previous attempts or solutions 49 | 50 | ### Example Effective Prompt: 51 | ``` 52 | "I need to architect a customer support ticket system for a mid-sized SaaS company. 53 | The system must handle 10,000 tickets/month, integrate with our existing Salesforce CRM, 54 | and comply with GDPR requirements. We need email integration, knowledge base search, 55 | and reporting dashboards. Please do NOT include live chat or phone support features. 56 | Our team specializes in Python/React and we need this deployed on AWS." 57 | ``` 58 | 59 | **Why This Works**: 60 | - ✅ Clear business context (customer support for SaaS) 61 | - ✅ Specific constraints (10k tickets/month, GDPR, AWS) 62 | - ✅ Technology preferences (Python/React) 63 | - ✅ Clear scope boundaries (no live chat/phone) 64 | - ✅ Integration requirements (Salesforce) 65 | - ✅ Success metrics (email, knowledge base, reporting) 66 | 67 | ## How to Use This Skill 68 | 69 | Follow the five-phase process in sequence: 70 | 71 | ### Phase 0: Verifiable Research and Technology Selection 72 | 73 | **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. 74 | 75 | **CRITICAL**: This phase prevents AI-generated misinformation that could lead to serious professional consequences. **You MUST complete this phase with proper verification before proceeding.** 76 | 77 | #### Strict Protocol: 78 | 1. **Initial Search**: Use the `WebSearch` tool to gather a list of potential sources relevant to the user's request. 79 | 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. 80 | 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. 81 | 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. 82 | 83 | #### Research Process: 84 | 1. **Analyze User Request** 85 | - Identify core domain (e.g., e-commerce, IoT, fintech, healthcare) 86 | - Extract key requirements (scale, performance, security, integrations) 87 | - Note any specific technology constraints or preferences 88 | 89 | 2. **Execute Research with Verification** 90 | - Use `WebSearch` to find relevant sources for domain architecture patterns 91 | - Use `WebFetch` to browse and verify each source's content 92 | - Research technology options with current best practices 93 | - Investigate integration approaches and deployment strategies 94 | 95 | 3. **Synthesize Evidence-Based Recommendations** 96 | - Create technology recommendations ONLY from verified sources 97 | - Support every claim with citations from browsed content 98 | - Compare options using evidence, not assumptions 99 | - Justify decisions with specific source references 100 | 101 | #### Strict Output Template: 102 | ```markdown 103 | # Verifiable Research and Technology Proposal 104 | 105 | ## 1. Core Problem Analysis 106 | [A brief, 1-2 sentence analysis of the user's request and the primary technical challenges.] 107 | 108 | ## 2. Verifiable Technology Recommendations 109 | | Technology/Pattern | Rationale & Evidence | 110 | |---|---| 111 | | **[Technology Name]** | [Rationale derived from browsed sources, with every factual claim cited.] | 112 | | **[Pattern Name]** | [Rationale derived from browsed sources, with every factual claim cited.] | 113 | 114 | ## 3. Browsed Sources 115 | - [1] [URL of browsed source 1] 116 | - [2] [URL of browsed source 2] 117 | - [...] 118 | ``` 119 | 120 | **Citation Requirements**: 121 | - Every factual claim MUST end with `[cite:INDEX]` citation 122 | - Citations must correspond to numbered browsed sources 123 | - No technology recommendations allowed without source evidence 124 | - All rationales must be derived from actual browsed content 125 | 126 | **Example of Proper Citation**: 127 | "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]." 128 | 129 | **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?" 130 | 131 | ### Phase 1: Architectural Blueprint (blueprint.md) 132 | 133 | **PREREQUISITE**: Approval of the technology stack 134 | **GOAL**: To establish a high-level map of the system, its components, interactions, and boundaries 135 | 136 | **CRITICAL SUCCESS FACTORS**: 137 | - **Component Clarity**: Each component must have a single, well-defined responsibility 138 | - **Data Flow Visualization**: Map how data moves through the system from input to output 139 | - **Integration Points**: Clearly define all APIs, protocols, and external system connections 140 | - **Boundaries Setting**: Explicitly define what's in scope vs. out of scope to prevent scope creep 141 | 142 | **STRICT TEMPLATE**: 143 | ```markdown 144 | # Architectural Blueprint 145 | ## 1. Core Objective 146 | [Single paragraph defining the primary goal and what success looks like.] 147 | 148 | ## 2. System Scope and Boundaries 149 | ### In Scope 150 | - [Specific feature 1 that WILL be built] 151 | - [Specific capability 2 that WILL be implemented] 152 | - [Integration 1 that WILL be supported] 153 | 154 | ### Out of Scope 155 | - [Feature 1 that will NOT be built - prevents scope creep] 156 | - [External system 1 that will NOT be integrated] 157 | - [Technology 1 that will NOT be used] 158 | 159 | ## 3. Core System Components 160 | | Component Name | Single Responsibility | 161 | |---|---| 162 | | **[ComponentName1]** | [One clear, focused responsibility - what this component DOES] | 163 | | **[ComponentName2]** | [One clear, focused responsibility - what this component DOES] | 164 | | **[ComponentName3]** | [One clear, focused responsibility - what this component DOES] | 165 | 166 | ## 4. High-Level Data Flow 167 | ```mermaid 168 | graph TD 169 | A[External Input/User] --> B[ComponentName1] 170 | B --> C[ComponentName2] 171 | C --> D[ComponentName3] 172 | D --> E[External Output/Result] 173 | 174 | %% Style components for clarity 175 | style ComponentName1 fill:#e1f5fe 176 | style ComponentName2 fill:#f3e5f5 177 | style ComponentName3 fill:#e8f5e8 178 | ``` 179 | 180 | ## 5. Key Integration Points 181 | - **[ComponentName1] ↔ [ComponentName2]**: [API/Protocol - e.g., REST API, gRPC, message queue] 182 | - **[ComponentName2] ↔ [ComponentName3]**: [API/Protocol - how they communicate] 183 | - **[ComponentName1] ↔ External**: [External system integration - e.g., database, third-party API] 184 | - **Authentication**: [How components authenticate with each other] 185 | - **Data Format**: [Standard data format between components - JSON, protobuf, etc.] 186 | ``` 187 | 188 | **Quality Gates**: 189 | - Are component responsibilities clear and non-overlapping? 190 | - Does the data flow diagram show the complete journey from input to output? 191 | - Are all integration points clearly specified with protocols? 192 | - Are in/out scope boundaries unambiguous? 193 | 194 | **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?" 195 | 196 | ### Phase 2: Requirements Generation (requirements.md) 197 | 198 | **PREREQUISITE**: Approval of the blueprint 199 | **RULE**: All `[System Component]` placeholders MUST use the exact component names from the blueprint 200 | 201 | **STRICT TEMPLATE**: 202 | ```markdown 203 | # Requirements Document 204 | [Introduction and Glossary...] 205 | ## Requirements 206 | ### Requirement 1: [Feature Name] 207 | #### Acceptance Criteria 208 | 1. WHEN [trigger], THE **[ComponentName1]** SHALL [specific, testable behavior]. 209 | ``` 210 | 211 | **Approval Gate**: "Requirements documented with [N] requirements and [M] acceptance criteria, each assigned to a specific component. Proceed to detailed design?" 212 | 213 | ### Phase 3: Detailed Design (design.md) 214 | 215 | **PREREQUISITE**: Approval of requirements 216 | **GOAL**: To elaborate on the blueprint with detailed specifications for each component 217 | 218 | **STRICT TEMPLATE**: 219 | ```markdown 220 | # Design Document 221 | [Overview, Principles...] 222 | ## Component Specifications 223 | #### Component: [ComponentName1] 224 | **Purpose**: [Responsibility from blueprint] 225 | **Location**: `path/to/component.py` 226 | **Interface**: [Code block with methods and requirement references, e.g., `Implements Req 1.1`] 227 | ``` 228 | 229 | **Approval Gate**: "Detailed design complete. All components from the blueprint have been specified. Proceed to generate implementation tasks?" 230 | 231 | ### Phase 4: Task Decomposition (tasks.md) 232 | 233 | **PREREQUISITE**: Approval of the design 234 | **GOAL**: To create a granular, actionable implementation plan 235 | 236 | **STRICT TEMPLATE**: 237 | ```markdown 238 | # Implementation Plan 239 | - [ ] 1. Implement the [ComponentName1] 240 | - [ ] 1.1 [Specific action, e.g., "Create class in file.py"] 241 | - [ ] 1.2 [Specific action, e.g., "Implement method_x()"] 242 | - _Requirements: 1.1, 1.2, 2.3_ 243 | ``` 244 | 245 | **Approval Gate**: "Implementation plan created with [N] tasks. Proceed to final validation?" 246 | 247 | ### Phase 5: Validation and Traceability (validation.md) 248 | 249 | **PREREQUISITE**: Generation of all previous documents 250 | **GOAL**: To perform a final, automated check that guarantees complete traceability from requirements to implementation tasks 251 | 252 | **STRICT TEMPLATE**: 253 | ```markdown 254 | # Validation Report 255 | 256 | ## 1. Requirements to Tasks Traceability Matrix 257 | 258 | | Requirement | Acceptance Criterion | Implementing Task(s) | Status | 259 | |---|---|---|---| 260 | | 1. [Name] | 1.1 | Task 2, Task 5 | Covered | 261 | | | 1.2 | Task 2, Task 3 | Covered | 262 | | ... | ... | ... | ... | 263 | | X. [Name] | X.Y | Task Z | Covered | 264 | 265 | ## 2. Coverage Analysis 266 | 267 | ### Summary 268 | - **Total Acceptance Criteria**: [M] 269 | - **Criteria Covered by Tasks**: [M] 270 | - **Coverage Percentage**: 100% 271 | 272 | ### Detailed Status 273 | - **Covered Criteria**: A list of all X.Y references that are successfully mapped to at least one task. 274 | - **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.** 275 | - **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.** 276 | 277 | ## 3. Final Validation 278 | All [M] acceptance criteria are fully traced to implementation tasks. The plan is validated and ready for execution. 279 | ``` 280 | 281 | **Final Approval Gate**: "Validation complete. Traceability matrix confirms 100% coverage. Type 'execute' to begin implementation." 282 | 283 | ## Key Principles 284 | 285 | 1. **Traceability First**: Every requirement must be traced to implementation tasks 286 | 2. **Approval Gates**: Get explicit approval before proceeding to next phase 287 | 3. **Template Adherence**: Use the exact document templates provided 288 | 4. **Component Consistency**: Use identical component names across all documents 289 | 5. **Validation Guarantees**: Ensure 100% coverage before completion 290 | 291 | ## Research Guidelines 292 | 293 | When conducting research in Phase 0: 294 | 295 | 1. **Identify Core Challenges**: Analyze the user's request to determine technical domains 296 | 2. **Search Current Best Practices**: Use `WebSearch` with specific queries about: 297 | - Current architectural patterns for the domain 298 | - Recommended technology stacks 299 | - Industry standards and conventions 300 | - Recent advancements or alternatives 301 | 3. **Evaluate Options**: Compare multiple approaches and justify the selected stack 302 | 4. **Document Rationale**: Briefly explain why each technology was chosen 303 | 304 | ## Validation Process 305 | 306 | The validation phase ensures: 307 | 308 | 1. **Complete Coverage**: Every acceptance criterion from requirements.md is referenced in at least one task 309 | 2. **Valid References**: All task requirement references correspond to real acceptance criteria 310 | 3. **Traceability Matrix**: Clear mapping from requirements through tasks 311 | 4. **100% Success Rate**: Validation only passes when coverage is complete 312 | 313 | ## Files Referenced 314 | 315 | - `scripts/traceability_validator.py` - Python script for automated validation 316 | - `references/document_templates.md` - Detailed templates and examples 317 | - `assets/sample_outputs/` - Example of complete specification documents 318 | 319 | ## Execution Workflow 320 | 321 | 1. **Phase 0**: Research → Get approval 322 | 2. **Phase 1**: Blueprint → Get approval 323 | 3. **Phase 2**: Requirements → Get approval 324 | 4. **Phase 3**: Design → Get approval 325 | 5. **Phase 4**: Tasks → Get approval 326 | 6. **Phase 5**: Validation → Get final approval 327 | 328 | Each phase must be completed and approved before proceeding to the next phase. The final validation confirms 100% traceability and coverage. -------------------------------------------------------------------------------- /specification-architect/scripts/traceability_validator.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | Traceability validator for specification architect skill. 4 | Validates that all requirements are covered by implementation tasks. 5 | """ 6 | 7 | import re 8 | import sys 9 | from pathlib import Path 10 | from typing import Dict, List, Tuple, Set 11 | 12 | class TraceabilityValidator: 13 | def __init__(self, base_path: str): 14 | self.base_path = Path(base_path) 15 | self.requirements = {} 16 | self.tasks = [] 17 | self.research_citations = {} 18 | 19 | def parse_requirements(self, requirements_file: str) -> Dict: 20 | """Parse requirements.md to extract requirements and acceptance criteria.""" 21 | req_file = self.base_path / requirements_file 22 | if not req_file.exists(): 23 | raise FileNotFoundError(f"Requirements file not found: {requirements_file}") 24 | 25 | content = req_file.read_text(encoding='utf-8') 26 | 27 | # Split content by requirement headers and capture requirement numbers 28 | pattern = r'\n### Requirement (\d+): ([^\n]+)' 29 | matches = list(re.finditer(pattern, content)) 30 | 31 | requirements = {} 32 | 33 | for match in matches: 34 | req_num = match.group(1).strip() 35 | req_title = match.group(2).strip() 36 | 37 | # Find the start and end of this requirement section 38 | start_pos = match.start() 39 | end_pos = content.find('\n### Requirement', start_pos + 1) 40 | if end_pos == -1: 41 | end_pos = len(content) 42 | 43 | # Extract this requirement's content 44 | section_content = content[start_pos:end_pos] 45 | 46 | # Find acceptance criteria within this section 47 | ac_match = re.search(r'#### Acceptance Criteria\n(.*?)(?=\n###|\n##|\Z)', section_content, re.DOTALL) 48 | if not ac_match: 49 | continue 50 | 51 | ac_text = ac_match.group(1).strip() 52 | 53 | 54 | # Parse acceptance criteria 55 | requirements[req_num] = { 56 | "title": req_title, 57 | "acceptance_criteria": {} 58 | } 59 | 60 | ac_pattern = r"(\d+)\.\s+(.+)" 61 | ac_matches = re.findall(ac_pattern, ac_text) 62 | for ac_num, ac_text in ac_matches: 63 | requirements[req_num]["acceptance_criteria"][f"{req_num}.{ac_num}"] = ac_text.strip() 64 | 65 | self.requirements = requirements 66 | return requirements 67 | 68 | def parse_tasks(self, tasks_file: str) -> List[Dict]: 69 | """Parse tasks.md to extract tasks and their requirement references.""" 70 | task_file = self.base_path / tasks_file 71 | if not task_file.exists(): 72 | raise FileNotFoundError(f"Tasks file not found: {tasks_file}") 73 | 74 | content = task_file.read_text(encoding='utf-8') 75 | 76 | # Parse tasks and requirement references 77 | task_pattern = r"- \[ \] (\d+).+?_Requirements: (.+?)_" 78 | matches = re.findall(task_pattern, content, re.MULTILINE | re.DOTALL) 79 | 80 | tasks = [] 81 | for task_num, req_refs in matches: 82 | # Parse requirement references 83 | req_refs = [ref.strip() for ref in req_refs.split(",")] 84 | tasks.append({ 85 | "task_id": task_num, 86 | "requirement_references": req_refs 87 | }) 88 | 89 | self.tasks = tasks 90 | return tasks 91 | 92 | def validate_traceability(self) -> Tuple[Dict, List[str], List[str]]: 93 | """Validate that all requirements are covered by tasks.""" 94 | all_criteria = set() 95 | for req_num, req_data in self.requirements.items(): 96 | for ac_ref in req_data["acceptance_criteria"]: 97 | all_criteria.add(ac_ref) 98 | 99 | covered_criteria = set() 100 | invalid_references = set() 101 | 102 | for task in self.tasks: 103 | for req_ref in task["requirement_references"]: 104 | if req_ref in all_criteria: 105 | covered_criteria.add(req_ref) 106 | else: 107 | invalid_references.add(req_ref) 108 | 109 | missing_criteria = all_criteria - covered_criteria 110 | 111 | return { 112 | "total_criteria": len(all_criteria), 113 | "covered_criteria": len(covered_criteria), 114 | "coverage_percentage": (len(covered_criteria) / len(all_criteria) * 100) if all_criteria else 100 115 | }, list(missing_criteria), list(invalid_references) 116 | 117 | def validate_research_evidence(self, research_file: str = "example_research.md") -> Dict: 118 | """Validate research document for proper citations and evidence.""" 119 | research_path = self.base_path / research_file 120 | if not research_path.exists(): 121 | return {"valid": False, "error": f"Research file not found: {research_file}"} 122 | 123 | content = research_path.read_text(encoding='utf-8') 124 | 125 | validation_results = { 126 | "valid": True, 127 | "citation_errors": [], 128 | "missing_sources": [], 129 | "uncited_claims": [], 130 | "total_sources": 0, 131 | "total_citations": 0 132 | } 133 | 134 | # Extract source list (## 3. Browsed Sources section) 135 | source_pattern = r'## 3\. Browsed Sources\n(.*?)(?=\n##|\Z)' 136 | source_match = re.search(source_pattern, content, re.DOTALL) 137 | 138 | if not source_match: 139 | validation_results["valid"] = False 140 | validation_results["citation_errors"].append("Missing 'Browsed Sources' section") 141 | return validation_results 142 | 143 | sources_text = source_match.group(1) 144 | source_lines = [line.strip() for line in sources_text.split('\n') if line.strip()] 145 | 146 | # Extract source URLs and indices 147 | sources = {} 148 | for line in source_lines: 149 | source_match = re.match(r'- \[(\d+)\] (https?://\S+)', line) 150 | if source_match: 151 | index = source_match.group(1) 152 | url = source_match.group(2) 153 | sources[index] = url 154 | 155 | validation_results["total_sources"] = len(sources) 156 | 157 | # Check for citations in rationale section 158 | rationale_pattern = r'\| \*\*(.+?)\*\* \| (.+?) \|' 159 | rationale_matches = re.findall(rationale_pattern, content, re.DOTALL) 160 | 161 | total_citations = 0 162 | for technology, rationale in rationale_matches: 163 | # Find all citations in rationale 164 | citations = re.findall(r'\[cite:(\d+)\]', rationale) 165 | total_citations += len(citations) 166 | 167 | # Check each citation has corresponding source 168 | for citation in citations: 169 | if citation not in sources: 170 | validation_results["citation_errors"].append(f"Citation [cite:{citation}] references non-existent source") 171 | validation_results["valid"] = False 172 | 173 | validation_results["total_citations"] = total_citations 174 | 175 | # Check for factual claims without citations (simplified detection) 176 | # Look for sentences with specific numbers, percentages, or strong claims 177 | factual_claims = re.findall(r'[^.!?]*\d+(?:\.\d+)?%?[^.!?]*\.|[^.!?]*?(excellent|proven|ideal|best|optimal)[^.!?]*\.', content) 178 | 179 | for claim in factual_claims: 180 | if not re.search(r'\[cite:\d+\]', claim): 181 | validation_results["uncited_claims"].append(claim.strip()) 182 | 183 | # Validate that we have both sources and citations 184 | if len(sources) == 0: 185 | validation_results["valid"] = False 186 | validation_results["citation_errors"].append("No sources found in research document") 187 | 188 | if total_citations == 0: 189 | validation_results["valid"] = False 190 | validation_results["citation_errors"].append("No citations found in technology rationales") 191 | 192 | # Check citation to source ratio (should have reasonable coverage) 193 | if total_citations < len(sources): 194 | validation_results["citation_errors"].append(f"Too few citations ({total_citations}) for number of sources ({len(sources)})") 195 | 196 | return validation_results 197 | 198 | def generate_validation_report(self, requirements_file: str = "requirements.md", 199 | tasks_file: str = "tasks.md", 200 | research_file: str = "example_research.md") -> str: 201 | """Generate a complete validation report.""" 202 | 203 | self.parse_requirements(requirements_file) 204 | self.parse_tasks(tasks_file) 205 | 206 | validation_result, missing, invalid = self.validate_traceability() 207 | research_validation = self.validate_research_evidence(research_file) 208 | 209 | report = f"""# Validation Report 210 | 211 | ## 1. Requirements to Tasks Traceability Matrix 212 | 213 | | Requirement | Acceptance Criterion | Implementing Task(s) | Status | 214 | |---|---|---|---|""" 215 | 216 | # Generate traceability matrix 217 | for req_num, req_data in self.requirements.items(): 218 | for ac_ref, ac_text in req_data["acceptance_criteria"].items(): 219 | # Find tasks implementing this criterion 220 | implementing_tasks = [] 221 | for task in self.tasks: 222 | if ac_ref in task["requirement_references"]: 223 | implementing_tasks.append(f"Task {task['task_id']}") 224 | 225 | status = "Covered" if implementing_tasks else "Missing" 226 | tasks_str = ", ".join(implementing_tasks) if implementing_tasks else "None" 227 | 228 | report += f"\n| {req_num} | {ac_ref} | {tasks_str} | {status} |" 229 | 230 | report += f""" 231 | 232 | ## 2. Coverage Analysis 233 | 234 | ### Summary 235 | - **Total Acceptance Criteria**: {validation_result['total_criteria']} 236 | - **Criteria Covered by Tasks**: {validation_result['covered_criteria']} 237 | - **Coverage Percentage**: {validation_result['coverage_percentage']:.1f}% 238 | 239 | ### Detailed Status 240 | - **Covered Criteria**: {[ref for ref in self._get_all_criteria() if ref in self._get_covered_criteria()]} 241 | - **Missing Criteria**: {missing if missing else 'None'} 242 | - **Invalid References**: {invalid if invalid else 'None'} 243 | 244 | ## 3. Research Evidence Validation 245 | 246 | ### Summary 247 | - **Total Sources**: {research_validation['total_sources']} 248 | - **Total Citations**: {research_validation['total_citations']} 249 | - **Research Validation**: {'PASSED' if research_validation['valid'] else 'FAILED'} 250 | 251 | ### Evidence Quality 252 | - **Citation Errors**: {len(research_validation['citation_errors'])} 253 | - **Uncited Claims**: {len(research_validation['uncited_claims'])} 254 | """ 255 | 256 | if research_validation['citation_errors']: 257 | report += "\n#### Citation Issues:\n" 258 | for error in research_validation['citation_errors']: 259 | report += f"- {error}\n" 260 | 261 | if research_validation['uncited_claims']: 262 | report += "\n#### Uncited Factual Claims:\n" 263 | for claim in research_validation['uncited_claims'][:5]: # Limit to first 5 264 | report += f"- {claim}\n" 265 | if len(research_validation['uncited_claims']) > 5: 266 | report += f"- ... and {len(research_validation['uncited_claims']) - 5} more\n" 267 | 268 | report += """ 269 | 270 | ## 4. Final Validation 271 | """ 272 | 273 | requirements_valid = validation_result['coverage_percentage'] == 100 and not invalid 274 | research_valid = research_validation['valid'] 275 | 276 | if requirements_valid and research_valid: 277 | 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." 278 | elif not requirements_valid and research_valid: 279 | 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." 280 | elif requirements_valid and not research_valid: 281 | 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." 282 | else: 283 | 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." 284 | 285 | return report 286 | 287 | def _get_all_criteria(self) -> Set[str]: 288 | """Get all acceptance criteria references.""" 289 | all_criteria = set() 290 | for req_num, req_data in self.requirements.items(): 291 | for ac_ref in req_data["acceptance_criteria"]: 292 | all_criteria.add(ac_ref) 293 | return all_criteria 294 | 295 | def _get_covered_criteria(self) -> Set[str]: 296 | """Get all covered acceptance criteria references.""" 297 | covered_criteria = set() 298 | all_criteria = self._get_all_criteria() 299 | 300 | for task in self.tasks: 301 | for req_ref in task["requirement_references"]: 302 | if req_ref in all_criteria: 303 | covered_criteria.add(req_ref) 304 | 305 | return covered_criteria 306 | 307 | if __name__ == "__main__": 308 | import argparse 309 | 310 | parser = argparse.ArgumentParser(description="Validate specification architect traceability") 311 | parser.add_argument("--path", default=".", help="Base path containing specification files") 312 | parser.add_argument("--requirements", default="requirements.md", help="Requirements file name") 313 | parser.add_argument("--tasks", default="tasks.md", help="Tasks file name") 314 | parser.add_argument("--research", default="example_research.md", help="Research file name") 315 | 316 | args = parser.parse_args() 317 | 318 | try: 319 | validator = TraceabilityValidator(args.path) 320 | report = validator.generate_validation_report(args.requirements, args.tasks, args.research) 321 | print(report) 322 | 323 | # Exit with error code if validation fails 324 | validation_result, missing, invalid = validator.validate_traceability() 325 | research_validation = validator.validate_research_evidence(args.research) 326 | 327 | requirements_valid = validation_result['coverage_percentage'] == 100 and not invalid 328 | research_valid = research_validation['valid'] 329 | 330 | if not requirements_valid or not research_valid: 331 | sys.exit(1) 332 | else: 333 | sys.exit(0) 334 | 335 | except FileNotFoundError as e: 336 | print(f"Error: {e}") 337 | sys.exit(1) 338 | except Exception as e: 339 | print(f"Unexpected error: {e}") 340 | sys.exit(1) -------------------------------------------------------------------------------- /specification-architect/references/document_templates.md: -------------------------------------------------------------------------------- 1 | # Document Templates 2 | 3 | This document provides detailed templates and examples for each of the five specification architect documents. 4 | 5 | ## Phase 0: Verifiable Research Template 6 | 7 | ### Strict Protocol - NO "RESEARCH SLOP" 8 | **CRITICAL**: This phase prevents AI-generated misinformation that could lead to serious professional consequences. Every claim MUST be verified with browsed sources. 9 | 10 | ### Evidence-Based Research Template 11 | ```markdown 12 | # Verifiable Research and Technology Proposal 13 | 14 | ## 1. Core Problem Analysis 15 | [A brief, 1-2 sentence analysis of the user's request and the primary technical challenges.] 16 | 17 | ## 2. Verifiable Technology Recommendations 18 | | Technology/Pattern | Rationale & Evidence | 19 | |---|---| 20 | | **[Technology Name]** | [Rationale derived from browsed sources, with every factual claim cited.] | 21 | | **[Pattern Name]** | [Rationale derived from browsed sources, with every factual claim cited.] | 22 | | **[Framework]** | [Specific capabilities and limitations supported by sources.] | 23 | | **[Database]** | [Performance characteristics and use case suitability with citations.] | 24 | 25 | ## 3. Browsed Sources 26 | - [1] [Complete URL of browsed source 1] - [Brief description of content] 27 | - [2] [Complete URL of browsed source 2] - [Brief description of content] 28 | - [3] [Complete URL of browsed source 3] - [Brief description of content] 29 | - [...] 30 | ``` 31 | 32 | ### Citation Requirements - MANDATORY 33 | 34 | **Every factual claim MUST end with `[cite:INDEX]` citation:** 35 | 36 | **Examples of Proper Citations:** 37 | - ❌ "Node.js is great for real-time applications" (NO CITATION - RESEARCH SLOP) 38 | - ✅ "Node.js excels at real-time applications due to its event-driven, non-blocking I/O model [cite:1]." 39 | - ❌ "TypeScript reduces errors" (NO CITATION - RESEARCH SLOP) 40 | - ✅ "TypeScript adds static typing that reduces runtime errors by approximately 15% in large codebases [cite:2]." 41 | - ❌ "PostgreSQL is reliable" (NO CITATION - RESEARCH SLOP) 42 | - ✅ "PostgreSQL provides ACID compliance and has been proven reliable for financial applications with 99.99% uptime [cite:3]." 43 | 44 | ### Mandatory Research Process 45 | 46 | 1. **Search THEN Browse**: Use WebSearch to find sources, then WebFetch to read the actual content 47 | 2. **NO Search Snippets**: You MUST read the full content of sources, not just search results 48 | 3. **Verify Claims**: Every technology claim must be supported by actual browsed content 49 | 4. **Cite Everything**: All factual statements must have corresponding citations 50 | 5. **Source Listing**: All browsed URLs must be listed with index numbers 51 | 52 | ### Quality Assurance Checklist 53 | 54 | **Before proceeding to Phase 1, verify:** 55 | - [ ] Every technology recommendation has citations 56 | - [ ] All citations correspond to browsed sources 57 | - [ ] No claims made without source evidence 58 | - [ ] Source URLs are complete and accessible 59 | - [ ] Rationales are derived from actual source content 60 | - [ ] No "research slop" or AI-generated assumptions 61 | 62 | **Professional Standards Compliance:** 63 | 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. 64 | 65 | **Quality Gate**: Do not proceed to Phase 1 until ALL claims are cited and verified with browsed sources. 66 | 67 | ## Blueprint Template 68 | 69 | ### Complete Template 70 | ```markdown 71 | # Architectural Blueprint 72 | ## 1. Core Objective 73 | [Single paragraph defining the primary goal and purpose of the system.] 74 | 75 | ## 2. System Scope and Boundaries 76 | ### In Scope 77 | - [Feature 1 that will be implemented] 78 | - [Feature 2 that will be implemented] 79 | - [Component 1 that will be developed] 80 | 81 | ### Out of Scope 82 | - [Feature 1 that will NOT be implemented] 83 | - [External system 1 that will NOT be integrated] 84 | - [Technology 1 that will NOT be used] 85 | 86 | ## 3. Core System Components 87 | | Component Name | Responsibility | 88 | |---|---| 89 | | **[ComponentName1]** | [Concise function description explaining what this component does.] | 90 | | **[ComponentName2]** | [Concise function description explaining what this component does.] | 91 | | **[ComponentName3]** | [Concise function description explaining what this component does.] | 92 | 93 | ## 4. High-Level Data Flow 94 | ```mermaid 95 | graph TD 96 | A[External Input] --> B[ComponentName1] 97 | B --> C[ComponentName2] 98 | C --> D[ComponentName3] 99 | D --> E[External Output] 100 | 101 | style ComponentName1 fill:#e1f5fe 102 | style ComponentName2 fill:#f3e5f5 103 | style ComponentName3 fill:#e8f5e8 104 | ``` 105 | 106 | ## 5. Key Integration Points 107 | - **API Gateway**: RESTful APIs between [ComponentName1] and [ComponentName2] 108 | - **Database Connection**: [ComponentName2] connects to PostgreSQL database 109 | - **External Service**: [ComponentName3] integrates with [External Service Name] via [Protocol] 110 | - **Authentication**: JWT-based authentication between all components 111 | ``` 112 | 113 | ### Blueprint Guidelines 114 | 115 | **CRITICAL: Upfront Planning Quality Determines Everything** 116 | 117 | - **Component Names**: Use clear, descriptive names (e.g., "UserAuthenticationService", "DataProcessingEngine") 118 | - Names should clearly indicate what the component DOES 119 | - Use consistent naming conventions (Service, Engine, Manager, Repository, etc.) 120 | - Avoid ambiguous names like "Helper" or "Utilities" 121 | 122 | - **Single Responsibility Principle**: Each component should have ONE clear purpose 123 | - If you find yourself saying "and also", split into multiple components 124 | - Clear responsibilities prevent confusion and enable independent testing 125 | 126 | - **Data Flow Visualization**: The Mermaid diagram is CRITICAL for understanding 127 | - Show the complete journey from external input to external output 128 | - Include all decision points and data transformations 129 | - Use colors/styles to make component boundaries obvious 130 | 131 | - **Integration Points**: Be explicit about how components communicate 132 | - Specify protocols (REST, gRPC, message queues, events) 133 | - Define data formats (JSON, protobuf, XML) 134 | - Include authentication and error handling strategies 135 | 136 | - **Boundaries Setting**: The In Scope/Out of Scope section prevents scope creep 137 | - Be specific about what you WILL NOT build 138 | - This protects against "while you're at it" additions 139 | - Clear boundaries enable accurate estimation and planning 140 | 141 | ## Requirements Template 142 | 143 | ### Complete Template 144 | ```markdown 145 | # Requirements Document 146 | 147 | ## Introduction 148 | This document defines the functional and non-functional requirements for the [System Name] system. 149 | 150 | ## Glossary 151 | - **Term1**: Definition of term1 152 | - **Term2**: Definition of term2 153 | - **[ComponentName1]**: The component responsible for [function] 154 | 155 | ## Requirements 156 | 157 | ### Requirement 1: [Feature Name] 158 | **Description**: [Brief description of what this requirement accomplishes.] 159 | 160 | #### Acceptance Criteria 161 | 1. WHEN [trigger condition], THE **[ComponentName1]** SHALL [specific, testable behavior]. 162 | 2. WHEN [another trigger condition], THE **[ComponentName2]** SHALL [specific, testable behavior]. 163 | 3. GIVEN [precondition], WHEN [action], THEN **[ComponentName3]** SHALL [expected outcome]. 164 | 165 | ### Requirement 2: [Another Feature Name] 166 | **Description**: [Brief description of what this requirement accomplishes.] 167 | 168 | #### Acceptance Criteria 169 | 1. WHEN [trigger condition], THE **[ComponentName1]** SHALL [specific, testable behavior]. 170 | 2. WHEN [trigger condition], THE **[ComponentName2]** SHALL [specific, testable behavior]. 171 | 172 | ## Non-Functional Requirements 173 | 174 | ### Requirement 3: Performance 175 | **Description**: System must meet performance requirements. 176 | 177 | #### Acceptance Criteria 178 | 1. WHEN [load condition], THE **[ComponentName1]** SHALL [response time requirement]. 179 | 2. WHEN [concurrent users condition], THE **[ComponentName2]** SHALL [throughput requirement]. 180 | ``` 181 | 182 | ### Requirements Guidelines 183 | - **Component References**: MUST use exact component names from blueprint (copy-paste to avoid errors) 184 | - **Testable Criteria**: Each acceptance criterion must be measurable and testable 185 | - **WHEN-THEN Format**: Use the format "WHEN [condition], THE **[Component]** SHALL [behavior]" 186 | - **Requirement Numbering**: Use sequential numbering (1, 2, 3...) 187 | - **Criteria Numbering**: Use decimal numbering (1.1, 1.2, 2.1, 2.2...) 188 | 189 | ## Design Template 190 | 191 | ### Complete Template 192 | ```markdown 193 | # Design Document 194 | 195 | ## Overview 196 | This document provides detailed design specifications for the [System Name] system components. 197 | 198 | ## Design Principles 199 | - **Single Responsibility**: Each component has a single, well-defined responsibility 200 | - **Loose Coupling**: Components interact through well-defined interfaces 201 | - **High Cohesion**: Related functionality is grouped together 202 | - **Scalability**: Design supports future growth and expansion 203 | 204 | ## Component Specifications 205 | 206 | ### Component: [ComponentName1] 207 | **Purpose**: [Responsibility from blueprint - copy exactly] 208 | 209 | **Location**: `src/components/[ComponentName1].py` 210 | 211 | **Interface**: 212 | ```python 213 | class [ComponentName1]: 214 | """ 215 | [Brief description of component purpose] 216 | Implements: Req 1.1, Req 1.2 217 | """ 218 | 219 | def __init__(self, dependency: [DependencyType]): 220 | """Initialize component with required dependencies""" 221 | pass 222 | 223 | def process_data(self, input: InputType) -> OutputType: 224 | """ 225 | Process input data and return results 226 | Implements: Req 1.1 227 | """ 228 | pass 229 | 230 | def validate_input(self, data: Any) -> bool: 231 | """ 232 | Validate input data format and constraints 233 | Implements: Req 1.2 234 | """ 235 | pass 236 | ``` 237 | 238 | **Dependencies**: 239 | - [Dependency1]: [Description of dependency] 240 | - [Dependency2]: [Description of dependency] 241 | 242 | **Data Model**: 243 | ```python 244 | from dataclasses import dataclass 245 | from typing import List, Optional 246 | 247 | @dataclass 248 | class [DataModelName]: 249 | """Data structure for [ComponentName1]""" 250 | field1: str 251 | field2: int 252 | field3: Optional[List[str]] = None 253 | ``` 254 | 255 | ### Component: [ComponentName2] 256 | **Purpose**: [Responsibility from blueprint - copy exactly] 257 | 258 | **Location**: `src/services/[ComponentName2].py` 259 | 260 | **Interface**: 261 | ```python 262 | class [ComponentName2]: 263 | """ 264 | [Brief description of component purpose] 265 | Implements: Req 2.1, Req 2.2, Req 3.1 266 | """ 267 | 268 | def __init__(self, config: ConfigType): 269 | """Initialize component with configuration""" 270 | pass 271 | 272 | def execute_service(self, request: RequestType) -> ResponseType: 273 | """ 274 | Execute main service functionality 275 | Implements: Req 2.1 276 | """ 277 | pass 278 | 279 | def handle_error(self, error: Exception) -> ErrorResponseType: 280 | """ 281 | Handle and log service errors 282 | Implements: Req 2.2 283 | """ 284 | pass 285 | ``` 286 | 287 | ## Integration Design 288 | 289 | ### API Contracts 290 | ```python 291 | # REST API between [ComponentName1] and [ComponentName2] 292 | POST /api/process 293 | Content-Type: application/json 294 | 295 | Request: 296 | { 297 | "data": "input_data", 298 | "options": { 299 | "validate": true, 300 | "format": "json" 301 | } 302 | } 303 | 304 | Response: 305 | { 306 | "status": "success", 307 | "result": "processed_data", 308 | "metadata": { 309 | "processing_time": 150, 310 | "timestamp": "2024-01-01T12:00:00Z" 311 | } 312 | } 313 | ``` 314 | 315 | ### Database Schema 316 | ```sql 317 | -- Table for [ComponentName2] data storage 318 | CREATE TABLE processed_data ( 319 | id SERIAL PRIMARY KEY, 320 | input_data TEXT NOT NULL, 321 | output_data TEXT NOT NULL, 322 | created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, 323 | processed_by VARCHAR(100) NOT NULL 324 | ); 325 | ``` 326 | ``` 327 | 328 | ### Design Guidelines 329 | - **Purpose**: Copy the responsibility exactly from the blueprint 330 | - **Location**: Specify the exact file path where the component will be implemented 331 | - **Requirement References**: Include "Implements: Req X.Y" comments for each method 332 | - **Dependencies**: List all external dependencies and services 333 | - **Data Models**: Define data structures used by the component 334 | 335 | ## Tasks Template 336 | 337 | ### Complete Template 338 | ```markdown 339 | # Implementation Plan 340 | 341 | ## Phase 1: Core Infrastructure 342 | - [ ] 1. Implement the [ComponentName1] 343 | - [ ] 1.1 Create project structure and setup 344 | - [ ] 1.2 Implement core [ComponentName1] class in `src/components/[ComponentName1].py` 345 | - [ ] 1.3 Add input validation methods 346 | - [ ] 1.4 Write unit tests for [ComponentName1] 347 | - [ ] 1.5 Create integration tests 348 | - _Requirements: 1.1, 1.2_ 349 | 350 | - [ ] 2. Implement the [ComponentName2] 351 | - [ ] 2.1 Create [ComponentName2] service class 352 | - [ ] 2.2 Implement main service methods 353 | - [ ] 2.3 Add error handling and logging 354 | - [ ] 2.4 Configure service dependencies 355 | - [ ] 2.5 Write service tests 356 | - _Requirements: 2.1, 2.2, 3.1_ 357 | 358 | ## Phase 2: Data Layer 359 | - [ ] 3. Implement the [ComponentName3] 360 | - [ ] 3.1 Setup database connection and schema 361 | - [ ] 3.2 Implement data access methods 362 | - [ ] 3.3 Add data validation and transformation 363 | - [ ] 3.4 Create database migration scripts 364 | - [ ] 3.5 Write database tests 365 | - _Requirements: 3.1, 3.2_ 366 | 367 | ## Phase 3: Integration 368 | - [ ] 4. API Integration 369 | - [ ] 4.1 Implement REST API endpoints 370 | - [ ] 4.2 Add request/response validation 371 | - [ ] 4.3 Configure API security and authentication 372 | - [ ] 4.4 Add API documentation 373 | - [ ] 4.5 Write API integration tests 374 | - _Requirements: 2.1, 4.1_ 375 | 376 | ## Phase 4: Testing and Deployment 377 | - [ ] 5. Testing 378 | - [ ] 5.1 Complete end-to-end test suite 379 | - [ ] 5.2 Performance testing and optimization 380 | - [ ] 5.3 Security testing and vulnerability scanning 381 | - [ ] 5.4 User acceptance testing 382 | - _Requirements: 3.1, 5.1_ 383 | 384 | - [ ] 6. Deployment 385 | - [ ] 6.1 Setup production environment 386 | - [ ] 6.2 Configure monitoring and logging 387 | - [ ] 6.3 Create deployment scripts 388 | - [ ] 6.4 Implement rollback procedures 389 | - _Requirements: 5.1, 5.2_ 390 | ``` 391 | 392 | ### Tasks Guidelines 393 | - **Component Names**: Use exact component names from blueprint 394 | - **Task Numbering**: Use sequential numbering (1, 2, 3...) 395 | - **Sub-tasks**: Use decimal numbering (1.1, 1.2, 1.3...) 396 | - **Requirement Tags**: Each main task must include `_Requirements: X.Y, Z.W_` tags 397 | - **Actionable Tasks**: Each sub-task should be a specific, actionable item 398 | - **Complete Coverage**: Every acceptance criterion from requirements must be referenced 399 | 400 | ## Validation Template 401 | 402 | ### Complete Template 403 | ```markdown 404 | # Validation Report 405 | 406 | ## 1. Requirements to Tasks Traceability Matrix 407 | 408 | | Requirement | Acceptance Criterion | Implementing Task(s) | Status | 409 | |---|---|---|---| 410 | | 1. User Authentication | 1.1 | Task 1, Task 2 | Covered | 411 | | | 1.2 | Task 1, Task 3 | Covered | 412 | | 2. Data Processing | 2.1 | Task 4, Task 5 | Covered | 413 | | | 2.2 | Task 4 | Covered | 414 | | | 2.3 | Task 6 | Covered | 415 | | 3. Performance | 3.1 | Task 7, Task 8 | Covered | 416 | | ... | ... | ... | ... | 417 | | X. [Final Requirement] | X.Y | Task Z | Covered | 418 | 419 | ## 2. Coverage Analysis 420 | 421 | ### Summary 422 | - **Total Acceptance Criteria**: [M] 423 | - **Criteria Covered by Tasks**: [M] 424 | - **Coverage Percentage**: 100% 425 | 426 | ### Detailed Status 427 | - **Covered Criteria**: 1.1, 1.2, 2.1, 2.2, 2.3, 3.1, ..., X.Y 428 | - **Missing Criteria**: None 429 | - **Invalid References**: None 430 | 431 | ## 3. Final Validation 432 | All [M] acceptance criteria are fully traced to implementation tasks. The plan is validated and ready for execution. 433 | ``` 434 | 435 | ### Validation Guidelines 436 | - **Matrix Generation**: Create a row for each acceptance criterion 437 | - **Task Mapping**: List all tasks that implement each criterion 438 | - **Status Indicators**: Use "Covered" for implemented criteria, "Missing" for gaps 439 | - **Coverage Analysis**: Provide summary statistics and detailed status 440 | - **Final Statement**: Confirm 100% coverage or identify gaps 441 | 442 | ## Template Usage Tips 443 | 444 | 1. **Copy-Paste Accuracy**: Copy component names exactly between documents to avoid traceability errors 445 | 2. **Sequential Numbering**: Maintain consistent numbering schemes across all documents 446 | 3. **Requirement References**: Double-check that all task requirement references exist in the requirements document 447 | 4. **Template Strictness**: Follow the templates exactly - the validation script depends on the specific format 448 | 5. **Validation First**: Run the traceability validator before considering the specification complete --------------------------------------------------------------------------------