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, data-contract, artifact-pipeline, data-sources, backtesting-library)
• Required: output/designs/skill-designs.md
• Required: output/designs/sub-agent-designs.md
• Required: output/designs/loop-designs.md
• Optional: output/designs/batch-designs.md (if batch architecture designed)
• Optional: output/designs/localization-designs.md (if localization designed)
• Optional: domain-input/backtesting-library.md (if backtesting designed)
• CRITICAL: reference/BLUEPRINT.md (master architectural specification — read FIRST)
• 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 (14 design principles)
• Auto-loaded: reference/artifact-pipeline-anatomy.md (artifact template)
• Auto-loaded: reference/batch-architecture-anatomy.md (batch template)
• Auto-loaded: reference/data-contract-anatomy.md (data contract template)
• Auto-loaded: reference/backtesting-anatomy.md (backtesting template)

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]
  ✓/✗ data-contract.md — [filled / empty / partial]
  ✓/✗ artifact-pipeline.md — [filled / empty / partial / N/A]
  ✓/✗ data-sources.md — [filled / empty / partial / N/A]
  ✓/✗ backtesting-library.md — [filled / empty / partial / N/A]

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

If any required file is missing or empty, STOP and tell the designer which skill to run. If any file is partial, WARN and proceed — note which sections may be thin. artifact-pipeline.md, data-sources.md, backtesting-library.md, batch-designs.md, and localization-designs.md are optional — mark N/A if the domain doesn't need them.

Process

Step 0: Read the Blueprint

Before generating anything, read reference/BLUEPRINT.md completely. It defines:

• The component map (Section 2) — what folders and file types MUST exist
• How each component serves its purpose (Section 3)
• The orchestration model (Section 4) — trigger chains, connectors, loops, dual declaration, data contract enforcement, artifact pipelines, batch execution, trust layers, backtesting wiring
• The interdependency table (Section 5)
• The 15 design principles (Section 6)
• The transferable skeleton (Section 7)
• The generation checklist (Section 8) — 23 items to verify

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
├── DATA_CONTRACT.md
├── README.md
├── START-HERE.md
├── .gitignore
├── .claude/skills/
│   └── [one folder per skill]/SKILL.md
├── context-library/
│   └── [one file per identity axis]
├── config/
│   ├── defaults.md
│   └── overrides.md
├── sub-agents/
│   └── [one file per reviewer]
├── insider-data/
│   ├── [domain-frameworks].md
│   └── [target-intel]/
│       └── index.md
├── cowork-tasks/
│   └── [briefing parts]
├── templates/
│   └── [scaffolding + artifact templates]
├── setup/
│   ├── installation-guide.md
│   └── first-session-checklist.md
├── batch/                          # [if batch-designs.md exists]
│   ├── batch-prompt.md
│   ├── batch-runner.sh
│   └── batch-state.tsv
├── modes/                          # [if localization-designs.md exists]
│   └── [lang]/
├── backtesting/                    # [if backtesting-library.md exists]
│   ├── library.md
│   ├── cases/
│   │   └── .gitkeep
│   └── results/
│       └── .gitkeep
└── [output-folder]/

Step 2: Generate CLAUDE.md (The Kernel)

Use reference/kernel-anatomy.md as the structural template. The kernel must 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 and config file with purpose.
4. Data contract summary: Classification table from data-contract.md. The Golden Rule.
5. Project structure: ASCII tree of the repository
6. Skills table: Every skill with command and one-line description
7. Sub-agents table: Every reviewer with command and description
8. Auto-behaviors: Every trigger chain (from skill-designs.md)
9. Verification rules: Every check (from quality-contract.md)
10. Data acquisition rules: Trust levels and verification rules (from data-sources.md, if applicable)
11. Empty context detection: Every dependency and message
12. Configuration precedence: overrides > defaults, with the Golden Rule
13. Writing style: Voice, banned words, length standards
14. Persona adaptations: Non-default user types
15. Key rules: Numbered list of the most important constraints
16. Insider data instructions: How to use reference data, staleness rules
17. Getting started: 4-step quickstart

Critical kernel rules (from BLUEPRINT.md):

• The non-negotiable rule must appear in bold, early in the document
• Every auto-behavior dual-declared (kernel AND skill)
• Context awareness lists files in dependency order (foundation first)
• Empty context detection includes zero-setup entry point exception
• Include dependency table, connector map, and trigger chain documentation
• Data contract summary makes ownership boundaries visible

Step 2.5: Generate DATA_CONTRACT.md

From domain-input/data-contract.md, generate the OS's data contract:

1. User-owned files: List every file with purpose and "NEVER auto-modify" rule
2. System-managed files: List every file with purpose and auto-update behavior
3. Hybrid files: List every file with system action (append) and user action (curate)
4. The Golden Rule: One sentence resolving ownership ambiguity

Step 2.6: Generate config/ Directory

From domain-input/identity-model.md and domain-input/quality-contract.md:

1. config/defaults.md: System defaults for scoring weights, thresholds, output preferences. Auto-updatable.
2. config/overrides.md: Template with placeholder sections for user customizations. User-owned.

Step 3: Generate Each SKILL.md

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

Each SKILL.md must contain:

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

Optional sections (add when applicable):

• Artifact Output: If skill produces non-text output — template, render pipeline, storage, naming, verification (from artifact-pipeline.md)
• Batch Mode Variant: If skill supports headless execution — what changes in batch mode, tool constraints, fallback behavior (from batch-designs.md)
• Data Source Dependencies: If skill queries external data — sources, trust levels, verification rules (from data-sources.md)

Step 4: Generate Each Sub-Agent

