create-team-foundry 1.0.0 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +128 -39
- package/dist/index.js +1118 -42
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,86 +1,175 @@
|
|
|
1
1
|
# team-foundry
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Make your AI coding outputs align with your product reality.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Your AI tool gives better answers when it knows what the product is for, who the customers are, and what quality means. team-foundry puts that context in your shared repo — where every AI tool on every teammate's machine reads the same files from the same repo.
|
|
6
6
|
|
|
7
|
-
```
|
|
7
|
+
```bash
|
|
8
8
|
npx create-team-foundry
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
**Run in your shared repo. Then say: `"Let's set up our team-foundry."`**
|
|
12
|
+
If your repo already has a README and commit history, setup takes about 1 minute — the AI reads your repo and pre-fills the answers. Starting fresh takes 15–25 minutes. Either way, your AI starts using the context immediately.
|
|
13
|
+
|
|
14
|
+
→ **[See what it looks like when populated](example/)** — a fully filled-in team-foundry for Clearline, a fictional 8-person B2B SaaS team. Open `example/` in Claude Code or Cursor and ask anything.
|
|
12
15
|
|
|
13
|
-
**
|
|
16
|
+
**[team-foundry.com](https://team-foundry.com)** · If this helps your team, [a star helps others find it](https://github.com/tomershahar/team-foundry).
|
|
14
17
|
|
|
15
18
|
---
|
|
16
19
|
|
|
17
|
-
##
|
|
20
|
+
## The problem
|
|
18
21
|
|
|
19
|
-
|
|
22
|
+
**Before team-foundry:**
|
|
23
|
+
> You ask the AI to help prioritize a sprint. It gives solid generic advice — but doesn't know your north star metric, hasn't seen your open assumptions, and has no idea that your top customer churned last month.
|
|
20
24
|
|
|
21
|
-
team-foundry
|
|
25
|
+
**After team-foundry:**
|
|
26
|
+
> The AI references your outcomes, flags an assumption that's been untested for 45 days, and notes that two roadmap items haven't been updated since 8 PRs shipped. It offers to draft the fixes. You confirm.
|
|
22
27
|
|
|
23
|
-
|
|
28
|
+
That context used to live in someone's head, a Notion page nobody reads, or a wiki 6 months stale. team-foundry puts it in your shared repo — where every AI tool reads it every session.
|
|
24
29
|
|
|
25
|
-
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npx create-team-foundry
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**Try it in 2 minutes.** Answer a few questions. Files appear. Open your AI tool. Done.
|
|
37
|
+
|
|
38
|
+
---
|
|
26
39
|
|
|
27
|
-
|
|
40
|
+
## Set up once. Everyone gets the same context.
|
|
28
41
|
|
|
29
|
-
**
|
|
42
|
+
**No cloud. No sync service. No extra accounts.** team-foundry uses your existing repo as the shared space.
|
|
30
43
|
|
|
31
|
-
|
|
44
|
+
**One person sets it up**
|
|
45
|
+
Run `npx create-team-foundry` in your shared repo. The CLI scaffolds a `team-foundry/` folder, generates the right tool file (`CLAUDE.md`, `GEMINI.md`, or `.cursor/rules/`), and commits everything to git.
|
|
32
46
|
|
|
33
|
-
|
|
47
|
+
**Everyone else pulls**
|
|
48
|
+
Teammates `git pull`. They now have the same team-foundry files locally. Their Claude Code, Cursor, or Gemini CLI reads from the same files yours does. No installs, no logins, no setup.
|
|
34
49
|
|
|
35
|
-
|
|
50
|
+
**Updates flow through git**
|
|
51
|
+
When someone updates a file — or the coach drafts an update they confirm — it's a normal git commit. Push, pull, review in PRs. Everyone stays in sync the same way they already sync code.
|
|
36
52
|
|
|
37
|
-
|
|
53
|
+
```
|
|
54
|
+
┌────────────────────────┐
|
|
55
|
+
│ Your shared repo │
|
|
56
|
+
│ (GitHub / GitLab) │
|
|
57
|
+
│ │
|
|
58
|
+
│ team-foundry/ │
|
|
59
|
+
│ ├─ outcomes.md │
|
|
60
|
+
│ ├─ customers.md │
|
|
61
|
+
│ ├─ decisions/ │
|
|
62
|
+
│ └─ ... │
|
|
63
|
+
└───────────┬────────────┘
|
|
64
|
+
│
|
|
65
|
+
git pull / push (no other sync)
|
|
66
|
+
│
|
|
67
|
+
┌─────────────────┼─────────────────┐
|
|
68
|
+
▼ ▼ ▼
|
|
69
|
+
┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
70
|
+
│ PM │ │ Engineer │ │ Designer │
|
|
71
|
+
│ Claude │ │ Cursor │ │ Gemini │
|
|
72
|
+
│ Code │ │ │ │ CLI │
|
|
73
|
+
└──────────┘ └──────────┘ └──────────┘
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
*Your repo is the shared space. Git is the sync. team-foundry adds the structure and the coach.*
|
|
77
|
+
|
|
78
|
+
---
|
|
38
79
|
|
|
39
|
-
|
|
80
|
+
## What gets created
|
|
81
|
+
|
|
82
|
+
**Solo profile (1–3 people):** 7 files, ~1 minute with repo scan / ~15 minutes fresh.
|
|
83
|
+
**Full profile (4–15 people):** 20 files, ~1 minute with repo scan / ~25 minutes fresh.
|
|
84
|
+
|
|
85
|
+
| Profile | Files | Includes |
|
|
86
|
+
|---|---|---|
|
|
87
|
+
| Solo | 7 | Root instruction file (CLAUDE.md/GEMINI.md), getting started guide, coach playbook, north star, outcomes, customers, stack |
|
|
88
|
+
| Full | 20 | Everything above + strategy, roadmap, assumptions, risks, trio, working agreement, AI practices, quality bar, decisions log, design principles, metrics, glossary, stakeholders |
|
|
89
|
+
| Full (federated) | 26 | Everything above + per-folder routing files for multi-instance setups |
|
|
40
90
|
|
|
41
|
-
|
|
42
|
-
- During setup you choose repo visibility (public / internal / private) and the coach adjusts its language accordingly
|
|
43
|
-
- Nothing in the generated files requires sensitive data — personas use first names, metrics use your definitions, decisions record rationale not revenue
|
|
91
|
+
Every file has YAML frontmatter (`purpose`, `read_when`, `last_updated`, `owner`) so the AI knows when to load it and why.
|
|
44
92
|
|
|
45
|
-
|
|
93
|
+
## Supported tools
|
|
94
|
+
|
|
95
|
+
| Tool | File generated |
|
|
96
|
+
|---|---|
|
|
97
|
+
| Claude Code | `CLAUDE.md` |
|
|
98
|
+
| Gemini CLI | `GEMINI.md` |
|
|
99
|
+
| Cursor | `.cursor/rules/team-foundry.mdc` |
|
|
100
|
+
| OpenAI Codex / generic agents | `AGENTS.md` |
|
|
101
|
+
| Both (Claude + Gemini) | `CLAUDE.md` + `GEMINI.md` |
|
|
46
102
|
|
|
47
103
|
## The coach
|
|
48
104
|
|
|
49
|
-
|
|
105
|
+
After setup, the coach watches your files for drift while you work. It runs in three modes:
|
|
50
106
|
|
|
51
|
-
- **Inline** — silent by default.
|
|
52
|
-
- **Explicit** —
|
|
53
|
-
- **Scheduled** —
|
|
107
|
+
- **Inline** — silent by default. Surfaces one sentence when a gap is directly relevant to what you're working on. Never interrupts.
|
|
108
|
+
- **Explicit** — `"let's do a team-foundry review"`. Full audit, all files, findings by severity.
|
|
109
|
+
- **Scheduled** — weekly check-in, top 3 findings, offers to draft fixes.
|
|
54
110
|
|
|
55
|
-
The coach never writes without your confirmation
|
|
111
|
+
**The coach never writes without your confirmation.**
|
|
56
112
|
|
|
57
|
-
###
|
|
113
|
+
### What it catches
|
|
114
|
+
|
|
115
|
+
| Pattern | Example |
|
|
116
|
+
|---|---|
|
|
117
|
+
| **Output-as-outcome drift** | `outcomes.md` says "ship the dashboard" instead of "reduce time-to-insight for SMB analysts" |
|
|
118
|
+
| **Assumption fossilization** | Core assumption logged 94 days ago, never retested, still driving three roadmap items |
|
|
119
|
+
| **Customer ghost syndrome** | Enterprise persona last interviewed in February. Three Q2 features built "for enterprise." |
|
|
120
|
+
| **Decision amnesia** | Q1 ADR rejects microservices. Q3 discussion reopens it with no reference to what changed. |
|
|
121
|
+
| **Reality drift** | 8 PRs shipped since `outcomes.md` was last updated. Coach cites the commit messages. |
|
|
122
|
+
| **Build-trap signal** | "Add collaborative editing" moves to Now with no linked assumption and no validation. |
|
|
58
123
|
|
|
59
|
-
|
|
124
|
+
Every finding cites the specific file, the specific content, and the evidence. Not "this looks stale."
|
|
125
|
+
|
|
126
|
+
### Triggering the coach
|
|
60
127
|
|
|
61
128
|
| What to say | What happens |
|
|
62
129
|
|---|---|
|
|
63
|
-
| `"let's do a team-foundry review"` | Full audit — all files
|
|
64
|
-
| `"coach mode"` | Same as above |
|
|
130
|
+
| `"let's do a team-foundry review"` | Full audit — all files, findings by severity |
|
|
65
131
|
| `"review our outcomes"` | Targeted review of one file |
|
|
66
|
-
| `"
|
|
67
|
-
| `"run the weekly
|
|
132
|
+
| `"tell me about feature X"` | Synthesizes status, rationale, customer evidence, open bets |
|
|
133
|
+
| `"run the weekly review"` | Top 3 issues, draft fixes offered |
|
|
68
134
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
If you find the inline nudges too frequent, add this to your `CLAUDE.md` (or `GEMINI.md`):
|
|
135
|
+
## Status command
|
|
72
136
|
|
|
137
|
+
```bash
|
|
138
|
+
npx create-team-foundry status
|
|
73
139
|
```
|
|
74
|
-
|
|
75
|
-
|
|
140
|
+
|
|
141
|
+
Health table across all your files: last updated, days since update, PRs shipped since then, owner, health classification (ok / stale / empty / missing). Link integrity checks flag outcomes with no linked assumption, Now items with no validated bet, and metrics referenced but not defined.
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
npx create-team-foundry
|
|
76
147
|
```
|
|
77
148
|
|
|
78
|
-
|
|
149
|
+
**Run in your shared repo. Then say: `"Let's set up our team-foundry."`**
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## What's next
|
|
154
|
+
|
|
155
|
+
**v2.x**
|
|
156
|
+
- `--json` output for `status` — pipe findings into CI or dashboards
|
|
157
|
+
- `--strict` mode — fail CI when critical drift is detected
|
|
158
|
+
- MCP server — expose team-foundry context as a tool for agents that don't read files natively
|
|
159
|
+
|
|
160
|
+
**v3 (exploring)**
|
|
161
|
+
- Cross-repo federation — one team-foundry for a platform team read by multiple product repos
|
|
162
|
+
- Status webhooks — post weekly drift report to Slack without leaving the terminal
|
|
163
|
+
- Team onboarding flow — guided interview for new team members joining an existing team-foundry
|
|
164
|
+
|
|
165
|
+
Have a use case or feature idea? [Open an issue](https://github.com/tomershahar/team-foundry/issues).
|
|
166
|
+
|
|
167
|
+
---
|
|
79
168
|
|
|
80
169
|
## Requirements
|
|
81
170
|
|
|
82
171
|
- Node 18+
|
|
83
|
-
- Claude Code, Gemini CLI, or any AI tool that reads files from your repo
|
|
172
|
+
- Claude Code, Gemini CLI, Cursor, or any AI tool that reads files from your repo
|
|
84
173
|
|
|
85
174
|
## Contributing
|
|
86
175
|
|