convez.ai
AgenteDevOps & InfraestruturaIntermediário
whanksta

Multi-Agent Setup

whanksta/Multi-Agent-Setup

Sistema único de instruções e auditoria para agentes de código multi-plataforma

Ver no GitHub
InicialPluginScore · de 0 a 100

Kit de configuração para coordenar múltiplos agentes de código (Claude Code, Codex, Antigravity) através de um sistema de instruções único e canônico. Inclui verificação estrutural de codebase com `codebase-audit` para garantir saúde do projeto antes de modificações.

Instalação

$npx convez-ai whanksta/Multi-Agent-Setup

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
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Manter consistência de regras entre diferentes agentes de IA
  • Auditar saúde estrutural do codebase antes de refatorações
  • Sincronizar automaticamente arquivos de instrução entre Claude Code, Codex e Antigravity

Veredito

Solução prática para orquestração de múltiplos agentes em projetos reais. Resolve um problema real (drift de instruções) com abordagem determinística baseada em symlinks e auditoria estrutural — recomendado para equipes usando várias plataformas de agentes simultaneamente.

README

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

MultiAgentSetup

Two things every multi-agent repo needs, wired once: one canonical instruction system that Claude Code, Codex, and Antigravity all read, and codebase-audit, a deterministic structural- health signal your agents run before touching risky code.

License: MIT Use this template works with

Start here: from inside your target repo, paste this link into your coding agent and tell it to set up (or update) the kit:

https://github.com/whanksta/Multi-Agent-Setup

The single adoption prompt below tells the agent exactly what to do — clone this repo for the exact files, replicate the kit-owned ones, merge only root CLAUDE.md, and run python3 scripts/docreview.py. The README and changelog are guidance for adoption only; the agent reads them but does not copy them into your repo unless you ask.

Changelog | Quick start | Manual install

Why This Exists

Different coding agents read different instruction files. Claude Code reads CLAUDE.md; Codex and Antigravity read AGENTS.md; skills live in different tool-specific folders. If those files are copied by hand, they drift.

MultiAgentSetup makes CLAUDE.md the single source of truth, exposes it to other agents through an AGENTS.md symlink, shares skills through a folder symlink, and ships docreview to verify and repair the wiring.

Two Pillars

This kit ships two core capabilities:

  1. Instruction-file wiring — CLAUDE.md is canonical; AGENTS.md and .agents/skills are symlinks so every agent reads the same bytes; docreview verifies and repairs that wiring and audits the docs for drift.
  2. codebase-audit — a deterministic, repo-agnostic structural-health signal. It decomposes size and layers in the git-temporal signals (churn, hotspot, temporal coupling) that actually predict where defects accrue, so an agent gets the wide quantitative picture before it judges what to refactor.

codebase-audit is signal, not a gate by design: it emits ranked evidence, never a pass/fail verdict, so it informs judgment instead of blocking work. That is a feature — the agent stays in control — not a disclaimer.

Quick Start

Two ways in. For a brand-new repo, use the GitHub template button — no agent needed. For an existing project (or to update an installed one), paste the single adoption prompt below; it detects which situation you're in and adapts.

New repo (template button)

Click Use this template, edit CLAUDE.md with your project's real rules, then run python3 scripts/docreview.py and expect docreview: PASS.

Existing or installed repo (one prompt)

Paste this into your agent from inside the repo you want to set up or update. The same prompt covers a fresh adoption, a repo that already has other agent files, and an update of an existing install:

Set up (or update) this repo with the MultiAgentSetup kit from
https://github.com/whanksta/Multi-Agent-Setup.

1. GET THE EXACT FILES. Clone the source so you have its real bytes — do not retype scripts from a
   web page:
       git clone --depth 1 https://github.com/whanksta/Multi-Agent-Setup /tmp/mas
   Read /tmp/mas/README.md and /tmp/mas/CHANGELOG.md for guidance only. Never copy the source's
   README.md or CHANGELOG.md into my repo unless I explicitly ask.

2. DETECT THE SITUATION:
   - My repo already has scripts/docreview.py  ->  UPDATE: read .claude/.mas-version, then apply
     only the CHANGELOG batches dated newer than it.
   - My repo has other instruction files (a real AGENTS.md, .cursorrules, GEMINI.md, scattered rule
     docs)  ->  PRE-CONSOLIDATE: fold their active rules into one canonical CLAUDE.md, dedupe, and
     preserve my conventions; then remove the redundant copies.
   - Neither  ->  FRESH install.

