From 7f42d64263a85e1fa60e2e4a353f4293c3c29671 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 17:50:59 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + plugin.lock.json | 104 ++++ skills/specification-architect/README.md | 78 +++ skills/specification-architect/SKILL.md | 328 +++++++++++++ .../VALIDATION_SCRIPTS_README.md | 403 ++++++++++++++++ .../sample_outputs/example_blueprint.md | 60 +++ .../assets/sample_outputs/example_design.md | 393 +++++++++++++++ .../sample_outputs/example_requirements.md | 78 +++ .../assets/sample_outputs/example_research.md | 123 +++++ .../assets/sample_outputs/example_tasks.md | 152 ++++++ .../sample_outputs/example_validation.md | 110 +++++ .../example_verifiable_research.md | 25 + skills/specification-architect/plugin.json | 25 + .../references/document_templates.md | 448 ++++++++++++++++++ .../scripts/traceability_validator.py | 340 +++++++++++++ skills/specification-architect/validate.bat | 24 + skills/specification-architect/validate.sh | 38 ++ .../validate_specifications.py | 164 +++++++ 19 files changed, 2908 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/specification-architect/README.md create mode 100644 skills/specification-architect/SKILL.md create mode 100644 skills/specification-architect/VALIDATION_SCRIPTS_README.md create mode 100644 skills/specification-architect/assets/sample_outputs/example_blueprint.md create mode 100644 skills/specification-architect/assets/sample_outputs/example_design.md create mode 100644 skills/specification-architect/assets/sample_outputs/example_requirements.md create mode 100644 skills/specification-architect/assets/sample_outputs/example_research.md create mode 100644 skills/specification-architect/assets/sample_outputs/example_tasks.md create mode 100644 skills/specification-architect/assets/sample_outputs/example_validation.md create mode 100644 skills/specification-architect/assets/sample_outputs/example_verifiable_research.md create mode 100644 skills/specification-architect/plugin.json create mode 100644 skills/specification-architect/references/document_templates.md create mode 100644 skills/specification-architect/scripts/traceability_validator.py create mode 100644 skills/specification-architect/validate.bat create mode 100644 skills/specification-architect/validate.sh create mode 100644 skills/specification-architect/validate_specifications.py diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..916bf21 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "architecture-skills", + "description": "Collection of architectural documentation and specification generation skills", + "version": "0.0.0-2025.11.28", + "author": { + "name": "George A Puiu", + "email": "puiu.adrian@gmail.com" + }, + "skills": [ + "./skills/specification-architect" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..4167822 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# architecture-skills + +Collection of architectural documentation and specification generation skills diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..f35316e --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,104 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:adrianpuiu/specification-document-generator:architecture-skills", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "a05ffc0b61bcf2dce213b9e3ba922d1815a65328", + "treeHash": "ea165f6a6b3b2e9cc1e06e1d131635743f7935b17b60aa6112a00b7ecfd31855", + "generatedAt": "2025-11-28T10:13:01.882699Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "architecture-skills", + "description": "Collection of architectural documentation and specification generation skills" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "aa46d2fd2965f0167381040bd508f0bd3fa404410c70c3b6f8bfa641a4925de5" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "ffbef060d9408d45a42636730dcd2a7c0a1fbaa6f793c18b4d7dc3fc314ee92d" + }, + { + "path": "skills/specification-architect/validate.bat", + "sha256": "fab04fc5e2cf1a8c0928b6e0cf5c808a211dbf8e206537dfa0f2f6c8a244ab38" + }, + { + "path": "skills/specification-architect/validate.sh", + "sha256": "2ba7305a92e7696e0a522e6cbe942b18d3da600ae80c842cba3c0455086da0dd" + }, + { + "path": "skills/specification-architect/validate_specifications.py", + "sha256": "429531bd3d64e5d712ad51897564325d6023290a66fb4cff8602d24150df8453" + }, + { + "path": "skills/specification-architect/plugin.json", + "sha256": "ac420827bbe164e48f9a663864e55b1b7052f15b0b1343ce2c36b70f0e3ad78d" + }, + { + "path": "skills/specification-architect/README.md", + "sha256": "942130a3dc0f15008e125373754bb8984cfcd2a93016c429f2dedc841dc99ffd" + }, + { + "path": "skills/specification-architect/SKILL.md", + "sha256": "caa270d54420e9bd0e1d9e7ed590d6c10c7bae07a622e08ace3411a1db5f03ff" + }, + { + "path": "skills/specification-architect/VALIDATION_SCRIPTS_README.md", + "sha256": "e23e0d50142625c4b6860691efd0224c71a1cb9be75eb425bd45c0dd3777fa2f" + }, + { + "path": "skills/specification-architect/references/document_templates.md", + "sha256": "2b1130d5acb9bc10c23b6d7fc33de89529ebbc55ae2b25a5e5cd709058d7df12" + }, + { + "path": "skills/specification-architect/scripts/traceability_validator.py", + "sha256": "8d896f3fd28f47171c4af9c141193ff1b66a4ef591dfaea981a9e6296aef417d" + }, + { + "path": "skills/specification-architect/assets/sample_outputs/example_tasks.md", + "sha256": "d23924fbc0b78710d062eb1891391c31575da6d855ac98cfbe265c798828272a" + }, + { + "path": "skills/specification-architect/assets/sample_outputs/example_design.md", + "sha256": "c8b76c46cf98eaa08ea04a22206f2c7fdd6b7dc8629f10f432b7f4b53140be4f" + }, + { + "path": "skills/specification-architect/assets/sample_outputs/example_requirements.md", + "sha256": "7e56d4ca9196f4caea398ab68f35b995c7d9a663e52c25c4f3ff176319e3dea0" + }, + { + "path": "skills/specification-architect/assets/sample_outputs/example_blueprint.md", + "sha256": "03dc691cb51c2d14545d014bf2fa1b15c7b0cfccc5a1cd9033d3423c717cbb49" + }, + { + "path": "skills/specification-architect/assets/sample_outputs/example_research.md", + "sha256": "40913d76ad2002b9303d3c52db215c86a72319d0f2f3621de3bba03791d776d2" + }, + { + "path": "skills/specification-architect/assets/sample_outputs/example_verifiable_research.md", + "sha256": "5a091a2bd64092b1687bd72bbea705e9ab795aaf5dc0ee79c25ffbc836a2a848" + }, + { + "path": "skills/specification-architect/assets/sample_outputs/example_validation.md", + "sha256": "e623b7d38c9dfd3d9ba40fd37787540d4f307f2b1bf707b2e09868b9af497461" + } + ], + "dirSha256": "ea165f6a6b3b2e9cc1e06e1d131635743f7935b17b60aa6112a00b7ecfd31855" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/specification-architect/README.md b/skills/specification-architect/README.md new file mode 100644 index 0000000..7605c27 --- /dev/null +++ b/skills/specification-architect/README.md @@ -0,0 +1,78 @@ +# Specification Architect Skill + +An AI skill that generates rigorous, evidence-based architectural documentation with complete traceability. + +## Quick Start + +### Generate Specification Documents + +The skill follows a 6-phase sequential process: + +1. **Phase 0: Verifiable Research** (research.md) - Evidence-based technology research with citations +2. **Phase 1: Blueprint** (blueprint.md) - Component architecture and data flow +3. **Phase 2: Requirements** (requirements.md) - Acceptance criteria with component assignments +4. **Phase 3: Design** (design.md) - Detailed component specifications +5. **Phase 4: Tasks** (tasks.md) - Implementation tasks with requirement traceability +6. **Phase 5: Validation** (validation.md) - Automated validation results + +### Validation Commands + +```bash +# Primary validation - ensures 100% requirements coverage +python validate_specifications.py + +# With options +python validate_specifications.py --path ./specs --verbose --generate-validation + +# Advanced traceability validation +python scripts/traceability_validator.py +``` + +### Cross-Platform Helpers + +```bash +# Linux/macOS +./validate.sh --verbose --generate + +# Windows +validate.bat --verbose --generate +``` + +## Key Files + +- **validate_specifications.py** - Main validation script +- **scripts/traceability_validator.py** - Advanced traceability validation +- **SKILL.md** - Complete skill documentation +- **references/document_templates.md** - Template examples and format specifications +- **assets/sample_outputs/** - Example generated documents + +## Validation Exit Codes + +- **0**: Success (100% coverage achieved) +- **1**: Failure (missing files, incomplete coverage, format errors) + +## Evidence-Based Research Protocol + +This skill implements a strict anti-"research slop" protocol: + +1. **Search THEN Browse**: Use WebSearch to find sources, then WebFetch to read actual content +2. **Cite Every Claim**: Every factual statement must end with `[cite:INDEX]` citation +3. **Verify Sources**: Read full source content, not just search snippets +4. **Auditable Trail**: Complete citation trail from claim to source + +## Quality Assurance + +The validation system ensures: +- All required documents exist +- Component names are consistent across documents +- Requirements have 100% task coverage +- Citations follow proper format +- Templates are correctly implemented + +## License + +MIT + +## Author + +George A Puiu (puiu.adrian@gmail.com) diff --git a/skills/specification-architect/SKILL.md b/skills/specification-architect/SKILL.md new file mode 100644 index 0000000..4768c42 --- /dev/null +++ b/skills/specification-architect/SKILL.md @@ -0,0 +1,328 @@ +--- +name: specification-architect +description: A rigorous, traceability-first system that generates five interconnected architectural documents (blueprint.md, requirements.md, design.md, tasks.md, and validation.md) with complete requirements-to-implementation traceability. Use this skill when users need to architect systems, create technical specifications, or develop structured project documentation with guaranteed traceability. +--- + +# Specification Architect AI + +## Overview + +This skill implements a rigorous, evidence-based system for generating architectural documentation that eliminates "research slop" and prevents AI-generated misinformation. It produces five interconnected markdown documents where every technological decision is backed by verifiable sources and complete traceability from research through implementation tasks. + +**Core Principle**: Every claim must be supported by evidence. No AI-generated "facts" without verification. + +## When to Use This Skill + +Use this skill when users request: +- System architecture documentation +- Technical specifications for software projects +- Requirements analysis and traceability +- Implementation planning with validation +- Project documentation with structured methodology + +## Prompt Optimization Guidelines + +**The quality of architectural specifications is directly proportional to the clarity of upfront goals and boundaries.** + +### For Best Results, Include in Your Request: + +1. **Clear Business Objectives** + - What problem are you solving? + - Who are the users/stakeholders? + - What does success look like? + +2. **Specific Constraints and Boundaries** + - Technology preferences or restrictions + - Performance requirements + - Security/compliance requirements + - Integration constraints + +3. **Scope Definition** + - Must-have features vs. nice-to-haves + - Explicit out-of-scope items + - Timeline and resource constraints + +4. **Context and Background** + - Existing systems to integrate with + - Team capabilities and expertise + - Previous attempts or solutions + +### Example Effective Prompt: +``` +"I need to architect a customer support ticket system for a mid-sized SaaS company. +The system must handle 10,000 tickets/month, integrate with our existing Salesforce CRM, +and comply with GDPR requirements. We need email integration, knowledge base search, +and reporting dashboards. Please do NOT include live chat or phone support features. +Our team specializes in Python/React and we need this deployed on AWS." +``` + +**Why This Works**: +- ✅ Clear business context (customer support for SaaS) +- ✅ Specific constraints (10k tickets/month, GDPR, AWS) +- ✅ Technology preferences (Python/React) +- ✅ Clear scope boundaries (no live chat/phone) +- ✅ Integration requirements (Salesforce) +- ✅ Success metrics (email, knowledge base, reporting) + +## How to Use This Skill + +Follow the five-phase process in sequence: + +### Phase 0: Verifiable Research and Technology Selection + +**GOAL**: To produce a technology proposal where every claim is supported by verifiable, browsed sources, thereby eliminating "research slop" and grounding the architecture in factual evidence. + +**CRITICAL**: This phase prevents AI-generated misinformation that could lead to serious professional consequences. **You MUST complete this phase with proper verification before proceeding.** + +#### Strict Protocol: +1. **Initial Search**: Use the `WebSearch` tool to gather a list of potential sources relevant to the user's request. +2. **Mandatory Verification**: Use the `WebFetch` tool on the URLs returned by the search. **You MUST NOT rely on search snippets alone.** You must read the content of the pages to confirm the information. +3. **Evidence-Based Synthesis**: For each proposed technology or architectural pattern, you must formulate a claim and support it with a rationale directly derived from the browsed content. +4. **Strict Citation Protocol**: Every sentence containing a factual claim in your rationale **MUST** end with a `[cite:INDEX]` citation corresponding to the browsed source. This creates an auditable trail from claim to evidence. + +#### Research Process: +1. **Analyze User Request** + - Identify core domain (e.g., e-commerce, IoT, fintech, healthcare) + - Extract key requirements (scale, performance, security, integrations) + - Note any specific technology constraints or preferences + +2. **Execute Research with Verification** + - Use `WebSearch` to find relevant sources for domain architecture patterns + - Use `WebFetch` to browse and verify each source's content + - Research technology options with current best practices + - Investigate integration approaches and deployment strategies + +3. **Synthesize Evidence-Based Recommendations** + - Create technology recommendations ONLY from verified sources + - Support every claim with citations from browsed content + - Compare options using evidence, not assumptions + - Justify decisions with specific source references + +#### Strict Output Template: +```markdown +# Verifiable Research and Technology Proposal + +## 1. Core Problem Analysis +[A brief, 1-2 sentence analysis of the user's request and the primary technical challenges.] + +## 2. Verifiable Technology Recommendations +| Technology/Pattern | Rationale & Evidence | +|---|---| +| **[Technology Name]** | [Rationale derived from browsed sources, with every factual claim cited.] | +| **[Pattern Name]** | [Rationale derived from browsed sources, with every factual claim cited.] | + +## 3. Browsed Sources +- [1] [URL of browsed source 1] +- [2] [URL of browsed source 2] +- [...] +``` + +**Citation Requirements**: +- Every factual claim MUST end with `[cite:INDEX]` citation +- Citations must correspond to numbered browsed sources +- No technology recommendations allowed without source evidence +- All rationales must be derived from actual browsed content + +**Example of Proper Citation**: +"Node.js excels at real-time applications due to its event-driven, non-blocking I/O model [cite:1]. TypeScript adds static typing that reduces runtime errors by approximately 15% in large codebases [cite:2]." + +**Approval Gate**: "Research complete. The technology proposal above is based on [N] verifiable, browsed sources. Every claim is cited and traceable to evidence. Proceed to define the architectural blueprint?" + +### Phase 1: Architectural Blueprint (blueprint.md) + +**PREREQUISITE**: Approval of the technology stack +**GOAL**: To establish a high-level map of the system, its components, interactions, and boundaries + +**CRITICAL SUCCESS FACTORS**: +- **Component Clarity**: Each component must have a single, well-defined responsibility +- **Data Flow Visualization**: Map how data moves through the system from input to output +- **Integration Points**: Clearly define all APIs, protocols, and external system connections +- **Boundaries Setting**: Explicitly define what's in scope vs. out of scope to prevent scope creep + +**STRICT TEMPLATE**: +```markdown +# Architectural Blueprint +## 1. Core Objective +[Single paragraph defining the primary goal and what success looks like.] + +## 2. System Scope and Boundaries +### In Scope +- [Specific feature 1 that WILL be built] +- [Specific capability 2 that WILL be implemented] +- [Integration 1 that WILL be supported] + +### Out of Scope +- [Feature 1 that will NOT be built - prevents scope creep] +- [External system 1 that will NOT be integrated] +- [Technology 1 that will NOT be used] + +## 3. Core System Components +| Component Name | Single Responsibility | +|---|---| +| **[ComponentName1]** | [One clear, focused responsibility - what this component DOES] | +| **[ComponentName2]** | [One clear, focused responsibility - what this component DOES] | +| **[ComponentName3]** | [One clear, focused responsibility - what this component DOES] | + +## 4. High-Level Data Flow +```mermaid +graph TD + A[External Input/User] --> B[ComponentName1] + B --> C[ComponentName2] + C --> D[ComponentName3] + D --> E[External Output/Result] + + %% Style components for clarity + style ComponentName1 fill:#e1f5fe + style ComponentName2 fill:#f3e5f5 + style ComponentName3 fill:#e8f5e8 +``` + +## 5. Key Integration Points +- **[ComponentName1] ↔ [ComponentName2]**: [API/Protocol - e.g., REST API, gRPC, message queue] +- **[ComponentName2] ↔ [ComponentName3]**: [API/Protocol - how they communicate] +- **[ComponentName1] ↔ External**: [External system integration - e.g., database, third-party API] +- **Authentication**: [How components authenticate with each other] +- **Data Format**: [Standard data format between components - JSON, protobuf, etc.] +``` + +**Quality Gates**: +- Are component responsibilities clear and non-overlapping? +- Does the data flow diagram show the complete journey from input to output? +- Are all integration points clearly specified with protocols? +- Are in/out scope boundaries unambiguous? + +**Approval Gate**: "Architectural blueprint complete with clear component mapping, data flow visualization, and integration points. The component names defined here will be used consistently across all documents. Proceed to generate requirements?" + +### Phase 2: Requirements Generation (requirements.md) + +**PREREQUISITE**: Approval of the blueprint +**RULE**: All `[System Component]` placeholders MUST use the exact component names from the blueprint + +**STRICT TEMPLATE**: +```markdown +# Requirements Document +[Introduction and Glossary...] +## Requirements +### Requirement 1: [Feature Name] +#### Acceptance Criteria +1. WHEN [trigger], THE **[ComponentName1]** SHALL [specific, testable behavior]. +``` + +**Approval Gate**: "Requirements documented with [N] requirements and [M] acceptance criteria, each assigned to a specific component. Proceed to detailed design?" + +### Phase 3: Detailed Design (design.md) + +**PREREQUISITE**: Approval of requirements +**GOAL**: To elaborate on the blueprint with detailed specifications for each component + +**STRICT TEMPLATE**: +```markdown +# Design Document +[Overview, Principles...] +## Component Specifications +#### Component: [ComponentName1] +**Purpose**: [Responsibility from blueprint] +**Location**: `path/to/component.py` +**Interface**: [Code block with methods and requirement references, e.g., `Implements Req 1.1`] +``` + +**Approval Gate**: "Detailed design complete. All components from the blueprint have been specified. Proceed to generate implementation tasks?" + +### Phase 4: Task Decomposition (tasks.md) + +**PREREQUISITE**: Approval of the design +**GOAL**: To create a granular, actionable implementation plan + +**STRICT TEMPLATE**: +```markdown +# Implementation Plan +- [ ] 1. Implement the [ComponentName1] + - [ ] 1.1 [Specific action, e.g., "Create class in file.py"] + - [ ] 1.2 [Specific action, e.g., "Implement method_x()"] + - _Requirements: 1.1, 1.2, 2.3_ +``` + +**Approval Gate**: "Implementation plan created with [N] tasks. Proceed to final validation?" + +### Phase 5: Validation and Traceability (validation.md) + +**PREREQUISITE**: Generation of all previous documents +**GOAL**: To perform a final, automated check that guarantees complete traceability from requirements to implementation tasks + +**STRICT TEMPLATE**: +```markdown +# Validation Report + +## 1. Requirements to Tasks Traceability Matrix + +| Requirement | Acceptance Criterion | Implementing Task(s) | Status | +|---|---|---|---| +| 1. [Name] | 1.1 | Task 2, Task 5 | Covered | +| | 1.2 | Task 2, Task 3 | Covered | +| ... | ... | ... | ... | +| X. [Name] | X.Y | Task Z | Covered | + +## 2. Coverage Analysis + +### Summary +- **Total Acceptance Criteria**: [M] +- **Criteria Covered by Tasks**: [M] +- **Coverage Percentage**: 100% + +### Detailed Status +- **Covered Criteria**: A list of all X.Y references that are successfully mapped to at least one task. +- **Missing Criteria**: A list of any X.Y references from `requirements.md` that were NOT found in any task's `_Requirements_` tag. **This list must be empty to pass validation.** +- **Invalid References**: A list of any task references (e.g., `_Requirements: 9.9_`) that do not correspond to a real acceptance criterion. **This list must be empty to pass validation.** + +## 3. Final Validation +All [M] acceptance criteria are fully traced to implementation tasks. The plan is validated and ready for execution. +``` + +**Final Approval Gate**: "Validation complete. Traceability matrix confirms 100% coverage. Type 'execute' to begin implementation." + +## Key Principles + +1. **Traceability First**: Every requirement must be traced to implementation tasks +2. **Approval Gates**: Get explicit approval before proceeding to next phase +3. **Template Adherence**: Use the exact document templates provided +4. **Component Consistency**: Use identical component names across all documents +5. **Validation Guarantees**: Ensure 100% coverage before completion + +## Research Guidelines + +When conducting research in Phase 0: + +1. **Identify Core Challenges**: Analyze the user's request to determine technical domains +2. **Search Current Best Practices**: Use `WebSearch` with specific queries about: + - Current architectural patterns for the domain + - Recommended technology stacks + - Industry standards and conventions + - Recent advancements or alternatives +3. **Evaluate Options**: Compare multiple approaches and justify the selected stack +4. **Document Rationale**: Briefly explain why each technology was chosen + +## Validation Process + +The validation phase ensures: + +1. **Complete Coverage**: Every acceptance criterion from requirements.md is referenced in at least one task +2. **Valid References**: All task requirement references correspond to real acceptance criteria +3. **Traceability Matrix**: Clear mapping from requirements through tasks +4. **100% Success Rate**: Validation only passes when coverage is complete + +## Files Referenced + +- `scripts/traceability_validator.py` - Python script for automated validation +- `references/document_templates.md` - Detailed templates and examples +- `assets/sample_outputs/` - Example of complete specification documents + +## Execution Workflow + +1. **Phase 0**: Research → Get approval +2. **Phase 1**: Blueprint → Get approval +3. **Phase 2**: Requirements → Get approval +4. **Phase 3**: Design → Get approval +5. **Phase 4**: Tasks → Get approval +6. **Phase 5**: Validation → Get final approval + +Each phase must be completed and approved before proceeding to the next phase. The final validation confirms 100% traceability and coverage. \ No newline at end of file diff --git a/skills/specification-architect/VALIDATION_SCRIPTS_README.md b/skills/specification-architect/VALIDATION_SCRIPTS_README.md new file mode 100644 index 0000000..9d5c5ba --- /dev/null +++ b/skills/specification-architect/VALIDATION_SCRIPTS_README.md @@ -0,0 +1,403 @@ +# Validation Scripts Documentation + +This directory includes automated validation scripts that verify complete traceability across all five specification documents. + +## Quick Start + +### Linux/macOS +```bash +# Make script executable +chmod +x validate.sh + +# Basic validation +./validate.sh + +# Validate specific directory +./validate.sh --path ./specs + +# Generate validation.md +./validate.sh --generate + +# Verbose output +./validate.sh --verbose +``` + +### Windows +```cmd +# Basic validation +validate.bat + +# Validate specific directory +validate.bat --path .\specs + +# Generate validation.md +validate.bat --generate + +# Verbose output +validate.bat --verbose +``` + +### Python (Cross-Platform) +```bash +# Basic validation +python validate_specifications.py + +# Validate specific directory +python validate_specifications.py --path ./specs + +# Generate validation.md +python validate_specifications.py --generate-validation + +# JSON output +python validate_specifications.py --json + +# Verbose mode +python validate_specifications.py --verbose +``` + +## What Gets Validated + +The scripts perform comprehensive validation checks: + +1. **File Presence** + - blueprint.md exists + - requirements.md exists + - design.md exists + - tasks.md exists + +2. **Component Consistency** + - All components from blueprint.md are used in requirements.md + - No undefined components are referenced + - Component names match exactly (case-sensitive) + +3. **Requirements Format** + - Requirement numbers: "### Requirement N: [Name]" + - Acceptance criteria: "N. WHEN ... THE **ComponentName** SHALL ..." + - Criteria use decimal notation (1.1, 1.2, 2.1, etc.) + +4. **Task Requirements Tags** + - All tasks include `_Requirements: X.Y, X.Z, ..._` tags + - All referenced criteria IDs are valid + - Format is correct with underscores and spaces + +5. **Traceability Coverage** + - Every acceptance criterion is referenced in at least one task + - No orphaned requirements exist + - No invalid requirement references + +6. **Coverage Calculation** + - Total acceptance criteria count + - Number covered by tasks + - Coverage percentage (must be 100%) + +## Output Examples + +### Success (100% Coverage) +``` +================================================================================ +SPECIFICATION VALIDATION REPORT +================================================================================ + +SUMMARY +-------------------------------------------------------------------------------- +Total Acceptance Criteria: 12 +Criteria Covered by Tasks: 12 +Coverage Percentage: 100.0% + +COVERAGE STATUS +-------------------------------------------------------------------------------- +✓ Covered Criteria: 12 +✗ Missing Criteria: 0 +! Invalid References: 0 + +VALIDATION STATUS +-------------------------------------------------------------------------------- +✅ VALIDATION PASSED +All acceptance criteria are fully traced to implementation tasks. +``` + +### Failure (Incomplete Coverage) +``` +MISSING CRITERIA (Not covered by any task) +-------------------------------------------------------------------------------- + - 3.1 + - 4.2 + +VALIDATION STATUS +-------------------------------------------------------------------------------- +❌ VALIDATION FAILED + - 2 acceptance criteria are not covered by tasks +``` + +## Command Options + +### --path DIR +Path to directory containing specification documents. + +**Default**: `.` (current directory) + +```bash +python validate_specifications.py --path /path/to/specs +``` + +### --verbose +Enable detailed output showing extraction progress. + +```bash +./validate.sh --verbose +``` + +Shows: +- Components found +- Requirements extracted +- Tasks parsed +- Validation steps + +### --generate-validation +Generate or update `validation.md` file with report. + +```bash +python validate_specifications.py --generate-validation +``` + +Creates `validation.md` with: +- Traceability matrix +- Coverage analysis +- Validation status + +### --json +Output results as JSON instead of human-readable text. + +```bash +python validate_specifications.py --json +``` + +Output: +```json +{ + "total_criteria": 12, + "covered_criteria": 12, + "missing_criteria": [], + "coverage_percentage": 100.0, + "is_valid": true, + "errors": [], + "warnings": [] +} +``` + +## Exit Codes + +- **0** = Success (validation passed, 100% coverage) +- **1** = Failure (incomplete coverage or errors) + +Use in scripts: +```bash +python validate_specifications.py --path ./specs +if [ $? -eq 0 ]; then + echo "Deployment approved" + ./deploy.sh +else + echo "Validation failed - fix requirements first" + exit 1 +fi +``` + +## Document Format Requirements + +For validation to work correctly: + +### Blueprint.md Format +```markdown +## 3. Core System Components + +| Component Name | Responsibility | +|---|---| +| **AuthenticationComponent** | Handles user authentication | +| **DatabaseAdapter** | Manages database connections | +``` + +### Requirements.md Format +```markdown +### Requirement 1: User Authentication + +#### Acceptance Criteria + +1. WHEN user submits credentials, THE **AuthenticationComponent** SHALL validate them. + +2. WHEN validation succeeds, THE **AuthenticationComponent** SHALL return a session token. +``` + +### Tasks.md Format +```markdown +## Task 1: Implement AuthenticationComponent + +- [ ] 1.1 Create AuthenticationComponent class +- [ ] 1.2 Implement validation method +- [ ] 1.3 Add unit tests +- _Requirements: 1.1, 1.2_ +``` + +## Troubleshooting + +### Components not extracted +**Issue**: "No components found in blueprint.md" + +**Solution**: Verify format matches exactly: +- `| **ComponentName** | description |` +- Component name must be between `**` markers +- Must be in a markdown table + +### Requirements not found +**Issue**: "No requirements found" + +**Solution**: Use exact format: +- `### Requirement N: [Name]` +- Criteria: `N. WHEN ... THE **Component** SHALL ...` +- Must have numbers and exact spacing + +### Missing criteria list has items +**Issue**: Validation fails with missing criteria + +**Solution**: Add `_Requirements:` tags to all tasks: +- Format: `_Requirements: 1.1, 1.2, 3.1_` +- Underscore prefix and suffix +- Space after colon +- IDs separated by commas + +### Invalid component names +**Issue**: "Unknown component: ComponentName" + +**Solution**: Check spelling and capitalization: +- Use exact names from blueprint +- Names are case-sensitive +- Verify in requirements criteria + +## Integration Examples + +### GitHub Actions +```yaml +name: Validate Specifications + +on: [push, pull_request] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + - name: Validate specifications + run: | + python validate_specifications.py \ + --path ./specs \ + --generate-validation +``` + +### GitLab CI +```yaml +validate_specs: + image: python:3.9 + script: + - python validate_specifications.py --path ./specs --generate-validation + only: + changes: + - specs/** +``` + +### Local Pre-commit Hook +```bash +#!/bin/bash +python validate_specifications.py --path ./specs +if [ $? -ne 0 ]; then + echo "Specifications validation failed!" + exit 1 +fi +``` + +## Performance + +- Validates 100+ requirements in <1 second +- Handles 1000+ tasks efficiently +- Minimal memory usage +- No external dependencies + +## Requirements + +- **Python**: 3.7 or higher +- **Dependencies**: None (standard library only) + +## File Structure + +``` +specification-architect-skill/ +├── validate_specifications.py # Main validation script +├── validate.bat # Windows helper +├── validate.sh # Linux/macOS helper +├── VALIDATION_SCRIPTS_README.md # This file +├── SKILL.md # Full skill documentation +├── TEMPLATE_REFERENCE.md # Document templates +├── USAGE_GUIDE.md # Phase-by-phase guide +└── README.md # Quick start +``` + +## Complete Validation Workflow + +1. **Write Specifications** + - Create blueprint.md + - Create requirements.md + - Create design.md + - Create tasks.md + +2. **Run Validation** + ```bash + python validate_specifications.py --path ./specs --verbose + ``` + +3. **Review Results** + - Check coverage percentage + - Review missing criteria (if any) + - Review invalid references (if any) + +4. **Fix Issues** + - Add missing requirement tags to tasks + - Fix invalid requirement references + - Update requirements if needed + +5. **Validate Again** + ```bash + python validate_specifications.py --path ./specs + ``` + +6. **Generate Report** + ```bash + python validate_specifications.py --path ./specs --generate-validation + ``` + +7. **Ready to Execute** + - validation.md confirms 100% coverage + - Commit all spec files + - Begin implementation + +## API Usage (Python) + +Use the validator as a Python module: + +```python +from validate_specifications import SpecificationValidator + +# Create validator +validator = SpecificationValidator("./specs", verbose=True) + +# Run validation +result = validator.validate_all() + +# Check results +if result.is_valid: + print("✅ Validation passed!") + print(f"Coverage: {result.coverage_percentage}%") +else: + print(f"❌ {len(result.missing_criteria)} missing criteria") + +# Generate and save validation.md +validator.save_validation_markdown() +``` diff --git a/skills/specification-architect/assets/sample_outputs/example_blueprint.md b/skills/specification-architect/assets/sample_outputs/example_blueprint.md new file mode 100644 index 0000000..793972c --- /dev/null +++ b/skills/specification-architect/assets/sample_outputs/example_blueprint.md @@ -0,0 +1,60 @@ +# Architectural Blueprint +## 1. Core Objective +To create a comprehensive task management system that enables users to create, assign, track, and complete tasks across multiple projects with real-time collaboration features. + +## 2. System Scope and Boundaries +### In Scope +- User authentication and authorization +- Task creation, assignment, and management +- Project organization and team collaboration +- Real-time notifications and updates +- Basic reporting and analytics + +### Out of Scope +- Advanced project management features (Gantt charts, critical path) +- File attachments and document management +- Integration with third-party project management tools +- Mobile application development +- Advanced workflow automation + +## 3. Core System Components +| Component Name | Responsibility | +|---|---| +| **UserAuthenticationService** | Handles user registration, login, and session management | +| **TaskManagementEngine** | Core task CRUD operations and business logic | +| **ProjectOrganizer** | Manages project creation, membership, and permissions | +| **NotificationService** | Handles real-time notifications and email alerts | +| **ReportingModule** | Generates basic reports and analytics dashboards | + +## 4. High-Level Data Flow +```mermaid +graph TD + A[User Interface] --> B[UserAuthenticationService] + A --> C[TaskManagementEngine] + A --> D[ProjectOrganizer] + + B --> E[User Database] + C --> F[Task Database] + D --> G[Project Database] + + C --> H[NotificationService] + H --> I[Email Service] + H --> J[WebSocket Service] + + C --> K[ReportingModule] + K --> L[Analytics Database] + + style UserAuthenticationService fill:#e1f5fe + style TaskManagementEngine fill:#f3e5f5 + style ProjectOrganizer fill:#e8f5e8 + style NotificationService fill:#fff3e0 + style ReportingModule fill:#fce4ec +``` + +## 5. Key Integration Points +- **Authentication API**: JWT-based authentication between User Interface and UserAuthenticationService +- **Task API**: RESTful APIs between User Interface and TaskManagementEngine +- **Project API**: RESTful APIs between User Interface and ProjectOrganizer +- **Notification Gateway**: WebSocket connections for real-time updates +- **Email Service**: SMTP integration for email notifications +- **Database Connections**: PostgreSQL connections for all data storage components \ No newline at end of file diff --git a/skills/specification-architect/assets/sample_outputs/example_design.md b/skills/specification-architect/assets/sample_outputs/example_design.md new file mode 100644 index 0000000..3b20c5f --- /dev/null +++ b/skills/specification-architect/assets/sample_outputs/example_design.md @@ -0,0 +1,393 @@ +# Design Document + +## Overview +This document provides detailed design specifications for the TaskMaster Pro task management system components. + +## Design Principles +- **Single Responsibility**: Each component has a single, well-defined responsibility +- **Loose Coupling**: Components interact through well-defined interfaces +- **High Cohesion**: Related functionality is grouped together +- **Scalability**: Design supports future growth and expansion +- **Security**: All components implement proper authentication and authorization + +## Component Specifications + +### Component: UserAuthenticationService +**Purpose**: Handles user registration, login, and session management + +**Location**: `src/services/auth/UserAuthenticationService.py` + +**Interface**: +```python +class UserAuthenticationService: + """ + User authentication and authorization service + Implements: Req 1.1, 1.2, 1.3, 1.4, 7.1, 7.2 + """ + + def __init__(self, user_repository: UserRepository, email_service: EmailService): + """Initialize authentication service with dependencies""" + self.user_repository = user_repository + self.email_service = email_service + self.jwt_secret = os.getenv('JWT_SECRET') + self.token_expiry = int(os.getenv('TOKEN_EXPIRY_HOURS', '24')) + + def register_user(self, user_data: UserRegistrationData) -> AuthResult: + """ + Register a new user account with email verification + Implements: Req 1.1 + """ + pass + + def authenticate_user(self, credentials: LoginCredentials) -> AuthResult: + """ + Authenticate user and return JWT token + Implements: Req 1.2 + """ + pass + + def reset_password(self, email: str) -> PasswordResetResult: + """ + Initiate password reset process + Implements: Req 1.3 + """ + pass + + def validate_token(self, token: str) -> TokenValidationResult: + """ + Validate JWT token and extract user information + Implements: Req 1.4 + """ + pass + + def hash_password(self, password: str) -> str: + """ + Hash password using bcrypt + Implements: Req 7.2 + """ + pass +``` + +**Dependencies**: +- UserRepository: Database access for user operations +- EmailService: Email sending functionality +- JWT library: Token generation and validation +- bcrypt: Password hashing + +**Data Model**: +```python +from dataclasses import dataclass +from typing import Optional, List +from datetime import datetime +from enum import Enum + +class UserRole(Enum): + ADMIN = "admin" + MANAGER = "manager" + MEMBER = "member" + +@dataclass +class User: + """User entity model""" + id: str + email: str + username: str + password_hash: str + role: UserRole + is_active: bool + email_verified: bool + created_at: datetime + last_login: Optional[datetime] = None + +@dataclass +class UserRegistrationData: + """User registration request data""" + email: str + username: str + password: str + confirm_password: str + +@dataclass +class LoginCredentials: + """User login credentials""" + email: str + password: str + +@dataclass +class AuthResult: + """Authentication operation result""" + success: bool + token: Optional[str] = None + user: Optional[User] = None + message: str = "" +``` + +### Component: TaskManagementEngine +**Purpose**: Core task CRUD operations and business logic + +**Location**: `src/services/tasks/TaskManagementEngine.py` + +**Interface**: +```python +class TaskManagementEngine: + """ + Task management and business logic engine + Implements: Req 2.1, 2.2, 2.3, 2.4, 6.1, 7.3 + """ + + def __init__(self, task_repository: TaskRepository, + notification_service: NotificationService, + auth_service: UserAuthenticationService): + """Initialize task engine with dependencies""" + self.task_repository = task_repository + self.notification_service = notification_service + self.auth_service = auth_service + + def create_task(self, task_data: TaskCreationData, user_id: str) -> TaskCreationResult: + """ + Create a new task with validation and assignment + Implements: Req 2.1 + """ + pass + + def update_task(self, task_id: str, updates: TaskUpdateData, user_id: str) -> TaskUpdateResult: + """ + Update existing task with change tracking + Implements: Req 2.2 + """ + pass + + def assign_task(self, task_id: str, assignee_id: str, assigner_id: str) -> TaskAssignmentResult: + """ + Assign task to user and send notification + Implements: Req 2.3 + """ + pass + + def change_task_status(self, task_id: str, new_status: TaskStatus, user_id: str) -> StatusChangeResult: + """ + Change task status and notify relevant users + Implements: Req 2.4 + """ + pass + + def get_user_tasks(self, user_id: str, filters: TaskFilters) -> List[Task]: + """ + Retrieve tasks for a specific user with filters + Implements: Req 6.1 + """ + pass +``` + +**Dependencies**: +- TaskRepository: Database access for task operations +- NotificationService: Real-time notifications +- UserAuthenticationService: User validation and permissions + +**Data Model**: +```python +from dataclasses import dataclass +from typing import Optional, List, Dict, Any +from datetime import datetime +from enum import Enum + +class TaskStatus(Enum): + TODO = "todo" + IN_PROGRESS = "in_progress" + IN_REVIEW = "in_review" + COMPLETED = "completed" + CANCELLED = "cancelled" + +class TaskPriority(Enum): + LOW = "low" + MEDIUM = "medium" + HIGH = "high" + URGENT = "urgent" + +@dataclass +class Task: + """Task entity model""" + id: str + title: str + description: str + status: TaskStatus + priority: TaskPriority + assignee_id: Optional[str] + creator_id: str + project_id: str + due_date: Optional[datetime] + created_at: datetime + updated_at: datetime + completed_at: Optional[datetime] = None + tags: List[str] = None + custom_fields: Dict[str, Any] = None + +@dataclass +class TaskCreationData: + """Task creation request data""" + title: str + description: str + priority: TaskPriority + assignee_id: Optional[str] + project_id: str + due_date: Optional[datetime] + tags: List[str] = None + +@dataclass +class TaskUpdateData: + """Task update request data""" + title: Optional[str] = None + description: Optional[str] = None + priority: Optional[TaskPriority] = None + assignee_id: Optional[str] = None + due_date: Optional[datetime] = None + tags: Optional[List[str]] = None +``` + +### Component: NotificationService +**Purpose**: Handles real-time notifications and email alerts + +**Location**: `src/services/notifications/NotificationService.py` + +**Interface**: +```python +class NotificationService: + """ + Real-time notification and alert service + Implements: Req 4.1, 4.2, 4.3, 4.4, 6.4 + """ + + def __init__(self, websocket_manager: WebSocketManager, + email_service: EmailService, + notification_repository: NotificationRepository): + """Initialize notification service with dependencies""" + self.websocket_manager = websocket_manager + self.email_service = email_service + self.notification_repository = notification_repository + + def send_task_assignment_notification(self, task_id: str, assignee_id: str) -> NotificationResult: + """ + Send real-time notification for task assignment + Implements: Req 4.1 + """ + pass + + def send_deadline_reminder(self, task_id: str, assignee_id: str) -> NotificationResult: + """ + Send reminder notification for approaching deadline + Implements: Req 4.2 + """ + pass + + def broadcast_task_update(self, task_id: str, update_data: Dict[str, Any]) -> BroadcastResult: + """ + Broadcast real-time task updates to prevent conflicts + Implements: Req 4.3 + """ + pass + + def send_maintenance_notification(self, message: str, scheduled_time: datetime) -> NotificationResult: + """ + Send system maintenance notifications + Implements: Req 4.4 + """ + pass +``` + +**Dependencies**: +- WebSocketManager: Real-time WebSocket connection management +- EmailService: Email notification delivery +- NotificationRepository: Database storage for notifications + +## Integration Design + +### API Contracts +```python +# REST API between User Interface and TaskManagementEngine +POST /api/tasks +Authorization: Bearer {jwt_token} +Content-Type: application/json + +Request: +{ + "title": "Complete user authentication", + "description": "Implement JWT-based authentication system", + "priority": "high", + "assignee_id": "user123", + "project_id": "proj456", + "due_date": "2024-01-15T17:00:00Z", + "tags": ["backend", "security"] +} + +Response: +{ + "id": "task789", + "status": "todo", + "created_at": "2024-01-01T12:00:00Z", + "assigned_at": "2024-01-01T12:00:00Z" +} +``` + +### Database Schema +```sql +-- Users table for UserAuthenticationService +CREATE TABLE users ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + email VARCHAR(255) UNIQUE NOT NULL, + username VARCHAR(100) UNIQUE NOT NULL, + password_hash VARCHAR(255) NOT NULL, + role VARCHAR(20) NOT NULL DEFAULT 'member', + is_active BOOLEAN DEFAULT true, + email_verified BOOLEAN DEFAULT false, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + last_login TIMESTAMP WITH TIME ZONE +); + +-- Tasks table for TaskManagementEngine +CREATE TABLE tasks ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + title VARCHAR(255) NOT NULL, + description TEXT, + status VARCHAR(20) NOT NULL DEFAULT 'todo', + priority VARCHAR(10) NOT NULL DEFAULT 'medium', + assignee_id UUID REFERENCES users(id), + creator_id UUID NOT NULL REFERENCES users(id), + project_id UUID NOT NULL REFERENCES projects(id), + due_date TIMESTAMP WITH TIME ZONE, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + completed_at TIMESTAMP WITH TIME ZONE +); + +-- Projects table for ProjectOrganizer +CREATE TABLE projects ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name VARCHAR(255) NOT NULL, + description TEXT, + owner_id UUID NOT NULL REFERENCES users(id), + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); +``` + +### Security Implementation +```python +# JWT Token validation middleware +def require_auth(func): + """Decorator to require JWT authentication""" + def wrapper(*args, **kwargs): + token = request.headers.get('Authorization') + if not token or not token.startswith('Bearer '): + return jsonify({'error': 'Authentication required'}), 401 + + token = token.split(' ')[1] + try: + payload = jwt.decode(token, JWT_SECRET, algorithms=['HS256']) + request.user_id = payload['user_id'] + return func(*args, **kwargs) + except jwt.ExpiredSignatureError: + return jsonify({'error': 'Token expired'}), 401 + except jwt.InvalidTokenError: + return jsonify({'error': 'Invalid token'}), 401 + return wrapper +``` \ No newline at end of file diff --git a/skills/specification-architect/assets/sample_outputs/example_requirements.md b/skills/specification-architect/assets/sample_outputs/example_requirements.md new file mode 100644 index 0000000..54cbe53 --- /dev/null +++ b/skills/specification-architect/assets/sample_outputs/example_requirements.md @@ -0,0 +1,78 @@ +# Requirements Document + +## Introduction +This document defines the functional and non-functional requirements for the TaskMaster Pro task management system. + +## Glossary +- **Task**: A unit of work that can be assigned to a user and tracked through completion +- **Project**: A collection of related tasks organized under a common goal +- **User**: An individual with login credentials who can interact with the system +- **Notification**: A message sent to users about task updates or assignments +- **UserAuthenticationService**: The component responsible for managing user accounts and authentication + +## Requirements + +### Requirement 1: User Management +**Description**: Users must be able to register, authenticate, and manage their profiles. + +#### Acceptance Criteria +1. WHEN a new user provides valid registration information, THE **UserAuthenticationService** SHALL create a new user account and send a verification email. +2. WHEN a registered user provides correct credentials, THE **UserAuthenticationService** SHALL return a valid JWT token for session management. +3. WHEN a user requests password reset, THE **UserAuthenticationService** SHALL send a password reset link to their registered email. +4. WHEN a JWT token expires, THE **UserAuthenticationService** SHALL require re-authentication. + +### Requirement 2: Task Creation and Management +**Description**: Users must be able to create, edit, assign, and track tasks. + +#### Acceptance Criteria +1. WHEN a user creates a new task with valid information, THE **TaskManagementEngine** SHALL save the task and assign it a unique identifier. +2. WHEN a user edits an existing task, THE **TaskManagementEngine** SHALL update the task and maintain change history. +3. WHEN a task is assigned to a user, THE **TaskManagementEngine** SHALL notify the assigned user via the **NotificationService**. +4. WHEN a task status changes, THE **TaskManagementEngine** SHALL update the task status and notify relevant users. + +### Requirement 3: Project Organization +**Description**: Tasks must be organized into projects with proper access control. + +#### Acceptance Criteria +1. WHEN a user creates a new project, THE **ProjectOrganizer** SHALL create the project and assign the user as project owner. +2. WHEN a project owner adds team members, THE **ProjectOrganizer** SHALL grant appropriate permissions based on role assignments. +3. WHEN a user accesses project tasks, THE **ProjectOrganizer** SHALL validate that the user has permission to view the project. +4. WHEN a project is deleted, THE **ProjectOrganizer** SHALL archive all associated tasks and notify project members. + +### Requirement 4: Real-time Notifications +**Description**: Users must receive real-time notifications about task updates and assignments. + +#### Acceptance Criteria +1. WHEN a task is assigned to a user, THE **NotificationService** SHALL send an immediate notification via WebSocket. +2. WHEN a task deadline approaches, THE **NotificationService** SHALL send reminder notifications to assigned users. +3. WHEN multiple users edit the same task, THE **NotificationService** SHALL broadcast real-time updates to prevent conflicts. +4. WHEN system maintenance occurs, THE **NotificationService** SHALL display maintenance notifications to all active users. + +### Requirement 5: Reporting and Analytics +**Description**: Users must be able to view reports and analytics about task completion and project progress. + +#### Acceptance Criteria +1. WHEN a project owner requests a progress report, THE **ReportingModule** SHALL generate a report showing task completion rates and team productivity. +2. WHEN a manager views analytics dashboard, THE **ReportingModule** SHALL display charts showing task distribution by status and assignee. +3. WHEN tasks are overdue, THE **ReportingModule** SHALL highlight overdue items and calculate impact on project timeline. +4. WHEN a project is completed, THE **ReportingModule** SHALL generate a final performance report with key metrics. + +## Non-Functional Requirements + +### Requirement 6: Performance +**Description**: System must respond quickly under normal load conditions. + +#### Acceptance Criteria +1. WHEN 100 concurrent users access the system, THE **TaskManagementEngine** SHALL respond to task operations within 200 milliseconds. +2. WHEN generating reports, THE **ReportingModule** SHALL complete report generation within 5 seconds for projects with up to 1000 tasks. +3. WHEN users authenticate, THE **UserAuthenticationService** SHALL complete login within 500 milliseconds. +4. WHEN notifications are sent, THE **NotificationService** SHALL deliver notifications within 1 second of trigger events. + +### Requirement 7: Security +**Description**: System must protect user data and prevent unauthorized access. + +#### Acceptance Criteria +1. WHEN users submit sensitive information, THE **UserAuthenticationService** SHALL encrypt all data in transit using HTTPS. +2. WHEN passwords are stored, THE **UserAuthenticationService** SHALL hash passwords using bcrypt with minimum 12 rounds. +3. WHEN API requests are made, THE **TaskManagementEngine** SHALL validate JWT tokens and enforce role-based access control. +4. WHEN database connections are established, THE system SHALL use SSL/TLS encryption for all database communications. \ No newline at end of file diff --git a/skills/specification-architect/assets/sample_outputs/example_research.md b/skills/specification-architect/assets/sample_outputs/example_research.md new file mode 100644 index 0000000..de80f30 --- /dev/null +++ b/skills/specification-architect/assets/sample_outputs/example_research.md @@ -0,0 +1,123 @@ +## Research Summary for Task Management System + +### Domain Analysis +- **Industry**: Productivity/Project Management Software +- **Scale Requirements**: 1,000+ concurrent users, 10,000+ tasks, real-time collaboration +- **Key Challenges**: Real-time updates, data consistency, user permission management, notification delivery + +### Architectural Approaches Considered + +1. **Microservices Architecture** + - Description: Decompose system into independent services for users, tasks, projects, notifications + - Pros: Independent scaling, fault isolation, technology diversity, team autonomy + - Cons: Operational complexity, network latency, distributed transactions, higher cost + +2. **Monolithic Architecture** + - Description: Single application with modular components within one deployable unit + - Pros: Simpler deployment, easier debugging, lower operational overhead, better performance + - Cons: Scalability limits, technology lock-in, deployment risks, team coordination challenges + +3. **Event-Driven Architecture with CQRS** + - Description: Command Query Responsibility Segregation with event sourcing + - Pros: Excellent scalability, audit trails, real-time updates, loose coupling + - Cons: High complexity, eventual consistency, steep learning curve, debugging challenges + +### Technology Stack Research + +#### Backend Frameworks +- **Node.js + Express**: Excellent for real-time features, large ecosystem, fast development +- **Python + FastAPI**: Strong typing, async support, good for APIs, data science integration +- **Java + Spring Boot**: Enterprise-grade, mature ecosystem, strong consistency + +#### Database Options +- **PostgreSQL**: ACID compliance, JSON support, reliability, good for complex queries +- **MongoDB**: Flexible schema, horizontal scaling, good for rapid development +- **MySQL**: Mature, widely used, good performance, familiar to most developers + +#### Real-time Communication +- **WebSockets**: Direct communication, low latency, widely supported +- **Server-Sent Events (SSE)**: Simpler than WebSockets, good for one-way updates +- **Message Queues (Redis/RabbitMQ)**: Reliable delivery, scalable, decoupled + +### Recommended Technology Stack + +- **Architecture Pattern**: **Modular Monolith with Microservice Readiness** + - Start with monolith for speed and simplicity + - Design modules to be easily extractable into microservices later + - Use clear boundaries between functional areas + +- **Backend**: **Node.js + TypeScript + Express** + - TypeScript for type safety and better development experience + - Express for mature, well-documented framework + - Excellent ecosystem for real-time features (Socket.io) + - Good performance for I/O-bound applications + +- **Database**: **PostgreSQL + Redis** + - PostgreSQL as primary database for ACID compliance and reliability + - Redis for session management, caching, and real-time data + - Both have excellent Node.js support + +- **Real-time Communication**: **Socket.io + Redis Adapter** + - Socket.io for WebSocket connections with fallback support + - Redis adapter for multi-instance scaling + - Proven solution for real-time collaboration + +- **Authentication**: **JWT + Refresh Tokens** + - JWT for stateless authentication + - Refresh tokens for security and better user experience + - Industry standard with good library support + +- **Infrastructure**: **Docker + AWS ECS/RDS** + - Docker for containerization and consistency + - AWS ECS for managed container orchestration + - AWS RDS for managed PostgreSQL with automatic backups + +### Research Sources + +1. **"Microservices vs Monolith: When to Choose Which"** (Martin Fowler, 2024) + - Key insight: Start with monolith, extract microservices when clear boundaries emerge + - Most successful microservices implementations evolved from monoliths + +2. **"Real-time Web Application Architecture Best Practices"** (InfoQ, 2024) + - WebSocket scaling challenges and solutions + - Redis adapter pattern for multi-instance deployments + +3. **"PostgreSQL vs MongoDB for Task Management Systems"** (Database Journal, 2024) + - PostgreSQL superior for complex queries and data consistency + - JSON support provides flexibility when needed + +4. **"Node.js TypeScript Best Practices for Enterprise Applications"** (Node.js Foundation, 2024) + - Type safety significantly reduces runtime errors + - Better development experience with IDE support + +5. **"Authentication Patterns for Modern Web Applications"** (OWASP, 2024) + - JWT + refresh token pattern recommended for SPA applications + - Proper token storage and refresh strategies + +### Decision Rationale + +**Why Modular Monolith First:** +- Team size (3-5 developers) doesn't warrant microservices complexity +- Faster time-to-market with simpler deployment and debugging +- Clear module boundaries will allow future extraction if needed +- Lower operational cost and complexity for initial launch + +**Why Node.js + TypeScript:** +- Real-time features are first-class citizens in Node.js ecosystem +- TypeScript provides enterprise-grade type safety +- Large talent pool and extensive library ecosystem +- Excellent performance for our I/O-bound use case + +**Why PostgreSQL + Redis:** +- Data consistency is critical for task management +- PostgreSQL handles complex queries and relationships well +- Redis provides excellent caching and real-time data capabilities +- Both technologies are mature, well-supported, and cost-effective + +**Why Socket.io for Real-time:** +- Handles WebSocket connection management complexity +- Provides automatic fallback to other transport methods +- Redis adapter enables horizontal scaling +- Large community and proven track record + +This technology stack balances development speed, operational simplicity, and future scalability while leveraging current best practices and well-established patterns. \ No newline at end of file diff --git a/skills/specification-architect/assets/sample_outputs/example_tasks.md b/skills/specification-architect/assets/sample_outputs/example_tasks.md new file mode 100644 index 0000000..526ef53 --- /dev/null +++ b/skills/specification-architect/assets/sample_outputs/example_tasks.md @@ -0,0 +1,152 @@ +# Implementation Plan + +## Phase 1: Core Infrastructure +- [ ] 1. Implement the UserAuthenticationService + - [ ] 1.1 Create project structure and setup configuration + - [ ] 1.2 Implement core UserAuthenticationService class in `src/services/auth/UserAuthenticationService.py` + - [ ] 1.3 Add user registration and validation methods + - [ ] 1.4 Implement JWT token generation and validation + - [ ] 1.5 Add password hashing with bcrypt + - [ ] 1.6 Create user repository interface and implementation + - [ ] 1.7 Write unit tests for UserAuthenticationService + - [ ] 1.8 Create integration tests for authentication flow + - _Requirements: 1.1, 1.2, 1.3, 1.4, 7.1, 7.2_ + +- [ ] 2. Implement the TaskManagementEngine + - [ ] 2.1 Create TaskManagementEngine class in `src/services/tasks/TaskManagementEngine.py` + - [ ] 2.2 Implement task CRUD operations (create, read, update, delete) + - [ ] 2.3 Add task assignment and status change methods + - [ ] 2.4 Implement task filtering and search functionality + - [ ] 2.5 Create task repository interface and implementation + - [ ] 2.6 Add input validation and business rules + - [ ] 2.7 Write unit tests for task operations + - [ ] 2.8 Create performance tests for task queries + - _Requirements: 2.1, 2.2, 2.3, 2.4, 6.1, 7.3_ + +## Phase 2: Data Layer and Storage +- [ ] 3. Setup Database Infrastructure + - [ ] 3.1 Configure PostgreSQL database connection + - [ ] 3.2 Create database migration scripts for schema + - [ ] 3.3 Implement users table with proper constraints + - [ ] 3.4 Create tasks table with foreign key relationships + - [ ] 3.5 Setup projects table and member relationships + - [ ] 3.6 Add indexes for performance optimization + - [ ] 3.7 Create database backup and recovery procedures + - [ ] 3.8 Write database integration tests + - _Requirements: 1.1, 2.1, 3.1, 3.2, 3.3, 3.4, 7.4_ + +- [ ] 4. Implement the ProjectOrganizer + - [ ] 4.1 Create ProjectOrganizer class in `src/services/projects/ProjectOrganizer.py` + - [ ] 4.2 Implement project creation and management methods + - [ ] 4.3 Add team member invitation and permission system + - [ ] 4.4 Create project repository interface and implementation + - [ ] 4.5 Implement role-based access control for projects + - [ ] 4.6 Add project archiving and deletion functionality + - [ ] 4.7 Write unit tests for project operations + - [ ] 4.8 Create tests for permission validation + - _Requirements: 3.1, 3.2, 3.3, 3.4_ + +## Phase 3: Communication Layer +- [ ] 5. Implement the NotificationService + - [ ] 5.1 Create NotificationService class in `src/services/notifications/NotificationService.py` + - [ ] 5.2 Setup WebSocket manager for real-time communications + - [ ] 5.3 Implement email service integration with SMTP + - [ ] 5.4 Create notification templates and formatting + - [ ] 5.5 Add notification queue and retry mechanisms + - [ ] 5.6 Implement notification preferences and filtering + - [ ] 5.7 Write tests for real-time notification delivery + - [ ] 5.8 Create email notification tests + - _Requirements: 4.1, 4.2, 4.3, 4.4, 6.4_ + +- [ ] 6. REST API Implementation + - [ ] 6.1 Create Flask/FastAPI application structure + - [ ] 6.2 Implement authentication middleware and decorators + - [ ] 6.3 Create user endpoints (register, login, profile) + - [ ] 6.4 Implement task CRUD endpoints with proper validation + - [ ] 6.5 Add project management endpoints + - [ ] 6.6 Create API documentation with OpenAPI/Swagger + - [ ] 6.7 Add rate limiting and request validation + - [ ] 6.8 Write comprehensive API tests + - _Requirements: 1.2, 2.1, 2.2, 3.1, 7.3_ + +## Phase 4: Business Intelligence +- [ ] 7. Implement the ReportingModule + - [ ] 7.1 Create ReportingModule class in `src/services/reports/ReportingModule.py` + - [ ] 7.2 Implement task completion rate calculations + - [ ] 7.3 Create productivity analytics and dashboards + - [ ] 7.4 Add overdue task identification and impact analysis + - [ ] 7.5 Implement project performance metrics + - [ ] 7.6 Create report generation and export functionality + - [ ] 7.7 Add caching for frequently accessed reports + - [ ] 7.8 Write tests for report accuracy and performance + - _Requirements: 5.1, 5.2, 5.3, 5.4, 6.2_ + +## Phase 5: Testing and Quality Assurance +- [ ] 8. Comprehensive Testing Suite + - [ ] 8.1 Complete unit test coverage for all components (target: 90%+) + - [ ] 8.2 Create integration tests for component interactions + - [ ] 8.3 Implement end-to-end tests for critical user flows + - [ ] 8.4 Add performance testing and load testing + - [ ] 8.5 Create security testing and vulnerability scanning + - [ ] 8.6 Implement automated testing in CI/CD pipeline + - [ ] 8.7 Add user acceptance testing scenarios + - [ ] 8.8 Create test data management and cleanup procedures + - _Requirements: 6.1, 6.2, 6.3, 6.4_ + +- [ ] 9. Security Implementation + - [ ] 9.1 Configure HTTPS/TLS for all communications + - [ ] 9.2 Implement secure password storage and hashing + - [ ] 9.3 Add input validation and sanitization + - [ ] 9.4 Create security headers and CSP policies + - [ ] 9.5 Implement audit logging for sensitive operations + - [ ] 9.6 Add rate limiting and DDoS protection + - [ ] 9.7 Create security monitoring and alerting + - [ ] 9.8 Write security tests and penetration testing + - _Requirements: 7.1, 7.2, 7.3, 7.4_ + +## Phase 6: Deployment and Operations +- [ ] 10. Production Deployment + - [ ] 10.1 Setup production environment and infrastructure + - [ ] 10.2 Configure application servers and load balancers + - [ ] 10.3 Implement database clustering and backup strategies + - [ ] 10.4 Setup monitoring and logging infrastructure + - [ ] 10.5 Create deployment scripts and CI/CD pipeline + - [ ] 10.6 Configure environment-specific settings + - [ ] 10.7 Implement health checks and monitoring alerts + - [ ] 10.8 Create disaster recovery and rollback procedures + - _Requirements: 5.1, 5.2_ + +- [ ] 11. Documentation and Training + - [ ] 11.1 Create comprehensive API documentation + - [ ] 11.2 Write user guides and documentation + - [ ] 11.3 Create administrator and deployment guides + - [ ] 11.4 Document system architecture and design decisions + - [ ] 11.5 Create troubleshooting and maintenance guides + - [ ] 11.6 Develop training materials for end users + - [ ] 11.7 Record video tutorials and walkthroughs + - [ ] 11.8 Create knowledge base and FAQ resources + - _Requirements: 5.1, 5.2_ + +## Phase 7: Performance Optimization +- [ ] 12. Performance Tuning + - [ ] 12.1 Optimize database queries and add query caching + - [ ] 12.2 Implement Redis caching for frequently accessed data + - [ ] 12.3 Add connection pooling and optimize resource usage + - [ ] 12.4 Optimize API response times and implement pagination + - [ ] 12.5 Add asynchronous processing for long-running tasks + - [ ] 12.6 Implement content delivery network for static assets + - [ ] 12.7 Monitor and optimize memory usage + - [ ] 12.8 Create performance benchmarks and monitoring + - _Requirements: 6.1, 6.2, 6.3, 6.4_ + +## Final Acceptance Criteria +- [ ] 13. System Integration and Validation + - [ ] 13.1 Validate all acceptance criteria from requirements document + - [ ] 13.2 Run complete traceability validation using automated script + - [ ] 13.3 Perform full system integration testing + - [ ] 13.4 Conduct security audit and penetration testing + - [ ] 13.5 Validate performance under expected load + - [ ] 13.6 Confirm all user workflows function correctly + - [ ] 13.7 Complete user acceptance testing with stakeholders + - [ ] 13.8 Finalize documentation and prepare for launch + - _Requirements: 1.1, 1.2, 1.3, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 4.4, 5.1, 5.2, 5.3, 5.4, 6.1, 6.2, 6.3, 6.4, 7.1, 7.2, 7.3, 7.4_ \ No newline at end of file diff --git a/skills/specification-architect/assets/sample_outputs/example_validation.md b/skills/specification-architect/assets/sample_outputs/example_validation.md new file mode 100644 index 0000000..f6667d6 --- /dev/null +++ b/skills/specification-architect/assets/sample_outputs/example_validation.md @@ -0,0 +1,110 @@ +# Validation Report + +## 1. Requirements to Tasks Traceability Matrix + +| Requirement | Acceptance Criterion | Implementing Task(s) | Status | +|---|---|---|---| +| 1. User Management | 1.1 | Task 1, Task 8 | Covered | +| | 1.2 | Task 1, Task 6 | Covered | +| | 1.3 | Task 1, Task 8 | Covered | +| | 1.4 | Task 1, Task 6 | Covered | +| 2. Task Creation and Management | 2.1 | Task 2, Task 6 | Covered | +| | 2.2 | Task 2, Task 6 | Covered | +| | 2.3 | Task 2, Task 5 | Covered | +| | 2.4 | Task 2, Task 5 | Covered | +| 3. Project Organization | 3.1 | Task 4, Task 6 | Covered | +| | 3.2 | Task 4, Task 8 | Covered | +| | 3.3 | Task 4, Task 8 | Covered | +| | 3.4 | Task 4, Task 8 | Covered | +| 4. Real-time Notifications | 4.1 | Task 5, Task 8 | Covered | +| | 4.2 | Task 5, Task 8 | Covered | +| | 4.3 | Task 5, Task 8 | Covered | +| | 4.4 | Task 5, Task 8 | Covered | +| 5. Reporting and Analytics | 5.1 | Task 7, Task 10 | Covered | +| | 5.2 | Task 7, Task 8 | Covered | +| | 5.3 | Task 7, Task 8 | Covered | +| | 5.4 | Task 7, Task 10 | Covered | +| 6. Performance | 6.1 | Task 2, Task 12 | Covered | +| | 6.2 | Task 7, Task 12 | Covered | +| | 6.3 | Task 8, Task 12 | Covered | +| | 6.4 | Task 5, Task 12 | Covered | +| 7. Security | 7.1 | Task 1, Task 9 | Covered | +| | 7.2 | Task 1, Task 9 | Covered | +| | 7.3 | Task 2, Task 9 | Covered | +| | 7.4 | Task 3, Task 9 | Covered | + +## 2. Coverage Analysis + +### Summary +- **Total Acceptance Criteria**: 28 +- **Criteria Covered by Tasks**: 28 +- **Coverage Percentage**: 100% + +### Detailed Status +- **Covered Criteria**: 1.1, 1.2, 1.3, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 4.4, 5.1, 5.2, 5.3, 5.4, 6.1, 6.2, 6.3, 6.4, 7.1, 7.2, 7.3, 7.4 +- **Missing Criteria**: None +- **Invalid References**: None + +## 3. Validation Summary + +### Component Coverage Analysis +- **UserAuthenticationService**: All 6 acceptance criteria covered across tasks 1, 6, 8, 9 +- **TaskManagementEngine**: All 4 acceptance criteria covered across tasks 2, 5, 6, 9, 12 +- **ProjectOrganizer**: All 4 acceptance criteria covered across tasks 4, 6, 8 +- **NotificationService**: All 4 acceptance criteria covered across tasks 5, 8, 12 +- **ReportingModule**: All 4 acceptance criteria covered across tasks 7, 8, 10, 12 +- **Infrastructure Components**: All 6 security and performance criteria covered across tasks 3, 9, 12 + +### Task Distribution Analysis +- **Phase 1 (Infrastructure)**: Tasks 1-2 cover 10 acceptance criteria +- **Phase 2 (Data Layer)**: Tasks 3-4 cover 8 acceptance criteria +- **Phase 3 (Communication)**: Tasks 5-6 cover 8 acceptance criteria +- **Phase 4 (Business Intelligence)**: Task 7 covers 4 acceptance criteria +- **Phase 5 (Testing)**: Tasks 8-9 cover 16 acceptance criteria +- **Phase 6 (Deployment)**: Task 10 covers 2 acceptance criteria +- **Phase 7 (Performance)**: Task 12 covers 4 acceptance criteria + +### Cross-Cutting Concerns +- **Security Requirements**: All 4 criteria (7.1-7.4) addressed in tasks 1, 2, 3, 9 +- **Performance Requirements**: All 4 criteria (6.1-6.4) addressed in tasks 2, 5, 7, 12 +- **Authentication/Authorization**: Integrated throughout tasks 1, 2, 4, 6 +- **Data Validation**: Covered in tasks 1, 2, 4, 6, 9 +- **Error Handling**: Addressed in tasks 1, 2, 4, 5, 7, 9 + +## 4. Final Validation + +All 28 acceptance criteria are fully traced to implementation tasks. The plan is validated and ready for execution. + +### Validation Results: +- ✅ **Requirements Coverage**: 100% (28/28 criteria covered) +- ✅ **Task Traceability**: All 13 major tasks have proper requirement references +- ✅ **Component Consistency**: All component names used consistently across documents +- ✅ **Template Adherence**: All documents follow the specified templates +- ✅ **Reference Validity**: No invalid requirement references found in tasks + +### Readiness Assessment: +- ✅ **Architecture**: Complete and validated +- ✅ **Requirements**: Fully specified and testable +- ✅ **Design**: Detailed and comprehensive +- ✅ **Implementation Plan**: Granular and actionable +- ✅ **Validation**: Automated and verified + +## 5. Next Steps + +The specification is now complete and validated. The following actions are recommended: + +1. **Begin Implementation**: Start with Phase 1 tasks as outlined in the implementation plan +2. **Setup Development Environment**: Configure tools, databases, and repositories +3. **Establish Quality Gates**: Implement the traceability validator in CI/CD pipeline +4. **Regular Validation**: Run validation checks after each major milestone +5. **Stakeholder Review**: Conduct final review with all project stakeholders + +## 6. Validation Command + +To re-run validation during implementation: + +```bash +python scripts/traceability_validator.py --path . --requirements requirements.md --tasks tasks.md +``` + +This command will verify that all requirements remain covered throughout the development process. \ No newline at end of file diff --git a/skills/specification-architect/assets/sample_outputs/example_verifiable_research.md b/skills/specification-architect/assets/sample_outputs/example_verifiable_research.md new file mode 100644 index 0000000..241475b --- /dev/null +++ b/skills/specification-architect/assets/sample_outputs/example_verifiable_research.md @@ -0,0 +1,25 @@ +# Verifiable Research and Technology Proposal + +## 1. Core Problem Analysis +The user requires a task management system for a growing SaaS company that must handle real-time collaboration, support 1,000+ concurrent users, integrate with existing tools, and scale horizontally. The primary technical challenges include real-time data synchronization, conflict resolution, and maintaining performance under high load. + +## 2. Verifiable Technology Recommendations + +| Technology/Pattern | Rationale & Evidence | +|---|---| +| **Node.js + TypeScript** | Node.js excels at real-time applications due to its event-driven, non-blocking I/O model that can handle thousands of concurrent connections efficiently [cite:1]. TypeScript adds static typing that reduces runtime errors by approximately 15% in large codebases while providing better IDE support and documentation [cite:2]. | +| **Modular Monolith Architecture** | A modular monolith approach is recommended over microservices for teams of 3-5 developers because it provides clear module boundaries that can be extracted into microservices later, while avoiding the operational complexity of distributed systems [cite:3]. This approach has been successfully used by companies like Basecamp and GitHub before scaling to microservices. | +| **PostgreSQL + Redis** | PostgreSQL provides ACID compliance and has been proven reliable for financial applications with 99.99% uptime, making it ideal for critical task data [cite:4]. Redis offers sub-millisecond latency for real-time features like notifications and presence detection, with proven scalability for millions of concurrent connections [cite:5]. | +| **Socket.io for Real-time Communication** | Socket.io provides automatic fallback from WebSockets to other transport methods, ensuring compatibility across all network environments including restrictive corporate firewalls [cite:6]. The library handles connection management, reconnection logic, and room-based messaging out of the box. | +| **Docker + Kubernetes Deployment** | Containerization with Docker provides consistent environments across development, testing, and production, eliminating "it works on my machine" issues [cite:7]. Kubernetes enables horizontal scaling with automatic load balancing and self-healing capabilities that have been proven to reduce infrastructure costs by 30-40% for SaaS applications [cite:8]. | + +## 3. Browsed Sources + +- [1] https://nodejs.org/en/docs/guides/blocking-vs-non-blocking/ - Official Node.js documentation explaining event-driven, non-blocking I/O architecture and its benefits for concurrent applications +- [2] https://www.typescriptlang.org/docs/handbook/intro.html - TypeScript documentation showing how static typing reduces runtime errors and improves development experience +- [3] https://martinfowler.com/articles/monoliths.html - Martin Fowler's analysis of modular monolith architecture, including successful case studies from Basecamp and GitHub +- [4] https://www.postgresql.org/about/ - PostgreSQL official documentation highlighting ACID compliance, reliability statistics, and financial industry adoption +- [5] https://redis.io/topics/introduction - Redis documentation showing performance benchmarks and scalability for real-time applications +- [6] https://socket.io/docs/ - Socket.io documentation demonstrating fallback mechanisms and compatibility features +- [7] https://www.docker.com/why-docker/ - Docker documentation showing containerization benefits and environment consistency +- [8] https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/ - Kubernetes documentation detailing scaling capabilities and cost reduction studies \ No newline at end of file diff --git a/skills/specification-architect/plugin.json b/skills/specification-architect/plugin.json new file mode 100644 index 0000000..3852bd3 --- /dev/null +++ b/skills/specification-architect/plugin.json @@ -0,0 +1,25 @@ +{ + "name": "specification-architect", + "version": "1.0.0", + "description": "A rigorous, evidence-based system that generates six interconnected architectural documents (research.md, blueprint.md, requirements.md, design.md, tasks.md, validation.md) with complete traceability. Implements a 6-phase process that eliminates AI-generated misinformation by mandating verification of all claims through web browsing and citations.", + "author": { + "name": "George A Puiu", + "email": "puiu.adrian@gmail.com" + }, + "license": "MIT", + "keywords": [ + "architecture", + "specification", + "documentation", + "traceability", + "requirements", + "design", + "evidence-based", + "validation" + ], + "category": "productivity", + "commands": "./SKILL.md", + "strict": false, + "repository": "https://github.com/adrianpuiu/specification-document-generator", + "homepage": "https://github.com/adrianpuiu/specification-document-generator" +} diff --git a/skills/specification-architect/references/document_templates.md b/skills/specification-architect/references/document_templates.md new file mode 100644 index 0000000..5bba0e2 --- /dev/null +++ b/skills/specification-architect/references/document_templates.md @@ -0,0 +1,448 @@ +# Document Templates + +This document provides detailed templates and examples for each of the five specification architect documents. + +## Phase 0: Verifiable Research Template + +### Strict Protocol - NO "RESEARCH SLOP" +**CRITICAL**: This phase prevents AI-generated misinformation that could lead to serious professional consequences. Every claim MUST be verified with browsed sources. + +### Evidence-Based Research Template +```markdown +# Verifiable Research and Technology Proposal + +## 1. Core Problem Analysis +[A brief, 1-2 sentence analysis of the user's request and the primary technical challenges.] + +## 2. Verifiable Technology Recommendations +| Technology/Pattern | Rationale & Evidence | +|---|---| +| **[Technology Name]** | [Rationale derived from browsed sources, with every factual claim cited.] | +| **[Pattern Name]** | [Rationale derived from browsed sources, with every factual claim cited.] | +| **[Framework]** | [Specific capabilities and limitations supported by sources.] | +| **[Database]** | [Performance characteristics and use case suitability with citations.] | + +## 3. Browsed Sources +- [1] [Complete URL of browsed source 1] - [Brief description of content] +- [2] [Complete URL of browsed source 2] - [Brief description of content] +- [3] [Complete URL of browsed source 3] - [Brief description of content] +- [...] +``` + +### Citation Requirements - MANDATORY + +**Every factual claim MUST end with `[cite:INDEX]` citation:** + +**Examples of Proper Citations:** +- ❌ "Node.js is great for real-time applications" (NO CITATION - RESEARCH SLOP) +- ✅ "Node.js excels at real-time applications due to its event-driven, non-blocking I/O model [cite:1]." +- ❌ "TypeScript reduces errors" (NO CITATION - RESEARCH SLOP) +- ✅ "TypeScript adds static typing that reduces runtime errors by approximately 15% in large codebases [cite:2]." +- ❌ "PostgreSQL is reliable" (NO CITATION - RESEARCH SLOP) +- ✅ "PostgreSQL provides ACID compliance and has been proven reliable for financial applications with 99.99% uptime [cite:3]." + +### Mandatory Research Process + +1. **Search THEN Browse**: Use WebSearch to find sources, then WebFetch to read the actual content +2. **NO Search Snippets**: You MUST read the full content of sources, not just search results +3. **Verify Claims**: Every technology claim must be supported by actual browsed content +4. **Cite Everything**: All factual statements must have corresponding citations +5. **Source Listing**: All browsed URLs must be listed with index numbers + +### Quality Assurance Checklist + +**Before proceeding to Phase 1, verify:** +- [ ] Every technology recommendation has citations +- [ ] All citations correspond to browsed sources +- [ ] No claims made without source evidence +- [ ] Source URLs are complete and accessible +- [ ] Rationales are derived from actual source content +- [ ] No "research slop" or AI-generated assumptions + +**Professional Standards Compliance:** +This research process prevents the types of errors that have led to legal sanctions, financial penalties, and professional ruin when relying on unverified AI-generated content. + +**Quality Gate**: Do not proceed to Phase 1 until ALL claims are cited and verified with browsed sources. + +## Blueprint Template + +### Complete Template +```markdown +# Architectural Blueprint +## 1. Core Objective +[Single paragraph defining the primary goal and purpose of the system.] + +## 2. System Scope and Boundaries +### In Scope +- [Feature 1 that will be implemented] +- [Feature 2 that will be implemented] +- [Component 1 that will be developed] + +### Out of Scope +- [Feature 1 that will NOT be implemented] +- [External system 1 that will NOT be integrated] +- [Technology 1 that will NOT be used] + +## 3. Core System Components +| Component Name | Responsibility | +|---|---| +| **[ComponentName1]** | [Concise function description explaining what this component does.] | +| **[ComponentName2]** | [Concise function description explaining what this component does.] | +| **[ComponentName3]** | [Concise function description explaining what this component does.] | + +## 4. High-Level Data Flow +```mermaid +graph TD + A[External Input] --> B[ComponentName1] + B --> C[ComponentName2] + C --> D[ComponentName3] + D --> E[External Output] + + style ComponentName1 fill:#e1f5fe + style ComponentName2 fill:#f3e5f5 + style ComponentName3 fill:#e8f5e8 +``` + +## 5. Key Integration Points +- **API Gateway**: RESTful APIs between [ComponentName1] and [ComponentName2] +- **Database Connection**: [ComponentName2] connects to PostgreSQL database +- **External Service**: [ComponentName3] integrates with [External Service Name] via [Protocol] +- **Authentication**: JWT-based authentication between all components +``` + +### Blueprint Guidelines + +**CRITICAL: Upfront Planning Quality Determines Everything** + +- **Component Names**: Use clear, descriptive names (e.g., "UserAuthenticationService", "DataProcessingEngine") + - Names should clearly indicate what the component DOES + - Use consistent naming conventions (Service, Engine, Manager, Repository, etc.) + - Avoid ambiguous names like "Helper" or "Utilities" + +- **Single Responsibility Principle**: Each component should have ONE clear purpose + - If you find yourself saying "and also", split into multiple components + - Clear responsibilities prevent confusion and enable independent testing + +- **Data Flow Visualization**: The Mermaid diagram is CRITICAL for understanding + - Show the complete journey from external input to external output + - Include all decision points and data transformations + - Use colors/styles to make component boundaries obvious + +- **Integration Points**: Be explicit about how components communicate + - Specify protocols (REST, gRPC, message queues, events) + - Define data formats (JSON, protobuf, XML) + - Include authentication and error handling strategies + +- **Boundaries Setting**: The In Scope/Out of Scope section prevents scope creep + - Be specific about what you WILL NOT build + - This protects against "while you're at it" additions + - Clear boundaries enable accurate estimation and planning + +## Requirements Template + +### Complete Template +```markdown +# Requirements Document + +## Introduction +This document defines the functional and non-functional requirements for the [System Name] system. + +## Glossary +- **Term1**: Definition of term1 +- **Term2**: Definition of term2 +- **[ComponentName1]**: The component responsible for [function] + +## Requirements + +### Requirement 1: [Feature Name] +**Description**: [Brief description of what this requirement accomplishes.] + +#### Acceptance Criteria +1. WHEN [trigger condition], THE **[ComponentName1]** SHALL [specific, testable behavior]. +2. WHEN [another trigger condition], THE **[ComponentName2]** SHALL [specific, testable behavior]. +3. GIVEN [precondition], WHEN [action], THEN **[ComponentName3]** SHALL [expected outcome]. + +### Requirement 2: [Another Feature Name] +**Description**: [Brief description of what this requirement accomplishes.] + +#### Acceptance Criteria +1. WHEN [trigger condition], THE **[ComponentName1]** SHALL [specific, testable behavior]. +2. WHEN [trigger condition], THE **[ComponentName2]** SHALL [specific, testable behavior]. + +## Non-Functional Requirements + +### Requirement 3: Performance +**Description**: System must meet performance requirements. + +#### Acceptance Criteria +1. WHEN [load condition], THE **[ComponentName1]** SHALL [response time requirement]. +2. WHEN [concurrent users condition], THE **[ComponentName2]** SHALL [throughput requirement]. +``` + +### Requirements Guidelines +- **Component References**: MUST use exact component names from blueprint (copy-paste to avoid errors) +- **Testable Criteria**: Each acceptance criterion must be measurable and testable +- **WHEN-THEN Format**: Use the format "WHEN [condition], THE **[Component]** SHALL [behavior]" +- **Requirement Numbering**: Use sequential numbering (1, 2, 3...) +- **Criteria Numbering**: Use decimal numbering (1.1, 1.2, 2.1, 2.2...) + +## Design Template + +### Complete Template +```markdown +# Design Document + +## Overview +This document provides detailed design specifications for the [System Name] system components. + +## Design Principles +- **Single Responsibility**: Each component has a single, well-defined responsibility +- **Loose Coupling**: Components interact through well-defined interfaces +- **High Cohesion**: Related functionality is grouped together +- **Scalability**: Design supports future growth and expansion + +## Component Specifications + +### Component: [ComponentName1] +**Purpose**: [Responsibility from blueprint - copy exactly] + +**Location**: `src/components/[ComponentName1].py` + +**Interface**: +```python +class [ComponentName1]: + """ + [Brief description of component purpose] + Implements: Req 1.1, Req 1.2 + """ + + def __init__(self, dependency: [DependencyType]): + """Initialize component with required dependencies""" + pass + + def process_data(self, input: InputType) -> OutputType: + """ + Process input data and return results + Implements: Req 1.1 + """ + pass + + def validate_input(self, data: Any) -> bool: + """ + Validate input data format and constraints + Implements: Req 1.2 + """ + pass +``` + +**Dependencies**: +- [Dependency1]: [Description of dependency] +- [Dependency2]: [Description of dependency] + +**Data Model**: +```python +from dataclasses import dataclass +from typing import List, Optional + +@dataclass +class [DataModelName]: + """Data structure for [ComponentName1]""" + field1: str + field2: int + field3: Optional[List[str]] = None +``` + +### Component: [ComponentName2] +**Purpose**: [Responsibility from blueprint - copy exactly] + +**Location**: `src/services/[ComponentName2].py` + +**Interface**: +```python +class [ComponentName2]: + """ + [Brief description of component purpose] + Implements: Req 2.1, Req 2.2, Req 3.1 + """ + + def __init__(self, config: ConfigType): + """Initialize component with configuration""" + pass + + def execute_service(self, request: RequestType) -> ResponseType: + """ + Execute main service functionality + Implements: Req 2.1 + """ + pass + + def handle_error(self, error: Exception) -> ErrorResponseType: + """ + Handle and log service errors + Implements: Req 2.2 + """ + pass +``` + +## Integration Design + +### API Contracts +```python +# REST API between [ComponentName1] and [ComponentName2] +POST /api/process +Content-Type: application/json + +Request: +{ + "data": "input_data", + "options": { + "validate": true, + "format": "json" + } +} + +Response: +{ + "status": "success", + "result": "processed_data", + "metadata": { + "processing_time": 150, + "timestamp": "2024-01-01T12:00:00Z" + } +} +``` + +### Database Schema +```sql +-- Table for [ComponentName2] data storage +CREATE TABLE processed_data ( + id SERIAL PRIMARY KEY, + input_data TEXT NOT NULL, + output_data TEXT NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + processed_by VARCHAR(100) NOT NULL +); +``` +``` + +### Design Guidelines +- **Purpose**: Copy the responsibility exactly from the blueprint +- **Location**: Specify the exact file path where the component will be implemented +- **Requirement References**: Include "Implements: Req X.Y" comments for each method +- **Dependencies**: List all external dependencies and services +- **Data Models**: Define data structures used by the component + +## Tasks Template + +### Complete Template +```markdown +# Implementation Plan + +## Phase 1: Core Infrastructure +- [ ] 1. Implement the [ComponentName1] + - [ ] 1.1 Create project structure and setup + - [ ] 1.2 Implement core [ComponentName1] class in `src/components/[ComponentName1].py` + - [ ] 1.3 Add input validation methods + - [ ] 1.4 Write unit tests for [ComponentName1] + - [ ] 1.5 Create integration tests + - _Requirements: 1.1, 1.2_ + +- [ ] 2. Implement the [ComponentName2] + - [ ] 2.1 Create [ComponentName2] service class + - [ ] 2.2 Implement main service methods + - [ ] 2.3 Add error handling and logging + - [ ] 2.4 Configure service dependencies + - [ ] 2.5 Write service tests + - _Requirements: 2.1, 2.2, 3.1_ + +## Phase 2: Data Layer +- [ ] 3. Implement the [ComponentName3] + - [ ] 3.1 Setup database connection and schema + - [ ] 3.2 Implement data access methods + - [ ] 3.3 Add data validation and transformation + - [ ] 3.4 Create database migration scripts + - [ ] 3.5 Write database tests + - _Requirements: 3.1, 3.2_ + +## Phase 3: Integration +- [ ] 4. API Integration + - [ ] 4.1 Implement REST API endpoints + - [ ] 4.2 Add request/response validation + - [ ] 4.3 Configure API security and authentication + - [ ] 4.4 Add API documentation + - [ ] 4.5 Write API integration tests + - _Requirements: 2.1, 4.1_ + +## Phase 4: Testing and Deployment +- [ ] 5. Testing + - [ ] 5.1 Complete end-to-end test suite + - [ ] 5.2 Performance testing and optimization + - [ ] 5.3 Security testing and vulnerability scanning + - [ ] 5.4 User acceptance testing + - _Requirements: 3.1, 5.1_ + +- [ ] 6. Deployment + - [ ] 6.1 Setup production environment + - [ ] 6.2 Configure monitoring and logging + - [ ] 6.3 Create deployment scripts + - [ ] 6.4 Implement rollback procedures + - _Requirements: 5.1, 5.2_ +``` + +### Tasks Guidelines +- **Component Names**: Use exact component names from blueprint +- **Task Numbering**: Use sequential numbering (1, 2, 3...) +- **Sub-tasks**: Use decimal numbering (1.1, 1.2, 1.3...) +- **Requirement Tags**: Each main task must include `_Requirements: X.Y, Z.W_` tags +- **Actionable Tasks**: Each sub-task should be a specific, actionable item +- **Complete Coverage**: Every acceptance criterion from requirements must be referenced + +## Validation Template + +### Complete Template +```markdown +# Validation Report + +## 1. Requirements to Tasks Traceability Matrix + +| Requirement | Acceptance Criterion | Implementing Task(s) | Status | +|---|---|---|---| +| 1. User Authentication | 1.1 | Task 1, Task 2 | Covered | +| | 1.2 | Task 1, Task 3 | Covered | +| 2. Data Processing | 2.1 | Task 4, Task 5 | Covered | +| | 2.2 | Task 4 | Covered | +| | 2.3 | Task 6 | Covered | +| 3. Performance | 3.1 | Task 7, Task 8 | Covered | +| ... | ... | ... | ... | +| X. [Final Requirement] | X.Y | Task Z | Covered | + +## 2. Coverage Analysis + +### Summary +- **Total Acceptance Criteria**: [M] +- **Criteria Covered by Tasks**: [M] +- **Coverage Percentage**: 100% + +### Detailed Status +- **Covered Criteria**: 1.1, 1.2, 2.1, 2.2, 2.3, 3.1, ..., X.Y +- **Missing Criteria**: None +- **Invalid References**: None + +## 3. Final Validation +All [M] acceptance criteria are fully traced to implementation tasks. The plan is validated and ready for execution. +``` + +### Validation Guidelines +- **Matrix Generation**: Create a row for each acceptance criterion +- **Task Mapping**: List all tasks that implement each criterion +- **Status Indicators**: Use "Covered" for implemented criteria, "Missing" for gaps +- **Coverage Analysis**: Provide summary statistics and detailed status +- **Final Statement**: Confirm 100% coverage or identify gaps + +## Template Usage Tips + +1. **Copy-Paste Accuracy**: Copy component names exactly between documents to avoid traceability errors +2. **Sequential Numbering**: Maintain consistent numbering schemes across all documents +3. **Requirement References**: Double-check that all task requirement references exist in the requirements document +4. **Template Strictness**: Follow the templates exactly - the validation script depends on the specific format +5. **Validation First**: Run the traceability validator before considering the specification complete \ No newline at end of file diff --git a/skills/specification-architect/scripts/traceability_validator.py b/skills/specification-architect/scripts/traceability_validator.py new file mode 100644 index 0000000..ea3d64c --- /dev/null +++ b/skills/specification-architect/scripts/traceability_validator.py @@ -0,0 +1,340 @@ +#!/usr/bin/env python3 +""" +Traceability validator for specification architect skill. +Validates that all requirements are covered by implementation tasks. +""" + +import re +import sys +from pathlib import Path +from typing import Dict, List, Tuple, Set + +class TraceabilityValidator: + def __init__(self, base_path: str): + self.base_path = Path(base_path) + self.requirements = {} + self.tasks = [] + self.research_citations = {} + + def parse_requirements(self, requirements_file: str) -> Dict: + """Parse requirements.md to extract requirements and acceptance criteria.""" + req_file = self.base_path / requirements_file + if not req_file.exists(): + raise FileNotFoundError(f"Requirements file not found: {requirements_file}") + + content = req_file.read_text(encoding='utf-8') + + # Split content by requirement headers and capture requirement numbers + pattern = r'\n### Requirement (\d+): ([^\n]+)' + matches = list(re.finditer(pattern, content)) + + requirements = {} + + for match in matches: + req_num = match.group(1).strip() + req_title = match.group(2).strip() + + # Find the start and end of this requirement section + start_pos = match.start() + end_pos = content.find('\n### Requirement', start_pos + 1) + if end_pos == -1: + end_pos = len(content) + + # Extract this requirement's content + section_content = content[start_pos:end_pos] + + # Find acceptance criteria within this section + ac_match = re.search(r'#### Acceptance Criteria\n(.*?)(?=\n###|\n##|\Z)', section_content, re.DOTALL) + if not ac_match: + continue + + ac_text = ac_match.group(1).strip() + + + # Parse acceptance criteria + requirements[req_num] = { + "title": req_title, + "acceptance_criteria": {} + } + + ac_pattern = r"(\d+)\.\s+(.+)" + ac_matches = re.findall(ac_pattern, ac_text) + for ac_num, ac_text in ac_matches: + requirements[req_num]["acceptance_criteria"][f"{req_num}.{ac_num}"] = ac_text.strip() + + self.requirements = requirements + return requirements + + def parse_tasks(self, tasks_file: str) -> List[Dict]: + """Parse tasks.md to extract tasks and their requirement references.""" + task_file = self.base_path / tasks_file + if not task_file.exists(): + raise FileNotFoundError(f"Tasks file not found: {tasks_file}") + + content = task_file.read_text(encoding='utf-8') + + # Parse tasks and requirement references + task_pattern = r"- \[ \] (\d+).+?_Requirements: (.+?)_" + matches = re.findall(task_pattern, content, re.MULTILINE | re.DOTALL) + + tasks = [] + for task_num, req_refs in matches: + # Parse requirement references + req_refs = [ref.strip() for ref in req_refs.split(",")] + tasks.append({ + "task_id": task_num, + "requirement_references": req_refs + }) + + self.tasks = tasks + return tasks + + def validate_traceability(self) -> Tuple[Dict, List[str], List[str]]: + """Validate that all requirements are covered by tasks.""" + all_criteria = set() + for req_num, req_data in self.requirements.items(): + for ac_ref in req_data["acceptance_criteria"]: + all_criteria.add(ac_ref) + + covered_criteria = set() + invalid_references = set() + + for task in self.tasks: + for req_ref in task["requirement_references"]: + if req_ref in all_criteria: + covered_criteria.add(req_ref) + else: + invalid_references.add(req_ref) + + missing_criteria = all_criteria - covered_criteria + + return { + "total_criteria": len(all_criteria), + "covered_criteria": len(covered_criteria), + "coverage_percentage": (len(covered_criteria) / len(all_criteria) * 100) if all_criteria else 100 + }, list(missing_criteria), list(invalid_references) + + def validate_research_evidence(self, research_file: str = "example_research.md") -> Dict: + """Validate research document for proper citations and evidence.""" + research_path = self.base_path / research_file + if not research_path.exists(): + return {"valid": False, "error": f"Research file not found: {research_file}"} + + content = research_path.read_text(encoding='utf-8') + + validation_results = { + "valid": True, + "citation_errors": [], + "missing_sources": [], + "uncited_claims": [], + "total_sources": 0, + "total_citations": 0 + } + + # Extract source list (## 3. Browsed Sources section) + source_pattern = r'## 3\. Browsed Sources\n(.*?)(?=\n##|\Z)' + source_match = re.search(source_pattern, content, re.DOTALL) + + if not source_match: + validation_results["valid"] = False + validation_results["citation_errors"].append("Missing 'Browsed Sources' section") + return validation_results + + sources_text = source_match.group(1) + source_lines = [line.strip() for line in sources_text.split('\n') if line.strip()] + + # Extract source URLs and indices + sources = {} + for line in source_lines: + source_match = re.match(r'- \[(\d+)\] (https?://\S+)', line) + if source_match: + index = source_match.group(1) + url = source_match.group(2) + sources[index] = url + + validation_results["total_sources"] = len(sources) + + # Check for citations in rationale section + rationale_pattern = r'\| \*\*(.+?)\*\* \| (.+?) \|' + rationale_matches = re.findall(rationale_pattern, content, re.DOTALL) + + total_citations = 0 + for technology, rationale in rationale_matches: + # Find all citations in rationale + citations = re.findall(r'\[cite:(\d+)\]', rationale) + total_citations += len(citations) + + # Check each citation has corresponding source + for citation in citations: + if citation not in sources: + validation_results["citation_errors"].append(f"Citation [cite:{citation}] references non-existent source") + validation_results["valid"] = False + + validation_results["total_citations"] = total_citations + + # Check for factual claims without citations (simplified detection) + # Look for sentences with specific numbers, percentages, or strong claims + factual_claims = re.findall(r'[^.!?]*\d+(?:\.\d+)?%?[^.!?]*\.|[^.!?]*?(excellent|proven|ideal|best|optimal)[^.!?]*\.', content) + + for claim in factual_claims: + if not re.search(r'\[cite:\d+\]', claim): + validation_results["uncited_claims"].append(claim.strip()) + + # Validate that we have both sources and citations + if len(sources) == 0: + validation_results["valid"] = False + validation_results["citation_errors"].append("No sources found in research document") + + if total_citations == 0: + validation_results["valid"] = False + validation_results["citation_errors"].append("No citations found in technology rationales") + + # Check citation to source ratio (should have reasonable coverage) + if total_citations < len(sources): + validation_results["citation_errors"].append(f"Too few citations ({total_citations}) for number of sources ({len(sources)})") + + return validation_results + + def generate_validation_report(self, requirements_file: str = "requirements.md", + tasks_file: str = "tasks.md", + research_file: str = "example_research.md") -> str: + """Generate a complete validation report.""" + + self.parse_requirements(requirements_file) + self.parse_tasks(tasks_file) + + validation_result, missing, invalid = self.validate_traceability() + research_validation = self.validate_research_evidence(research_file) + + report = f"""# Validation Report + +## 1. Requirements to Tasks Traceability Matrix + +| Requirement | Acceptance Criterion | Implementing Task(s) | Status | +|---|---|---|---|""" + + # Generate traceability matrix + for req_num, req_data in self.requirements.items(): + for ac_ref, ac_text in req_data["acceptance_criteria"].items(): + # Find tasks implementing this criterion + implementing_tasks = [] + for task in self.tasks: + if ac_ref in task["requirement_references"]: + implementing_tasks.append(f"Task {task['task_id']}") + + status = "Covered" if implementing_tasks else "Missing" + tasks_str = ", ".join(implementing_tasks) if implementing_tasks else "None" + + report += f"\n| {req_num} | {ac_ref} | {tasks_str} | {status} |" + + report += f""" + +## 2. Coverage Analysis + +### Summary +- **Total Acceptance Criteria**: {validation_result['total_criteria']} +- **Criteria Covered by Tasks**: {validation_result['covered_criteria']} +- **Coverage Percentage**: {validation_result['coverage_percentage']:.1f}% + +### Detailed Status +- **Covered Criteria**: {[ref for ref in self._get_all_criteria() if ref in self._get_covered_criteria()]} +- **Missing Criteria**: {missing if missing else 'None'} +- **Invalid References**: {invalid if invalid else 'None'} + +## 3. Research Evidence Validation + +### Summary +- **Total Sources**: {research_validation['total_sources']} +- **Total Citations**: {research_validation['total_citations']} +- **Research Validation**: {'PASSED' if research_validation['valid'] else 'FAILED'} + +### Evidence Quality +- **Citation Errors**: {len(research_validation['citation_errors'])} +- **Uncited Claims**: {len(research_validation['uncited_claims'])} +""" + + if research_validation['citation_errors']: + report += "\n#### Citation Issues:\n" + for error in research_validation['citation_errors']: + report += f"- {error}\n" + + if research_validation['uncited_claims']: + report += "\n#### Uncited Factual Claims:\n" + for claim in research_validation['uncited_claims'][:5]: # Limit to first 5 + report += f"- {claim}\n" + if len(research_validation['uncited_claims']) > 5: + report += f"- ... and {len(research_validation['uncited_claims']) - 5} more\n" + + report += """ + +## 4. Final Validation +""" + + requirements_valid = validation_result['coverage_percentage'] == 100 and not invalid + research_valid = research_validation['valid'] + + if requirements_valid and research_valid: + report += f"[PASS] **VALIDATION PASSED**\n\nAll {validation_result['total_criteria']} acceptance criteria are fully traced to implementation tasks AND all research claims are properly cited with verifiable sources. The plan is validated and ready for execution." + elif not requirements_valid and research_valid: + report += f"[FAIL] **VALIDATION FAILED** - Requirements Issues\n\n{len(missing)} criteria not covered, {len(invalid)} invalid references. Research evidence is properly cited, but requirements traceability needs attention." + elif requirements_valid and not research_valid: + report += f"[FAIL] **VALIDATION FAILED** - Research Evidence Issues\n\nRequirements traceability is complete, but research evidence has {len(research_validation['citation_errors'])} citation errors and {len(research_validation['uncited_claims'])} uncited claims. This violates the evidence-based protocol and prevents professional use." + else: + report += f"[FAIL] **VALIDATION FAILED** - Multiple Issues\n\nRequirements: {len(missing)} criteria not covered, {len(invalid)} invalid references. Research: {len(research_validation['citation_errors'])} citation errors, {len(research_validation['uncited_claims'])} uncited claims." + + return report + + def _get_all_criteria(self) -> Set[str]: + """Get all acceptance criteria references.""" + all_criteria = set() + for req_num, req_data in self.requirements.items(): + for ac_ref in req_data["acceptance_criteria"]: + all_criteria.add(ac_ref) + return all_criteria + + def _get_covered_criteria(self) -> Set[str]: + """Get all covered acceptance criteria references.""" + covered_criteria = set() + all_criteria = self._get_all_criteria() + + for task in self.tasks: + for req_ref in task["requirement_references"]: + if req_ref in all_criteria: + covered_criteria.add(req_ref) + + return covered_criteria + +if __name__ == "__main__": + import argparse + + parser = argparse.ArgumentParser(description="Validate specification architect traceability") + parser.add_argument("--path", default=".", help="Base path containing specification files") + parser.add_argument("--requirements", default="requirements.md", help="Requirements file name") + parser.add_argument("--tasks", default="tasks.md", help="Tasks file name") + parser.add_argument("--research", default="example_research.md", help="Research file name") + + args = parser.parse_args() + + try: + validator = TraceabilityValidator(args.path) + report = validator.generate_validation_report(args.requirements, args.tasks, args.research) + print(report) + + # Exit with error code if validation fails + validation_result, missing, invalid = validator.validate_traceability() + research_validation = validator.validate_research_evidence(args.research) + + requirements_valid = validation_result['coverage_percentage'] == 100 and not invalid + research_valid = research_validation['valid'] + + if not requirements_valid or not research_valid: + sys.exit(1) + else: + sys.exit(0) + + except FileNotFoundError as e: + print(f"Error: {e}") + sys.exit(1) + except Exception as e: + print(f"Unexpected error: {e}") + sys.exit(1) \ No newline at end of file diff --git a/skills/specification-architect/validate.bat b/skills/specification-architect/validate.bat new file mode 100644 index 0000000..b933396 --- /dev/null +++ b/skills/specification-architect/validate.bat @@ -0,0 +1,24 @@ +@echo off +REM Specification Architect Validation Helper + +setlocal enabledelayedexpansion +set SCRIPT_DIR=%~dp0 +set SPEC_DIR=. +set VERBOSE= +set GENERATE= + +:parse_args +if "%1"=="" goto run +if "%1"=="-p" (set SPEC_DIR=%2 & shift & shift & goto parse_args) +if "%1"=="--path" (set SPEC_DIR=%2 & shift & shift & goto parse_args) +if "%1"=="-v" (set VERBOSE=--verbose & shift & goto parse_args) +if "%1"=="--verbose" (set VERBOSE=--verbose & shift & goto parse_args) +if "%1"=="-g" (set GENERATE=--generate-validation & shift & goto parse_args) +if "%1"=="--generate" (set GENERATE=--generate-validation & shift & goto parse_args) +shift +goto parse_args + +:run +echo Running specification validation... +python "%SCRIPT_DIR%validate_specifications.py" --path "%SPEC_DIR%" %VERBOSE% %GENERATE% +exit /b %ERRORLEVEL% diff --git a/skills/specification-architect/validate.sh b/skills/specification-architect/validate.sh new file mode 100644 index 0000000..9b8d298 --- /dev/null +++ b/skills/specification-architect/validate.sh @@ -0,0 +1,38 @@ +#!/bin/bash +# Specification Architect Validation Helper + +SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" +SPEC_DIR="." +VERBOSE="" +GENERATE="" + +while [[ $# -gt 0 ]]; do + case $1 in + -p|--path) + SPEC_DIR="$2" + shift 2 + ;; + -v|--verbose) + VERBOSE="--verbose" + shift + ;; + -g|--generate) + GENERATE="--generate-validation" + shift + ;; + -h|--help) + echo "Usage: ./validate.sh [options]" + echo "Options:" + echo " -p, --path DIR Path to spec directory" + echo " -v, --verbose Verbose output" + echo " -g, --generate Generate validation.md" + exit 0 + ;; + *) + shift + ;; + esac +done + +python3 "$SCRIPT_DIR/validate_specifications.py" --path "$SPEC_DIR" $VERBOSE $GENERATE +exit $? diff --git a/skills/specification-architect/validate_specifications.py b/skills/specification-architect/validate_specifications.py new file mode 100644 index 0000000..e23ac26 --- /dev/null +++ b/skills/specification-architect/validate_specifications.py @@ -0,0 +1,164 @@ +#!/usr/bin/env python3 +"""Specification Architect Validation Script""" +import re, sys, json, argparse +from pathlib import Path +from dataclasses import dataclass, field +from typing import Dict, Set, List + +@dataclass +class Result: + total: int = 0 + covered: Set[str] = field(default_factory=set) + missing: Set[str] = field(default_factory=set) + coverage: float = 0.0 + valid: bool = False + errors: List[str] = field(default_factory=list) + +class Validator: + def __init__(self, spec_dir: str, verbose=False): + self.dir = Path(spec_dir) + self.verbose = verbose + self.result = Result() + self.components = set() + self.requirements = {} + self.task_reqs = set() + + def log(self, msg, level="INFO"): + if self.verbose or level=="ERROR": + print(f"[{level}] {msg}") + + def validate(self) -> Result: + self.log("Starting validation...") + + if not self._files_exist(): + return self.result + if not self._extract_components(): + return self.result + if not self._extract_requirements(): + return self.result + if not self._extract_tasks(): + return self.result + + self._calculate() + self._report() + return self.result + + def _files_exist(self) -> bool: + for name in ["blueprint.md", "requirements.md", "tasks.md"]: + if not (self.dir / name).exists(): + self.result.errors.append(f"Missing: {name}") + return len(self.result.errors) == 0 + + def _extract_components(self) -> bool: + try: + content = (self.dir / "blueprint.md").read_text() + self.components = set(re.findall(r'\|\s*\*\*([A-Za-z0-9_]+)\*\*\s*\|', content)) + if not self.components: + self.log("No components found", "WARNING") + return False + self.log(f"Found {len(self.components)} components") + return True + except Exception as e: + self.log(f"Error: {e}", "ERROR") + return False + + def _extract_requirements(self) -> bool: + try: + content = (self.dir / "requirements.md").read_text() + for match in re.finditer(r'### Requirement (\d+):', content): + req_num = match.group(1) + start = match.end() + end = len(content) + text = content[start:end] + + criteria = [f"{req_num}.{c}" for c, _ in re.findall( + r'(\d+)\.\s+WHEN.*?THE\s+\*\*([A-Za-z0-9_]+)\*\*\s+SHALL', + text, re.DOTALL)] + if criteria: + self.requirements[req_num] = criteria + + self.result.total = sum(len(v) for v in self.requirements.values()) + self.log(f"Found {self.result.total} criteria") + return self.result.total > 0 + except Exception as e: + self.log(f"Error: {e}", "ERROR") + return False + + def _extract_tasks(self) -> bool: + try: + content = (self.dir / "tasks.md").read_text() + for match in re.findall(r'_Requirements:\s*([\d., ]+)_', content): + for c in match.split(','): + self.task_reqs.add(c.strip()) + if not self.task_reqs: + self.log("No requirement tags found", "WARNING") + return False + self.log(f"Found {len(self.task_reqs)} covered criteria") + return True + except Exception as e: + self.log(f"Error: {e}", "ERROR") + return False + + def _calculate(self): + all_crit = set() + for crit_list in self.requirements.values(): + all_crit.update(crit_list) + + self.result.covered = self.task_reqs & all_crit + self.result.missing = all_crit - self.task_reqs + + if all_crit: + self.result.coverage = (len(self.result.covered) / len(all_crit)) * 100 + + self.result.valid = self.result.coverage == 100.0 + + def _report(self): + print("\n" + "="*80) + print("SPECIFICATION VALIDATION REPORT") + print("="*80 + "\n") + + print("SUMMARY") + print("-"*80) + print(f"Total Criteria: {self.result.total}") + print(f"Covered by Tasks: {len(self.result.covered)}") + print(f"Coverage: {self.result.coverage:.1f}%\n") + + if self.result.missing: + print("MISSING CRITERIA") + print("-"*80) + for c in sorted(self.result.missing, key=lambda x: tuple(map(int, x.split('.')))): + print(f" - {c}") + print() + + print("VALIDATION STATUS") + print("-"*80) + if self.result.valid: + print("✅ PASSED - All criteria covered\n") + else: + print(f"❌ FAILED - {len(self.result.missing)} uncovered\n") + + print("="*80 + "\n") + +def main(): + parser = argparse.ArgumentParser(description="Validate specifications") + parser.add_argument("--path", default=".", help="Spec directory") + parser.add_argument("--verbose", action="store_true", help="Verbose") + parser.add_argument("--json", action="store_true", help="JSON output") + args = parser.parse_args() + + v = Validator(args.path, args.verbose) + result = v.validate() + + if args.json: + print(json.dumps({ + "total": result.total, + "covered": len(result.covered), + "missing": list(result.missing), + "coverage": result.coverage, + "valid": result.valid, + }, indent=2)) + + sys.exit(0 if result.valid else 1) + +if __name__ == "__main__": + main()