Skip to content

CLAUDE.md

Latest commit

 

History

History
156 lines (121 loc) · 7.49 KB

CLAUDE.md

File metadata and controls

156 lines (121 loc) · 7.49 KB
Raw

Ouroboros - Development Environment

This CLAUDE.md is for local development only. End users install via:

claude plugin marketplace add Q00/ouroboros
claude plugin install ouroboros@ouroboros

Once installed as a plugin, skills/hooks/agents work natively without this file.

ooo Commands (Dev Mode)

When the user types any of these commands, read the corresponding SKILL.md file and follow its instructions exactly:

Input Action
ooo (bare, no subcommand) Read skills/welcome/SKILL.md and follow it
ooo auto ... Read skills/auto/SKILL.md and follow it
ooo interview ... Read skills/interview/SKILL.md and follow it
ooo seed Read skills/seed/SKILL.md and follow it
ooo run Read skills/run/SKILL.md and follow it
ooo evaluate or ooo eval Read skills/evaluate/SKILL.md and follow it
ooo evolve ... Read skills/evolve/SKILL.md and follow it
ooo unstuck or ooo stuck or ooo lateral Read skills/unstuck/SKILL.md and follow it
ooo status or ooo drift Read skills/status/SKILL.md and follow it
ooo ralph Read skills/ralph/SKILL.md and follow it
ooo tutorial Read skills/tutorial/SKILL.md and follow it
ooo setup Read skills/setup/SKILL.md and follow it
ooo welcome Read skills/welcome/SKILL.md and follow it
ooo cancel Read skills/cancel/SKILL.md and follow it
ooo config Read skills/config/SKILL.md and follow it
ooo qa or ooo qa ... Read skills/qa/SKILL.md and follow it
ooo help Read skills/help/SKILL.md and follow it
ooo update Read skills/update/SKILL.md and follow it
ooo pm or ooo pm ... Read skills/pm/SKILL.md and follow it
ooo brownfield or ooo brownfield ... Read skills/brownfield/SKILL.md and follow it
ooo publish or ooo publish ... Read skills/publish/SKILL.md and follow it
ooo resume-session Read skills/resume-session/SKILL.md and follow it

Important: Do NOT use the Skill tool. Read the file with the Read tool and execute its instructions directly.

Agents

Bundled agents live in src/ouroboros/agents/. When a skill references an agent (e.g., ouroboros:socratic-interviewer), read its definition from src/ouroboros/agents/{name}.md and adopt that role. Use OUROBOROS_AGENTS_DIR or .claude-plugin/agents/ only for explicit custom overrides.

Pull Request Boundary Policy

Before implementing or reviewing a PR, read Review Boundary Contract. The PR description is the review contract, not an informal suggestion.

Require contributors to declare: the one user problem; supported inputs and execution conditions; observable contract and invariants; changed subsystem, data/security boundary, and owner; non-goals; and evidence. Do not absorb new lifecycle, rollback, concurrency, filesystem-authority, or other ownership requirements without a maintainer decision.

For every review finding, ask:

  1. Does it reproduce under the promised inputs and execution conditions?
  2. Does it break the promised contract?
  3. Does fixing it require a new subsystem or ownership boundary?
  4. Can the original user problem be solved without the subsystem introduced by this PR?
  5. If scope is split, does immediate user-data or security risk remain?

Use these decisions:

  • Q1 + Q2: Changes Requested.
  • Q3 + Q5: stop and revisit the RFC with the maintainer; do not silently absorb the new subsystem or owner.
  • Q3 + Q4 and not Q5: owned follow-up, not a blocker; require a named owner and link.
  • Q5 without Q3 + Q5 escalation: Changes Requested for the immediate user-data or security risk.
  • Outside the declared boundary without a contract violation: not a blocker; record a valid, actionable finding only as an owned follow-up with a named owner and tracking link; do not expand the PR.

Only the maintainer decides scope expansion. Keep review comments tied to the declared boundary and directly evidenced behavior. The declared boundary cannot waive existing public or repository contracts, approved issue or RFC requirements, or maintainer decisions.

Shipping a change (read before you commit)

The code you edit is not the code that runs, by default. The checked-in .mcp.json points at the published PyPI package, so edits to this working tree have no effect on a client until you repoint it at local source. See docs/contributing/developing.md.

main is protected: direct pushes are rejected with GH006, for everyone, including the owner. Every change lands through a squash-merged PR, so a release tag must be created on the merged main commit — not before.

Four checks are required to merge — reproduce them locally first:

uv run ruff format src/ tests/ && uv run ruff check src/ tests/ --fix
uv run mypy src/ouroboros
uv run pytest

(Ruff Lint, MyPy Type Check, Test Python 3.12, Bridge TypeScript.)

Other gates fire conditionally and are easy to trip blind:

  • Issue link present — every PR needs Refs #123 in the body. Exempt via the no-issue label, or a title starting chore(deps) / chore(release) / release:. Note chore: release vX.Y.Z does not match the prefix.
  • enforce-module-size — 2000-line cap per module; grandfathered modules may shrink, never grow, and no new entries.
  • enforce-boundary — no domain keywords (github, jira, slack, …) in src/ouroboros/auto/.
  • enforce-perf-budget — PRs touching src/ouroboros/auto/ need the R-run table filled in the PR body.

Full reference, including every escape hatch and the release sequence: docs/contributing/ci-gates.md.

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.

Most AI coding fails at the input, not the output. Ouroboros fixes this by exposing hidden assumptions before any code is written.

  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

Each command loads its agent/MCP on-demand. Details in each skill file.

Command Loads
ooo —
ooo auto MCP: ouroboros_auto
ooo interview ouroboros:socratic-interviewer
ooo seed ouroboros:seed-architect
ooo run MCP required
ooo evolve MCP: evolve_step
ooo evaluate ouroboros:evaluator
ooo qa ouroboros:qa-judge
ooo unstuck ouroboros:{persona}
ooo status MCP: session_status
ooo ralph Persistent loop until verified
ooo tutorial Interactive hands-on learning
ooo setup —
ooo help —
ooo update PyPI version check + upgrade
ooo publish gh CLI — Seed to GitHub Issues
ooo resume-session Restore previous Claude Code session context

Agents

Loaded on-demand — not preloaded.

Core: socratic-interviewer, ontologist, seed-architect, evaluator, qa-judge, contrarian Support: hacker, simplifier, researcher, architect