3. REPLICATE KIT-OWNED FILES EXACTLY from /tmp/mas (see the Adoption File Policy table for the full
   list + per-file action): scripts/docreview.py, .claude/skills/docreview/,
   .claude/skills/codebase-audit/, .githooks/pre-commit, and VERSION. Create AGENTS.md as a relative
   symlink to CLAUDE.md and .agents/skills as a folder symlink to .claude/skills. Add the needed
   .gitignore entries without removing unrelated ones.

4. MERGE ONLY ROOT CLAUDE.md — it is my repo's master instruction file. Blend the kit's wiring
   sections with my existing project rules; never overwrite them.

5. STAMP THE VERSION: copy /tmp/mas/VERSION into my repo as .claude/.mas-version so the next update
   knows its baseline.

6. Run python3 scripts/docreview.py, confirm it prints docreview: PASS, then summarize what changed
   and any adoption notes from CHANGELOG.md.

No git? Fetch each kit-owned file from https://raw.githubusercontent.com/whanksta/Multi-Agent-Setup/main/<path> (e.g. .../main/scripts/docreview.py), then follow steps 2–6 — or wire it yourself with Manual install.

Adoption File Policy

The agent's per-file contract. "Copy exactly" means byte-for-byte from the clone in step 1.

Source pathAgent action in target repo
README.md, CHANGELOG.mdRead for guidance and adoption notes only. Do not copy or overwrite target docs unless the user explicitly asks.
scripts/docreview.pyCopy exactly from the clone.
.claude/skills/docreview/Copy exactly into the canonical skill location.
.claude/skills/codebase-audit/Copy exactly — it is a core part of the kit, not an optional add-on.
.githooks/pre-commitCopy exactly (enable with git config core.hooksPath .githooks).
VERSIONCopy its value into the target as .claude/.mas-version to record the adopted version.
.gitignoreAdd required entries such as CLAUDE.local.md, *.clobbered-*, __pycache__/, and *.py[cod]; preserve unrelated target entries.
CLAUDE.mdMerge/blend wiring guidance with existing project instructions; never overwrite project rules blindly.
AGENTS.mdCreate as a relative symlink to CLAUDE.md after consolidating existing agent rules.
.agents/skillsCreate as a folder symlink to .claude/skills; do not copy skill files into the mirror.

What You Get

PathPurpose
CLAUDE.mdCanonical shared rulebook. Edit project rules here.
AGENTS.mdSymlink to CLAUDE.md for Codex and Antigravity.
.claude/skills/Canonical shared skills directory.
.agents/skillsFolder symlink to .claude/skills.
scripts/docreview.pyVerifies and repairs wiring; checks instruction-file size budgets.
.claude/skills/docreview/Agent skill for wiring checks and doc-doctrine review.
.claude/skills/codebase-audit/Core agent skill + script for structural hotspot/churn signals (advisory, not a gate).
VERSIONKit version string; copied into an adopting repo as .claude/.mas-version.
CHANGELOG.mdSource-side update notes for agents to read before adopting changes.

How It Works

AgentRulesSkills
Claude CodeCLAUDE.md.claude/skills/
CodexAGENTS.md -> CLAUDE.md.agents/skills -> .claude/skills
AntigravityAGENTS.md -> CLAUDE.md.agents/skills -> .claude/skills

AGENTS.md is a symlink, not a copy, because Codex and Antigravity read AGENTS.md but do not need a separate rulebook. They read the same bytes Claude Code reads from CLAUDE.md.

Skills use the same pattern. Author shared skills once in .claude/skills/; Codex and Antigravity see them through .agents/skills.

Daily Workflow

  • Edit shared rules in CLAUDE.md, never in AGENTS.md.
  • Edit shared skills in .claude/skills/, never in .agents/skills.
  • Run /docreview or python3 scripts/docreview.py after changing instruction files or skills.
  • Add scoped CLAUDE.md files only for real folder-specific rules or foot-guns; point to root doctrine and keep scoped files small.
  • Read CHANGELOG.md before pulling updates from this repo into an installed project.

Manual Install

Most users should paste the repo link into an agent. If you want to wire the files yourself:

git clone --depth 1 https://github.com/whanksta/Multi-Agent-Setup /tmp/mas
SRC=/tmp/mas
DST=.

