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

> Integrate Ouroboros reference blocks into your project with CLAUDE.md setup. Automatically add command, philosophy, and agent details, with backup and uninstall.

- Repository: [Q00/ouroboros](https://github.com/Q00/ouroboros)
- Tags: how-to-guide
- Published: 2026-03-14

---

**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`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/CLAUDE.md) file. This prompt appears at lines 94-103 of [`skills/setup/SKILL.md`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/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:

```bash

# 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:

```bash
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`](https://github.com/Q00/ouroboros/blob/main/skills/setup/SKILL.md):

```bash

# 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`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/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`](https://github.com/Q00/ouroboros/blob/main/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.