llms.txt

# Co-Evolution

> Tools for structured iterative refinement between AI agents. Two agents bounce
> a shared markdown document back and forth using in-document disagreement
> markers - `[CONTESTED]` and `[CLARIFY]` - that auto-expire after 2 passes,
> guaranteeing bounded convergence. Agent-agnostic via CLI adapters.

## Core Concepts

- [README](https://github.com/alanshurafa/co-evolution/blob/master/README.md): overview of the default co-evolution runner, Claude Code skills, Agent Bouncer, and code runtime
- [Co-Evolution SKILL.md](https://github.com/alanshurafa/co-evolution/blob/master/skills/co-evolution/SKILL.md): default Claude Code skill for questions, drafts, plans, specs, arguments, and document refinement
- [Bounce protocol + marker semantics](https://github.com/alanshurafa/co-evolution/blob/master/agent-bouncer/README.md): `[CONTESTED]` / `[CLARIFY]` usage, 2-pass staleness rule, convergence guarantee
- [dev-review SKILL.md](https://github.com/alanshurafa/co-evolution/blob/master/skills/dev-review/SKILL.md): code-focused compose -> bounce -> execute -> verify workflow for real repo changes
- [Codex standalone runtime](https://github.com/alanshurafa/co-evolution/blob/master/dev-review/codex/README.md): Bash runtime for the same code workflow outside Claude Code
- [Eval harness](https://github.com/alanshurafa/co-evolution/blob/master/evals/README.md): YAML case files with 5-tier scoring

## Routing Rule

Default to `co-evolve-bouncer.sh` or `skills/co-evolution/` for general
co-evolution. Use `dev-review` only when the task specifically needs code
execution, diff verification, or a repo-change trail.

## What Makes This Different

- First-class in-document expiring disagreement markers
- Filesystem as coordination substrate: agents are subprocesses reading/writing a shared markdown file
- Bounded convergence by protocol construction, not by heuristic iteration cap
- Bash-first core with adapter functions per agent

## Optional

- [Project contract](https://github.com/alanshurafa/co-evolution/blob/master/.planning/PROJECT.md): project-level constraints and value statement
- [v1.2 roadmap](https://github.com/alanshurafa/co-evolution/blob/master/.planning/ROADMAP.md): Protocol Evolution Loop - self-mutating harness with human review gate on proposed mutations