How CLAUDE.md Integration Adds Ouroboros Reference Blocks to Your Project

Running ooo setup appends a fenced markdown block containing the Ouroboros command reference, philosophy, and agent catalog between <!-- ooo:START --> and <!-- ooo:END --> markers in your project's CLAUDE.md file, with automatic backup and uninstall support.

The Ouroboros toolchain (available at Q00/ouroboros) provides a specification-first AI development workflow that integrates directly with your project documentation. When you initialize the toolchain using the setup skill, it offers an optional CLAUDE.md integration step that injects a self-documenting reference block directly into your project's CLAUDE.md file. This integration ensures that every ooo command, agent mapping, and philosophical principle is instantly accessible without leaving your codebase.

How the CLAUDE.md Integration Works

The integration process is handled entirely within the skills/setup/SKILL.md file and operates through five distinct phases:

Step 1: User Prompt After MCP Registration

After registering the MCP server, the setup skill displays an interactive UI that asks whether to add an Ouroboros quick-reference block to the project's CLAUDE.md file. This prompt appears at lines 94-103 of skills/setup/SKILL.md and presents three options: Integrate, Skip, or Preview.

Step 2: Automatic Backup Creation

If you choose to integrate, the skill first safeguards your existing documentation by copying the current CLAUDE.md to CLAUDE.md.bak. This backup logic is implemented at lines 68-73 of the skill file, ensuring zero data loss during the modification process.

Step 3: Inserting the Reference Block

The skill appends a fenced-markdown snippet (approximately 40 lines) between machine-readable markers. According to lines 20-46 of skills/setup/SKILL.md, the block contains:

• A version header: <!-- ooo:VERSION:0.14.0 -->
• A philosophy statement covering Socratic Clarity, Ontological Precision, and Evolutionary Loops
• A command-to-agent mapping table
• A concise catalog of available agents

The block is wrapped in <!-- ooo:START --> and <!-- ooo:END --> HTML-style comments, making it both human-readable and machine-detectable for future updates or removal.

Step 4: Integration Confirmation

After successfully appending the reference block, the skill prints a confirmation message (lines 73-77) indicating that the Ouroboros reference is now available in every project session.

Step 5: Uninstall and Clean Rollback

If you later run ooo setup --uninstall, the skill uses the same <!-- ooo:START --> and <!-- ooo:END --> markers to locate and delete the block from CLAUDE.md (lines 86-89), restoring your documentation to its pre-integration state.

Reference Block Structure and Content

The injected block serves as a self-contained quick-reference guide. As defined in the skill template (lines 20-46), it documents the complete ooo command palette:

Commands mapped to agents:

• ooo interview → ouroboros:socratic-interviewer
• ooo seed → ouroboros:seed-architect
• ooo run → MCP required
• ooo evolve → MCP: evolve_step
• ooo evaluate → ouroboros:evaluator
• ooo unstuck → ouroboros:{persona}
• ooo status → MCP: session_status

Agent categories:

• Core: socratic-interviewer, ontologist, seed-architect, evaluator
• Support: hacker, simplifier, researcher, architect

Automated Setup with ooo setup

To integrate the reference block into your project, execute the setup command in your terminal:

# Run the initial setup (first time in a new project)

ooo setup

You will see the interactive prompt:

Add Ouroboros quick-reference to your CLAUDE.md? [Integrate / Skip / Preview]

Select Preview to view the block content without modifying your file, or select Integrate to proceed with the injection. After integration, verify the installation:

grep -A2 -B2 '<!-- ooo:START -->' CLAUDE.md

This command displays the marker tags and surrounding context, confirming the block is properly positioned.

Manual Integration for Advanced Users

While the automated setup is recommended, you can manually insert the reference block by first creating a backup and then appending the content extracted from lines 20-46 of skills/setup/SKILL.md:

# Backup existing documentation

cp CLAUDE.md CLAUDE.md.bak

# Append the reference block

cat >> CLAUDE.md <<'EOF'

<!-- ooo:START -->
<!-- ooo:VERSION:0.14.0 -->

# Ouroboros — Specification-First AI Development

> Before telling AI what to build, define what should be built.
> As Socrates asked 2,500 years ago — "What do you truly know?"
> Ouroboros turns that question into an evolutionary AI workflow engine.

1. **Socratic Clarity** — Question until ambiguity ≤ 0.2
2. **Ontological Precision** — Solve the root problem, not symptoms
3. **Evolutionary Loops** — Each evaluation cycle feeds back into better specs

Interview → Seed → Execute → Evaluate
    ↑                           ↓
    └─── Evolutionary Loop ─────┘

## ooo Commands

| Command | Loads |
|---------|-------|
| `ooo` | — |
| `ooo interview` | `ouroboros:socratic-interviewer` |
| `ooo seed` | `ouroboros:seed-architect` |
| `ooo run` | MCP required |
| `ooo evolve` | MCP: `evolve_step` |
| `ooo evaluate` | `ouroboros:evaluator` |
| `ooo unstuck` | `ouroboros:{persona}` |
| `ooo status` | MCP: `session_status` |
| `ooo help` | — |

## Agents

Loaded on-demand — not preloaded.
**Core**: socratic-interviewer, ontologist, seed-architect, evaluator, …
**Support**: hacker, simplifier, researcher, architect
<!-- ooo:END -->
EOF

Summary

• CLAUDE.md integration is initiated via ooo setup and managed through the skills/setup/SKILL.md script according to the Q00/ouroboros source code.
• The process creates an automatic backup (CLAUDE.md.bak) before modifying your documentation.
• Reference blocks are wrapped in <!-- ooo:START --> and <!-- ooo:END --> markers to enable machine detection and clean uninstallation.
• The block includes version tracking (<!-- ooo:VERSION:0.14.0 -->), philosophy statements, command tables, and agent catalogs.
• Uninstallation is handled via ooo setup --uninstall, which locates markers and removes the injected content.

Frequently Asked Questions

What happens if I don't have a CLAUDE.md file when running ooo setup?

If your project lacks a CLAUDE.md file, the setup skill will create one during the integration process. The reference block is appended to the new file, and a backup is still generated (though it may be empty if no previous content existed). This ensures the Ouroboros documentation is available regardless of your project's initial state.

Can I update the reference block after the initial integration?

Yes, though the current implementation requires re-running the setup process. The skill uses the <!-- ooo:START --> and <!-- ooo:END --> markers to identify existing blocks, allowing future versions to replace outdated content automatically. For now, run ooo setup --uninstall followed by ooo setup to refresh the block with the latest version.

Does the CLAUDE.md integration affect my git repository?

The integration operates purely on the filesystem level and does not execute git commands. However, since CLAUDE.md is typically tracked in version control, you will see the new reference block appear in your working directory changes. The backup file CLAUDE.md.bak is created in the same directory but should be added to your .gitignore to avoid committing temporary files.

What is the purpose of the version comment in the reference block?

The <!-- ooo:VERSION:0.14.0 --> tag serves as a metadata marker that allows the Ouroboros toolchain to detect which version of the documentation is currently installed in your project. This enables future tooling to alert you when newer reference blocks are available or to perform automatic migrations between versions during setup operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}