create-team-foundry 1.0.0 → 2.0.0

package/README.md

@@ -1,19 +1,25 @@
 # team-foundry
 
-**Give your AI coding tool the context it needs to be a real product partner.**
+**A Context Engine for product teams.**
 
-`npx create-team-foundry` scaffolds a `team-foundry/` directory of structured files — outcomes, customers, decisions, quality bar, strategy — in a format that Claude Code, Gemini CLI, and other AI tools read natively as context.
+team-foundry scaffolds the shared brain your AI coding tools read from — outcomes, customers, decisions, quality bar — in a repo every team member commits to. Every AI tool, every team member, the same context. Automatically.
 
 ```
 npx create-team-foundry
 ```
 
-That's it. Answer 4 questions. Files appear in your repo.
+Answer 4 questions. Files appear in your repo. That's it.
 
-**Run this in your shared product/engineering repo** — the one the whole team commits to. That's how everyone's AI tool picks up the same context automatically. Running it in a personal or feature branch repo works for solo use but misses the point for teams.
+team-foundry is agent-agnostic by design. The context files are the product. The AI tool reading them is a replaceable component.
+
+**Run this in your shared product/engineering repo** — the one the whole team commits to. Running it in a personal repo works for solo use but misses the point for teams.
 
 ---
 
+## See what populated looks like
+
+→ **[example/](example/)** — a fully populated team-foundry for Clearline, a fictional 8-person B2B SaaS team. Clone this repo, open `example/` in Claude Code, and ask the AI anything about the team. This is what your team-foundry can look like after the setup conversation.
+
 ## What it does
 
 Most teams use AI tools for code. The AI gives better answers when it knows what the product is for, who the customers are, and what quality means to this team.
@@ -24,9 +30,9 @@ It also installs a coach: a set of behaviors that notice when your files go stal
 
 ## What gets created
 
-**Solo profile (1–3 people):** 7 files. Identity, north star, outcomes, customers, stack, coach.
+**Solo profile (1–3 people):** 7 files. Root instruction file, getting started guide, coach playbook, north star, outcomes, customers, stack.
 
-**Full profile (4–15 people):** 15 files. Everything above plus strategy, roadmap, assumptions, risks, trio, working agreement, AI practices, quality bar, decisions log, design principles, metrics, glossary, stakeholders.
+**Full profile (4–15 people):** 20 files. Everything above plus strategy, roadmap, assumptions, risks, trio, working agreement, AI practices, quality bar, decisions log, design principles, metrics, glossary, stakeholders.
 
 Every file has YAML frontmatter (`purpose`, `read_when`, `last_updated`) so the AI knows when to load it and why.
 
@@ -34,6 +40,28 @@ Every file has YAML frontmatter (`purpose`, `read_when`, `last_updated`) so the
 
 team-foundry enables the work of building a shared understanding of your product. It doesn't replace it. If your team isn't willing to have the hard conversations about outcomes, customers, and quality — no tool fixes that. What team-foundry does is make those conversations easier to start, and easier to keep current.
 
+## Shared floor, individual ceiling
+
+team-foundry sets a shared baseline of context that every team member's AI tool reads from. Outcomes, customers, decisions, quality bar, glossary — the things everyone should be grounded in.
+
+It does not cap what individuals do above that baseline. A senior PM can add their own prompts, their own discovery framework, their own depth. An engineer can bring their own AI practices. A designer can layer on top.
+
+The floor is shared. The ceiling is individual. That's the point.
+
+## What drift looks like
+
+The coach catches specific, named patterns. These are the most common:
+
+| Pattern | What it is | Example |
+|---|---|---|
+| **Output-as-outcome drift** | An outcome that's actually a shipped feature | `outcomes.md` says "ship the new dashboard" instead of "reduce time-to-insight for SMB analysts" |
+| **Assumption fossilization** | A core assumption logged long ago, never revisited, still driving decisions | `assumptions.md` lists "users want faster checkout" dated 94 days ago. Three roadmap items cite it. No one's tested it. |
+| **Customer ghost syndrome** | A persona with no direct team contact in 60+ days, while roadmap items still claim to serve them | Enterprise persona last interviewed in February. Three Q2 features built "for enterprise." |
+| **Metric ambiguity** | A metric cited across files without an agreed definition | "Active user" in `outcomes.md` and `metrics.md` with no shared definition. PM means weekly; engineer means daily. |
+| **Decision amnesia** | A previous ADR rejecting an approach is invisible to a discussion heading the same direction | Q1 ADR rejects microservices migration. Q3 discussion reopens it with no reference to what changed. |
+| **Output roadmap disguised as strategy** | `strategy.md` guiding policy is all "yes" — doesn't name what the team is deliberately not pursuing | "We will be the best tool for product teams." No "we will not build X for Y." |
+| **Build-trap signal** | An item moves into "Now" with no linked experiment and no validated assumption | "Add collaborative editing" moves to Now. No assumption linked. Last validation: none. |
+
 ## Strategy in Git
 
 Putting strategy and product context in a repo might feel wrong. A few things worth knowing:
@@ -82,6 +110,12 @@ The coach will then only run when you explicitly ask for it.
 - Node 18+
 - Claude Code, Gemini CLI, or any AI tool that reads files from your repo as context
 
+## What's next
+
+team-foundry v1 supports Claude Code and Gemini CLI. Cursor is the highest-priority v2 addition — it has the largest active user base of any AI coding tool and fits the same file-based context model.
+
+v2 shortlist: Cursor support and scheduled coach runs via cron.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import fs3 from "fs/promises";
-import path3 from "path";
+import fs4 from "fs/promises";
+import path4 from "path";
 import { outro as outro2, log, confirm } from "@clack/prompts";
 
 // src/prompts.ts
