~aod-project-plan

# 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 /aod.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

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

---

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "Architect can sign off later — PM approval is what matters" | plan.md requires both PM AND Architect sign-off (CLAUDE.md governance); Architect-pending blocks `/aod.tasks`. |
| "Constitution Check is boilerplate, I'll just write 'pass' for all 7" | Step 2 (line 38) requires evidence per principle; Example 2 NOT READY shows missing evidence on Principle VI fails. |
| "Security architecture lives in code review, not the plan" | Step 5 (line 65) requires auth, authz, secrets, and API security documented; absence returns NOT READY. |
| "data-model.md is overkill for this feature" | Step 3 (line 53) treats data-model.md as a design artifact; missing entities show in the report's Design Artifacts row. |
| "Spec alignment is implicit if the plan addresses the feature" | Step 4 (line 58) cross-checks every spec FR against plan; unaddressed FRs flag a quality-check failure. |

## Red Flags

- Agent reports READY without confirming all 7 constitutional principles per Step 2 Constitution Check.
- Agent skips Step 5 Security Architecture review because "no user-facing auth in this feature."
- Agent's report omits the Design Artifacts block (data-model.md, contracts/, research.md) defined in Step 6.
- Agent declares dual sign-off complete with only one signoff present in the plan.md frontmatter.
- Agent invokes `/aod.tasks` while plan.md status is NOT READY from Step 6's report.
- Agent fills Constitution Check rows with empty evidence and reports 7/7 pass per Step 2 (line 36).