Skip to content

README.md

Latest commit

 

History

History
76 lines (61 loc) · 3.5 KB

README.md

File metadata and controls

76 lines (61 loc) · 3.5 KB
Raw

agents-md-orchestrator

Audit, prune, and sync your CLAUDE.md / AGENTS.md files across all your projects — propose-then-approve, with best-practice digests as the yardstick. Works with Claude Code and Codex.

Memory files rot: best practices shift, files bloat until the model ignores them, and every project drifts in its own direction. This orchestrator gives you one place to scan, audit, and fix them — with an inventory, an audit log, and date-stamped best-practice digests as the yardstick.

How it works

Open this folder in Claude Code or Codex. The orchestrator instructions (CLAUDE.md) drive a propose-then-approve workflow:

  1. Scan your managed folders for projects and their memory files
  2. Compare each against the digests in best-practices/
  3. Propose a diff per project — nothing is written without your approval
  4. Apply approved diffs
  5. Log the outcome in your inventory

Setup

git clone https://github.com/Goodsmileduck/agents-md-orchestrator
cd agents-md-orchestrator
claude   # then: "set me up"
# or
codex    # then: "set me up"

Setup discovers your project folders, asks a few questions (caution levels, folders to skip), and writes SCOPES.md (your folder list) and PROJECTS.md (your inventory). Both are gitignored — your project names stay private. Prefer manual config? Copy SCOPES.example.md to SCOPES.md and fill it in.

What's in the box

File Purpose
CLAUDE.md (+ AGENTS.md symlink) Orchestrator instructions: workflow, safety rules
best-practices/claude-code.md Digest of the official Claude Code guidance
best-practices/codex.md Digest of the official Codex AGENTS.md guidance
SCOPES.example.md Template for your managed-folder config
PROJECTS.example.md Inventory format reference
.claude/skills/setup/ Workflow spec: interactive first-run setup — discover folders, build your config
.claude/skills/scan-projects/ Workflow spec: regenerate the inventory from your scopes (bundled scan script)
.claude/skills/audit-memory-file/ Workflow spec: per-project audit — score, propose diff, apply, log
.claude/skills/seed-memory-file/ Workflow spec: bootstrap a minimal CLAUDE.md for projects that have none
.claude/skills/refresh-best-practices/ Workflow spec: check the official docs for changes and update the digests
.agents/skills (symlink) Lets Codex load the same skills natively

Claude Code loads .claude/skills/* as skills; Codex loads the same files through the .agents/skills symlink. CLAUDE.md also routes each workflow to its SKILL.md path as a fallback, so one set of workflow specs stays the source of truth for both tools.

Opinions baked in

  • One source of truth per project: CLAUDE.md as the file, AGENTS.md as a symlink to it — Claude Code and Codex read the same content, no drift.
  • Propose-then-approve, always. The orchestrator never edits another project silently.
  • Relocate, don't delete. Oversized memory files get split: always-needed rules stay, reference material moves to docs/ behind plain-path pointers (not @imports, which load eagerly).
  • Caution levels. Work/client repos get per-project diffs and a no-new-files constraint — guidance lives at scope root, outside the repos.
  • Evidence-grown files. Rules get added when the agent actually makes the mistake, not speculatively (per both vendors' guidance).

License

MIT