Agent Foundry

Agent Foundry seeds a repository with policies that coding agents follow to turn a request into delivered and verified work.

Description

AGENTS.md routes each request to the workflow for its kind of change. Each workflow is a skill that chains action skills, such as a design, a plan, or a verification, which the user can also ask for alone. Every change workflow grows one work file, from .agents/templates/work.md, phase by phase: a Brief of goals with their checks and constraints, the decisions the user agrees, tasks that execution loops until their checks pass, stopping for the user after three failed attempts, and the verification's evidence. Its Brief answers any diagnosis or audit the work starts from. The workflows guide charts the workflows, their actions and documents, and where the work stops for the user.

The workflows and skills run in Claude Code 2.1.277 or later, Codex, and OpenCode, whose hooks, the shell check and the main-checkout guard, run in 1.x only. In Claude Code, .claude/settings.json denies the tools no skill uses, Workflow, ScheduleWakeup, ReportFindings, and ListAgents, whose definitions would add about 5k tokens to every call; that also turns off Claude Code's own /loop, Workflow runs, and /code-review findings, and no user's own settings can allow them again, so a repository that needs one deletes its line.

Dependencies

Every environment needs:

• Git 2.48 or later
• Bash
• ShellCheck 0.7.0 or later
• jq

Optional, but suggested:

• GitHub's gh or Forgejo's fj, logged in to the repository's host, so agents open pull requests, issues, and review comments themselves instead of handing over the text to paste
• Prettier 3, to keep Markdown in the format .prettierrc sets; maintaining this source requires it
• bubblewrap (bwrap, tested with 0.11.1), the sandbox review-pr, check-issue, and diagnose run code in, and the behavioral evals run agents in

Quick start

To adopt Agent Foundry into a repository that already exists:

1. Clone this source outside the repository.
2. Start an agent session at the repository's root and ask: "Adopt Agent Foundry from <clone> as its README's Quick start describes."
3. When the agent has copied the files, start a fresh session, which loads them, and ask it to carry on adopting from <clone>.
4. Answer its questions and approve the sections it drafts for AGENTS.md.

Later, ask an agent to upgrade the repository's agent policy: its foundry-upgrade skill merges the source's changes since the commit its Record names, following the source's UPGRADING.md. To check the repository's agent configuration for static consistency, run these from the repository's root; the validator, the clone's script, checks the target given as its argument, or the current directory:

<clone>/scripts/verify-agent-config.sh [<target>]
git diff --check <main branch>

A new repository, an umbrella workspace, and a repository adopted before the foundry-upgrade skill existed follow docs/INSTALL.md.

Adoption steps

The agent adopts the source in these steps, preserving what the repository already has, and reports any conflict it cannot reconcile.

1. Inspect the source read-only, and read the instructions the repository tracks for itself, root and nested, its README, ignore rules, build files, and CI.
2. Switch the main checkout to a new branch from the main branch, where every adoption step works, the adoption being the one change made in the main checkout since the worktree rule arrives with it, and copy the source's tracked AGENTS.md, .agents/, .claude/, .codex/, .opencode/, .gitignore, and .prettierrc. Merge AGENTS.md so nested AGENTS.md files carry over and the repository's own rules land as its Project rules subsection describes, and merge .gitignore entries, including AGENTS.local.md. Move the instructions of the repository's own CLAUDE.md and .claude/CLAUDE.md files into the matching AGENTS.md, then remove those files, and ask the user, for each CLAUDE file the repository does not track that sits beside or above one of the repository's own AGENTS.md files, such as CLAUDE.local.md, to move its content into AGENTS.local.md and remove the file or, where the repository has no nested AGENTS.md, to import its sibling AGENTS.md as Baseline instructions in AGENTS.md give it; tell the user every other workstation needs the same once the adoption lands. Then ask the user to start a fresh agent session, which loads the copied files. For Codex, complete Codex hook setup before continuing.
3. Read AGENTS.md, the existing code, and any project or CI evidence. Resolve the architecture summary from evidence or explicit user decisions into the Architecture section of AGENTS.md. Draft each subsection of its section How to interact with the project from the build files, CI, and documentation, and the user approves it: under its definition, a sentence or two on what the area holds, with commands in backticks and the directory they run from, and a link to the section of the project's documentation that holds it, or a note that the area does not apply. Project rules states the rules no project document holds, and links to those one does. For an area the documentation lacks, propose writing it in the repository's contributor guide, or in a new CONTRIBUTING.md when there is none, and link to it; a subsection describes the procedure itself only for an area the user chooses to leave undocumented. Replace each placeholder token and drop the commented examples.
4. Extend .gitignore for the project's stack. Keep .prettierrc only when the project has no Prettier configuration of its own, meaning no prettier key in package.json or package.yaml and no other .prettierrc* or prettier.config.* file.
5. Delete the template-state comment on the first line of AGENTS.md and its Template lifecycle section, which apply to the source only, and the Members section, which only an umbrella keeps; fill the Record of the foundry-upgrade skill with this source's location and the copied commit, and keep the repository's own README.
6. Run this source's validator against the repository, then the project's set-up, its full verification, and its tests when the verification does not run them, as its section How to interact with the project gives them, skipping an area that section says does not apply; then review the complete diff, commit, and run run-reviews on that tip, with this README, the source checkout's path, and the copied commit as the goal and the source's AGENTS.md and briefs as the rules; act on their findings as step 5 of UPGRADING.md does, and hand the branch to deliver, switching the main checkout back to the main branch before a merge, or once a pull request lands.

