convez.ai
AgenteAutomaçãoIntermediário
alanshurafa

Co-Evolution

alanshurafa/co-evolution

Refinamento iterativo entre agentes de IA com marcadores de discordância

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent para refinamento iterativo e estruturado de documentos entre agentes de IA. Dois agentes trocam um arquivo usando marcadores de discordância até convergência, produzindo saídas mais precisas que qualquer agente isolado. Agnóstico a plataforma, executa direto do terminal via Bash.

Instalação

$npx convez-ai alanshurafa/co-evolution

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
4
Contribuidores
2

Casos de uso

  • Melhorar documentação iterativamente com perspectivas múltiplas
  • Refinar planos, propostas e especificações técnicas
  • Revisão de código entre agentes com validação cruzada

Veredito

Ferramenta sólida para cenários onde múltiplas iterações melhoram resultado final. Abordagem agnóstica (funciona com Claude, Codex e outros) é vantagem; requer familiaridade com Bash e CLI tools, não é zero-config.

README

A tradução para o português deste README ainda está na fila.

Co-Evolution

Tools for structured iterative refinement between AI agents and humans. Documents bounce back and forth between agents using disagreement markers until they converge, producing tighter and more precise output than any single agent would alone.

Default Usage

Start with the general Co-Evolution runner unless the task specifically needs code execution:

bash ./co-evolve-bouncer.sh --vanilla "stress test this idea"

For an existing markdown document:

bash ./co-evolve-bouncer.sh --vanilla --bounce-only docs/plan.md

Use dev-review only when you want a code-focused compose -> bounce -> execute -> verify workflow.

Prerequisites

Check your machine in one command — it lists everything below with an OK / MISSING / OPTIONAL verdict per item:

bash scripts/doctor.sh

What the components need:

  • Everywhere: Bash (3.2+ works, including stock macOS /bin/bash; 4+ recommended), git, jq, awk, and the claude CLI — logged in (run claude once interactively; an unauthenticated CLI is the most common silent failure).
  • Cross-AI passes and dev-review (default composer/executor): the codex CLI. co-evolve --vanilla works without it.
  • Eval harness (evals/) and PEL lab (lab/pel/): the mikefarah/Go yq (v4+), not the Python yq from Debian/Ubuntu's apt install yq, which is incompatible. Those components fail fast if the wrong yq is on PATH. xxd is used for byte-level eval diagnostics.
  • PEL PR emission: the gh CLI (dry-run mode works without it).
  • Per-phase timeouts: timeout(1) from GNU coreutils. Stock macOS lacks it — brew install coreutils — but a built-in perl fallback keeps timeouts working without it.

Installation