Same as v1.0. Use reference/sub-agent-anatomy.md as template. Enforce adversarial principle.

If sub-agent reviews non-text artifacts, add "Artifact Review" section with format-specific checks.

Step 5: Generate Context-Library Templates

Same as v1.0. Generate empty templates with placeholder examples. Include ownership classification from data-contract.md.

Step 5.5: Generate Artifact Templates

If domain-input/artifact-pipeline.md exists and is filled:

For each artifact type:

1. Generate the base template file in templates/ (HTML, CSV schema, etc.)
2. Define design tokens (if visual) in templates/design-tokens.md or within the template
3. Generate any render scripts (if applicable)

Step 5.6: Generate Batch Infrastructure

If output/designs/batch-designs.md exists:

1. batch/batch-prompt.md: Self-contained worker prompt with all instructions
2. batch/batch-runner.sh: Orchestrator script with --dry-run, --retry-failed, --parallel N, --start-from N
3. batch/batch-state.tsv: Header row with schema columns
4. batch/tracker-additions/.gitkeep: Staging directory for worker output

Step 5.7: Generate Localized Modes

If output/designs/localization-designs.md exists:

For each language:

1. Create modes/[lang]/ directory
2. Generate localized mode files preserving default structure
3. Include culture-specific vocabulary and evaluation criteria

Step 5.8: Generate Backtesting Infrastructure

If domain-input/backtesting-library.md exists and is filled:

1. backtesting/library.md: Empty library index template with:

   • Ordering scheme (from backtesting-library.md design)
   • Case table headers matching the domain's artifact types
   • Instructions for adding cases

2. backtesting/cases/.gitkeep: Empty directory for user to populate with case subdirectories

3. backtesting/results/.gitkeep: Empty directory for system-generated comparison reports

4. Update DATA_CONTRACT.md: Add backtesting file classifications:

   • User-owned: backtesting/library.md, backtesting/cases/*/input.md, backtesting/cases/*/ground-truth.md
   • System-managed: backtesting/results/*.md

5. Update CLAUDE.md: Add backtesting library section with:

   • Live reference rules (which skills, how many cases, what to extract)
   • Ownership rules (never modify cases/)
   • Ordering scheme

6. Update backtestable skills: Add "Backtesting Integration" section to each backtestable SKILL.md declaring:

   • How the skill reads from the library during live generation
   • What it extracts from ground truth (patterns, not content)
   • How it acknowledges calibration in output

7. Update START-HERE.md and setup/: Add backtesting library setup section with:

   • What to upload and how to organize it
   • Minimum viable library size
   • Time estimate per case
   • Link to v3.0 roadmap for automatic input/output separation

Step 6: Generate Cowork Tasks (Briefing)

Same as v1.0. Split into 2-3 parts. Include quality gate, persona detection, scheduled cadence.

Step 7: Generate Supporting Files

1. README.md: Product overview
2. START-HERE.md: Onboarding guide with time estimates
3. .gitignore: Ignore sensitive context-library files
4. setup/installation-guide.md: Prerequisites and setup
5. setup/first-session-checklist.md: Step-by-step first run
6. insider-data/index.md: Index of reference data
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 23 items:

Core Architecture:

1. One kernel file that shapes all behavior.
2. User state externalized into flat markdown files.
3. Skills are stateless pure functions.
4. Every generation skill has an adversarial reviewer.
5. One zero-setup entry point.
6. Auto-behaviors dual-declared in kernel AND skill.
7. Verification is 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. No factory back-references.

Infrastructure: 17. [ ] DATA_CONTRACT.md exists classifying every file. 18. [ ] Layered configuration with defaults and overrides. 19. [ ] Artifact pipelines declared for non-text output skills. 20. [ ] External data sources have trust levels. 21. [ ] Batch operations (if applicable) are resumable. 22. [ ] Orthogonal evaluation axes — independent dimensions scored independently. 23. [ ] Backtesting library (if applicable) — cases structure, ordering, live reference, onboarding.

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" reference match a real file?
• Sub-agent wiring: Is every sub-agent triggered by at least one skill?
• Cross-reference integrity: No broken file paths.
• Data contract consistency: Do skills actually respect the ownership boundaries?

Report any gaps found.

Output

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

Tell the designer:

OS generated at output/[domain]-os/

Repository contents:
- CLAUDE.md (kernel): [line count]
- DATA_CONTRACT.md: [N] files classified
- Skills: [N] files in .claude/skills/
- Sub-agents: [N] files in sub-agents/
- Context templates: [N] files in context-library/
- Config: defaults.md + overrides.md
- Briefing: [N] parts in cowork-tasks/
- Artifact templates: [N] in templates/ (if applicable)
- Batch infrastructure: [present / not applicable]
- Backtesting library: [present with N backtestable skills / not applicable]
- Localized modes: [N] languages (if applicable)
- Supporting files: README, START-HERE, DATA_CONTRACT, setup guide

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

Next: Run /review-os for a thorough architectural audit.

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: 120-250 lines)
• DATA_CONTRACT.md classifies every persistent file
• Every SKILL.md has domain-specific content, not generic placeholders
• Context-library templates show the expected format with realistic examples
• config/overrides.md is clearly user-owned; config/defaults.md is system-updatable
• START-HERE.md onboarding guide has accurate time estimates

Bad generation:

• References to domain-input/ files (factory files, not OS files)
• Generic skill processes copied across all skills
• DATA_CONTRACT.md missing or incomplete
• No config/ directory — single config file mixing defaults and user data
• Skills that write to user-owned files without confirmation
• Batch workers that depend on conversation context