Your coding agents know the code. They do not know which customer matters, what the team decided, or what quality bar applies — so each teammate's AI gives different answers to the same question. team-foundry turns that missing product context into one shared, versioned layer that Claude Code, Cursor, Gemini CLI, and Codex all read from the repo.
Try a populated fictional team in 10 seconds, without changing your repo:
npx create-team-foundry playgroundOr set it up for your own team:
npx create-team-foundryLocal-first and MIT licensed — no backend, no API keys, no telemetry. Each tool's loading route is verified in the compatibility matrix.
On July 2, 2026, two fresh Codex background agents received the same prompt, runner configuration, and repository snapshot of Clearline — the fictional team the playground generates. Both ran on the runner's default model (the runner does not report which); neither case used a model override, so the comparison is like-for-like. The control could not read team-foundry context; the other could. We fixed the five-point scoring rubric before running either case.
Prompt: Our deploys are slow. Should we automate database migrations in CI? Give a recommendation and implementation constraints.
| Without team-foundry | With team-foundry |
|---|---|
| "Automate migration validation in CI and execution in the deployment pipeline." | "Automate migration validation in CI, but do not automatically execute production migrations yet." |
| Sensible generic safeguards, but it conflicts with Clearline's existing decision. Score: 0/5. | Cited two prior incidents, three prevented near-misses, Marcus and Priya's ownership, customer-trust risk, and the active ADR. Score: 5/5. |
In this controlled example, repository context changed the recommendation rather than merely making it longer. See the complete first responses, fixed rubric, and reproduction notes, plus the source decision.
The same fixture produced this real health report:
team-foundry doctor
Context health: 80/100 Needs attention
Completeness 30/30 16/16 required files contain real content
Freshness 0/20 0/16 populated files are current
Connectedness 25/25 3/3 integrity rule families clean
Ownership 10/10 16/16 existing files have an owner
Tool routing 15/15 4/4 pointer files reference AGENTS.md
Clearline is a frozen Q2 example, so Doctor correctly flags its April context as stale. The score was preserved rather than improved by changing dates for the demonstration.
npx create-team-foundry playgroundThis creates a populated example team in team-foundry-playground/. Open that folder in Claude Code, Cursor, Gemini CLI, Codex, or another tool that reads repository instructions, then ask:
- "What are we working toward this quarter?"
- "Should we prioritize collaborative editing?"
- "What architecture decisions have we made and why?"
Instead of inferring answers from code, the AI can cite the team's outcomes, customers, risks, and decisions. The same example lives in example/ if you would rather browse it.
A real, populated AGENTS.md looks like this. Tools that support AGENTS.md read it directly. For tools with their own instruction format, team-foundry generates a small adapter file (like CLAUDE.md or a Cursor rule) whose only job is routing that tool to AGENTS.md.
# Agents
## Project overview
**clearline** — Finance teams at mid-market companies close their month-end
without chasing anyone.
## Where to find context
| Topic | Path |
|---|---|
| Vision and north star metric | team-foundry/product/north-star.md |
| This quarter's outcomes | team-foundry/product/outcomes.md |
| Who our customers are | team-foundry/product/customers.md |
| Tech stack and conventions | team-foundry/engineering/stack.md |
| Architecture decisions | team-foundry/engineering/decisions/ |…and an outcome it routes to reads like a PM wrote it, not a template:
### O1 — AP leads process month-end in under 2 days
Baseline: 4.1 days average (cohort data, Q1 2026). Target: ≤2 days.
Signal: time-to-close in approval routing data, tracked per cohort.
Why it matters: month-end duration is the #1 complaint in NPS verbatims.| What the AI sees | |
|---|---|
| Before team-foundry | Each teammate's AI guesses from code + whatever they paste into chat |
Right after npx create-team-foundry |
AGENTS.md with project overview, stack, and owners auto-detected from your package.json, README, and git — the rest scaffolded as visible gaps to fill |
| After onboarding | Outcomes, customers, decisions, and quality bar - selected tools receive the same repo-owned context |
- You edit everything under
team-foundry/(outcomes, customers, decisions…). These are your team's words. - The CLI generates and owns the pointer files (
CLAUDE.md,GEMINI.md,.cursor/rules/…) and theAGENTS.mdscaffold. Re-running is safe — it merges in place. - Keep it honest with
npx create-team-foundry status(andstatus --ciin CI).
One person runs npx create-team-foundry in the shared repo. The CLI generates AGENTS.md
as the shared routing map plus documented adapters for the selected tools. Commit and push;
teammates receive the same repository-owned context through Git.
No cloud. No sync service. No accounts. Git is the sync.
| Tool | Loading mechanism |
|---|---|
| Codex | Reads AGENTS.md natively |
| Claude Code | CLAUDE.md imports @AGENTS.md |
| Gemini CLI | GEMINI.md imports @./AGENTS.md |
| Cursor | Root AGENTS.md plus an always-applied rule reference |
| GitHub Copilot | Repository instructions ask Copilot to follow AGENTS.md — not yet verified end-to-end (help wanted) |
| Other tools | AGENTS.md only - confirm support in your tool version |
See the evidence-labeled compatibility matrix for official loading contracts, exact generated paths, and which tools have been exercised locally.
| Command | What it does |
|---|---|
npx create-team-foundry |
Scaffold context into the current repo (interactive) |
npx create-team-foundry adopt |
Import existing .cursorrules/CLAUDE.md/etc. before scaffolding |
npx create-team-foundry playground |
Drop a populated example team into team-foundry-playground/ |
npx create-team-foundry doctor |
Score context health and show the highest-leverage fix |
npx create-team-foundry status |
Health table: stale, empty, missing, link-integrity, owners |
npx create-team-foundry status --ci |
Same checks, non-interactive, exits 1 on drift (for CI) |
npx create-team-foundry init-ci |
Write a GitHub Action that runs the drift gate on every PR |
npx create-team-foundry feedback |
Open a prefilled GitHub issue to send feedback |
npx create-team-foundry migrate |
Upgrade an existing install to the latest profile |
- How it works — architecture, AGENTS.md primacy, pointer files, detect-and-merge, drift detection
- Tool compatibility — native vs adapter loading, exact output matrix, and verification status
- Drift gate in CI —
status --ci, the GitHub Action, and what fails a build - The coach — drift detection patterns, trigger phrases, three modes, the flywheel
- Claude Code skills — six slash commands and their file layout
- Profiles — solo, full, federated; file counts and frontmatter
- Migrating — upgrade paths from v2 and v3.x to v3.3
- Getting buy-in — handling team objections
- Changelog
The most useful question is not "do you like it?" It is: would you use team-foundry again, and why?
Run npx create-team-foundry feedback to open three short, prefilled questions, or answer on GitHub. Rough notes are more useful than polished praise.
Node 18+. Claude Code, Gemini CLI, Cursor, or any AI tool that reads files from your repo.
See CONTRIBUTING.md.
MIT