~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.
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ~aod-blueprintSkill
- ~aod-bugfixSkill
- ~aod-buildSkill
- ~aod-defineSkill
- ~aod-deliverSkill
- ~aod-discoverSkill
- aod-foundationSkill
- ~aod-kickstartSkill
- aod-lensSkill
- aod-orchestrateSkill
- ~aod-planSkill
- ~aod-runSkill
- ~aod-scoreSkill
- ~aod-specSkill
- aod-stackSkill
- ~aod-statusSkill
- code-execution-helperSkill
- git-workflow-helperSkill
- kb-createSkill
- kb-querySkill
- root-cause-analyzerSkill
- securitySkill
- tachi-control-analysisSkill
- tachi-infographicsSkill
- tachi-orchestrationSkill
- tachi-report-assemblySkill
- tachi-risk-scoringSkill
- tachi-sharedSkill
- tachi-threat-reportingSkill
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
- Very specific: line 16
Search for specs/*/plan.md files
- Distinctive: line 17
If specific feature directory provided, validate that plan.md
- Distinctive: line 22
Check for mandatory sections per AOD plan template:
- Distinctive: line 36
All 7 constitutional principles validated
- Distinctive: line 53
Verify technical decisions are documented:
- Distinctive: line 61
Check all functional requirements addressed
- Distinctive: line 62
Verify success criteria have implementation strategy
- Distinctive: line 63
Ensure out-of-scope items respected
- Distinctive: line 67
Verify security considerations documented:
- Distinctive: line 117
Check constitution compliance (7/7 pass)
- Distinctive: line 118
Verify design artifacts exist (data-model.md, contracts/)
- Distinctive: line 149
No performance targets specified
- Distinctive: line 196
Grep: Search for required section headers and keywords
- Distinctive: line 207
data-model.md: Check entity definitions
- Distinctive: line 208
contracts/: Verify API specifications
- Distinctive: line 241
Read-Only: No modifications, only validation
≈ “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.
Files
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.mdfiles - 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:
- Read
specs/005-create-a-specification/plan.md - Validate all required sections present
- Check constitution compliance (7/7 pass)
- Verify design artifacts exist (data-model.md, contracts/)
- 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:
- Read
specs/004-feature/plan.md - Missing security architecture section
- Constitution check incomplete (missing principle VI)
- 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 diagramsIntegration
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
| 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.taskswhile 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).
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
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.

