agentleFS
davidmatousekdavidmatousek/tachi/.claude/skills/~aod-project-plan/SKILL.md

~aod-project-plan

Skill95 starsChanged 37 days agoApache-2.0View on GitHub

Validates architecture documentation completeness by checking for technology stack, API specifications, database schema, security architecture, and alignment with feature specification. Use this skill when you need to check if plan.md is complete before implementation, validate architecture documentation, or review technical plans for completeness.

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 15 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈15

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Search for specs/*/plan.md files

    line 16
  2. Distinctive:

    If specific feature directory provided, validate that plan.md

    line 17
  3. Distinctive:

    Check for mandatory sections per AOD plan template:

    line 22
  4. Distinctive:

    All 7 constitutional principles validated

    line 36
  5. Distinctive:

    Verify technical decisions are documented:

    line 53
  6. Distinctive:

    Check all functional requirements addressed

    line 61
  7. Distinctive:

    Verify success criteria have implementation strategy

    line 62
  8. Distinctive:

    Ensure out-of-scope items respected

    line 63
  9. Distinctive:

    Verify security considerations documented:

    line 67
  10. Distinctive:

    Check constitution compliance (7/7 pass)

    line 117
  11. Distinctive:

    Verify design artifacts exist (data-model.md, contracts/)

    line 118
  12. Distinctive:

    No performance targets specified

    line 149
  13. Distinctive:

    Grep: Search for required section headers and keywords

    line 196
  14. Distinctive:

    data-model.md: Check entity definitions

    line 207
  15. Distinctive:

    contracts/: Verify API specifications

    line 208
  16. Distinctive:

    Read-Only: No modifications, only validation

    line 241

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

# 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

RationalizationReality
"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).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.