generate-os

name	generate-os
description	Assemble all domain inputs and component designs into a complete, deployable Claude Code agent OS repository.

/generate-os - OS Repository Generation

When to Use

• After all domain-input/ files are filled AND skill, sub-agent, and loop designs exist in output/designs/
• When the designer says "generate the OS" or "build it"

Inputs

• Required: ALL domain-input/ files (domain-workflow, audiences, scoring-rubrics, identity-model, quality-contract, domain-knowledge, feedback-loops)
• Required: output/designs/skill-designs.md
• Required: output/designs/sub-agent-designs.md
• Required: output/designs/loop-designs.md
• CRITICAL: reference/BLUEPRINT.md (master architectural specification — read FIRST, governs all generation)
• Auto-loaded: reference/kernel-anatomy.md (CLAUDE.md template)
• Auto-loaded: reference/skill-anatomy.md (SKILL.md template)
• Auto-loaded: reference/sub-agent-anatomy.md (sub-agent template)
• Auto-loaded: reference/architecture-patterns.md (design principles)

Pre-Flight Check

Before generating, verify all inputs exist and are substantive:

Checking domain-input/:
  ✓/✗ domain-workflow.md — [filled / empty / partial]
  ✓/✗ audiences.md — [filled / empty / partial]
  ✓/✗ scoring-rubrics.md — [filled / empty / partial]
  ✓/✗ identity-model.md — [filled / empty / partial]
  ✓/✗ quality-contract.md — [filled / empty / partial]
  ✓/✗ domain-knowledge.md — [filled / empty / partial]
  ✓/✗ feedback-loops.md — [filled / empty / partial]

Checking output/designs/:
  ✓/✗ skill-designs.md — [exists / missing]
  ✓/✗ sub-agent-designs.md — [exists / missing]
  ✓/✗ loop-designs.md — [exists / missing]

If any required file is missing or empty, STOP and tell the designer which skill to run to fill it.

If any file is partial, WARN and proceed — note which sections of the generated OS may be thin.

Process

Step 0: Read the Blueprint

Before generating anything, read reference/BLUEPRINT.md completely. This is the master specification. It defines:

• The component map (Section 2) — what folders and file types MUST exist
• How each component serves its purpose (Section 3) — why each piece exists and what breaks if it's missing
• The orchestration model (Section 4) — trigger chains, file-based connectors, compounding loops, dual declaration rule
• The interdependency table (Section 5) — what degrades when each context file is empty
• The 8 design principles (Section 6) — every OS must embody all 8
• The transferable skeleton (Section 7) — the exact folder structure to generate
• The generation checklist (Section 8) — 15 items to verify before delivering

Use Section 7's skeleton as the literal folder structure. Use Section 4's orchestration model to wire skills together. Use Section 8's checklist as the final verification step.

Step 1: Generate Repository Structure

Create the folder structure at output/[domain]-os/ using the skeleton from BLUEPRINT.md Section 7:

[domain]-os/
├── CLAUDE.md
├── README.md
├── START-HERE.md
├── .gitignore
├── .claude/skills/
│   └── [one folder per skill]/SKILL.md
├── context-library/
│   └── [one file per identity axis]
├── sub-agents/
│   └── [one file per reviewer]
├── insider-data/
│   ├── [domain-frameworks].md
│   └── [target-intel]/
│       └── index.md
├── cowork-tasks/
│   └── [briefing parts]
├── templates/
│   └── [scaffolding files]
├── setup/
│   ├── installation-guide.md
│   └── first-session-checklist.md
└── [output-folder]/

Step 2: Generate CLAUDE.md (The Kernel)

This is the most critical file. Use reference/kernel-anatomy.md as the structural template.

The kernel must conform to BLUEPRINT.md Section 7 (kernel structure) and contain ALL of these sections:

1. Identity statement: "You are a [domain] assistant powered by [OS name]."
2. Core philosophy: 3-5 rules from quality-contract.md
3. Context awareness: List every context-library file with its purpose. Include "read at session start" instruction.
4. Project structure: ASCII tree of the repository
5. Skills table: Every skill with command and one-line description
6. Sub-agents table: Every reviewer with command and description
7. Auto-behaviors: Every trigger chain (from skill-designs.md)
8. Verification rules: Every check (from quality-contract.md)
9. Empty context detection: Every dependency and message (from quality-contract.md)
10. Writing style: Voice, banned words, length standards
11. Persona adaptations: Non-default user types and how skills adjust
12. Key rules: Numbered list of the most important constraints
13. Insider data instructions: How to use reference data, staleness rules
14. Getting started: 4-step quickstart

