claudiomaradonna/agent-foundry
claudiomaradonna/agent-foundry
Template
1
0
Fork 0
Code Issues Pull requests Activity Actions
A lean Git repository template for disciplined AI-agent development with Claude Code, Codex and OpenCode.
580 commits 5 branches 0 tags 6.4 MiB
  • Shell 98.2%
  • JavaScript 1.8%
Find a file Use this template
Exact
Motoko Kusanagi 725055a1f3
All checks were successful
Maintenance / checks (pull_request) Successful in 4m32s
Details
Maintenance / checks (push) Successful in 3m59s
Details
fix(agents): point a trimming workflow to its audit 
Since 612d6b6 the rule that a workflow whose change is also a trim
first runs implement-feature step 1 was reachable only from the end of
that skill's description, so an agent routed to fix-bug could skip the
audit. The pointer is a sentence of the routing bullet rather than a
bullet of its own, and the migration that moved the old bullet now
tells the two apart; Prettier rewraps the rest of its paragraph.

Refs: #220
2026-11-12 19:03:47 +00:00
.agents fix(deliver): name both first-push errors 2026-11-12 14:27:30 +00:00
.claude
.codex
.forgejo feat(templates): aim PR bodies at outside readers 2026-11-11 11:06:33 +00:00
.opencode
docs docs: say the landing merge always asks 2026-11-11 09:38:05 +00:00
evals
scripts
tests fix(deliver): name both first-push errors 2026-11-12 14:27:30 +00:00
.gitignore
.prettierrc
AGENTS.md fix(agents): point a trimming workflow to its audit 2026-11-12 19:03:47 +00:00
LICENSE
README.md docs: say the landing merge always asks 2026-11-11 09:38:05 +00:00
UPGRADING.md fix(agents): point a trimming workflow to its audit 2026-11-12 19:03:47 +00:00

README.md

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 its Brief to the evidence of its verification. The workflows guide charts the workflows, their actions and work 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. Adoption also brings two hooks and a Claude Code settings file, which act on every session as Hooks and settings describes.

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
  • bubblewrap (bwrap, tested with 0.11.1), the sandbox review-pr, check-issue, and diagnose run code in
  • socat, with bubblewrap, for Claude Code's own sandbox on Linux and WSL2

Quick start

A new repository, an umbrella workspace, and a repository adopted before the foundry-upgrade skill existed follow docs/INSTALL.md. 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; on Codex, trust the hooks in it as Codex hook setup describes. Then ask it to carry on adopting from <clone>.
  4. Answer its questions and approve the sections it drafts for AGENTS.md.

The agent follows the adoption steps of the install guide, which end with the commands that check the repository's agent configuration.

Hooks and settings

Agent Foundry's two hooks run in each client: the main-checkout guard refuses an edit that the client's file-editing tool is about to make in a main checkout on its main branch, since every change happens in a worktree, and the shell check runs ShellCheck on each shell script such a tool writes. The header of each script in .agents/hooks/ gives the cases it covers, and a refusal says its reason. In OpenCode, whose 2.1.4 plugin API the hooks are written against, they run in 2.x only, and the tests exercise the plugins against stubs of the hooks, so they have not yet run in OpenCode itself.

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. The same file turns off auto memory, the attribution lines Claude Code adds to commits and pull requests, its telemetry plugin, and the built-in skills it lists, such as the browsers and computer use.

The same file keeps secrets from Claude. Its Read deny rules refuse Claude's file tools, and the file commands Claude Code recognizes in Bash when they name the file, the files that hold secrets in most projects: .env files, the examples included; secrets directories; private keys, certificates, and keystores; Terraform variables and state; and service-account and client-secret files. The rules hold in every permission mode.

It turns on Claude Code's Bash sandbox for one purpose, to keep those secrets from every command as well: on macOS, Linux, and WSL2 a recursive search, a glob, and a program a command starts are refused the files, where the rules alone stop Claude's file tools and a recognized file command that names the file. Inside the sandbox the sixty credential variables the settings name are unset for each command too, and every other variable stays set. Where bubblewrap or socat is missing on Linux and WSL2, or on Windows, commands run unsandboxed, and only the Read rules hold.

The sandbox is open to everything else. Sandboxed commands reach every host and every Unix socket, which a commit signed through an agent needs, and write anywhere in your home directory, and nothing asks before one in Manual and acceptEdits mode; only plan mode and auto mode's classifier review it. So git pull and git push run inside the sandbox, unasked. The keys and logins of your home directory are readable to a command and to Claude's file tools. The sandbox is therefore no defence against an instruction injected into what Claude reads: such a command can send what it reads, sign and authenticate with each key an agent holds, change the files the clients load as policy, and leave the sandbox, through a socket that runs commands for it, such as Docker's, or by rewriting a script that runs outside it, a hook or run-sandboxed.sh under .agents/, or a file git or your shell loads from the home directory.

Two commands run outside the sandbox, with your full access: git merge --ff-only --end-of-options <rev>, which lands a branch in the main checkout and always asks first, and .agents/scripts/run-sandboxed.sh, which builds a bubblewrap sandbox of its own and asks as your permission mode decides. Any other command that fails inside the sandbox may be retried outside it, as your permission mode and allow rules decide, and there too only the Read rules hold and every variable stays set.

The settings' Edit ask rules have Claude's file tools ask you before they edit the files that configure the agents: .agents/, AGENTS.md, AGENTS.local.md, the CLAUDE files, .claude/, .codex/, and .opencode/, at the project root and every depth below it, the worktrees included. They ask in every permission mode, bypassPermissions included. A shell command that writes those files asks nothing more: inside the sandbox it writes them unasked, but for .claude/settings.json, .claude/settings.local.json, .claude/skills, and .claude/hooks, which Claude Code keeps read-only there, and outside it your permission mode and allow rules decide.

A repository deletes the entry of a tool or setting it needs, and a rule it cannot live with; a developer adds rules and entries in .claude/settings.local.json, or turns the sandbox off there, since only the repository's own file loses a deny or ask rule. The sandbox guide says what a command meets inside the sandbox, when one runs outside it, how deep each secret rule reaches, and how to tune it.

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.

Codex subagent permissions

Codex subagents inherit the parent session's sandbox and approval settings. Set those permissions on the parent before delegating; implementers need write access to their assigned worktree. Reviewers and the advisor follow read-only instructions within those inherited permissions, rather than a separate read-only sandbox. See Codex's permission controls.

Upgrading Agent Foundry

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.

Maintenance

To change this source, follow docs/MAINTENANCE.md.

License

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