Foundry

Foundry is the marketplace that lists the Foreman, Hush and Razor plugins for Claude Code and Codex. The plugins are Git submodules pinned by commit; this repository holds the two catalogs, the release procedure, the README contract the plugins share, the brand kit their images come from and the benchmark harness that measures them. Foreman and Razor also run on Antigravity, which has no catalog: its users install a plugin directory from a Foundry clone, which checks the plugin out at its pinned commit, and Antigravity reads that plugin's own root plugin.json and hooks.json. Nothing is installed here except one package in benchmarks/, the Agent SDK that live --sdk runs need, and the only build is the artwork under brand/. The plugins run their hooks and tests with Node.js 22 or later and Git; Foreman needs Git 2.25 or later.

Start here

• For installation and the plugin table, read README.md.
• Before changing a catalog or cutting a release, read the release procedure.
• Before changing a plugin or flint, read its own AGENTS.md; each submodule is a separate repository with its own rules, tests and changelog.
• Before editing or reviewing a plugin README, read the README contract.
• Before adding or removing Antigravity in a skill's compatibility line, read the Antigravity skills record.
• Before changing any banner, icon, host card, Ember scene or evidence graphic, read the brand guide.
• Before writing or changing a mod (a hooks module that draws in Claude Code), read the native-look rules.
• Before changing benchmarks/ or starting a run, read the benchmarks README; a live run starts paid model sessions.
• To add, pick, correct or close roadmap work, use Foreman (/foreman:foreman). Foundry's ROADMAP.jsonl and .foreman/ are local and ignored; read the pitfall on old commits before any checkout.

Rules that outrank everything

• A catalog entry never carries a version. The version lives in the plugin's manifests, and a release moves only source.sha and the gitlink.
• A plugin listed in both catalogs pins the same main commit in both. Hush ships for Claude Code only and stays out of the Codex catalog. Antigravity needs no catalog entry; a plugin that ships for it carries a root plugin.json with the same version as its other manifests.
• Plugin source changes happen in the plugin's repository on a topic branch, never as loose edits on the pinned checkout.

Commands

Run from the repository root unless a row names another directory.

CI runs .github/workflows/validate-marketplace.yml on pushes and pull requests to main. Its validate job is the check the default branch's ruleset requires. It checks both catalogs: no entry carries a version, each has a full source.sha and a ref, each name is a submodule path whose gitlink names that same commit, and a plugin in both catalogs has one pin. Then it runs claude plugin validate .. A gitlink moved off its pin therefore fails CI. The cut-release step 4 pin check and shared-copy check stay local steps, because they read the plugin checkouts and CI checks out no submodules.

Where things live

Conventions

CLAUDE.md imports this file; keep shared project facts here. Codex reads this file directly.

Each plugin keeps its README, AGENTS.md, tests and docs/knowledge/changelog.md in its own repository. Edit them there, merge into that plugin's main, then re-pin here through the release procedure. This repository carries no single plugin's documentation, only the README contract the three share.

Pitfalls

• Old commits track the roadmap. Commits before 23db23e8 track ROADMAP.jsonl and .foreman/, so checking one out, or a reset or rebase across it, replaces or deletes the local roadmap. Copy both outside the repository first, or read old commits with git show or a separate worktree.
• A fresh clone leaves every plugin on a detached HEAD at its pin. A commit made there lands on no branch; switch to a branch in the plugin first.
• A plugin checkout serves one session at a time. When another task holds a branch or uncommitted edits in foreman/, hush/ or razor/, work in a separate worktree under the root's ignored .private/: git -C <plugin> worktree add ../.private/<plugin>-<id> -b <branch> main, where <id> names your task. The post-edit hook reruns the worktree's suite after an edit in its scripts/ or hooks/. To compare its committed shared copies before merge, run node scripts/check-shared-copies.js --<plugin> .private/<plugin>-<id>, which reads that plugin at the worktree's HEAD and the others at their pins. When an entry changes a shared file in several plugins, pass one override per worktree in the same run; one worktree alone is compared with the others' old pins. For a flint worktree, --flint <dir> reads that worktree's HEAD and compares its output-styles/hush.md with Hush's. After the branch merges, remove it with git -C <plugin> worktree remove ../.private/<plugin>-<id>.
• A desktop-app worktree keeps the plugin worktree inside it. A session the desktop app started in its own worktree under .claude/worktrees/ adds the plugin worktree there. First run git -C <app worktree> rev-parse --show-toplevel. When it prints the Foundry root, called <root> below, the app folder is not a worktree and Git there acts on the root: if the folder is empty, run git -C <root> worktree add --detach <app worktree> main; if it is not empty, stop and report it rather than clear it, because that command then fails with already exists. Otherwise run git -C <app worktree> switch --detach main. After either command, .private/ is ignored there; add the plugin worktree at <app worktree>/.private/<plugin>-<id>. Pass that absolute path to --<plugin>, as in node scripts/check-shared-copies.js --<plugin> <app worktree>/.private/<plugin>-<id> <root>, because a relative override resolves against the root argument, not the current directory.
• A pushed gitlink ships to Antigravity. Claude Code and Codex install the catalog's source.sha, but a Foundry clone checks each plugin out at its gitlink, and Antigravity installs that checkout. A release moves both together; never push a main where they differ.
• git submodule update moves each plugin back to its pin. It stops on uncommitted edits to tracked files; untracked files stay.
• An Antigravity install is a copy of a checkout, not a pin. agy plugin install copies the directory it is given; a plugin checked out anywhere but its pinned commit installs that other state. An install takes a new release only when its user pulls the clone, runs git submodule update --init and installs again.
• A plugin's assets/ holds copies. An image edited there is overwritten by the next copy from brand/; change the kit, rebuild, then copy.
• Codex trusts the Foundry root, not a worktree. Codex loads .codex/agents/ and .codex/hooks.json only in a trusted project, and it keys that trust on the main checkout's path. From a worktree, trust the Foundry root, as in codex -c "projects.'<root>'.trust_level='trusted'"; Codex reports a worktree path under projects as an ignored setting. Project trust loads the hooks, but each hook runs only after the owner also trusts it in Codex's /hooks step, which only the owner persists.
• Codex's /hooks trust covers a hook's registration, not its script. The trust records a hash of the hook's event, matcher and handler settings: its command, timeout and other handler fields. Codex keys that trust on the absolute path of .codex/hooks.json, so a hook trusted in one checkout is not trusted in another. A changed registration stays off until the owner trusts it again; a changed hook script needs no new trust. From a worktree, the owner runs that trust step as codex --no-daemon, because a long worktree path breaks the TUI's socket.