# Architecture Validator

> Validates architecture documentation completeness by checking for technology stack, API specifications, database schema, security architecture, and alignment with feature specification. Ensures plan.md is complete before implementation.

- Skill: `majiayu000/architecture-validator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/architecture-validator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/architecture-validator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/architecture-validator

---


# 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 Speckit 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 /speckit.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
- **.specify/memory/constitution.md**: Validate constitutional compliance

## Validation Logic

```bash
# 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