Critical kernel rules (from BLUEPRINT.md Sections 4-5):

• The non-negotiable rule must appear in bold, early in the document
• Every auto-behavior must be declared here AND in the triggering skill (dual declaration — BLUEPRINT Section 4d)
• The context awareness section must list files in dependency order (foundation first)
• The empty context detection must include the zero-setup entry point exception
• Include a dependency table mapping what breaks when each context file is empty (BLUEPRINT Section 5)
• Include a connector map showing which skills read/write which files (BLUEPRINT Section 4b)
• Include trigger chain documentation for every creation skill (BLUEPRINT Section 4a)

Step 3: Generate Each SKILL.md

For each skill from output/designs/skill-designs.md, generate a full SKILL.md file using reference/skill-anatomy.md as the template.

Each SKILL.md must contain:

1. Frontmatter (name, description)
2. When to Use section
3. Persona/function detection (if applicable from identity-model.md)
4. Inputs section (required, auto-loaded, optional)
5. Empty context behavior (from quality-contract.md dependency map)
6. Process section (detailed, step-by-step)
7. Output format (with example structure)
8. Auto-triggers (what runs after this skill)
9. Quality checks (good output / bad output)

For each skill, enforce:

• Process steps reference specific context-library files by path
• Output format is a concrete markdown template, not a vague description
• Quality checks include domain-specific examples, not generic criteria
• Empty context messages tell the user exactly what to do

Step 4: Generate Each Sub-Agent

For each reviewer from output/designs/sub-agent-designs.md, generate a full markdown file using reference/sub-agent-anatomy.md as the template.

Each sub-agent must contain:

1. Role section (vivid persona)
2. When to Use section (including auto-trigger declaration)
3. Inputs section
4. Process section (scan → score → flag → suggest)
5. Output format
6. Quality checks

Enforce the adversarial principle: The process section of each sub-agent must evaluate from a DIFFERENT perspective than the creation skill it reviews. If you cannot articulate the conflict, the sub-agent needs redesign.

Step 5: Generate Context-Library Templates

CRITICAL DESIGN BOUNDARY: The factory generates the OS. The OS handles its own user personalization. These are two separate systems with no runtime relationship.

The factory's job is to produce Layer 1 (domain knowledge) AND the machinery the OS needs to handle Layer 2 (user personalization) on its own. That machinery includes: context-library templates, empty-context detection in every skill, the zero-setup entry point, START-HERE.md, and setup/. The factory generates all of this, but the factory never interacts with end users. The generated OS does.

When an end user opens the generated OS for the first time, the OS itself says "Your experience library is empty. Run Help me build my experience library first." That message, that flow, that skill — the factory generated them. But the factory isn't running them. The OS is.

For each identity axis from domain-input/identity-model.md, generate a template file in context-library/:

What the template contains:

• A header comment: <!-- Fill this file with YOUR data. The OS reads this to personalize all output. -->
• A one-paragraph explanation of what this file is for and why it matters
• Clear section headers matching the schema from identity-model.md
• Placeholder examples at the right specificity level — not "[fill in here]" but realistic examples that show the expected format, detail, and tone. The user should see what a good entry looks like.
• For the foundation file: a note that this is the most important file to fill first, and that all skills depend on it

What the template does NOT contain:

• Any real user data — no names, no companies, no personal details
• No domain-input/ content leaking in — the factory's design inputs are NOT the user's identity
• No pre-filled answers — the template is a structure, not a suggestion

Template quality test: A new user opening this file should immediately understand (1) what data to put here, (2) what format to use, (3) how detailed to be, and (4) why this file matters. If they need to read documentation to understand the template, it's too sparse. If they confuse placeholder examples for real data, the placeholders aren't obviously fake enough.

Onboarding integration: Generate a START-HERE.md that the OS will use to guide its own users through filling context-library files in dependency order — foundation file first, then goals, then the rest. Include time estimates per file (derived from domain-input/domain-workflow.md). This is the OS's onboarding flow, not the factory's — the factory generates it, the OS runs it.

