AGENTS.md · diff
git:20260825.d4dcc80 to git:20260927.9231c1b
26 added, 0 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# Ouroboros - Development Environment
> This AGENTS.md is for **local development only**. End users install via:
> ```
> Codex plugin marketplace add Q00/ouroboros
> Codex plugin add 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 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 maintain` or `ooo maintain ...` | Read `skills/maintain/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 `.Codex-plugin/agents/` only for explicit custom overrides.
+ ## Pull Request Boundary Policy
+
+ Before implementing or reviewing a PR, read [Review Boundary Contract](CONTRIBUTING.md#review-boundary-contract). Treat the PR description as the review contract.
+
+ Contributors MUST declare the user problem, supported inputs and execution conditions, observable contract, touched subsystem and owner, non-goals, and verification evidence. Do not silently widen these while responding to review. A declared boundary narrows implementation scope but cannot waive an existing public or repository contract, an approved issue or RFC requirement, or a maintainer decision; conflicts require maintainer approval or RFC review.
+
+ Review agents MUST evaluate every finding in this order:
+
+ 1. Reproduce it under the PR's promised inputs and execution conditions.
+ 2. Determine whether it violates the PR's promised contract.
+ 3. Determine whether the fix requires a new subsystem or ownership boundary.
+ 4. Determine whether the original user problem can be solved without the subsystem introduced by the PR.
+ 5. Determine whether splitting the scope leaves an immediate user-data or security risk.
+
+ Outcomes are strict:
+
+ - Questions 1 and 2 are yes: **Changes Requested**.
+ - Questions 3 and 5 are yes: stop the PR and ask a maintainer to revisit the RFC; do not silently absorb the new subsystem or owner.
+ - Questions 3 and 4 are yes while question 5 is no: non-blocking follow-up with a named owner and link.
+ - Question 5 is yes without the Q3 + Q5 escalation: **Changes Requested** for the immediate user-data or security risk.
+ - Outside the declared boundary and no contract violation: not a blocker; record only as a valid, actionable, owned follow-up.
+
+ Review severity alone never expands PR scope. Maintainers own scope-expansion 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](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:
```bash
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](docs/contributing/ci-gates.md)**.
<!-- ooo:START -->
<!-- ooo:VERSION:0.26.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.
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_start_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 maintain` | `gh` CLI — review and disposition of issues and PRs |
| `ooo resume-session` | Restore previous Codex session context |
## Agents
Loaded on-demand — not preloaded.
**Core**: socratic-interviewer, ontologist, seed-architect, evaluator, qa-judge, contrarian
**Support**: hacker, simplifier, researcher, architect
**Analysis**: analysis-agent, ontology-analyst, codebase-explorer, research-agent, breadth-keeper
**Execution**: code-executor, seed-closer, consensus-reviewer, semantic-evaluator
**Specialist**: advocate, judge
<!-- ooo:END -->