Multi Agent Repo

Live context

!git rev-parse --show-toplevel 2>/dev/null && echo "cwd repo: $(basename "$(git rev-parse --show-toplevel)")" || echo "not a git repo" !gh auth status 2>&1 | head -1 || echo "gh: not available"

multi-agent-repo

Audit, plan, and implement canonical multi-agent repository setup: one AGENTS.md source of truth, thin adapters per tool, portable skills, and CI-enforced validation.

Why this skill exists

Teams running Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, and OpenCode in parallel often maintain a diverging instruction file per tool. Policies drift, context bloats past Codex's 32 KiB limit, and agents ignore duplicated rules. Worse, "which target supports hooks?" gets answered differently in three documents. The fix is structural: one canonical body per rule, a thin generated adapter per target, and one capability registry — core/capabilities/platforms.json — that every other file derives from. make check-feature-equivalence fails the build when two views of the platform set disagree. This skill runs review → plan → dev so you know what's missing, what order to fix it, and can land the full setup via PR. For quick file generation without a prior audit, use dev mode directly.

Supporting files

Required execution flow

1. Parse args with parse-mode-args.sh — do not guess mode from free text alone.
2. Run inventory + gap scoring before any rubric walk (review) or plan grouping.
3. Route to exactly one mode section; plan/dev may chain prior modes in the same turn.
4. Write outputs only to paths in references/mode-contracts.md.

Parse input

SKILL_DIR="$CLAUDE_SKILL_DIR"
PARSED="$(bash "$SKILL_DIR/scripts/parse-mode-args.sh" $ARGUMENTS)"
MODE="$(echo "$PARSED" | jq -r '.mode')"
TARGET_ROOT="$(echo "$PARSED" | jq -r '.target')"
DOC_PATH="$(echo "$PARSED" | jq -r '.doc_path // empty')"
CONSTRAINTS="$(echo "$PARSED" | jq -r '.constraints')"
DATE="$(date +%Y-%m-%d)"
INVENTORY="$(bash "$SKILL_DIR/scripts/inventory-agent-setup.sh" "$TARGET_ROOT")"
GAPS="$(echo "$INVENTORY" | bash "$SKILL_DIR/scripts/score-inventory-gaps.sh")"
REPO_TYPE="$(echo "$INVENTORY" | jq -r '.repo_type')"
REVIEW_PATH="$TARGET_ROOT/docs/agent-guidelines/multi-agent-review-$DATE.md"
PLAN_PATH="$TARGET_ROOT/docs/agent-guidelines/multi-agent-plan-$DATE.md"

Route to the matching section below. Do not skip review data in plan/dev when no prior doc path is given.

Mode: review (read-only)

Goal: Gap report vs canonical multi-agent layout. No repo edits except docs/agent-guidelines/ + report file.

Steps

1. Read references/target-layouts.md — note expected layout for $REPO_TYPE.
2. Run inventory and score-inventory-gaps.sh (already captured above). Read references/gap-scoring.md for auto vs manual split.
3. Start the report gap table from auto-scored $GAPS JSON.
4. Walk manual sections in references/audit-rubric.md (content quality, duplication, command accuracy). Merge new findings; dedupe by rubric ID.
5. mkdir -p "$TARGET_ROOT/docs/agent-guidelines"
6. Write $REVIEW_PATH using templates/review-report.md.tmpl.

Report structure

ALWAYS include these sections in order:

# Multi-agent review — [repo name]
## Executive summary
## Repo classification
## Gap summary (P1 / P2 / P3 counts)
## Findings table
| ID | Severity | Evidence | Remediation | Phase |
## Recommended next step
## Inventory appendix (JSON)

7. Print executive summary: repo type, P1/P2/P3 counts, path to report.

Stop. Do not edit AGENTS.md, CLAUDE.md, or rules in review mode.

Mode: plan

Goal: Phased remediation plan from review findings.

Steps

1. If user did not pass a review doc path, run review mode first in the same turn.
2. Read the review report ($DOC_PATH, user path, or latest multi-agent-review-*.md under docs/agent-guidelines/).
3. Group P1/P2 gaps into phases:

