Prepared by: Hermes (intelligence pipeline) · 2026-06-28 For: Pantheon fleet (fleet-standard candidate) · routed to Arsenal #7 Research tier: T-deep (decision-grade) — 4 parallel research lanes, every load-bearing claim verified against primary sources; the two highest-stakes claims (the adopt-not-build headline; the ETH empirical finding) independently re-verified by Hermes against the source repo/paper, not just sub-agent-reported. Source-coverage ledger §7. Scope: Trending GitHub repos optimizing CLAUDE.md / AGENTS.md / skills → a recommended harness-agnostic unified agent-environment targeting Claude Code · Codex · opencode · Pi, as a Pantheon fleet-standard. Deliverable = research report + recommended design. No build.
The unified agent-environment we were asked to design already exists as mature, MIT-licensed OSS. Building a Pantheon-custom unified format would be vaporware (rule #18 violation).
The field has converged on three layers, each with an established standard or tool:
| Layer | The convergence | Pantheon move |
|---|---|---|
| Instructions | AGENTS.md is the cross-harness standard (60k+ repos, Linux-Foundation-stewarded). Codex, opencode, Pi read it natively; Claude Code is the lone holdout (reads CLAUDE.md only) |
Author AGENTS.md; ln -s AGENTS.md CLAUDE.md |
| Skills / capabilities | SKILL.md / the agentskills.io open standard (Anthropic-authored, open-released) is natively portable across all four target harnesses |
Author skills to the base spec; place in .agents/skills/, mirror to .claude/skills/ |
| Config (MCP / hooks / permissions / commands) | divergent per harness (JSON vs TOML; declarative vs programmatic hooks). rulesync (MIT) generates all of it from one source — uniquely covers hooks and permissions |
Author once in .rulesync/; rulesync generate |
The only genuinely net-new, build-justified work is a thin fleet-broadcast wrapper over rulesync: one canonical ruleset → ~N constellation repos + a drift check. That is an orchestration layer over an existing tool, not a new standard — and it maps onto Pantheon's existing skill-symlink + rules-provenance machinery.
REQUIREMENT: One source of truth → per-harness instruction files + skills + MCP +
hooks + permissions, across Claude Code / Codex / opencode / Pi, fleet-wide.
PRIOR ART: rulesync (MIT, 1.2k★, ALL 8 dims incl. hooks+permissions — Hermes-verified
capability matrix); ruler (MIT, 2.8k★, rules+MCP+skills+subagents, ~25 agents);
block/ai-rules (Apache-2.0, 109★, rules+commands+skills+MCP);
AGENTS.md standard (60k+ repos, instruction-md only);
agentskills.io SKILL.md standard (portable across all 4 harnesses).
ADOPT PATH: rulesync as generator (only tool covering hooks+permissions, which the
Pantheon gate/credential/settings surfaces need) + AGENTS.md + SKILL.md.
BUILD JUSTIFY: NOT justified for format/sync. ONLY net-new = a fleet-broadcast wrapper
over rulesync (shared ruleset → N repos + drift check).
Three actively-maintained tools already unify agent config across harnesses. rulesync is the strongest match for Pantheon because it is the only one covering hooks and permissions — the dimensions the fleet's Moirai gates, vault guards, and settings.json allow/deny model depend on.
| Tool | License | ★ | Harnesses | Unifies | Key limitation |
|---|---|---|---|---|---|
| rulesync (dyoshikawa) | MIT | ~1.2k | 20+ (Claude Code, Codex, opencode, Cursor, Copilot, Gemini, Cline, Goose, Amp…) | rules · ignore · mcp · commands · subagents · skills · hooks · permissions (all 8 ✅ for Claude Code — verified) | per-repo single source; no cross-repo fleet broadcast; generates files, doesn't enforce drift |
| ruler (intellectronica) | MIT | ~2.8k | ~25 | rules + MCP + skills + subagents (no hooks/permissions) | no hooks/permissions; per-repo |
| block/ai-rules (Block/Square) | Apache-2.0 | ~109 | 11 | rules + commands + skills + MCP (no hooks/permissions) | smallest coverage; per-repo |
Verified (Hermes, direct scrape of rulesync README): capability matrix row
| Claude Code | ✅ rules | ✅ ignore | ✅ mcp | ✅ commands | ✅ subagents | ✅ skills | ✅ hooks | ✅ permissions |;
1.2k★ / 132 forks; last commit 2026-06-26 (active daily). [deep-read]
The standard — AGENTS.md: open instruction-file format (single predictable Markdown file), industry working group (OpenAI-convened, now Agentic AI Foundation / Linux Foundation). 60k+ repos; read natively by Codex, Cursor, Gemini CLI, Aider, VS Code, Zed. Standardizes only the filename + freeform markdown — deliberately NOT skills, hooks, MCP, permissions, subagents. It is the lowest-common-denominator instruction layer, which is exactly why a sync tool (above) is still needed for everything else. [deep-read]
Headline: the portable capability layer is SKILL.md / the agentskills.io open standard (originally Anthropic-authored, released as an open spec; ~40+ adopting tools). It is natively portable across all four target harnesses — closer to "author once, runs everywhere" than convert-on-export.
SKILL.md carrying name + description frontmatter, a markdown body, optional scripts/ references/ assets/. Progressive disclosure (discover name/desc → activate body → execute) is uniform across all four. [deep-read across all 4 harness docs]allowed-tools/context:fork; Codex agents/openai.yaml sidecar; opencode license/compatibility)..claude/skills/; Codex → .agents/skills/; Pi → .pi/skills/ + .agents/skills/; opencode reads all of them. .agents/skills/ is the emerging common ground (Codex + opencode + Pi); mirror/symlink to .claude/skills/ for Claude Code.Counter-intuitive correction — MCP is NOT the universal layer for these four. MCP is the portable external-tool layer and works on Claude Code, Codex, opencode — but Pi ships no native MCP (extension-only, by design). So for this specific four, SKILL.md has broader native reach than MCP. Skills (procedural knowledge) and MCP (external tools) are complementary, not substitutes. Any fleet design assuming MCP universality breaks on Pi.
Per-harness native config, the load-bearing input for any unified writer. All cells [deep-read] against each harness's official docs unless flagged.
| Dimension | Claude Code | Codex (OpenAI) | opencode | Pi |
|---|---|---|---|---|
| Project instr. file | CLAUDE.md only |
AGENTS.md (+.override.md) |
AGENTS.md (CLAUDE.md fallback) |
AGENTS.md (CLAUDE.md accepted) |
| Merge rule | concatenate, cwd-closest last | concatenate root→cwd, closest wins | merge (instructions key adds) |
concatenate global→cwd |
| Skills | SKILL.md @ .claude/skills/ |
SKILL.md @ .agents/skills/ |
reads .claude+.agents+.opencode skills |
SKILL.md (agentskills.io) @ .pi/skills/,.agents/skills/ |
| Subagents | .claude/agents/*.md |
agents/openai.yaml |
.opencode/agent[s]/*.md |
none native (extension only) |
| MCP client | .mcp.json (mcpServers), 3 scopes |
[mcp_servers.<id>] in config.toml |
mcp key in opencode.json |
none native ("No MCP") |
| Hooks | declarative hooks in settings.json (richest) |
hooks.json / [hooks] in config.toml |
programmatic via JS/TS plugins | programmatic via TS extensions (pi.on) |
| Permissions | permissions.{allow,deny,ask} |
approval_policy + sandbox_mode |
permission key |
CLI flags + Trust |
| Settings format | settings.json (JSON) |
config.toml (TOML) |
opencode.json/.jsonc |
settings.json (JSON) |
| Sandboxing | sandbox key |
sandbox_mode (3 levels) |
permission-gated (no OS sandbox) | none native |
Four structural takeaways:
From a 2,500-repo GitHub corpus, the agents.md spec, Anthropic best-practices, HumanLayer's 12-factor-agents (23.6k★), and an ETH Zurich empirical study. Bake the patterns in; respect the caveat.
The empirical caveat (load-bearing, Hermes-verified on arXiv): Gloaguen et al., "Evaluating AGENTS.md," arXiv:2602.11988 (v2, 2026-06-23, ETH Zurich). Across SWE-bench + real repos: context files do NOT generally raise task success, and add >20% inference cost — for both LLM-generated and human-committed files. Instructions ARE followed; repository-overview sections are NOT helpful. Conclusion: context files earn their cost only for non-standard practices; any performance claim must be evaluated before deployment. (Abstract direct-read; exact sub-percentages remain [snippet] — pull the PDF if a decision hinges on them.)
Pattern library:
file:line, @path imports) — never embed snippets that go stale..claude/agents/.Anti-patterns: auto-generation (/init — ETH: ~3% worse + >20% cost; treat /init as a draft to prune, not a finished file); repository-overview / directory-listing sections (empirically don't help — counter-intuitive, most templates include them); the bloated kitchen-sink file; code-style guidelines (linter's job); vague directives ("write clean code"); task-specific instructions in the always-loaded file; pasted code that drifts.
One genuine source conflict: Anthropic recommends
/init; the empirical literature (ETH + HumanLayer + philschmid) says don't auto-generate. Resolution:/initas scaffold, then hand-prune to a deliberate file.
A harness-agnostic agent environment, assembled entirely from adopted components + one thin wrapper.
6.1 Source of truth — three canonical artifacts per repo
AGENTS.md = the instruction file. Author here; ln -s AGENTS.md CLAUDE.md for Claude Code. Apply patterns P1–P12; drop repo-overview sections (ETH), keep specific non-standard practices (where context files actually pay off)..agents/skills/<skill>/SKILL.md to the agentskills.io base spec. Mirror/symlink to .claude/skills/ for Claude Code. Harness-specific frontmatter stays optional (degrades gracefully)..rulesync/ = the canonical source for the divergent layers (MCP servers, hooks, permissions, commands, ignore). rulesync generate emits each harness's native files (incl. Codex TOML, Claude settings.json hooks/permissions, opencode opencode.json).6.2 The one net-new build — fleet-broadcast wrapper over rulesync
The single gap no tool fills: one canonical fleet ruleset → ~N constellation repos + drift detection. This is exactly Pantheon's existing problem (today solved ad-hoc via skill-symlink-rewrite + ~/.claude/rules/ provenance). Recommendation: a thin wrapper that (a) holds the fleet-shared .rulesync/ baseline, (b) runs rulesync generate per repo, (c) flags drift between generated and committed files (an Argus/Talos check). Wraps rulesync; does not replace it.
6.3 Pi-specific carve-outs (the constraint)
Pi has no native MCP, declarative hooks, or subagents. For Pi targets: MCP servers reach Pi only via an mcporter (MCP→CLI) shim or a TS extension; declarative hooks/permissions degrade to extension code or are dropped. Decision the fleet must make: is Pi a first-class fleet harness (then budget the extension/shim work) or a best-effort target (instructions + skills only, no MCP/hooks)? This is the load-bearing fork for any Pi adoption.
6.4 What this buys One author surface; every constellation's instructions/skills/MCP/hooks/permissions render to Claude Code, Codex, opencode, and (within its limits) Pi from a single committed source — with drift caught automatically. Zero new file format, zero new standard, one small wrapper.
Tags: [deep-read] = primary source opened; [snippet] = search/third-party snippet; [training-knowledge]; [verified-hermes] = Hermes independently re-confirmed beyond sub-agent report.
| # | Claim | Tag | Source |
|---|---|---|---|
| 1 | rulesync covers all 8 dims (incl. hooks+permissions) for Claude Code; MIT; 1.2k★; active 2026-06-26 | [verified-hermes] | github.com/dyoshikawa/rulesync README capability matrix (direct scrape) |
| 2 | ETH study: context files don't generally raise success, +20% cost, instructions followed / overviews not helpful | [verified-hermes] | arXiv:2602.11988 v2 abstract (direct scrape) |
| 3 | ruler MIT ~2.8k★ ~25 agents, rules+MCP+skills+subagents, no hooks/permissions | [deep-read] | github.com/intellectronica/ruler |
| 4 | block/ai-rules Apache-2.0 ~109★, rules+commands+skills+MCP | [deep-read] | github.com/block/ai-rules |
| 5 | AGENTS.md standard, 60k+ repos, instruction-md only, LF-stewarded | [deep-read] | agents.md |
| 6 | SKILL.md / agentskills.io portable across all 4 harnesses; base format identical | [deep-read] | code.claude.com/docs/skills; developers.openai.com/codex/skills; opencode.ai/docs/skills; pi-mono skills doc; agentskills.io |
| 7 | Pi has no native MCP (extension-only, by design) | [deep-read]+[snippet] | badlogic/pi-mono README; pi.dev (MCP-absence corroborated, not single canonical line) |
| 8 | Per-harness config matrix (files/formats/hooks/permissions) | [deep-read] | each harness's official docs (ledger in lane-3 findings) |
| 9 | Codex uses TOML config.toml; others JSON/JSONC | [deep-read] | developers.openai.com/codex/config-reference |
| 10 | Authoring patterns P1–P13 + anti-patterns | [deep-read] | GitHub blog (2,500 repos); HumanLayer; Anthropic best-practices; philschmid; josix/awesome-claude-md |
| 11 | "tools named used 160× more"; ETH exact sub-percentages | [snippet] | philschmid reading of ETH §4.3 — NOT PDF-verified |
| 12 | Codex skills path .agents/skills vs community-cited ~/.codex/skills |
[deep-read]+flag | official docs authoritative; verify per CLI version |
Not execution-tested: no tool was run against actual Pantheon files this arc. Before fleet rollout, a rulesync generate smoke-test on one constellation repo converts the adopt recommendation from documented-capable to execution-verified (recommended as the first build step).
~/.claude/ + CLAUDE.md exclusively. Moving canonical authorship to AGENTS.md + .rulesync/ is a real migration — phase it (strangler-fig: generate alongside, cut over per-repo).