gh-adrianpuiu-specification-document-generator-architecture-skills/skills/specification-architect

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

# 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

# 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)