review-os

name	review-os
description	Audit a generated OS repository for completeness, consistency, and architectural integrity against the 8 design principles.

/review-os - OS Architecture Audit

When to Use

• After /generate-os produces the OS repository
• When the designer wants to verify the OS is complete and consistent
• Before deploying the OS for real use

Inputs

• Required: A generated OS at output/[domain]-os/
• CRITICAL: reference/BLUEPRINT.md (master specification — the OS is audited against this)
• Auto-loaded: ALL domain-input/ files (as the spec to audit against)
• Auto-loaded: reference/architecture-patterns.md (the principles to verify)

Process

Audit 1: Structural Completeness

Check that all expected files exist:

[ ] CLAUDE.md exists and is non-empty
[ ] README.md exists
[ ] START-HERE.md exists with time estimates
[ ] .claude/skills/ has [N] skill folders (match skill-designs.md count)
[ ] Each skill folder has SKILL.md
[ ] sub-agents/ has [N] files (match sub-agent-designs.md count)
[ ] context-library/ has [N] template files (match identity-model.md count)
[ ] cowork-tasks/ has briefing files
[ ] setup/ has installation guide and checklist
[ ] insider-data/ has at minimum an index.md

Audit 2: Kernel Integrity

Read CLAUDE.md and verify:

[ ] Core philosophy present (3-5 rules)
[ ] Context awareness lists ALL context-library files
[ ] Skills table lists ALL skills with correct /commands
[ ] Sub-agents table lists ALL sub-agents
[ ] Auto-behaviors section lists ALL trigger chains
[ ] Verification rules present and specific
[ ] Empty context detection covers ALL context dependencies
[ ] Writing style section present
[ ] Non-negotiable rule appears early and in bold
[ ] Getting started section present

Audit 3: Skill Consistency

For each SKILL.md:

[ ] Frontmatter has name and description
[ ] "When to Use" section present
[ ] Inputs list auto-loaded files that exist in context-library/
[ ] Process is step-by-step (not a vague description)
[ ] Output format is a concrete template
[ ] Quality checks have "good" AND "bad" examples
[ ] Empty context behavior defined for all required files
[ ] Auto-triggers match what CLAUDE.md declares (dual declaration check)

Audit 4: Sub-Agent Adversarial Check

For each sub-agent:

[ ] Has a vivid persona (not generic "reviewer")
[ ] Triggers after a specific creation skill
[ ] Scoring dimensions DIFFER from the creation skill's process
[ ] "Good review" and "bad review" criteria defined
[ ] Output format includes specific scoring and actionable fixes

Critical check: For each sub-agent, answer: "What does this reviewer catch that the creation skill would miss?" If the answer is unclear, the sub-agent needs redesign.

Audit 5: Loop Integrity

For each feedback loop:

[ ] Data producer skill exists and writes to a real file
[ ] Data consumer skill exists and reads from the same file
[ ] Degradation behavior defined for 0, 1-2, 3-9, 10+ data points
[ ] Retro skill reads from all accumulating files
[ ] Briefing evolves as data accumulates

Audit 6: Blueprint Conformance (BLUEPRINT.md Sections 2-8)

Read reference/BLUEPRINT.md and verify each requirement:

Component Map (Section 2): Every component type exists:

[ ] CLAUDE.md (Kernel)
[ ] context-library/ (State / User Memory) — 4-7 files
[ ] .claude/skills/ (Capabilities / Verbs) — 8-18 skills
[ ] sub-agents/ (Quality Gates / Review Lenses) — 2-4 reviewers
[ ] insider-data/ (Reference Knowledge / Read-Only)
[ ] cowork-tasks/ (Automation / Cron) — 2-3 part briefing
[ ] templates/ (Scaffolding)
[ ] setup/ (Onboarding)
[ ] [output-folder]/ (Logs — persistent, feeds back in)

Orchestration (Section 4):

[ ] Trigger chains documented for every creation skill (Section 4a)
[ ] Connector map: every context file has its readers/writers listed (Section 4b)
[ ] At least 2 compounding loops fully wired (Section 4c)
[ ] Dual declaration: every auto-behavior in BOTH kernel AND skill (Section 4d)