mkdir -p "$DST"/{scripts,.claude/skills}
cp "$SRC"/scripts/docreview.py "$DST"/scripts/
cp -r "$SRC"/.claude/skills/docreview "$DST"/.claude/skills/
cp -r "$SRC"/.claude/skills/codebase-audit "$DST"/.claude/skills/
mkdir -p "$DST"/.githooks
cp "$SRC"/.githooks/pre-commit "$DST"/.githooks/
cat "$SRC"/.gitignore >> "$DST"/.gitignore
cp "$SRC"/VERSION "$DST"/.claude/.mas-version   # record the adopted version

if [ -e "$DST"/CLAUDE.md ]; then
  echo "CLAUDE.md exists; merge the wiring sections from $SRC/CLAUDE.md manually."
else
  cp "$SRC"/CLAUDE.md "$DST"/
fi

ln -snf CLAUDE.md "$DST"/AGENTS.md
python3 "$DST"/scripts/docreview.py   # also creates .agents/skills -> ../.claude/skills

For new repos, replace the template conventions in CLAUDE.md with your project's real rules. For existing repos, merge the source CLAUDE.md wiring sections into the current project instructions instead of overwriting them.

Compatibility

  • Claude Code: reads CLAUDE.md directly.
  • Codex: reads AGENTS.md, which points to CLAUDE.md.
  • Antigravity: reads AGENTS.md, which points to CLAUDE.md.
  • Cloud sync: OneDrive, Google Drive, and Dropbox on macOS preserve symlinks; Git stores symlinks portably as mode 120000.
  • Windows: symlinks require Developer Mode plus git config core.symlinks true, or an elevated shell. If symlinks check out as plain files, docreview will report the problem and repair it when the OS permits.
  • Gemini CLI: Google announced that individual/free, Pro, and Ultra Gemini CLI request serving ends on June 18, 2026, with those users moving to Antigravity CLI; enterprise and API-key access differs. See Google's transition note. This kit targets Antigravity through AGENTS.md and no longer ships GEMINI.md.

docreview

docreview has two jobs:

  1. Verify and repair the mechanical wiring: CLAUDE.md, AGENTS.md -> CLAUDE.md, and .agents/skills -> .claude/skills.
  2. Audit instruction docs for size, scope, drift, broken links, and authoring quality.

Run it anytime:

python3 scripts/docreview.py

If an agent clobbers a symlink with a real file, docreview backs up the divergent content to a *.clobbered-<timestamp> file before restoring the symlink.

To inventory folders that do not have scoped instruction files, use the report-only missing command. It does not create files or repair symlinks:

python3 scripts/docreview.py missing
python3 scripts/docreview.py missing --scope repo
python3 scripts/docreview.py missing --scope path --path path/to/subtree

The default scope is the current Git worktree. Use --scope repo / --scope whole-repo only when you explicitly want the repo that owns scripts/docreview.py. Missing scoped files are informational prompts: add a scoped CLAUDE.md only when that folder has a real folder-specific convention or foot-gun, then run the normal wiring check.

Requires Python 3.7+.

codebase-audit

codebase-audit emits a ranked health digest for source files: decomposed size, biggest symbol, biggest function, nesting, density, churn, hotspot, and temporal coupling. It is a thinking aid for agents, not a linter and not a gate.

Run a full audit from any wired repo:

python3 .claude/skills/codebase-audit/scripts/audit.py

The pre-commit hook runs audit.py --staged after docreview passes. That staged check is advisory and must always exit zero; do not add thresholds that block commits.

To verify the bundled script in this source repo, run the stdlib test suite:

python3 -m unittest discover -s tests

FAQ

Why a symlink instead of copying into AGENTS.md?

Copies drift. A symlink makes AGENTS.md read the same content as CLAUDE.md, with no sync step.

Can I keep private local instructions?

Yes. Put machine-local preferences in CLAUDE.local.md; it is ignored by Git.

What about rules for one subfolder?

Add a scoped CLAUDE.md only when that folder has a real convention or foot-gun not obvious from the code. Keep must-hold-everywhere rules in the root CLAUDE.md.

Does this survive a machine wipe?

Yes, as long as the repo is pushed to a Git remote. User-profile config such as ~/.claude/ is not the durable unit; the repo is.

How does an update know what changed?

On install the agent stamps .claude/.mas-version with the kit's VERSION. On the next update it reads that marker and applies only the CHANGELOG.md batches dated newer than it, then re-stamps — so updates are incremental and you can see exactly which version a repo is on.

License

MIT

Ver o original no GitHub

Bom para

Relacionados