@@ -20,7 +20,8 @@ async function runPrompts() {
     options: [
       { value: "claude", label: "Claude Code" },
       { value: "gemini", label: "Gemini CLI" },
-      { value: "both", label: "Both" }
+      { value: "cursor", label: "Cursor" },
+      { value: "both", label: "Multiple (Claude Code + Gemini CLI)" }
     ]
   });
   cancelIfNeeded(tool);
@@ -41,6 +42,18 @@ async function runPrompts() {
     ]
   });
   cancelIfNeeded(repoVisibility);
+  let federated;
+  if (profile === "full") {
+    const federatedAnswer = await select({
+      message: "Context layout?",
+      options: [
+        { value: "flat", label: "Flat  (one root CLAUDE.md \u2014 simpler, recommended for most teams)" },
+        { value: "federated", label: "Federated  (CLAUDE.md per folder \u2014 for larger teams, 8+ people)" }
+      ]
+    });
+    cancelIfNeeded(federatedAnswer);
+    federated = federatedAnswer === "federated";
+  }
   const ingestion = await select({
     message: "Do you have existing docs to ingest?\n  (Strategy docs, old roadmaps, customer research \u2014 the interview uses them to pre-populate answers)",
     options: [
@@ -68,7 +81,8 @@ async function runPrompts() {
     profile,
     repoVisibility,
     ingestion,
-    ingestionPath
+    ingestionPath,
+    federated
   };
 }
 
@@ -76,6 +90,137 @@ async function runPrompts() {
 import fs from "fs/promises";
 import path from "path";
 
+// src/templates/federated/product-claude.ts
+function federatedProductTemplate(ctx) {
+  return `---
+purpose: Routing context for the product/ folder \u2014 read before answering product questions
+read_when: Any question about outcomes, customers, roadmap, strategy, assumptions, or risks
+last_updated: ${ctx.date}
+---
+
+# Product context
+
+This folder contains the team's product thinking. Read the relevant file before answering.
+
+| Topic | File |
+|---|---|
+| Vision and north star metric | \`north-star.md\` |
+| This quarter's outcomes | \`outcomes.md\` |
+| Named customers and personas | \`customers.md\` |
+| What we're building now / next / later | \`now-next-later.md\` |
+| Strategic logic and guiding policy | \`strategy.md\` |
+| Open assumptions and untested bets | \`assumptions.md\` |
+| Key product risks | \`risks.md\` |
+
+Files with recent \`last_updated\` dates are more reliable than older ones. If asked about freshness, note if a file hasn't been updated in 60+ days.
+`;
+}
+
+// src/templates/federated/team-claude.ts
+function federatedTeamTemplate(ctx) {
+  return `---
+purpose: Routing context for the team/ folder \u2014 read before answering team questions
+read_when: Any question about who owns decisions, how the team works, or AI tool usage
+last_updated: ${ctx.date}
+---
+
+# Team context
+
+This folder describes how the product trio works and how the team operates.
+
+| Topic | File |
+|---|---|
+| Who's on the trio and how decisions are made | \`trio.md\` |
+| Ceremonies, DoD, working norms | \`working-agreement.md\` |
+| How this team uses AI tools | \`ai-practices.md\` |
+
+When answering questions about ownership or process, read \`trio.md\` first. It reflects how the team actually operates, not an org chart.
+`;
+}
+
+// src/templates/federated/engineering-claude.ts
+function federatedEngineeringTemplate(ctx) {
+  return `---
+purpose: Routing context for the engineering/ folder \u2014 read before answering technical questions
+read_when: Any question about the stack, conventions, tech debt, or past architecture decisions
+last_updated: ${ctx.date}
+---
+
+# Engineering context
+
+This folder contains the team's technical context. Read before writing or reviewing code.
+
+| Topic | File |
+|---|---|
+| Stack, conventions, deployment | \`stack.md\` |
+| Quality stance and tech debt policy | \`quality-bar.md\` |
+| Past architecture decisions | \`decisions/\` |
+
+Always read \`stack.md\` before writing code for this repo \u2014 it contains the conventions and the non-obvious choices that would surprise an outsider. Read the relevant ADR in \`decisions/\` before making a technical decision that's already been decided.
+`;
+}
+
+// src/templates/federated/design-claude.ts
+function federatedDesignTemplate(ctx) {
+  return `---
+purpose: Routing context for the design/ folder \u2014 read before answering design questions
+read_when: Any question about UI copy, visual decisions, accessibility, or tone of voice
+last_updated: ${ctx.date}
+---
+
+# Design context
+
+This folder contains the team's design principles and standards.
+
+| Topic | File |
+|---|---|
+| Design principles, tone of voice, accessibility | \`principles.md\` |
+
+Read \`principles.md\` before writing UI copy, reviewing designs, or making visual decisions. The tone and accessibility standards here apply to all customer-facing work.
+`;
+}
+
+// src/templates/federated/data-claude.ts
+function federatedDataTemplate(ctx) {
+  return `---
+purpose: Routing context for the data/ folder \u2014 read before discussing metrics
+read_when: Any question about metrics, success criteria, or what numbers mean
+last_updated: ${ctx.date}
+---
+
+# Data context
+
+This folder contains metric definitions for this team.
+
+| Topic | File |
+|---|---|
+| Metric definitions, ownership, data sources | \`metrics.md\` |
+
+Read \`metrics.md\` before citing any metric or writing success criteria in a spec. If a metric isn't defined here, it doesn't have an agreed definition \u2014 flag that rather than inventing one.
+`;
+}
+
+// src/templates/federated/context-claude.ts
+function federatedContextTemplate(ctx) {
+  return `---
+purpose: Routing context for the context/ folder \u2014 read before using domain terminology
+read_when: Any question involving domain terms, acronyms, or stakeholder communication
+last_updated: ${ctx.date}
+---
+
+# Domain context
+
+This folder contains the team's shared vocabulary and stakeholder map.
+
+| Topic | File |
+|---|---|
+| Domain terms and acronyms | \`glossary.md\` |
+| Stakeholders and what they care about | \`stakeholders.md\` |
+
+Read \`glossary.md\` when writing specs, copy, or anything using domain-specific terms \u2014 especially terms flagged as "used inconsistently." Read \`stakeholders.md\` before drafting any communication intended for a specific stakeholder.
+`;
+}
+
 // src/templates/root-claude.ts
 function rootClaudeTemplate(ctx) {
   return `---
@@ -226,6 +371,82 @@ it notices something relevant to your current work. You can also invoke it direc
 `;
 }
 
+// src/templates/root-cursor.ts
+function rootCursorTemplate(ctx) {
+  return `---
+purpose: Identity, routing map, and coach activation \u2014 read at the start of every session
+read_when: Every Cursor session in this repo \u2014 this is the root instruction file
+last_updated: ${ctx.date}
+alwaysApply: true
+---
+
+# team-foundry
+
+This repo uses **team-foundry** \u2014 structured files that give you real team context.
+Read this file first. It tells you where to find everything and how to activate the coach.
+
+<!-- GAP: The onboarding interview hasn't run yet.
+     When the user says "Let's set up our team-foundry" or similar, do this:
+     1. Read GETTING_STARTED.md for context on what to expect
+     2. Load .team-foundry/coach.md \u2014 it contains the interview sequence
+     3. Begin the onboarding interview as described there
+     Do not improvise the interview. Follow the sequence in coach.md. -->
+
+## Who we are
+
+<!-- Filled in during the onboarding interview. -->
+
+## Routing map
+
+When the user's question relates to any of the following, read the corresponding file
+before answering. Files with recent \`last_updated\` dates are more reliable than older ones.
+
+| Topic | File |
+|---|---|
+| Who we are / what this product does | team-foundry.mdc \u2014 "Who we are" section (this file) |
+| What success looks like / vision | \`team-foundry/product/north-star.md\` |
+| What we're working toward this quarter | \`team-foundry/product/outcomes.md\` |
+| Who our customers are | \`team-foundry/product/customers.md\` |
+| What we're building now / next / later | \`team-foundry/product/now-next-later.md\` |
+| Strategic logic and guiding policy | \`team-foundry/product/strategy.md\` |
+| Open assumptions and untested bets | \`team-foundry/product/assumptions.md\` |
+| Key product risks | \`team-foundry/product/risks.md\` |
+| How the product trio works | \`team-foundry/team/trio.md\` |
+| Team norms, DoD, ceremonies | \`team-foundry/team/working-agreement.md\` |
+| How we use AI tools | \`team-foundry/team/ai-practices.md\` |
+| Tech stack and conventions | \`team-foundry/engineering/stack.md\` |
+| Quality stance and tech debt policy | \`team-foundry/engineering/quality-bar.md\` |
+| Past architecture decisions | \`team-foundry/engineering/decisions/\` |
+| Design principles and tone | \`team-foundry/design/principles.md\` |
+| Metric definitions | \`team-foundry/data/metrics.md\` |
+| Domain terms and acronyms | \`team-foundry/context/glossary.md\` |
+| Stakeholders and what they care about | \`team-foundry/context/stakeholders.md\` |
+
+## Coach
+
+The team-foundry coach keeps these files honest over time. It runs automatically when
+it notices something relevant to your current work. You can also invoke it directly:
+
+| What to say | What happens |
+|---|---|
+| "Let's set up our team-foundry" | Runs the onboarding interview (first time only) |
+| "let's do a team-foundry review" | Full audit \u2014 all files checked, findings listed |
+| "coach mode" | Same as above |
+| "review our [outcomes / customers / stack / etc.]" | Targeted review of one file |
+| "what's missing from team-foundry?" | Lists gaps across all files |
+| "run the weekly team-foundry review" | Weekly check-in, top 3 issues surfaced |
+
+<!-- AI instructions:
+     - Normal coding sessions: do NOT load coach.md. Use the routing map above to load
+       specific files only when directly relevant to the user's question.
+     - Explicit mode / Scheduled mode / onboarding: load .team-foundry/coach.md in full
+       before activating any mode. Triggered only by the phrases in the table above.
+     - Inline mode nudges: if you notice a clear gap in a team-foundry file while answering
+       a normal question, surface it in one sentence \u2014 without loading the full coach.md.
+       Keep it brief and non-blocking. Do not coach unprompted on back-to-back messages. -->
+`;
+}
+
 // src/templates/getting-started.ts
 function gettingStartedTemplate(ctx) {
   const toolName = ctx.tool === "gemini" ? "Gemini CLI" : ctx.tool === "both" ? "Claude Code or Gemini CLI" : "Claude Code";
@@ -315,8 +536,14 @@ You can delete this file once the onboarding interview is complete.
 // src/templates/coach.ts
 function coachTemplate(ctx) {
   const isSolo = ctx.profile === "solo";
-  const questionCount = isSolo ? "10" : "18\u201325";
+  const questionCount = isSolo ? "9" : "18\u201325";
   const timeEstimate = isSolo ? "15\u201320 minutes" : "25\u201335 minutes";
+  const featureQueryFullSteps = isSolo ? "" : `3. Read \`team-foundry/product/now-next-later.md\` \u2014 find the feature's current status (Now / Next / Later / shipped)
+4. Read \`team-foundry/product/assumptions.md\` \u2014 find any assumptions linked to this feature
+5. Read \`team-foundry/engineering/decisions/\` \u2014 find any ADRs related to how it's being built
+`;
+  const featureQuerySynthesis = isSolo ? "why it's being built (outcome + customer evidence)." : "why it's being built (outcome + customer evidence), current status, open bets (assumptions), and any relevant technical decisions.";
+  const featureQueryIndexNote = isSolo ? "Your solo profile covers outcomes, customers, north-star, and stack \u2014 feature queries draw from those." : "For full profile teams, this covers status, rationale, customer evidence, open bets, and decisions.";
   return `---
 purpose: Full coach playbook \u2014 loaded on demand to preserve token budget
 read_when: When the user triggers coach mode (explicit, inline, scheduled review, or onboarding interview)
@@ -336,6 +563,67 @@ You are a mirror, not a template pack. The files in this repo are the team's own
 thinking. Your role is to reflect it back to them accurately, including the parts
 that have gone stale or were never written down.
 
+## Reality observation
+
+This is the authoritative protocol for reading git activity. It supersedes any git-reading
+instructions elsewhere in this file (including the "Why this nudge?" block and Behavior 5).
+Those sections define what to surface \u2014 this section defines how to gather the evidence.
+
+**When to run:**
+- **Explicit and scheduled modes:** Run all four steps before any behavior fires.
+- **Inline mode:** Run Steps 1\u20132 only when an inline trigger fires, scoped to the specific
+  file being evaluated. Do not run a full git audit on every inline response \u2014 that
+  contradicts the token-budget framing of this file.
+
+**Step 1 \u2014 Read recent commits.**
+
+\`\`\`
+git log --oneline --since="30 days ago"
+\`\`\`
+
+This returns all commits regardless of merge strategy. Extract:
+- Total commit count in the window
+- Commit messages that describe shipped features, decisions, or major changes
+
+**Merge strategy note:** \`git log --merges\` returns zero results on repos that use
+squash-merge or rebase-merge (GitHub's common defaults). Do not use it as the primary
+activity signal. Instead, use total commit count from the regular log. If commit volume
+is high (>10 commits) but \`--merges\` returns zero, conclude "squash or rebase merge
+strategy \u2014 using commit messages as activity proxy" and proceed accordingly.
+
+**Step 2 \u2014 Check \`last_updated\` dates in team-foundry files.**
+
+For each file being evaluated, note its \`last_updated\` frontmatter date. Calculate:
+- Days between \`last_updated\` and today
+- Commits since that date: \`git log --oneline --since="<last_updated date>"\`
+- If the log returns no results, treat activity as zero and skip the high-activity threshold.
+
+**Step 3 \u2014 Build the observed reality summary (internal, not shown to user).**
+
+Synthesize into a mental model carried through the rest of the session:
+- What shipped recently (from commit messages)
+- Which team-foundry files haven't been updated since shipping started
+- Activity level: high (>3 commits since last update) or low (\u22643 commits since last update).
+  High activity means push harder on drift. Low activity means lighter touch.
+
+**Step 4 \u2014 Use this in every finding.**
+
+When surfacing drift, always cite the observed reality explicitly. This is the single format
+for "Why this nudge?" across all behaviors:
+
+> "[N] commits have merged since outcomes.md was last updated ([X] days ago). Based on
+> recent commit messages \u2014 [list 2-3 relevant ones] \u2014 it looks like [what changed].
+> outcomes.md doesn't reflect this yet."
+
+**Fallback when git is unavailable:** If the tool doesn't have shell access, fall back to
+\`last_updated\` dates only and note: "I don't have access to git history \u2014 using
+\`last_updated\` dates as the staleness signal."
+
+**What counts as high activity:** More than 3 commits since the file was last updated.
+This is the single threshold used throughout this file.
+
+---
+
 ## Activation modes
 
 You have three activation modes. Read which one applies and behave accordingly.
@@ -524,6 +812,31 @@ order and **name the conflict explicitly** rather than silently picking one:
 Say: "I see a conflict between [file A] and [file B]. Based on the context priority
 order, I'm going with [file A] \u2014 but you may want to reconcile these."
 
+When running any coaching behavior, also load \`.team-foundry/team-lessons.md\` if it exists.
+Apply Active rules from that file alongside built-in behaviors \u2014 they carry equal weight.
+
+## Feature queries
+
+**Applies in explicit and scheduled modes.** In inline mode, treat feature questions as
+potential B5 (reality drift) triggers rather than running this full multi-file read.
+
+When the user asks about a specific feature \u2014 "tell me about X," "what's the status of Y,"
+"what do we know about Z," "has X shipped?," "where are we on X?," "who owns X?," or any
+close variant \u2014 read the following files in order:
+
+1. Read \`team-foundry/product/outcomes.md\` \u2014 find which outcome this feature supports (the why)
+2. Read \`team-foundry/product/customers.md\` \u2014 find customer quotes or personas that motivated it
+${featureQueryFullSteps}
+For each file above: if the file doesn't exist on disk, skip it silently. If it exists
+but doesn't mention the feature, note that gap explicitly \u2014 don't invent connections.
+
+Synthesize into a single response: ${featureQuerySynthesis}
+
+If the feature doesn't appear in any file, say: "I couldn't find [X] in any team-foundry
+file \u2014 it may be undocumented or tracked under a different name. Want me to help capture it?"
+
+The team-foundry files are the index. ${featureQueryIndexNote}
+
 ---
 
 ## Behaviors
@@ -537,6 +850,11 @@ For every finding: name it specifically (cite the file and the exact content),
 explain why it matters in one sentence, offer to draft the fix. Never list a finding
 without a proposed next step.
 
+**"Why this nudge?" \u2014 required for every drift finding.** Use the evidence gathered in the
+Reality observation section above. Always be specific \u2014 a team that understands why a nudge
+fired is far more likely to act on it. Never say "this looks stale" without citing the
+commit count, day delta, and (if blank) missing owner.
+
 ---
 
 ### Behavior 1: Outputs framed as outcomes
@@ -1094,6 +1412,61 @@ as a deliberate strategy update. If item should be removed: flag only \u2014 do
 the current strategy.md guiding policy explicitly excludes \u2014 or when strategy.md has no
 Guiding Policy filled in.
 
+### Behavior 17: Team-specific lesson capture
+
+**Severity:** Informational \u2014 surfaced as an offer, never a blocker.
+
+**Trigger condition:** The user's message contains a recurring-pattern signal:
+- "we keep doing X"
+- "this is the third time we've had this problem"
+- "we always confuse Y with Z"
+- "every time we [situation], we [result]"
+- Any close variant signaling a pattern the team has noticed about itself.
+
+**What to say:**
+> "Sounds like a recurring pattern. Want me to add a coaching rule to \`.team-foundry/team-lessons.md\`
+> so I watch for this on future reviews?"
+
+**If the user confirms:**
+1. Draft the rule in this format:
+   \`- [date] [concise rule] \u2014 [brief context]\`
+2. Ask: "Does this capture it, or want to edit the wording?"
+3. After confirmation, write it to the Active rules section of \`.team-foundry/team-lessons.md\`.
+   If the file doesn't exist, create it with this structure:
+
+\`\`\`markdown
+---
+purpose: Team-specific coaching rules learned from this team's patterns
+read_when: Coach runs any coaching behavior
+last_updated: [date]
+---
+
+# Team lessons
+
+Rules this specific team has accumulated for their coach.
+Added when the team flags a recurring issue they want the coach to watch for.
+
+## Active rules
+
+- [date] [rule] \u2014 [context]
+
+## Retired rules
+
+<!-- Move rules here when no longer relevant, with the date retired. -->
+\`\`\`
+
+**Rule retirement:** When a team says a rule is no longer relevant ("we fixed that," "we changed process"),
+offer to retire it: move it from Active rules to Retired rules with today's date prepended.
+
+**Loading instruction:** When running any coaching behavior (inline, explicit, or scheduled),
+check if \`.team-foundry/team-lessons.md\` exists. If it does, load it and apply Active rules
+with equal weight to built-in behaviors, scoped to this team's context.
+
+**What not to do:** Do not proactively suggest adding rules unless the user explicitly names a pattern.
+This behavior is listener-only \u2014 it waits for the signal, it does not fish for it.
+
+---
+
 ## Quarterly retrospective
 
 ### Trigger
@@ -1491,11 +1864,11 @@ Example answers:
 
 ---
 
-### Theme 3: Measurement
+${isSolo ? "" : `### Theme 3: Measurement
 
 *Files written: data/metrics.md*
 
-**Q${isSolo ? "5" : "7"}. What are the 3\u20135 numbers you actually look at to know if the product is healthy?**
+**Q7. What are the 3\u20135 numbers you actually look at to know if the product is healthy?**
 *Why it matters: data/metrics.md is read whenever the AI is asked about product performance.
 Undefined metrics cause disagreements \u2014 two people reading the same number and reaching different conclusions.*
 
@@ -1506,7 +1879,7 @@ Example answers:
 - "Listing-to-sale rate \u2014 % of active listings that get bought within 30 days, from our DB."
 - "P1 bug count \u2014 open bugs tagged P1 in Linear, reviewed Monday mornings."
 
-*After the answer: write each metric as a definition block to data/metrics.md.*
+*After the answer: write each metric as a definition block to data/metrics.md.*`}
 
 ---
 
@@ -1514,7 +1887,7 @@ Example answers:
 
 *Files written: product/customers.md*
 
-**Q${isSolo ? "6" : "8"}. Name three customers you've spoken to directly.**
+**Q${isSolo ? "5" : "8"}. Name three customers you've spoken to directly.**
 *Why it matters: customers.md is read whenever the AI helps with prioritization, specs,
 or discovery. Generic personas don't resolve real disagreements. Named customers do.*
 
@@ -1576,7 +1949,7 @@ Example answers:
 
 *After the answer: write to engineering/quality-bar.md (tech debt stance).*`}
 
-**Q${isSolo ? "7" : "12"}. What does "shipped" mean on your team?**
+**Q${isSolo ? "6" : "12"}. What does "shipped" mean on your team?**
 *Why it matters: misaligned definitions of done cause the most common sprint friction.
 Writing it down means the argument happens once, not every week.*
 
@@ -1658,7 +2031,7 @@ Example answers:
 
 *Files written: engineering/stack.md*
 
-**Q${isSolo ? "8" : "18"}. What's the tech stack, and what would surprise an incoming engineer?**
+**Q${isSolo ? "7" : "18"}. What's the tech stack, and what would surprise an incoming engineer?**
 *Why it matters: stack.md is read every time the AI helps write or review code.
 The "what would surprise" framing surfaces the non-obvious conventions.*
 
@@ -1691,7 +2064,7 @@ If no: note that the decisions/ folder is ready when one comes up.
 
 *Files written: context/glossary.md${isSolo ? "" : ", context/stakeholders.md"}*
 
-**Q${isSolo ? "9" : "21"}. What words does your team use that would confuse an outsider?**
+**Q${isSolo ? "8" : "21"}. What words does your team use that would confuse an outsider?**
 *Why it matters: glossary.md is read when the AI writes specs, reviews code, or
 discusses product strategy. Shared vocabulary prevents the AI from guessing at meaning.*
 
@@ -1712,7 +2085,7 @@ For each stakeholder: name/role, what they really care about, how they prefer to
 
 *After the answer: write to context/stakeholders.md.*`}
 
-**Q${isSolo ? "10" : "23"}. Are there any terms your team uses inconsistently with each other?**
+**Q${isSolo ? "9" : "23"}. Are there any terms your team uses inconsistently with each other?**
 *Why it matters: inconsistent internal vocabulary is a reliable source of meeting friction.
 Naming it here gives the AI a flag to raise when it notices the inconsistency.*
 
@@ -1752,6 +2125,7 @@ function northStarTemplate(ctx) {
 purpose: The single metric that best captures whether we're creating the value we intend to create
 read_when: Setting quarterly direction, evaluating big bets, writing OKRs, onboarding new team members
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # North Star
@@ -1805,6 +2179,7 @@ function outcomesTemplate(ctx) {
 purpose: Current quarter outcomes \u2014 the changes in customer behavior that define success this quarter
 read_when: Prioritizing work, writing specs, deciding what to build next, evaluating tradeoffs
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Outcomes
@@ -1848,6 +2223,7 @@ function customersTemplate(ctx) {
 purpose: Named customers, personas, jobs to be done, and direct quotes from real conversations
 read_when: Writing specs, prioritizing features, evaluating tradeoffs, any time you're guessing what customers want
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Customers
@@ -1901,6 +2277,7 @@ function nowNextLaterTemplate(ctx) {
 purpose: What we're building now, what we're committed to next, and what's directional
 read_when: Sprint planning, stakeholder updates, evaluating new requests, prioritization discussions
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Now / Next / Later
@@ -1960,6 +2337,7 @@ function assumptionsTemplate(ctx) {
 purpose: Open assumptions and untested beliefs \u2014 the bets the team is currently making
 read_when: Designing discovery work, scoping experiments, retros, any time a decision feels risky
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Assumptions
@@ -2035,6 +2413,7 @@ function risksTemplate(ctx) {
 purpose: The four product risks \u2014 tracked so they don't become surprises at launch
 read_when: Scoping new features, go/no-go decisions, discovery planning, quarterly reviews
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Risks
@@ -2094,6 +2473,7 @@ function trioTemplate(ctx) {
 purpose: The product trio \u2014 who owns what decisions and how the three roles work together
 read_when: Escalations, onboarding, clarifying ownership, any "who decides this?" conversation
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Team Trio
@@ -2115,11 +2495,17 @@ last_updated: ${ctx.date}
 
 ## Members
 
-| Role | Person | Focus area |
-|---|---|---|
-| Product Manager | <!-- name --> | What to build and why |
-| Engineering Lead | <!-- name --> | How to build it, tech debt, architecture |
-| Design Lead | <!-- name --> | UX, flows, visual quality |
+| Role | Person | GitHub (optional) | Focus area |
+|---|---|---|---|
+| Product Manager | <!-- name --> | <!-- @handle --> | What to build and why |
+| Engineering Lead | <!-- name --> | <!-- @handle --> | How to build it, tech debt, architecture |
+| Design Lead | <!-- name --> | <!-- @handle --> | UX, flows, visual quality |
+
+<!-- Optional additional fields per member (add inline or as a sub-list):
+     - slack: U0C3D4E5F  (Slack member ID for @mentions)
+     - linear: user ID  (for issue assignment lookups)
+     Fill in what's known; leave blank what isn't. These fields let AI tools
+     take cross-platform actions when relevant. -->
 
 ## How we make decisions
 
@@ -2151,6 +2537,7 @@ function workingAgreementTemplate(ctx) {
 purpose: Definition of done, definition of ready, ceremonies, and team norms \u2014 the honest version
 read_when: Code review, sprint planning, retrospectives, any "this isn't how we said we'd work" moment
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Working Agreement
@@ -2221,6 +2608,7 @@ function aiPracticesTemplate(ctx) {
 purpose: How this team uses AI tools \u2014 what's working, what we've decided not to do, and our norms
 read_when: Onboarding engineers, evaluating new AI tooling, retrospectives on AI-assisted work
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # AI Practices
@@ -2275,6 +2663,7 @@ function stackTemplate(ctx) {
 purpose: Tech stack, conventions, deployment pipeline, and local dev setup
 read_when: Writing code, reviewing PRs, evaluating new dependencies, onboarding engineers
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Engineering Stack
@@ -2324,6 +2713,7 @@ function qualityBarTemplate(ctx) {
 purpose: The team's honest stance on tech debt, bugs, and what "shipped" actually means
 read_when: Code review, sprint planning, evaluating shortcuts, any quality-vs-speed conversation
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Quality Bar
@@ -2394,6 +2784,7 @@ function decisionsReadmeTemplate(ctx) {
 purpose: Index and template for architecture decision records (ADRs)
 read_when: Evaluating architectural choices, understanding why the codebase looks the way it does
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Architecture Decisions
@@ -2450,6 +2841,7 @@ function principlesTemplate(ctx) {
 purpose: Design principles, tone of voice, and accessibility stance
 read_when: Designing new features, writing copy, reviewing designs, evaluating UX tradeoffs
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Design Principles
@@ -2507,6 +2899,7 @@ function metricsTemplate(ctx) {
 purpose: Metric definitions, ownership, and data sources \u2014 so the team means the same thing
 read_when: Building dashboards, writing OKRs, reviewing product health, debugging data discrepancies
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Metrics
@@ -2553,6 +2946,7 @@ function glossaryTemplate(ctx) {
 purpose: Domain terms, acronyms, and jargon specific to this team and product
 read_when: Onboarding, writing specs, any time a term feels ambiguous or overloaded
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Glossary
@@ -2594,6 +2988,7 @@ function stakeholdersTemplate(ctx) {
 purpose: Who cares about this product, what they care about, and how the team works with them
 read_when: Stakeholder updates, go/no-go decisions, escalations, quarterly planning
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Stakeholders
@@ -2637,6 +3032,7 @@ function strategyTemplate(ctx) {
 purpose: The strategic logic connecting our north-star gap to what we're building. Read before adding anything to the roadmap.
 read_when: Roadmap planning, evaluating new feature requests, quarterly retrospective, when a new item is proposed for Now or Next, when a new team member is onboarding
 last_updated: ${ctx.date}
+owner: 
 ---
 
 # Strategy
@@ -2725,6 +3121,14 @@ var FULL_ONLY_ENTRIES = [
   { relativePath: "team-foundry/context/stakeholders.md", content: stakeholdersTemplate },
   { relativePath: "team-foundry/product/strategy.md", content: strategyTemplate }
 ];
+var FEDERATED_ENTRIES = [
+  { relativePath: "team-foundry/product/CLAUDE.md", content: federatedProductTemplate },
+  { relativePath: "team-foundry/team/CLAUDE.md", content: federatedTeamTemplate },
+  { relativePath: "team-foundry/engineering/CLAUDE.md", content: federatedEngineeringTemplate },
+  { relativePath: "team-foundry/design/CLAUDE.md", content: federatedDesignTemplate },
+  { relativePath: "team-foundry/data/CLAUDE.md", content: federatedDataTemplate },
+  { relativePath: "team-foundry/context/CLAUDE.md", content: federatedContextTemplate }
+];
 function rootEntries(tool) {
   if (tool === "claude") {
     return [{ relativePath: "CLAUDE.md", content: rootClaudeTemplate }];
@@ -2732,18 +3136,22 @@ function rootEntries(tool) {
   if (tool === "gemini") {
     return [{ relativePath: "GEMINI.md", content: rootGeminiTemplate }];
   }
+  if (tool === "cursor") {
+    return [{ relativePath: ".cursor/rules/team-foundry.mdc", content: rootCursorTemplate }];
+  }
   return [
     { relativePath: "CLAUDE.md", content: rootClaudeTemplate },
     { relativePath: "GEMINI.md", content: rootGeminiTemplate }
   ];
 }
 async function scaffold(options) {
-  const { targetDir, profile, tool, repoVisibility, date, ingestionPath, ingestion } = options;
+  const { targetDir, profile, tool, repoVisibility, date, ingestionPath, ingestion, federated } = options;
   const ctx = { profile, tool, repoVisibility, date, ingestionPath, ingestion };
   const entries = [
     ...rootEntries(tool),
     ...SOLO_ENTRIES,
-    ...profile === "full" ? FULL_ONLY_ENTRIES : []
+    ...profile === "full" ? FULL_ONLY_ENTRIES : [],
+    ...profile === "full" && federated ? FEDERATED_ENTRIES : []
   ];
   for (const entry of entries) {
     const fullPath = path.join(targetDir, entry.relativePath);
@@ -2778,10 +3186,185 @@ async function writeGitignore(targetDir) {
 `, "utf-8");
 }
 
+// src/status.ts
+import fs3 from "fs/promises";
+import path3 from "path";
+import { spawnSync } from "child_process";
+var SOLO_FILES = [
+  "team-foundry/product/north-star.md",
+  "team-foundry/product/outcomes.md",
+  "team-foundry/product/customers.md",
+  "team-foundry/engineering/stack.md"
+];
+var FULL_ONLY_FILES = [
+  "team-foundry/product/now-next-later.md",
+  "team-foundry/product/assumptions.md",
+  "team-foundry/product/risks.md",
+  "team-foundry/product/strategy.md",
+  "team-foundry/team/trio.md",
+  "team-foundry/team/working-agreement.md",
+  "team-foundry/team/ai-practices.md",
+  "team-foundry/engineering/quality-bar.md",
+  "team-foundry/design/principles.md",
+  "team-foundry/data/metrics.md",
+  "team-foundry/context/glossary.md",
+  "team-foundry/context/stakeholders.md"
+];
+var ALL_FILES = [...SOLO_FILES, ...FULL_ONLY_FILES];
+var STALE_DAYS = 45;
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const result = {};
+  for (const line of match[1].split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+    result[key] = value;
+  }
+  return result;
+}
+function daysSince(dateStr) {
+  const then = new Date(dateStr).getTime();
+  if (isNaN(then)) return null;
+  return Math.floor((Date.now() - then) / 864e5);
+}
+function prsSinceDate(targetDir, dateStr) {
+  try {
+    const since = new Date(dateStr).toISOString();
+    if (isNaN(new Date(dateStr).getTime())) return null;
+    const result = spawnSync(
+      "git",
+      ["-C", targetDir, "log", "--oneline", "--merges", `--since=${since}`],
+      { encoding: "utf-8", timeout: 5e3 }
+    );
+    if (result.status !== 0) return null;
+    return result.stdout.trim().split("\n").filter(Boolean).length;
+  } catch {
+    return null;
+  }
+}
+function isEffectivelyEmpty(body) {
+  const stripped = body.replace(/<!--[\s\S]*?-->/g, "").replace(/^#+\s.*$/gm, "").trim();
+  return stripped.length < 30;
+}
+async function analyzeFile(targetDir, relativePath) {
+  const fullPath = path3.join(targetDir, relativePath);
+  let exists = false;
+  let isEmpty = false;
+  let lastUpdated = null;
+  let owner = null;
+  let daysSinceUpdate = null;
+  let prsSince = null;
+  try {
+    const content = await fs3.readFile(fullPath, "utf-8");
+    exists = true;
+    const body = content.replace(/^---[\s\S]*?---\n?/, "").trim();
+    isEmpty = isEffectivelyEmpty(body);
+    const fm = parseFrontmatter(content);
+    if (fm["last_updated"]) {
+      lastUpdated = fm["last_updated"];
+      daysSinceUpdate = daysSince(lastUpdated);
+      prsSince = prsSinceDate(targetDir, lastUpdated);
+    }
+    owner = fm["owner"] || null;
+  } catch {
+  }
+  let health = "ok";
+  if (!exists) health = "missing";
+  else if (isEmpty) health = "empty";
+  else if (daysSinceUpdate !== null && daysSinceUpdate >= STALE_DAYS) health = "stale";
+  return {
+    relativePath,
+    lastUpdated,
+    owner,
+    daysSinceUpdate,
+    prsSinceUpdate: prsSince,
+    exists,
+    isEmpty,
+    health
+  };
+}
+function healthIcon(health) {
+  if (health === "ok") return "\u2713";
+  if (health === "stale") return "~";
+  if (health === "empty") return "\u25CB";
+  return "\u2717";
+}
+function formatRow(s) {
+  const icon = healthIcon(s.health);
+  const rawName = s.relativePath.replace("team-foundry/", "");
+  const name = rawName.slice(0, 42).padEnd(42);
+  const updated = s.lastUpdated ?? "\u2014";
+  const age = s.daysSinceUpdate !== null ? `${s.daysSinceUpdate}d` : "\u2014";
+  const prs = s.prsSinceUpdate !== null ? `${s.prsSinceUpdate} PRs` : "\u2014";
+  const owner = s.owner || "\u2014";
+  return `  ${icon}  ${name} ${updated.padEnd(12)} ${age.padEnd(6)} ${prs.padEnd(8)} ${owner}`;
+}
+function whyNudge(s) {
+  const parts = [];
+  if (s.daysSinceUpdate !== null) parts.push(`${s.daysSinceUpdate} days since last update`);
+  if (s.prsSinceUpdate !== null && s.prsSinceUpdate > 0)
+    parts.push(`${s.prsSinceUpdate} PRs shipped since then`);
+  if (!s.owner) parts.push("no owner set");
+  return parts.join(", ");
+}
+async function runStatus(targetDir) {
+  const fullProfileFile = path3.join(targetDir, "team-foundry/team/trio.md");
+  let isFullProfile = false;
+  try {
+    await fs3.access(fullProfileFile);
+    isFullProfile = true;
+  } catch {
+  }
+  const filesToCheck = isFullProfile ? ALL_FILES : SOLO_FILES;
+  const results = await Promise.all(filesToCheck.map((f) => analyzeFile(targetDir, f)));
+  const ok = results.filter((r) => r.health === "ok");
+  const stale = results.filter((r) => r.health === "stale");
+  const empty = results.filter((r) => r.health === "empty");
+  const missing = results.filter((r) => r.health === "missing");
+  console.log("\n  team-foundry status\n");
+  console.log(`  ${"File".padEnd(44)} ${"Last updated".padEnd(12)} ${"Age".padEnd(6)} ${"PRs".padEnd(8)} Owner`);
+  console.log(`  ${"\u2500".repeat(90)}`);
+  for (const s of results) console.log(formatRow(s));
+  console.log();
+  console.log(`  \u2713 ${ok.length} current   ~ ${stale.length} stale   \u25CB ${empty.length} empty   \u2717 ${missing.length} missing
+`);
+  if (stale.length > 0) {
+    console.log("  Stale files \u2014 why this nudge:\n");
+    for (const s of stale) {
+      console.log(`    ~ ${s.relativePath.replace("team-foundry/", "")}`);
+      console.log(`      ${whyNudge(s)}
+`);
+    }
+  }
+  if (empty.length > 0) {
+    console.log("  Empty files \u2014 not yet filled in:\n");
+    for (const s of empty) {
+      console.log(`    \u25CB ${s.relativePath.replace("team-foundry/", "")}`);
+    }
+    console.log();
+  }
+  if (missing.length > 0) {
+    console.log("  Missing files \u2014 run `npx create-team-foundry` to scaffold:\n");
+    for (const s of missing) {
+      console.log(`    \u2717 ${s.relativePath.replace("team-foundry/", "")}`);
+    }
+    console.log();
+  }
+  const noOwner = results.filter((r) => r.exists && !r.owner);
+  if (noOwner.length > 0) {
+    console.log(`  ${noOwner.length} file(s) have no owner set. Add \`owner: <name>\` to their frontmatter.
+`);
+  }
+}
+
 // src/index.ts
 var TOOL_LABEL = {
   claude: "Claude Code",
   gemini: "Gemini CLI",
+  cursor: "Cursor",
   both: "Claude Code or Gemini CLI"
 };
 var PASTE_PLACEHOLDER = `# Paste your existing docs here
@@ -2799,16 +3382,16 @@ You can paste multiple documents \u2014 just separate them with a heading like:
 When you're done, save this file and start the onboarding interview.
 `;
 async function checkDirectory(targetDir) {
-  const prdPath = path3.join(targetDir, "team-foundry-prd-v2.md");
-  const scaffoldPath = path3.join(targetDir, "src", "scaffold.ts");
+  const prdPath = path4.join(targetDir, "team-foundry-prd-v2.md");
+  const scaffoldPath = path4.join(targetDir, "src", "scaffold.ts");
   let isSourceRepo = false;
   try {
-    await fs3.access(prdPath);
+    await fs4.access(prdPath);
     isSourceRepo = true;
   } catch {
   }
   try {
-    await fs3.access(scaffoldPath);
+    await fs4.access(scaffoldPath);
     isSourceRepo = true;
   } catch {
   }
@@ -2818,17 +3401,17 @@ async function checkDirectory(targetDir) {
     );
     process.exit(1);
   }
-  const pkgPath = path3.join(targetDir, "package.json");
-  const srcPath = path3.join(targetDir, "src");
+  const pkgPath = path4.join(targetDir, "package.json");
+  const srcPath = path4.join(targetDir, "src");
   let hasPkg = false;
   let hasSrc = false;
   try {
-    await fs3.access(pkgPath);
+    await fs4.access(pkgPath);
     hasPkg = true;
   } catch {
   }
   try {
-    await fs3.access(srcPath);
+    await fs4.access(srcPath);
     hasSrc = true;
   } catch {
   }
@@ -2845,17 +3428,21 @@ async function checkDirectory(targetDir) {
 }
 async function main() {
   const targetDir = process.cwd();
+  if (process.argv[2] === "status") {
+    await runStatus(targetDir);
+    return;
+  }
   await checkDirectory(targetDir);
   const answers = await runPrompts();
   const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   await scaffold({ ...answers, targetDir, date });
   await writeGitignore(targetDir);
   if (answers.ingestion === "paste") {
-    const pastePath = path3.join(targetDir, ".team-foundry", "paste-content.md");
+    const pastePath = path4.join(targetDir, ".team-foundry", "paste-content.md");
     try {
-      await fs3.access(pastePath);
+      await fs4.access(pastePath);
     } catch {
-      await fs3.writeFile(pastePath, PASTE_PLACEHOLDER, "utf-8");
+      await fs4.writeFile(pastePath, PASTE_PLACEHOLDER, "utf-8");
     }
   }
   const tool = TOOL_LABEL[answers.tool];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-team-foundry",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Scaffold a team-foundry into any repo — structured context files for Claude Code and Gemini CLI",
   "license": "MIT",
   "type": "module",