{"id":51351109,"url":"https://github.com/tomershahar/team-foundry","last_synced_at":"2026-07-02T16:01:04.806Z","repository":{"id":352235996,"uuid":"1213579661","full_name":"tomershahar/team-foundry","owner":"tomershahar","description":"A CLI that scaffolds shared context for AI coding tools. Outcomes, customers, decisions, quality bar  in your repo.","archived":false,"fork":false,"pushed_at":"2026-06-09T19:29:52.000Z","size":3126,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T21:15:57.767Z","etag":null,"topics":["ai","ai-tools-","claude-code","cli","cursor","developer-tools","gemini-cli","product-management","team-context","typescript"],"latest_commit_sha":null,"homepage":"https://team-foundry.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomershahar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-17T14:30:17.000Z","updated_at":"2026-06-09T19:29:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tomershahar/team-foundry","commit_stats":null,"previous_names":["tomershahar/team-foundry"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/tomershahar/team-foundry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomershahar%2Fteam-foundry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomershahar%2Fteam-foundry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomershahar%2Fteam-foundry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomershahar%2Fteam-foundry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomershahar","download_url":"https://codeload.github.com/tomershahar/team-foundry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomershahar%2Fteam-foundry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35053492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-tools-","claude-code","cli","cursor","developer-tools","gemini-cli","product-management","team-context","typescript"],"created_at":"2026-07-02T16:00:42.098Z","updated_at":"2026-07-02T16:01:04.789Z","avatar_url":"https://github.com/tomershahar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# team-foundry\n\n**Your coding agents know the code. They usually do not know which customer matters,\nwhat the team is optimizing for, or why a decision was made. team-foundry turns that\nmissing product context into versioned files your team's AI tools can load from the repo.**\n\n[![npm](https://img.shields.io/npm/v/create-team-foundry)](https://www.npmjs.com/package/create-team-foundry)\n[![npm downloads](https://img.shields.io/npm/dw/create-team-foundry)](https://www.npmjs.com/package/create-team-foundry)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n```bash\nnpx create-team-foundry\n```\n\nOr try a populated fictional team without changing your repo:\n\n```bash\nnpx create-team-foundry playground\n```\n\n## Controlled comparison\n\nOn July 2, 2026, two fresh Codex background agents received the **same prompt**, runner\nconfiguration, and Clearline repository snapshot, with no model override. The runner did\nnot expose the exact model ID. The control could not read team-foundry context; the other\ncould. We fixed the five-point scoring rubric before running either case.\n\n\u003e **Prompt:** Our deploys are slow. Should we automate database migrations in CI? Give\n\u003e a recommendation and implementation constraints.\n\n| Without team-foundry | With team-foundry |\n|---|---|\n| **\"Automate migration validation in CI and execution in the deployment pipeline.\"** | **\"Automate migration validation in CI, but do not automatically execute production migrations yet.\"** |\n| 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.** |\n\nIn this controlled example, repository context changed the recommendation rather than\nmerely making it longer. See the [complete first responses, fixed rubric, and reproduction\nnotes](docs/evidence/f07-controlled-comparison.md), plus the source\n[decision](example/team-foundry/engineering/decisions/ADR-005.md).\n\nThe same fixture produced this real health report:\n\n```text\nteam-foundry doctor\n\nContext health: 80/100  Needs attention\n\n  Completeness      30/30   16/16 required files contain real content\n  Freshness          0/20    0/16 populated files are current\n  Connectedness     25/25    3/3 integrity rule families clean\n  Ownership         10/10   16/16 existing files have an owner\n  Tool routing      15/15    4/4 pointer files reference AGENTS.md\n```\n\nClearline is a frozen Q2 example, so Doctor correctly flags its April context as stale.\nThe score was preserved rather than improved by changing dates for the demonstration.\n\n## See the difference in 60 seconds\n\n```bash\nnpx create-team-foundry playground\n```\n\nThis 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:\n\n- *\"What are we working toward this quarter?\"*\n- *\"Should we prioritize collaborative editing?\"*\n- *\"What architecture decisions have we made and why?\"*\n\nInstead of inferring answers from code, the AI can cite the team's outcomes, customers, risks, and decisions. The same example lives in [`example/`](example/) if you would rather browse it.\n\n---\n\n![Three teammates - PM on Claude Code, Engineer on Cursor, Designer on Gemini CLI - connected to a shared AGENTS.md](assets/hero.svg)\n\n## What gets generated\n\nA real, populated `AGENTS.md` looks like this. Tools that support `AGENTS.md` read it directly; team-foundry generates thin pointer files for tools with their own instruction format.\n\n```markdown\n# Agents\n\n## Project overview\n\n**clearline** — Finance teams at mid-market companies close their month-end\nwithout chasing anyone.\n\n## Where to find context\n\n| Topic | Path |\n|---|---|\n| Vision and north star metric | team-foundry/product/north-star.md |\n| This quarter's outcomes      | team-foundry/product/outcomes.md  |\n| Who our customers are        | team-foundry/product/customers.md |\n| Tech stack and conventions   | team-foundry/engineering/stack.md |\n| Architecture decisions       | team-foundry/engineering/decisions/ |\n```\n\n…and an outcome it routes to reads like a PM wrote it, not a template:\n\n```markdown\n### O1 — AP leads process month-end in under 2 days\nBaseline: 4.1 days average (cohort data, Q1 2026). Target: ≤2 days.\nSignal: time-to-close in approval routing data, tracked per cohort.\nWhy it matters: month-end duration is the #1 complaint in NPS verbatims.\n```\n\n### Before / after\n\n| | What the AI sees |\n|---|---|\n| **Before team-foundry** | Each teammate's AI guesses from code + whatever they paste into chat |\n| **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 |\n| **After onboarding** | Outcomes, customers, decisions, and quality bar - selected tools receive the same repo-owned context |\n\n### Who edits what\n\n- **You edit** everything under `team-foundry/` (outcomes, customers, decisions…). These are your team's words.\n- **The CLI generates and owns** the pointer files (`CLAUDE.md`, `GEMINI.md`, `.cursor/rules/…`) and the `AGENTS.md` scaffold. Re-running is safe — it merges in place.\n- **Keep it honest** with `npx create-team-foundry status` (and `status --ci` in CI).\n\n---\n\n## How it works\n\nOne person runs `npx create-team-foundry` in the shared repo. The CLI generates `AGENTS.md`\nas the shared routing map plus documented adapters for the selected tools. Commit and push;\nteammates receive the same repository-owned context through Git.\n\nNo cloud. No sync service. No accounts. Git is the sync.\n\n---\n\n## Supported tools\n\n| Tool | Loading mechanism |\n|---|---|\n| Codex | Reads `AGENTS.md` natively |\n| Claude Code | `CLAUDE.md` imports `@AGENTS.md` |\n| Gemini CLI | `GEMINI.md` imports `@./AGENTS.md` |\n| Cursor | Root `AGENTS.md` plus an always-applied rule reference |\n| GitHub Copilot | Repository instructions ask Copilot to follow `AGENTS.md`; route requires surface-specific verification |\n| Other tools | `AGENTS.md` only - confirm support in your tool version |\n\nSee the [evidence-labeled compatibility matrix](docs/compatibility.md) for official loading\ncontracts, exact generated paths, and which tools have been exercised locally.\n\n---\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `npx create-team-foundry` | Scaffold context into the current repo (interactive) |\n| `npx create-team-foundry adopt` | Import existing `.cursorrules`/`CLAUDE.md`/etc. before scaffolding |\n| `npx create-team-foundry playground` | Drop a populated example team into `team-foundry-playground/` |\n| `npx create-team-foundry doctor` | Score context health and show the highest-leverage fix |\n| `npx create-team-foundry status` | Health table: stale, empty, missing, link-integrity, owners |\n| `npx create-team-foundry status --ci` | Same checks, non-interactive, exits 1 on drift (for CI) |\n| `npx create-team-foundry init-ci` | Write a GitHub Action that runs the drift gate on every PR |\n| `npx create-team-foundry feedback` | Open a prefilled GitHub issue to send feedback |\n| `npx create-team-foundry migrate` | Upgrade an existing install to the latest profile |\n\n---\n\n## Learn more\n\n- [How it works](docs/how-it-works.md) — architecture, AGENTS.md primacy, pointer files, detect-and-merge, drift detection\n- [Tool compatibility](docs/compatibility.md) — native vs adapter loading, exact output matrix, and verification status\n- [Drift gate in CI](docs/ci.md) — `status --ci`, the GitHub Action, and what fails a build\n- [The coach](docs/coach.md) — drift detection patterns, trigger phrases, three modes, the flywheel\n- [Claude Code skills](docs/skills.md) — six slash commands and their file layout\n- [Profiles](docs/profiles.md) — solo, full, federated; file counts and frontmatter\n- [Migrating](docs/migrate.md) — upgrade paths from v2 and v3.x to v3.3\n- [Getting buy-in](docs/getting-buy-in.md) — handling team objections\n- [Changelog](CHANGELOG.md)\n\n---\n\n## Feedback\n\nThe most useful question is not \"do you like it?\" It is: **would you use team-foundry again, and why?**\n\nRun `npx create-team-foundry feedback` to open three short, prefilled questions, or [answer on GitHub](https://github.com/tomershahar/team-foundry/issues/new). Rough notes are more useful than polished praise.\n\n---\n\n## Requirements\n\nNode 18+. Claude Code, Gemini CLI, Cursor, or any AI tool that reads files from your repo.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomershahar%2Fteam-foundry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomershahar%2Fteam-foundry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomershahar%2Fteam-foundry/lists"}