4. For each phase list: actions, files, implementation notes (references/platform-setup.md for phases 0–1), validation command, risk.
5. Write $PLAN_PATH from templates/remediation-plan.md.tmpl.
6. Present plan summary to user.

Stop unless mode is dev.

Mode: dev

Goal: Implement plan on feature branch; open PR. Never merge.

Preconditions

• Git repo at $TARGET_ROOT
• gh authenticated (gh auth status)
• Warn if working tree dirty; do not discard user changes

Steps

1. If no plan doc in arguments, run plan mode first.
2. Read plan doc ($DOC_PATH, user path, or $PLAN_PATH).
3. Create branch:

cd "$TARGET_ROOT"
BRANCH="feat/multi-agent-setup"
git checkout -b "$BRANCH" 2>/dev/null || git checkout -b "feat/multi-agent-setup-$(date +%s)"

4. Implement phases in order:

Phase 0–1 — platform files

Follow references/platform-setup.md for live doc fetch, AGENTS.md, CLAUDE.md (@AGENTS.md), and 000-project.mdc. Respect $CONSTRAINTS.

Phase 2–3 — local

• Add scoped .mdc rules (globs for src/tests/db per stack)
• Create docs/agent-guidelines/ stubs linked from AGENTS.md
• For app repos: ensure .agents/skills/ or document bridge
• For claude-plugin repos: keep skills/ per plugin.json — do not force .agents/skills/

Phase 4 — enforcement

• Copy or adapt scripts/check-agent-drift.sh, check-feature-equivalence.sh, and check-platform-targets.sh from _contract/scripts/ into target scripts/
• For Node repos: copy templates/check-no-agent-drift.mjs.tmpl → scripts/check-no-agent-drift.mjs
• Wire agent:rules or extend validate in Makefile / package.json scripts
• Add CI step if .github/workflows/ exists (mirror AGENTS.md validation command)

Phase 5 — feature equivalence + platform targets

• Scaffold missing manifests, .agents/skills/ bridges, platform-equivalence.md, and platform-targets.json per _contract/feature-equivalence.json
• Optional: Skill("platform-sync") read-only for latest platform versions

Phase 6 — validate

make agent-polish-gate
make platform-targets-sync (then update JSON/badges) and make platform-targets-assert
bash scripts/check-agent-drift.sh
# plus stack-specific command from AGENTS.md
bash "$SKILL_DIR/scripts/inventory-agent-setup.sh" "$TARGET_ROOT"

5. Commit in logical chunks (feat(agents): …, chore(ci): …).
6. Push and open PR:

git push -u origin HEAD
gh pr create --title "feat(agents): multi-agent repo setup" --body "$(cat <<'EOF'
<fill from templates/pr-body.md.tmpl>
EOF
)"

7. Print PR URL and re-inventory summary.

Stop at PR. User or pr-dev merges after approval.

Agent execution rule

Agents run Make targets — never ask the user to run bash scripts.

Users invoke /repo-standards polish or /multi-agent-repo dev — not manual make commands.

Anti-patterns (do not do these)

Hard rules

• AGENTS.md is canonical — CLAUDE.md and .mdc files point to it; never duplicate full policy text.
• ≤ 2 Cursor rules with alwaysApply: true.
• AGENTS.md ≤ 32 KiB — no Claude-only syntax in AGENTS.md.
• Plugin repos — respect existing skills/ layout; do not migrate to .agents/skills/ without explicit user request.
• Windows — prefer @AGENTS.md in CLAUDE.md over symlinks.
• Never force-push or push to branches other than the feature branch.
• Never merge the PR from this skill.

Relationship to other skills

Error handling

Example invocations

/multi-agent-repo
/multi-agent-repo review ../other-repo
/multi-agent-repo plan
/multi-agent-repo plan docs/agent-guidelines/multi-agent-review-2026-06-23.md
/multi-agent-repo dev
/multi-agent-repo dev . -- prioritize CI and drift checker only