Architecture Validator Skill

Purpose

Automatically validates architecture documentation (plan.md) for completeness, technical rigor, and alignment with feature specifications. Implements FR-006 from the feature specification.

How It Works

Step 1: Locate Architecture Plan

• •Search for specs/*/plan.md files
• •If specific feature directory provided, validate that plan.md
• •Report if plan.md not found

Step 2: Validate Required Sections

Check for mandatory sections per AOD plan template:

Technical Context (Required)

• •Language/Version
• •Primary Dependencies
• •Storage solution
• •Testing approach
• •Target Platform
• •Project Type
• •Performance Goals
• •Constraints
• •Scale/Scope

Constitution Check (Required)

• •All 7 constitutional principles validated
• •Evidence for each principle
• •Violations justified (if any)

Project Structure (Required)

• •Documentation structure
• •Source code structure
• •File organization

Technology Stack (Required)

• •Languages and versions
• •Frameworks and libraries
• •Database and storage
• •Infrastructure components

Step 3: Check Technical Decisions

Verify technical decisions are documented:

• •data-model.md: Entity definitions and relationships
• •contracts/: API specifications (if applicable)
• •research.md: Technical unknowns resolved

Step 4: Validate Spec Alignment

• •Compare plan.md with spec.md
• •Check all functional requirements addressed
• •Verify success criteria have implementation strategy
• •Ensure out-of-scope items respected

Step 5: Security Architecture Check

Verify security considerations documented:

• •Authentication approach
• •Authorization model
• •Data protection strategy
• •API security measures
• •Secrets management

Step 6: Generate Validation Report

✅ Architecture Validation Report

File: specs/{feature-id}/plan.md

Required Sections:
- [✓/✗] Technical Context
- [✓/✗] Constitution Check (7/7 principles)
- [✓/✗] Project Structure
- [✓/✗] Technology Stack

Design Artifacts:
- [✓/✗] data-model.md (entities defined)
- [✓/✗] contracts/ (API specs)
- [✓/✗] research.md (decisions documented)

Quality Checks:
- [✓/✗] All FRs from spec.md addressed
- [✓/✗] Security architecture documented
- [✓/✗] Performance targets specified
- [✓/✗] Complexity justified

Status: READY / NOT READY

Issues Found:
1. [Issue description]
2. [Issue description]

Recommendations:
- [Specific action to resolve each issue]

Examples

Example 1: Complete Architecture Plan

User Query: "Is my plan complete?"

Skill Actions:

1. •Read specs/005-create-a-specification/plan.md
2. •Validate all required sections present
3. •Check constitution compliance (7/7 pass)
4. •Verify design artifacts exist (data-model.md, contracts/)
5. •Validate spec alignment

Result:

✅ Architecture Validation: READY

File: specs/005-create-a-specification/plan.md

All required sections complete ✓
Constitution check: 7/7 passed ✓
Design artifacts present ✓
Spec alignment validated ✓

Your architecture is ready for /triad.tasks!

Highlights:
- Comprehensive data model (5 entities)
- 10 technical decisions documented
- Security architecture complete
- Performance targets specified (<500ms)

Example 2: Incomplete Architecture

User Query: "Validate architecture"

Skill Actions:

1. •Read specs/004-feature/plan.md
2. •Missing security architecture section
3. •Constitution check incomplete (missing principle VI)
4. •No performance targets specified

Result:

✗ Architecture Validation: NOT READY

Issues Found:
1. Missing Security Architecture section
   - No authentication approach documented
   - No authorization model specified
   - No secrets management strategy

2. Constitution Check incomplete
   - Principle VI (Observability): No evidence provided
   - Need to document root cause analysis approach

3. Performance targets not specified
   - No latency requirements
   - No throughput targets
   - No scalability goals

4. data-model.md missing relationship diagrams
   - Entities defined but relationships unclear

Recommendations:
1. Add Security Architecture section:
   - Document authentication method (JWT, OAuth, etc.)
   - Define authorization model (RBAC, ABAC, etc.)
   - Specify secrets management (env vars, vault, etc.)

2. Complete Constitution Check:
   - Add evidence for Principle VI
   - Document observability and root cause analysis approach

3. Add Performance Goals section:
   - Specify latency targets (e.g., <500ms)
   - Define throughput requirements
   - Document scalability approach

4. Enhance data-model.md with relationship diagrams

Integration

Uses

• •Read: Load plan.md and related design artifacts
• •Grep: Search for required section headers and keywords
• •Glob: Find plan.md and design artifact files
• •TodoWrite: Track architecture issues if revising plan

Updates

• •None (read-only validation)

Cross-References

• •spec.md: Validate alignment with requirements
• •data-model.md: Check entity definitions
• •contracts/: Verify API specifications
• •research.md: Confirm technical decisions
• •.aod/memory/constitution.md: Validate constitutional compliance

Validation Logic

# Check required sections
grep "## Technical Context" plan.md
grep "## Constitution Check" plan.md
grep "## Project Structure" plan.md

# Validate constitution compliance
grep -A 5 "### I\." plan.md  # Defensive Security
grep -A 5 "### II\." plan.md  # Spec-Driven
grep -A 5 "### III\." plan.md  # 3-Step DoD
# ... (continue for all 7 principles)

# Check design artifacts
test -f data-model.md && echo "✓ data-model.md exists"
test -d contracts && echo "✓ contracts/ directory exists"
test -f research.md && echo "✓ research.md exists"

# Validate spec alignment
diff -u <(grep "^- \*\*FR-" spec.md | cut -d: -f1) \
        <(grep "FR-" plan.md | cut -d: -f1)

Constitutional Compliance

• •Specification-Driven: Enforces plan completion before implementation (Principle II)
• •Constitution Validation: Ensures all 7 principles addressed
• •Quality Focus: Prevents incomplete designs from proceeding
• •Read-Only: No modifications, only validation