Codex hook setup

In the local Codex CLI, trust the project so its .codex/ configuration loads, then open /hooks. Review and trust the definitions from .codex/hooks.json, checking that the main-checkout guard (PreToolUse) and ShellCheck (PostToolUse) are both enabled and trusted. Do this on each workstation after adoption, and repeat the review when a hook definition changes. Codex skips hooks awaiting trust; the static validator checks their files, while /hooks shows their activation. See Codex hooks.

Maintenance

Changes to this source pass these checks, run from its root:

bash tests/verify-agent-config.sh
bash tests/check-work-folder.sh
.agents/hooks/shellcheck.sh repo
prettier --check '**/*.md'
scripts/verify-agent-config.sh
git diff --check main

A fold runs bash tests/verify-agent-config.sh, .agents/hooks/shellcheck.sh repo, prettier --check '**/*.md', and git diff --check HEAD^ at each commit, as its every-commit checks.

To rerun one area of tests/verify-agent-config.sh, run its file under tests/agent-config/, such as bash tests/agent-config/skills.sh; every file there but lib.sh is an area.

Behavioral evals

Before merging a change to AGENTS.md, a skill, a template, a brief, or a Claude reviewer's effort or model, the maintainer runs the behavioral evals, repeating the review-pr case for a reviewer's, or an agent does when the user asks, since each run is billed. They show what agents do under the policy rather than whether its files agree. evals/run.sh runs each case in evals/cases/ with Claude Code headless, in a bubblewrap sandbox, on a fresh copy of the toy repository in evals/fixture/ with the policy of a commit installed, and grades the outcome, the process the policy asks for, the work folder, and, in the review-pr case, whether each reviewer's report lists, among its findings, the defects seeded in a contributor's branch; evals/report.sh tabulates passes, turns, tokens, cost, and time, against a base run when given one. From the change's worktree, once its edits are committed:

base=$(evals/run.sh --policy main)
tip=$(evals/run.sh --policy HEAD)
evals/report.sh "$tip" "$base"

A failed attempt's reasons are in <run>/<case>/<n>/grade.txt, and the header of evals/run.sh lays out the rest of the attempt and how to add a case. The review-pr grader matches the words of each finding, so before a pass decides a reviewer's effort or model, read the reviewers' reports in the attempts' session transcripts.

A run bills the key in ANTHROPIC_API_KEY when it is set, else the Claude account the CLI is logged in to: about 7 USD and 25 minutes for the cases on the main branch's policy in October 2026, capped by --budget and --timeout per attempt.

License

Agent Foundry is released under the MIT No Attribution License in LICENSE.

References

• Codex AGENTS.md
• Claude Code memory and instruction files
• OpenCode agents
• Agent Skills best practices