Step 6: Generate Cowork Tasks (Briefing)

From domain-input/domain-workflow.md and output/designs/loop-designs.md, generate:

1. A master briefing document (like daily-morning-briefing.md)
2. Split into 2-3 parts for context window management
3. Each part is self-contained and can run independently
4. The last part reads output from earlier parts

Include:

• Quality gate (check context files before running)
• Persona detection (adapt based on user type)
• Scheduled cadence instructions
• Output save path

Step 7: Generate Supporting Files

1. README.md: Product overview, what it does, how to use it
2. START-HERE.md: Onboarding guide with time estimates per step
3. .gitignore: Ignore sensitive context-library files if needed
4. setup/installation-guide.md: Prerequisites and setup steps
5. setup/first-session-checklist.md: Step-by-step first run
6. insider-data/index.md: Index of reference data (may be empty initially)
7. templates/: Any scaffolding templates referenced by skills

Step 8: Self-Verification Against the Blueprint

After generating all files, run the BLUEPRINT.md Section 8 Generation Checklist — all 15 items:

1. One kernel file that shapes all behavior. Everything traces back to it.
2. User state externalized into flat markdown files the user owns. Never overwritten; flag gaps.
3. Skills are stateless pure functions. Input: (context + user input). Output: artifact. No inter-skill coupling.
4. Every generation skill has an adversarial reviewer with different priorities.
5. One zero-setup entry point that delivers value before the user invests in setup.
6. Auto-behaviors declared, not coded. "After X, trigger Y" in the kernel AND the skill (dual declaration).
7. Verification is mandatory. Every skill checks its output against the source of truth.
8. Compounding loops exist. Output of action → logged to history → read by retro → coaches next action.
9. Persona-conditional branching from a single config file, not separate systems per persona.
10. Graceful degradation. Empty state → STOP or WARN, never garbage. Stale data → FLAG. Unverifiable → LABEL.
11. Function-adaptive markers throughout, so the same skeleton works for multiple sub-domains.
12. Scheduled automation converts the system from reactive to proactive.
13. Dependency table in the kernel maps what breaks when each file is empty.
14. Connector map documents which skills read/write which files.
15. Trigger chains documented for every creation skill.
16. Two-system boundary enforced. Factory produced Layer 1 AND the onboarding machinery for Layer 2. The OS handles Layer 2 at runtime with its own users. No user data baked in. No factory back-references. No domain-input/ content leaked into the OS.

Additionally, verify structural integrity:

• Kernel completeness: Does CLAUDE.md reference every skill, sub-agent, context file, and auto-behavior?
• Dependency consistency: Does every "auto-loaded" file reference in skills match a real file in context-library/?
• Sub-agent wiring: Is every sub-agent triggered by at least one skill?
• Cross-reference integrity: No broken file paths anywhere in the generated OS.

Report any gaps found during self-verification.

Output

The complete OS repository at output/[domain]-os/.

Tell the designer:

OS generated at output/[domain]-os/

Repository contents:
- CLAUDE.md (kernel): [word count]
- Skills: [N] files in .claude/skills/
- Sub-agents: [N] files in sub-agents/
- Context templates: [N] files in context-library/
- Briefing: [N] parts in cowork-tasks/
- Supporting files: README, START-HERE, setup guide

Self-verification: [PASS / N issues found]
[list any issues]

Next: Run /review-os for a thorough architectural audit.
Or: Copy output/[domain]-os/ to your working directory and start using it.

Quality Checks

Good generation:

• The generated OS is self-contained — no references to files that don't exist
• CLAUDE.md is comprehensive but not bloated (target: 100-200 lines)
• Every SKILL.md has domain-specific content, not generic placeholders
• Context-library templates show the expected format with realistic placeholder examples
• The START-HERE.md onboarding guide has accurate time estimates

Bad generation:

• References to domain-input/ files (these are factory files, not OS files)
• Generic skill processes copied across all skills
• CLAUDE.md that's too thin (missing auto-behaviors or verification) or too thick (500+ lines)
• Context templates with no placeholder examples
• Sub-agents that don't reference their trigger skills