agentleFS
Tamircohen28Tamircohen28/tamirs-superpowers/skills/repo/multi-agent-repo/SKILL.md

multi-agent-repo

Skill2 starsChanged 4 months agoMITView on GitHub

Use when auditing or setting up a repository for multi-agent development across Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, and OpenCode. Triggers: multi-agent repo, audit agent setup, AGENTS.md gaps, make this repo work with Claude and Cursor, add Codex, Gemini CLI or OpenCode support, generate cursor rules from AGENTS.md, capability registry, agent drift, canonical AGENTS.md, multi-agent-repo review, plan or dev.

  • Commits and pushes

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. About 0 are common, 5 are distinctive, and 13 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 13

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run inventory + gap scoring before any rubric walk (review) or plan grouping.

    line 77
  2. Very specific:

    Write outputs only to paths in references/mode-contracts.md.

    line 79
  3. Very specific:

    Read references/target-layouts.md — note expected layout for $REPO_TYPE.

    line 108
  4. Very specific:

    Run inventory and score-inventory-gaps.sh (already captured above).

    line 109
  5. Very specific:

    Start the report gap table from auto-scored $GAPS JSON.

    line 110
  6. Very specific:

    Write $REVIEW_PATH using templates/review-report.md.tmpl.

    line 113
  7. Distinctive:

    ALWAYS include these sections in order:

    line 117
  8. Distinctive:

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

    line 132
  9. Distinctive:

    If user did not pass a review doc path, run review mode first in the same turn.

    line 142
  10. Very specific:

    Read the review report ($DOC_PATH, user path, or latest multi-agent-review-*.md under docs/agent-guidelines/).

    line 143
  11. Very specific:

    Write $PLAN_PATH from templates/remediation-plan.md.tmpl.

    line 158
  12. Distinctive:

    If no plan doc in arguments, run plan mode first.

    line 177
  13. Very specific:

    Read plan doc ($DOC_PATH, user path, or $PLAN_PATH).

    line 178
  14. Very specific:

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

    line 191
  15. Very specific:

    Add scoped .mdc rules (globs for src/tests/db per stack)

    line 195
  16. Very specific:

    Create docs/agent-guidelines/ stubs linked from AGENTS.md

    line 196
  17. Very specific:

    Add CI step if .github/workflows/ exists (mirror AGENTS.md validation command)

    line 205
  18. Very specific:

    Commit in logical chunks (feat(agents): …, chore(ci): …).

    line 222

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

PathWhen to read
references/mode-contracts.mdParse arguments; know stop conditions per mode
references/target-layouts.mdClassify app vs claude-plugin vs hybrid
references/audit-rubric.mdFull checklist for review mode
references/gap-scoring.mdAuto vs manual rubric mapping
references/platform-setup.mdFetch docs + generate AGENTS.md and thin adapters (phases 0–1)
references/platform-specs.mdSchema fallback when live doc fetch fails
scripts/parse-mode-args.shDeterministic mode/target parsing
scripts/inventory-agent-setup.shRe-export → ../_contract/scripts/
scripts/score-inventory-gaps.shRe-export → ../_contract/scripts/
scripts/check-agent-drift.shRe-export → ../_contract/scripts/
templates/*.md.tmplReport, plan, and PR body shapes

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="$(bash "$SKILL_DIR/scripts/score-inventory-gaps.sh" <<<"$INVENTORY")"
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)
  1. 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:
PhaseFocus
0Canonical AGENTS.md
1Thin adapters: CLAUDE.md (@AGENTS.md), .cursor/rules/000-project.mdc
2Scoped .mdc rules + docs/agent-guidelines/{testing,security,style}.md
3Portable skills (.agents/skills/ or plugin skills/ per repo type)
4Copy check scripts + makefile-agent-targets.mk.tmpl into Makefile; wire agent:check in CI
5Feature equivalence — manifests, bridges, MCP, platform-equivalence.md (see _contract/feature-equivalence.json)
5bPlatform targets — Skill("platform-sync") read-only; update platform-targets.json + README Row 3 badges
6Run validation scripts; re-inventory; P1 must be 0
  1. For each phase list: actions, files, implementation notes (references/platform-setup.md for phases 0–1), validation command, risk.
  2. Write $PLAN_PATH from templates/remediation-plan.md.tmpl.
  3. 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 signed in to the repository's host (gh repo view succeeds in $TARGET_ROOT; it resolves the host from the remote)
  • 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)"
  1. 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"
  1. Commit in logical chunks (feat(agents): …, chore(ci): …).
  2. 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
)"
  1. 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.

WhenAgent runs
After wiring scripts/Makefilemake agent:check
Before polish PR (multi-platform)make agent-polish-gate (syncs targets, asserts current, full check)
After changing repo skills (tamirs-superpowers)make platform-targets-sync then update platform-targets.json + README Row 3

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

Anti-patterns (do not do these)

Anti-patternWhy it fails
Editing AGENTS.md in review modeReview is read-only except the report path
Skipping review before dev on unfamiliar reposMisses P1 gaps; run review or plan first unless user explicitly wants quick dev
Duplicating AGENTS.md into CLAUDE.md or .mdcDrift on next policy change; violates thin-adapter model
More than 2 alwaysApply: true Cursor rulesContext bloat; Codex/Cursor ignore overflow
Skipping score-inventory-gaps.shManual rubric walk alone misses deterministic P1s inconsistently
Merging the PR from this skillUser or pr-dev owns merge after review

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

SkillWhen to use instead
repo-standardsFull Tamir repo standards (README, docs, CI, multi-agent) — uses shared _contract
repo-scaffoldGreenfield repos — output must pass app-gold contract
plan-devBreak arbitrary features into GitHub issues
start-devImplement a feature issue, not agent infrastructure
pr-devDrive the PR to merge after dev mode opens it

Error handling

SituationAction
Target not a directoryAsk for valid path; stop
Not a git repo in dev modeStop; suggest review/plan only
gh not signed inStop; ask the user to sign in to the GitHub CLI
Platform doc fetch partial failureLog platform; use references/platform-specs.md fallback; continue
Inventory shows P1 after devList remaining gaps; do not claim complete

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.