- Claude Code installed and running
Method 1: Using Claude Code Chat Interface
Inside Claude Code's chat, run these commands:
/plugin marketplace add adrianpuiu/specification-document-generator
/plugin install architecture-skills@specification-document-generator
Method 2: Using Terminal/CLI
In your terminal, run:
claude plugin marketplace add adrianpuiu/specification-document-generator
claude plugin install architecture-skills@specification-document-generatorWhat this does:
- Claude Code fetches
.claude-plugin/marketplace.jsonfrom this GitHub repository - Discovers the
architecture-skillsplugin (which includes thespecification-architectskill) - Installs the plugin and makes all skills available in your session
Option 2: Install from Central Skills Marketplace
Claude Code chat:
/plugin marketplace add adrianpuiu/claude-skills-marketplace
/plugin install architecture-skills@claude-skills-marketplace
Terminal:
claude plugin marketplace add adrianpuiu/claude-skills-marketplace
claude plugin install architecture-skills@claude-skills-marketplaceOption 3: Local Development Installation
Clone the repository:
git clone https://github.com/adrianpuiu/specification-document-generator.git
cd specification-document-generatorThen install via CLI:
claude plugin marketplace add adrianpuiu/specification-document-generator
claude plugin install architecture-skills@specification-document-generatorOr via Claude Code chat:
/plugin marketplace add /absolute/path/to/specification-document-generator
/plugin install architecture-skills@specification-document-generator
Claude Code chat:
/plugin list
Terminal:
claude plugin listYou should see architecture-skills in the list of installed plugins.
Once installed, you can use the specification-architect skill in Claude Code. Simply provide your project requirements and the skill will guide you through the 6-phase documentation generation process.
A rigorous, evidence-based system that generates six interconnected architectural documents while eliminating "research slop" and preventing AI-generated misinformation. Every technological decision is backed by verifiable sources with complete traceability from research through implementation.
The Problem: AI generates content that is polished, articulate, and inspires "faith-like confidence," yet is often unverified and factually incorrect. This has led to:
- Legal sanctions for law firms submitting fabricated citations
- Financial penalties for consulting firms providing incorrect statistics
- Professional ruin from relying on plausible-sounding falsehoods
Our Solution: Mandatory verification protocol that transforms AI from "confident author" to "diligent research assistant" with auditable evidence trails.
The quality of your architectural specification is directly proportional to the verifiability of your research evidence.
- Phase 0: 🔍 Verifiable Research (Mandatory Web Search + Browsing + Citations)
- Phase 1: Architectural Blueprint (Evidence-Based Component Mapping)
- Phase 2: Requirements Generation (Research-Backed Acceptance Criteria)
- Phase 3: Detailed Design (Source-Validated Specifications)
- Phase 4: Task Decomposition (Traceable Implementation Plan)
- Phase 5: Validation & Traceability (100% Coverage + Evidence Verification)
"I need to architect an inventory management system for a growing e-commerce business.
The system must handle 50,000 SKUs, integrate with our existing Shopify store,
and provide real-time stock updates. We need barcode scanning, low-stock alerts,
and supplier management. Please do NOT include POS functionality or customer-facing
features. Our team uses Node.js/React and we need cloud deployment with automatic backups."
✅ Clear Business Context: E-commerce inventory management ✅ Specific Constraints: 50,000 SKUs, Shopify integration, real-time updates ✅ Technology Stack: Node.js/React, cloud deployment ✅ Clear Scope Boundaries: No POS, no customer-facing features ✅ Success Metrics: Barcode scanning, stock alerts, supplier management
🎯 Clear Component Boundaries: Each service has single responsibility 🎯 Explicit Data Flow: Complete journey from barcode scan to inventory update 🎯 Defined Integration Points: Shopify API, backup systems, cloud infrastructure 🎯 Traceable Requirements: Every feature traced to implementation tasks 🎯 No Scope Creep: Clear boundaries prevent "feature additions"
- research.md - Web search findings, technology comparison, stack selection (NEW!)
- blueprint.md - Component mapping, data flow diagrams, integration points
- requirements.md - Testable acceptance criteria with component assignments
- design.md - Detailed component specifications and interfaces
- tasks.md - Implementation plan with requirement traceability
- validation.md - Automated validation confirming 100% coverage
- 🚫 Research Slop Prevention: Mandatory verification eliminates AI-generated misinformation
- 🔍 Evidence-Based Research: Every claim supported by browsed sources with citations
- 📋 Citation Protocol: Strict
[cite:INDEX]format creates auditable evidence trails - 🛡️ Professional Standards: Prevents legal sanctions, financial penalties, and professional ruin
- Automated Validation: Python script ensures 100% requirements coverage + evidence verification
- Source Verification: Mandatory browsing of sources, not just search snippets
- Template Enforcement: Guarantees consistency and completeness
- Component Consistency: Exact name matching across all documents
- Traceability Matrix: Complete mapping from requirements to tasks
- Quality Gates: Sequential approval process with evidence verification
CRITICAL: This phase prevents the exact types of AI errors that cause legal sanctions and professional ruin.
- Search THEN Browse: Use WebSearch to find sources, then WebFetch to read actual content
- NO Search Snippets: You MUST read full source content, not just search results
- Cite Every Claim: Every factual statement MUST end with
[cite:INDEX]citation - Evidence-Based Decisions: Technology choices only from verified sources
- Auditable Trail: Complete citation trail from claim to source
❌ Research Slop: "Node.js is great for real-time apps" ✅ Evidence-Based: "Node.js excels at real-time applications due to its event-driven, non-blocking I/O model [cite:1]"
❌ Research Slop: "TypeScript reduces errors" ✅ Evidence-Based: "TypeScript adds static typing that reduces runtime errors by approximately 15% in large codebases [cite:2]"
This protocol prevents the types of errors that have led to:
- Legal sanctions for law firms (fabricated citations)
- Financial penalties for consulting firms (incorrect statistics)
- Professional ruin from AI-generated misinformation
Never skip Phase 0! Web research ensures:
- Current best practices and patterns
- Proven technology stacks
- Industry-specific considerations
- Avoidance of outdated approaches
Each component must have a single, well-defined responsibility. If you find yourself saying "and also," split into multiple components.
Map how data moves through the system from input to output. The Mermaid diagram should show the complete journey.
Clearly define all APIs, protocols, and external system connections. Specify data formats, authentication, and error handling.
Explicitly define what's in scope vs. out of scope to prevent scope creep and enable accurate estimation.
- Provide Clear Requirements: Include business objectives, constraints, and scope boundaries
- Follow Sequential Phases: Each phase builds upon the previous one
- Review Quality Gates: Ensure each phase meets quality criteria before proceeding
- Validate Traceability: Use the automated validator to confirm complete coverage
Validation Report:
- Total Acceptance Criteria: 28
- Criteria Covered by Tasks: 28
- Coverage Percentage: 100%
- Invalid References: 0
✅ Plan validated and ready for execution
Clear upfront goals + structured methodology = high-quality architectural specifications
This skill transforms vague project ideas into concrete, implementable plans with guaranteed traceability from business requirements to implementation tasks.
"The best architectural plans come from the clearest upfront thinking."