v0.5.1 Agent plugin for Codex, Claude Code & Agent Plugins hosts
SWE Foundry turns a coding agent into a disciplined engineering partner. It carries your project from a rough idea — or an existing codebase — through design, planning, implementation, review and release, keeps every decision in your repository so any session can pick up where the last one stopped, and checks its delivery promises with commands instead of trusting prose.
I have an idea for an app that helps a shared workshop manage tool lending. Help me structure it.
Foundry
Routing to foundry-discover. I saved a first brief and recorded the decisions so far. Next question: who can borrow tools — only members, or also guests vouched for by a member?
docs/engineering/BRIEF.mddraft.swe-foundry/state.jsonrev 3.swe-foundry/history.jsonlchainedWhen the scope is settled: “Use foundry-design on the brief to prepare the PRD and architecture.”
Why Foundry
A single chat can produce an impressive diff. A product needs requirements that stay true, plans that survive the session, and claims backed by evidence. Foundry adds that missing layer — without adding a platform.
Requirements, architecture, ADRs, backlog and a revision-checked, digest-chained history live next to the code. Nothing important depends on a model remembering a long conversation.
Test runs, CI on the current head, review verdicts and provider read-backs are recorded as they happen. Simulated checks are never presented as live ones.
Test-driven development with a verifiable red commit, small increments, current design documents, security, operability and performance budgets — with Standard or Advisory discipline and explicit overrides.
Refine an idea for weeks, publish a backlog, and implement a selected story in a different session. Each issue carries an executable plan that is re-checked against current code; empirical unknowns become bounded spikes.
After author checks and CI, a reviewer in a fresh context — the strongest model unless you choose another — checks the exact pull request revision against a fixed rubric, and its verdict is published on the PR. Where the host offers no separate context, that is disclosed. Findings come back to you — nothing is merged or auto-fixed behind your back.
Reconcile work with Jira or GitHub through the connectors your agent already has, or export a validated Jira CSV. Foundry never ships credentials or pretends a remote write happened.
The lifecycle
Every phase is a focused skill. Finishing one never silently starts the next: Foundry tells you what is complete, where it is saved, and proposes the most useful next step.
foundry-discover
Start from something rough. Foundry organizes what is known, challenges unsupported assumptions and asks one substantive question at a time. Decisions, alternatives and open questions are saved, so the conversation can span many sessions without losing depth. When only an experiment can settle a question, it proposes a spike instead of guessing.
Try“Use foundry-discover for thorough idea refinement only. Explore the idea with me one question at a time.”
foundry-design
Requirements, architecture, contracts, quality strategy and decision records — kept current and consistent. Facts available in the code are inspected; real product choices become questions for you. Products with an interface get an optional brand identity and design-system proposal, offered once.
Try“Use foundry-design on the brief to prepare the PRD and architecture; stop before backlog creation.”
foundry-backlog · foundry-sync
Epics, stories, tasks, bugs, debt and spikes with testable acceptance criteria, justified dependencies and an executable plan in each description. Small fixes take the lite tier: one issue add call. Publish to Jira or GitHub with verified read-back, or export a lossless Jira CSV.
Try“Turn this PRD into stories with acceptance criteria and dependencies, then publish them to GitHub.”
foundry-implement
Pick the issues to build. Foundry re-reads their plan against the current code and lands a failing test(<ISSUE>) commit before the implementation. The strongest model coordinates; a medium-tier worker can take a whole planned unit. Delivery is a pull request on a typed branch, with current CI and deliver-check.
Try“Implement STORY-001 now.”
foundry-review
A fresh reviewer context receives the request, the approved plan, the exact diff and the check evidence — not the author’s conversation. It covers a fixed rubric, reproduces the red commit, and its verdict is published on the PR bound to the reviewed head. Then control comes back to you.
Try“Review this pull request against its plan and acceptance criteria.”
foundry-release
A versioned release kit keeps every version copy in step, prepares a release PR from one frozen commit and, only after you merge it, tags and publishes the artifacts with checksums. Rollback constraints are recorded, and post-release feedback flows straight into new backlog items.
Try“Prepare release 1.2.0 from develop and stop before publishing.”
Greenfield
“Use Foundry to refine this idea, design the first increment, and prepare an implementable backlog.”
Evolution
“Use Foundry to add this capability to the existing product, updating requirements before implementation.”
Adoption
“Use Foundry to understand this repository and establish a trustworthy baseline before fixing the reported bug.”
How it works
Skills handle the conversation and the engineering decisions. A small standard-library Python runtime, four agents and two hooks handle what must be exact. Your repository holds the result.
Nine composable Markdown skills guide dialogue, design, planning, delivery and review inside the agent you already use.
Self-validating apply, close, deliver-check, review-publish, sync planning, CSV export and the release kit. Python 3.11+, no packages to install.
Documents in docs/engineering/, state.json and a digest-chained history.jsonl in .swe-foundry/, plus a copied tools bundle your CI can run.
foundryStart, route and resume work.foundry-adoptReconstruct an existing repository’s baseline.foundry-discoverRefine ideas and changes through dialogue.foundry-designRequirements, architecture, contracts and ADRs.foundry-backlogTraceable work with meaningful dependencies.foundry-syncReconcile Jira or GitHub, or export CSV.foundry-implementSelected work through reviewed PR delivery.foundry-reviewReview designs or code and verify findings.foundry-releaseAuthorized releases and the feedback loop.The strongest model coordinates and reviews; cheaper tiers take whole planned units. Agents run at depth one and never write shared state. Claude Code loads them with the plugin; Codex projects can generate equivalents with init --codex-agents. Your recorded model choices win.
foundry-implementerMedium tier. One PR-sized unit from a precise plan, test commit first.foundry-reviewerStrongest tier, fresh context. The final review against the rubric.foundry-researcherMedium tier. Spikes and source-cited research.foundry-mechanicSmall tier. Fully specified mechanical edits only.You stay in control
Foundry follows only the phases your request authorizes. It recommends; you decide.
Guarantees
More instructions do not make an agent more compliant. A guarantee is real only when a deterministic command checks or performs it, so Foundry ships those commands and runs them at the right moments.
deliver-checkBefore handoff, one command lists what the pull request still lacks: branch and base, CI on the head, a published review covering the rubric, validation, issue status, English prose, lockfiles, spike scope and version consistency.
A test(<ISSUE>) commit must fail on behavior before the implementation lands. The check replays red on that commit and green on the head, so TDD is evidence, not a claim.
apply and closeEvery state change is one revision-checked write that validates the result. close records a delivery stage — issue status, evidence, backlog view and approved digest — in a single call.
review-publishThe final review is published on the pull request with a marker bound to the reviewed head, and its receipt stays local, so the head never changes just to record its review.
A guardrail hook blocks merges and auto-merge unless you recorded an authorization for the pull request’s base branch, and force-pushes without a separate grant. A Stop hook runs deliver-check once before the agent finishes. One hooks file serves Codex and Claude Code.
A benchmark with real headless agent runs compares the plugin with plain agent work. In the October 2026 campaign every measured guarantee held in all 12 plugin runs, and three of four overhead targets were met.
Get started
Requirements: a coding agent with repository access, Python 3.11+ and Git. No Python packages, virtual environments or background services. GitHub and Jira tools are optional until you ask for remote work.
Get swe-foundry-0.5.1.zip from the release page. The GitHub-generated “Source code” archive is not the packaged plugin.
In the Codex desktop app open Plugins → Add → Upload plugin archive and select the ZIP. Leave it compressed. To update, use the archive replacement control and check that the displayed version matches the release.
Codex skips plugin hooks until you trust them: run /hooks in the Codex CLI, review the two Foundry hooks and trust them.
Want the four agents as Codex custom agents? Run init --codex-agents in the project. Prefer local marketplaces? Follow the marketplace steps in the installation guide shipped with the plugin.
Extract the complete swe-foundry directory, including hidden folders, then validate and load it. The agents and hooks load with the plugin.
claude plugin validate /path/to/swe-foundry --strictclaude --plugin-dir /path/to/swe-foundryLoad the extracted directory with your host’s local-plugin mechanism; plugin.json declares Agent Plugins 1.0.0 and the skills follow Agent Skills. Keep skills/, references/, templates/, schemas/, scripts/, agents/ and hooks/ together.
No native plugin support? Ask your agent to read skills/foundry/SKILL.md from the extracted folder.
Confirm Python can run the helpers. Nothing in your projects is changed.
python3 /path/to/swe-foundry/scripts/foundry.py --helpStart a fresh conversation in your repository, attach SWE Foundry and describe the outcome you want. You don’t need to name a skill — Foundry routes the request.
Use Foundry to understand this repository and propose the next useful step.Runs inside the agent you already use. Keeps everything in your repository.