Organon File Creation Workflow

Implements PROTO-ORG-6 from organon/protocols/PROTOCOLS.md. Creates valid organon files with correct placement, structure, and references.

When to Use This Skill

Use this skill when:

• •Adding a new domain that needs its own ETHOS.md
• •Adding a new feature organon (cross-cutting capability)
• •Creating PHILOSOPHY.md for design rationale
• •Creating PROTOCOL.md for step-by-step procedures
• •Adding a new scope directory that needs a README.md router

Purpose: Ensure every organon file is created correctly from the start — right location, right structure, right frontmatter, right inheritance.

Context Loading

1. •Load templates and structure:
   • •Read book-llms/templates.md (copy-paste scaffolds for each artifact type)
   • •Read book-llms/scopes.md (scope classification: product, domain, feature, component)
   • •Read book-llms/frontmatter-system.md (complete YAML frontmatter schema)
2. •Load quality standards:
   • •Read book-llms/ETHOS.md (meta-organon constraints — what every organon must follow)
   • •Read CLAUDE.md (project-level constraints)
3. •Load parent scope:
   • •Read the parent scope's ETHOS.md (new file must inherit, never contradict)

Steps

Step 1: Classify Scope

Determine the scope of the new file:

Decision heuristic: Has ≥3 unique concepts + lifecycle → domain. Crosses multiple domains → feature. Users think in code terms → component.

Step 2: Check Parent Scope

Load the parent scope's ETHOS.md. The new file must:

• •Inherit all parent constraints (never relax them)
• •Add constraints specific to this scope
• •Reference the parent in inherits_from frontmatter field

Step 3: Select Template

Based on the artifact type, load the correct template from book-llms/templates.md:

Step 4: Determine File Placement

Follow Pattern A (dedicated organon/ directory):

organon/
├── domains/
│   └── <domain-name>/
│       ├── ETHOS.md
│       ├── PHILOSOPHY.md
│       └── README.md
├── features/
│   └── <feature-name>/
│       ├── ETHOS.md
│       └── README.md
└── protocols/
    └── PROTOCOLS.md

For product-level scope: place directly in organon/.

Step 5: Generate Frontmatter

Fill in all required fields:

---
type: [constraints|rationale|procedures|navigation]
scope: [product|domain|feature|component|methodology]
name: [kebab-case-name]
version: "1.0"
summary: [One-sentence, max 200 chars]
token_estimate: [number, ~12 tokens/line]
# Type-specific fields (e.g., invariants_count for constraints)
inherits_from: [parent-scope-names]
load_priority: [high|medium|low]
audience: [llm, human]
---

Use organon generate if available to auto-generate frontmatter scaffold.

Step 6: Write Content

Follow the template's section structure exactly:

For ETHOS.md:

• •Write ≥3 IS statements (specific, not generic)
• •Write ≥3 IS NOT statements (real boundaries)
• •Write ≥3 invariants with enforcement mechanisms
• •Write ≥3 prioritized principles (lower number wins)
• •Write ≥5 decision heuristics (situation → action)

For PHILOSOPHY.md:

• •Write problem statement with root causes
• •Write the bet (falsifiable hypothesis)
• •Write ≥5 trade-offs with rationale
• •Write ≥3 alternatives considered

For PROTOCOL.md:

• •Write clear goal statement
• •Write ≥3 preconditions
• •Write numbered steps with decision points
• •Write verification checklist
• •Write recovery table

For README.md:

• •Keep under 100 lines (router, not content)
• •Include contents table with all children

Step 7: Validate

cd packages/tools && npx organon validate <path-to-new-file>

Runs all 4 validation stages:

1. •Schema — frontmatter structure is valid
2. •Content — required sections present
3. •References — file paths resolve
4. •Relationships — inheritance chain is valid

Step 8: Check Bidirectional References

If the new file references other organon files, ensure those files reference back:

• •If creating a protocol with workflow: <name>, ensure the workflow has protocol_id matching
• •If setting inherits_from: [parent], ensure parent exists
• •If setting related_files, ensure those files exist

cd packages/tools && npx organon verify --gate triplets

Verification

• • organon validate passes all 4 stages
• • File is in the correct directory per scope classification
• • Frontmatter has all required fields (type, scope, name, version, summary, token_estimate)
• • Section headings match the template for this artifact type
• • Parent scope constraints are inherited, not contradicted
• • Bidirectional references are complete (no orphans)

Error Recovery