The runtime is plain Bash, so Co-Evolution installs the same way on every platform. You need a Bash shell, git, and the agent CLIs the bouncer calls — claude, plus codex for the default cross-AI pass. jq and yq (mikefarah's Go build) are only needed if you run the eval harness under evals/.

PlatformShell to run it inInstall git (+ optional jq/yq)
macOSTerminalbrew install git jq yq
Linuxany terminalapt install git jq, and yq from mikefarah
WindowsGit Bash (ships with Git for Windows) or WSLscoop install git jq yq

From the cloned repo, in that Bash shell, install the co-evolve command:

mkdir -p ~/.claude/skills/co-evolution ~/.local/bin
cp -R skills/co-evolution/* ~/.claude/skills/co-evolution/

cat > ~/.local/bin/co-evolve <<EOF
#!/usr/bin/env bash
cd "$PWD" || exit 1
exec bash ./co-evolve-bouncer.sh "\$@"
EOF
chmod +x ~/.local/bin/co-evolve

Make sure ~/.local/bin is on your PATH — echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc (use ~/.zshrc on macOS). Then the default command is:

co-evolve --vanilla "what should I do next?"

Optional code workflow:

mkdir -p ~/.claude/skills/dev-review
cp -R skills/dev-review/* ~/.claude/skills/dev-review/

Windows

Run from Git Bash or WSL rather than PowerShell or CMD — the tool is a Bash program. Two cross-platform details are handled for you:

  • Shell scripts are pinned to LF line endings (via .gitattributes), so they run correctly whatever your Git autocrlf setting is.
  • Path arguments are normalized: under WSL you can pass a Windows path such as C:\work\plan.md and it is converted automatically; under Git Bash, use forward slashes (C:/work/plan.md).

What's In This Repo

Co-Evolution Skill

/co-evolution is the default Claude Code skill for general questions, ideas, drafts, markdown files, plans, specs, and arguments. It routes to co-evolve-bouncer.sh and does not execute repo changes.

/co-evolution Stress test this launch plan

Co-Evolve Bouncer

The primary standalone runner. It can compose from a question, bounce an existing document, or run staged critique -> defend -> tighten passes.

bash ./co-evolve-bouncer.sh --vanilla "What is the strongest version of this argument?"
bash ./co-evolve-bouncer.sh --vanilla --chain "Should we ship this migration?"

Agent Bouncer

A standalone bash script that bounces any markdown document between two agents. Agent-agnostic: ships with Claude and Codex adapters, and new agents can be added by writing one function. Runs from any terminal.

# Pass any document you want refined
bash ./agent-bouncer/agent-bouncer.sh your-document.md

Codex Runtime

A standalone Bash runtime for the full dev-review compose -> bounce -> execute -> optional verify workflow. Use it when the task is a real repo change and you want a bounced plan, an execution trail, or a verifier pass outside Claude Code.

# Produce a plan and stop
bash dev-review/codex/dev-review.sh --plan-only "Add docs for the Codex runtime"

# Execute an approved plan file
bash dev-review/codex/dev-review.sh --skip-plan --plan .planning/phases/04-docs-and-routing/04-01-PLAN.md

Start with dev-review/codex/README.md for usage details and dev-review/codex/instructions.md when you want Codex to route between the repo entrypoints automatically.

Dev-Review Skill

/dev-review is a Claude Code skill that wraps the bounce protocol in a code-focused compose-bounce-execute-verify workflow. Use it inside Claude Code when the intended deliverable is a repo change, not a general answer or document refinement.

Lab

First-class beta channel for experimental features that could break the core runner if shipped prematurely. Opt-in only: users who never pass --lab <mode> see zero behavior change. See lab/README.md for the boundary conventions, graduation criteria, anti-criteria, and sandbox guarantee.

# Invoke a lab mode
co-evolve --lab pel-proposer "task"
bash dev-review/codex/dev-review.sh --lab pel-proposer "task"

Unknown modes fail fast with a list of available modes. There is no silent fallthrough.

Picking The Right Entrypoint

Task shapeTool
General question, idea, strategy, draft, or argumentco-evolve-bouncer.sh
Existing markdown document needs refinementco-evolve-bouncer.sh --bounce-only
Small, low-risk repo edit in 1-2 filesDirect execution
Multi-file code change, medium/high risk, or plan/verify workflowdev-review/codex/dev-review.sh
Codex builds in the background while the session plans and reviewsskills/codex-build/ (--preset codex-build, detached)
General co-evolution inside Claude Codeskills/co-evolution/
Code pipeline inside Claude Codeskills/dev-review/
External MCP client (Claude Desktop, Cursor, Continue)npm i -g @alanshurafa/co-evolution-mcp

MCP Server

The bounce protocol without git clone: @alanshurafa/co-evolution-mcp wraps the co-evolve bouncer as an MCP server with one co_evolve tool. External clients get the bounced document plus the v1.3 receipts — behavior scorecard, marker-fate ledger, human report — on every call. See mcp/README.md for install and client config.

The Bounce Protocol

The shared foundation. Two markers - [CONTESTED] and [CLARIFY] - coordinate structured disagreement between agents. Both auto-expire after 2 passes, guaranteeing convergence. The protocol is customizable: swap in domain-specific markers, adjust convergence rules, change role lenses.

Status

Early development. The Co-Evolution skill, Co-Evolve Bouncer, Agent Bouncer, Dev-Review skill, and standalone Codex runtime are functional and run cross-platform on macOS, Linux, and Windows (Git Bash or WSL) — shell scripts are pinned to LF endings and Windows/WSL path arguments are normalized automatically. Next steps:

  • Additional agent adapters (Gemini CLI, Ollama, direct API calls)
  • Standalone bounce protocol spec
  • Proper CLI (co-evolve bounce, co-evolve init)

License

MIT

Ver o original no GitHub

Bom para

Relacionados