Interdependencies (Section 5):

[ ] Dependency table exists in kernel — maps what breaks when each file is empty
[ ] Foundation file is identified as deliberate single point of failure

Generation Checklist (Section 8) — all 15 items:

[ ] 1. One kernel file
[ ] 2. User state externalized
[ ] 3. Skills are stateless pure functions
[ ] 4. Every generation skill has adversarial reviewer
[ ] 5. One zero-setup entry point
[ ] 6. Auto-behaviors dual-declared
[ ] 7. Verification mandatory per skill
[ ] 8. Compounding loops exist
[ ] 9. Persona-conditional branching
[ ] 10. Graceful degradation
[ ] 11. Function-adaptive markers
[ ] 12. Scheduled automation
[ ] 13. Dependency table in kernel
[ ] 14. Connector map documented
[ ] 15. Trigger chains documented
[ ] 16. Two-system boundary enforced (factory → Layer 1 + onboarding machinery; OS → Layer 2 at runtime)

Two-System Boundary Check:

[ ] No skill contains hardcoded user data (names, companies, personal details)
[ ] No context-library file contains skill logic or domain frameworks
[ ] All context-library files ship as empty templates with placeholder examples
[ ] Every skill reads user identity from context-library at runtime
[ ] domain-input/ content (factory designer's input) does NOT leak into the generated OS
[ ] No references to agent-os-factory, domain-input/, or reference/ anywhere in the OS
[ ] The OS has its own onboarding: START-HERE.md, setup/, empty-context messages in skills
[ ] The OS's empty-context detection guides users through filling context-library without external help

Verify each of the 8 design principles (Section 6):

1. Separation of identity from capability:

   • Context-library files contain no skill logic
   • Skills contain no hardcoded user data

2. Generation ≠ evaluation:

   • Every creation skill has a corresponding reviewer
   • No skill both creates and reviews its own output

3. Declarative orchestration:

   • Auto-behaviors declared in CLAUDE.md
   • Same auto-behaviors declared in triggering skills
   • No programmatic orchestration needed

4. State in flat files:

   • All persistent state is in context-library/ or output folder
   • No state depends on conversation history

5. Compounding feedback loops:

   • At least one loop identified and fully wired
   • Retro skill exists and reads accumulated data

6. Graceful degradation:

   • Every skill handles empty context
   • At least one zero-setup entry point exists
   • Stale data has freshness thresholds

7. Function-adaptive markers:

   • Skills adapt to persona variants (if applicable)
   • Scoring weights shift by context (if applicable)

8. Zero-setup entry point:

   • At least one skill works with no context files
   • That skill delivers value and leads to setup

Audit 7: Cross-Reference Check

Verify no broken references:

[ ] Every file path in CLAUDE.md points to a real file
[ ] Every "auto-loaded" reference in skills points to a real context file
[ ] Every sub-agent trigger references a real skill
[ ] Every auto-behavior's target skill exists
[ ] Briefing references correct file paths for output

Output

# OS Architecture Audit - [Domain] OS

## Summary
- Files checked: [N]
- Issues found: [N] critical, [N] warnings
- Architectural principles: [N]/8 verified

## Critical Issues (must fix)
1. [Issue]: [where] — [what's wrong] — [how to fix]
2. ...

## Warnings (should fix)
1. [Issue]: [where] — [what's wrong] — [how to fix]
2. ...

## Verified
- [list of all checks that passed]

## Recommendation
[READY TO DEPLOY / FIX CRITICAL ISSUES FIRST / NEEDS SIGNIFICANT REWORK]

After the audit, offer to fix any issues found:

• Critical issues: fix automatically
• Warnings: describe the fix and ask if the designer wants it applied
• If READY TO DEPLOY: congratulate and suggest the designer copy the output folder

Quality Checks

Good audit:

• Every check produces a specific pass/fail, not a vague assessment
• Critical issues have specific fix instructions
• Cross-reference check catches broken file paths
• Adversarial check for each sub-agent produces a clear answer

Bad audit:

• Rubber stamp ("everything looks good")
• Vague findings ("some skills could be more detailed")
• Missing cross-reference check (the most common source of bugs)
• Doesn't verify dual declaration of auto-behaviors