create-team-foundry 2.1.2 → 3.0.0

package/dist/index.js

@@ -1,12 +1,19 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import fs4 from "fs/promises";
-import path4 from "path";
-import { outro as outro2, log, confirm } from "@clack/prompts";
+import fs5 from "fs/promises";
+import path5 from "path";
+import { outro as outro3, log as log2, confirm as confirm2, select as select2, isCancel as isCancel2 } from "@clack/prompts";
 
 // src/prompts.ts
 import { intro, select, text, outro, isCancel } from "@clack/prompts";
+function questionCount(profile, federated, ingestion) {
+  if (profile === void 0) return 5;
+  const hasLocalPath = ingestion === "local" || ingestion === "repo+local";
+  if (profile === "solo") return hasLocalPath ? 5 : 4;
+  const base = federated ? 6 : 5;
+  return hasLocalPath ? base + 1 : base;
+}
 function cancelIfNeeded(value) {
   if (isCancel(value)) {
     outro("Cancelled.");
@@ -17,6 +24,7 @@ async function runPrompts() {
   intro("create-team-foundry");
   const tool = await select({
     message: "Which AI tool does your team use?",
+    hint: "1 of ~5",
     options: [
       { value: "claude", label: "Claude Code" },
       { value: "gemini", label: "Gemini CLI" },
@@ -27,14 +35,18 @@ async function runPrompts() {
   cancelIfNeeded(tool);
   const profile = await select({
     message: "Team size?",
+    hint: "2 of ~5",
     options: [
       { value: "solo", label: "1\u20133 people  (solo profile \u2014 7 files)" },
       { value: "full", label: "4\u201315 people  (full profile \u2014 20 files)" }
     ]
   });
   cancelIfNeeded(profile);
+  const profileTyped = profile;
+  const totalNoFed = questionCount(profileTyped, false, void 0);
   const repoVisibility = await select({
     message: "Is this repo public, internal-only, or private?",
+    hint: `3 of ${totalNoFed}`,
     options: [
       { value: "public", label: "Public  (GitHub public, open source)" },
       { value: "internal", label: "Internal  (company-private, not public)" },
@@ -46,6 +58,7 @@ async function runPrompts() {
   if (profile === "full") {
     const federatedAnswer = await select({
       message: "Context layout?",
+      hint: "4 of ?",
       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)" }
@@ -54,8 +67,11 @@ async function runPrompts() {
     cancelIfNeeded(federatedAnswer);
     federated = federatedAnswer === "federated";
   }
+  const federatedResolved = federated ?? false;
+  const ingestionQ = profileTyped === "solo" ? 4 : 5;
   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)",
+    hint: `${ingestionQ} of ${questionCount(profileTyped, federatedResolved, void 0)}`,
     options: [
       { value: "repo", label: "Repo signals only  (README, package.json, git history, GitHub PRs/issues)" },
       { value: "repo+local", label: "Repo + local docs folder  (repo signals + point me at a folder)" },
@@ -70,8 +86,10 @@ async function runPrompts() {
   cancelIfNeeded(ingestion);
   let ingestionPath;
   if (ingestion === "local" || ingestion === "repo+local") {
+    const total = questionCount(profileTyped, federatedResolved, ingestion);
     const rawPath = await text({
       message: "Path to the folder containing your docs?",
+      hint: `${total} of ${total}`,
       placeholder: "./docs  or  /Users/you/exports",
       validate: (value) => {
         if (!value.trim()) return "Please enter a path.";
@@ -225,6 +243,328 @@ Read \`glossary.md\` when writing specs, copy, or anything using domain-specific
 `;
 }
 
+// src/templates/skills/team-foundry-intro.ts
+function introSkillTemplate(_ctx) {
+  return `---
+description: Team and product overview \u2014 great for onboarding a new session or new team member
+---
+
+# /team-foundry-intro
+
+You have been asked to orient yourself to this team's product context.
+
+## What to do
+
+Read the following files in order. After reading each one, note what you learned and what questions it raises.
+
+1. **Who we are and why we exist**
+   - \`team-foundry/product/north-star.md\` \u2014 mission, long-term vision, success metric
+   - \`team-foundry/product/customers.md\` \u2014 who we serve, validated segments, pain points
+
+2. **What we're working toward**
+   - \`team-foundry/product/outcomes.md\` \u2014 current cycle outcomes and their status
+   - \`team-foundry/product/strategy.md\` \u2014 how we're choosing to win (if present)
+
+3. **How we work**
+   - \`team-foundry/team/trio.md\` \u2014 PM, engineering lead, design lead (if present)
+   - \`team-foundry/team/working-agreement.md\` \u2014 norms and expectations (if present)
+
+4. **What we're building on**
+   - \`team-foundry/engineering/stack.md\` \u2014 tech stack, key constraints
+   - \`team-foundry/engineering/quality-bar.md\` \u2014 definition of done (if present)
+
+5. **Shared language**
+   - \`team-foundry/context/glossary.md\` \u2014 domain terms (if present)
+
+## After reading
+
+Summarize what you know in three parts:
+
+**This team exists to:** [one sentence from north-star]
+
+**Right now they're focused on:** [current outcomes in plain language]
+
+**Key constraints I should keep in mind:** [stack, quality bar, working agreement norms]
+
+Then ask: "Is there anything outdated or missing from these files before we start?"
+
+## Files that may not exist
+
+For solo profile setups, only a subset of these files is present. Skip any that are missing \u2014 do not report them as errors.
+`;
+}
+
+// src/templates/skills/team-foundry-status.ts
+function statusSkillTemplate(_ctx) {
+  return `---
+description: Current sprint/cycle status \u2014 what's on track, what's at risk, what's blocked
+---
+
+# /team-foundry-status
+
+You have been asked for a status read on this team's current work.
+
+## What to do
+
+Read these files:
+
+- \`team-foundry/product/outcomes.md\` \u2014 current cycle outcomes and their validation status
+- \`team-foundry/product/now-next-later.md\` \u2014 what's in flight, what's queued (if present)
+- \`team-foundry/product/assumptions.md\` \u2014 open assumptions that could invalidate work (if present)
+- \`team-foundry/product/risks.md\` \u2014 known risks and their mitigations (if present)
+
+## Report format
+
+Produce a status report in this structure:
+
+### On track
+[Outcomes or work items that are validated and progressing. Cite the source field or inline evidence if present.]
+
+### At risk
+[Work that lacks validation, has an open assumption underneath it, or has a known risk with no mitigation. Be specific about what's missing.]
+
+### Blocked
+[Anything explicitly marked blocked or waiting on a dependency.]
+
+### Gaps I noticed
+[Files that exist but have placeholder content. Sections that are empty. Frontmatter with no \`last_validated\` date on items marked Validated. Claims in a Validated section with no \`source:\` reference.]
+
+## Tone
+
+Be direct. "No validated outcomes this cycle" is a useful status. "Everything looks great" when files have placeholders is not.
+
+If the files are mostly empty or stubbed, say: "The team-foundry files exist but haven't been filled in yet. The highest-value thing right now is completing [most important missing section]."
+`;
+}
+
+// src/templates/skills/team-foundry-review.ts
+function reviewSkillTemplate(_ctx) {
+  return `---
+description: Full team-foundry audit by the coach \u2014 all files, findings by severity
+---
+
+# /team-foundry-review
+
+You have been asked to audit this team's team-foundry files and act as a diagnostic coach.
+
+## What to do
+
+Read every team-foundry file that exists:
+
+- \`team-foundry/product/\` \u2014 all files
+- \`team-foundry/team/\` \u2014 all files (if present)
+- \`team-foundry/engineering/\` \u2014 all files
+- \`team-foundry/design/\` \u2014 all files (if present)
+- \`team-foundry/data/\` \u2014 all files (if present)
+- \`team-foundry/context/\` \u2014 all files (if present)
+- \`.team-foundry/coach.md\` \u2014 coaching playbook (if present)
+
+## Audit findings format
+
+Group findings by severity:
+
+### Critical \u2014 acting on bad information
+[Claims marked Validated with no \`source:\` reference or inline evidence. Outcomes with no signal. Decisions that contradict each other. These are the cases where the AI is most likely to give wrong advice.]
+
+### Important \u2014 gaps that limit usefulness
+[Files with placeholder content. Missing sections for the profile. Stale \`last_validated\` dates (>90 days). Outcomes with no owner. Assumptions with no test plan.]
+
+### Suggestions \u2014 would strengthen the context
+[Things that would make AI answers more specific: adding a source to a hypothesis, filling in a glossary term, adding a stakeholder. Low urgency.]
+
+## After findings
+
+Recommend the top 3 actions in priority order. For each one, say:
+- What to do (one sentence)
+- Which file to update
+- Why it matters for AI accuracy
+
+## Tone
+
+Name gaps directly. "outcomes.md has four outcomes, three of which are placeholders with no signal" is useful. Softening findings makes the audit pointless.
+`;
+}
+
+// src/templates/skills/team-foundry-capture.ts
+function captureSkillTemplate(_ctx) {
+  return `---
+description: Capture what was learned in this session into the right team-foundry file
+---
+
+# /team-foundry-capture
+
+You have been asked to capture what was learned or decided in this session into the team's team-foundry files.
+
+## What to do
+
+**Do not write any file until you have shown the proposed content and received explicit confirmation.**
+
+### Step 1 \u2014 identify what's worth keeping
+
+Review this conversation for:
+
+- **Validated claims**: something that was confirmed by data, user research, or a real event (e.g., "we tested X and users did Y")
+- **Decisions**: something the team chose to do or not do, and why
+- **Invalidated assumptions**: something the team believed that turned out to be wrong
+- **New risks or blockers**: something that emerged that could affect the work
+- **Glossary terms**: domain language that came up and should be defined for the AI
+
+Ignore: process discussions, brainstorming that went nowhere, anything already in the files.
+
+### Step 2 \u2014 map to the right file
+
+| What you learned | Where it goes |
+|------------------|---------------|
+| An outcome is now validated | \`team-foundry/product/outcomes.md\` \u2014 move to Validated section, add source |
+| A customer segment was confirmed | \`team-foundry/product/customers.md\` \u2014 add to Validated with source |
+| An assumption was tested | \`team-foundry/product/assumptions.md\` \u2014 update status, add result |
+| A key decision was made | \`team-foundry/engineering/decisions/\` \u2014 new ADR or update existing |
+| A new risk surfaced | \`team-foundry/product/risks.md\` \u2014 add with impact and mitigation |
+| A term needs defining | \`team-foundry/context/glossary.md\` \u2014 add entry |
+| A metric moved | \`team-foundry/data/metrics.md\` \u2014 update with date and source |
+
+### Step 3 \u2014 write the update
+
+For each piece of learning, draft the update text and show it to the team before writing. Include:
+
+- The claim or decision in plain language
+- The source or evidence (who said it, what data, what date)
+- For validated items: update \`last_validated:\` in the frontmatter if stale
+
+### Step 4 \u2014 confirm and write
+
+Show the proposed changes. Ask: "Should I write these to the files?"
+
+Do not write anything without confirmation.
+`;
+}
+
+// src/templates/skills/team-foundry-decision.ts
+function decisionSkillTemplate(_ctx) {
+  return `---
+description: Draft a new architecture decision record (ADR) from the current conversation
+---
+
+# /team-foundry-decision
+
+You have been asked to draft an Architecture Decision Record (ADR) from this conversation.
+
+## What to do
+
+**Do not write any file until you have shown the proposed content and received explicit confirmation.**
+
+### Step 1 \u2014 extract the decision
+
+From the conversation, identify:
+
+- **The decision**: what was chosen (one sentence)
+- **The context**: what problem were we solving, what constraints existed
+- **The options considered**: what else was on the table (even if briefly)
+- **The rationale**: why this option over the others
+- **The consequences**: what becomes easier, what becomes harder, what we're committing to
+
+If any of these are unclear, ask before drafting.
+
+### Step 2 \u2014 draft the ADR
+
+Use this format:
+
+\`\`\`markdown
+---
+title: [Short descriptive title]
+date: [today's date]
+status: Proposed
+---
+
+## Context
+[What situation or problem led to this decision. What constraints were in play.]
+
+## Decision
+[The choice made, stated as a clear action or commitment.]
+
+## Options considered
+- **[Option A]**: [Brief description and why it was considered]
+- **[Option B]**: [Brief description and why it was considered]
+
+## Rationale
+[Why this option over the others. What evidence or reasoning tipped it.]
+
+## Consequences
+- What becomes easier: [...]
+- What becomes harder: [...]
+- What we're committing to: [...]
+\`\`\`
+
+### Step 3 \u2014 pick the file name
+
+ADRs go in \`team-foundry/engineering/decisions/\`. Use the format \`NNN-short-title.md\` where NNN is the next sequential number. List the files in \`team-foundry/engineering/decisions/\` to find the highest existing number, then use that number + 1. If the directory is empty or does not exist, start at \`001\`.
+
+### Step 4 \u2014 confirm and write
+
+Show the draft. Ask: "Should I write this to \`team-foundry/engineering/decisions/[filename].md\`?"
+
+Do not write without confirmation.
+`;
+}
+
+// src/templates/skills/team-foundry-feature.ts
+function featureSkillTemplate(_ctx) {
+  return `---
+description: Synthesize everything team-foundry knows about a specific feature or work item
+---
+
+# /team-foundry-feature
+
+You have been asked to synthesize the full team context for a specific feature or work item.
+
+## What to do
+
+Ask (or infer from the conversation): **what feature or work item are we focusing on?**
+
+Then read the team-foundry files for everything relevant to it:
+
+### Product context
+- \`team-foundry/product/outcomes.md\` \u2014 which outcome(s) does this feature serve?
+- \`team-foundry/product/customers.md\` \u2014 which customer segment is this for?
+- \`team-foundry/product/now-next-later.md\` \u2014 where does this sit in the roadmap? (if present)
+- \`team-foundry/product/assumptions.md\` \u2014 what assumptions is this feature resting on? (if present)
+
+### Design and quality
+- \`team-foundry/design/principles.md\` \u2014 design constraints that apply (if present)
+- \`team-foundry/engineering/quality-bar.md\` \u2014 definition of done (if present)
+
+### Prior decisions
+- \`team-foundry/engineering/decisions/\` \u2014 any ADRs that affect this feature's approach
+
+### Domain context
+- \`team-foundry/context/glossary.md\` \u2014 terms relevant to this feature (if present)
+
+## Output format
+
+Produce a feature brief:
+
+**Feature:** [name]
+
+**Why this matters:** [which validated outcome it moves, for which customer segment]
+
+**Assumptions underneath it:** [open assumptions from assumptions.md that this feature depends on]
+
+**Design constraints:** [relevant principles or quality bar items]
+
+**Prior decisions that shape the approach:** [relevant ADRs]
+
+**What the AI should keep in mind while working on this:** [anything that would change how code is written, what trade-offs to make, what not to do]
+
+## If files are sparse
+
+If the team-foundry files don't have enough to answer the questions above, say so explicitly:
+
+"I can see this feature targets [X], but there's no validated customer segment in customers.md to confirm who it's for. Before we build, it's worth checking whether [assumption] holds."
+
+Don't invent context. Surface the gap instead.
+`;
+}
+
 // src/templates/root-claude.ts
 function rootClaudeTemplate(ctx) {
   return `---
@@ -276,7 +616,8 @@ before answering. Files with recent \`last_updated\` dates are more reliable tha
 | 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\` |
+| Stakeholders and what they care about | \`team-foundry/context/stakeholders.md\` |${ctx.profile === "full" ? `
+| Which source wins when context conflicts | \`.team-foundry/hierarchy.md\` |` : ""}
 
 ## Coach
 
@@ -300,6 +641,19 @@ it notices something relevant to your current work. You can also invoke it direc
      - 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. -->
+
+## Skills
+
+Pre-built Claude Code skills are in \`.claude/skills/\`. Invoke them with a slash command:
+
+| Skill | What it does |
+|---|---|
+| \`/team-foundry-intro\` | Orient to the team \u2014 reads all context files, produces a summary |
+| \`/team-foundry-status\` | Status read \u2014 what's on track, at risk, or blocked this cycle |
+| \`/team-foundry-review\` | Full audit \u2014 all files checked, findings by severity |
+| \`/team-foundry-capture\` | Capture what was learned in this session into the right file |
+| \`/team-foundry-decision\` | Draft an ADR from the current conversation |
+| \`/team-foundry-feature\` | Synthesize everything team-foundry knows about a specific feature |
 `;
 }
 
@@ -354,7 +708,8 @@ before answering. Files with recent \`last_updated\` dates are more reliable tha
 | 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\` |
+| Stakeholders and what they care about | \`team-foundry/context/stakeholders.md\` |${ctx.profile === "full" ? `
+| Which source wins when context conflicts | \`.team-foundry/hierarchy.md\` |` : ""}
 
 ## Coach
 
@@ -463,7 +818,7 @@ it notices something relevant to your current work. You can also invoke it direc
 // 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";
-  const questionCount = ctx.profile === "solo" ? "10" : "18\u201325";
+  const questionCount2 = ctx.profile === "solo" ? "10" : "18\u201325";
   const fileCount = ctx.profile === "solo" ? "7" : "19";
   const ingestionNote = ctx.ingestionPath ? `
 > **Tip:** Before saying the phrase above, tell ${toolName}:
@@ -485,7 +840,7 @@ You've scaffolded ${fileCount} files. They're mostly empty. One thing to do now:
 
 > Open this project in **${toolName}** and say: **"Let's set up our team-foundry."**
 ${ingestionNote}
-The AI will walk you through a setup conversation \u2014 ${questionCount} questions, about 30 minutes.
+The AI will walk you through a setup conversation \u2014 ${questionCount2} questions, about 30 minutes.
 By the end, most files will be meaningfully populated.
 
 ## What the setup covers
@@ -549,7 +904,7 @@ 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 ? "9" : "18\u201325";
+  const questionCount2 = 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
@@ -671,7 +1026,7 @@ context of their actual work.
 **How to behave:**
 - Run all active coaching behaviors in priority order: B1 (outputs-vs-outcomes) \u2192
   B2 (customer staleness) \u2192 B3 (stale assumptions) \u2192 B4 (decisions without rationale) \u2192
-  ... \u2192 B12 (MCP suggestions) \u2192 discovery and strategy behaviors
+  ... \u2192 B12 (MCP suggestions) \u2192 discovery and strategy behaviors \u2192 B18 (unsourced claims, full only)
 - For each issue found: name it specifically (cite the file and exact content),
   explain why it matters in one sentence, offer to draft the fix
 - Group findings by severity: blockers (things actively misleading the AI or the team)
@@ -814,7 +1169,12 @@ window (inline mode) or until the next explicit review (explicit/scheduled mode)
 
 ## Context priority
 
-When two team-foundry files appear to contradict each other, resolve using this
+${!isSolo ? `Before reconciling any conflicting signals, read \`.team-foundry/hierarchy.md\`.
+It defines the authoritative precedence order across file types, data sources, expertise levels,
+and version authority. Apply it. Do not average conflicting claims \u2014 name the conflict and state
+which source wins.
+
+` : ""}When two team-foundry files appear to contradict each other, resolve using this
 order and **name the conflict explicitly** rather than silently picking one:
 
 1. \`north-star.md\` \u2014 destination, never overridden
@@ -854,7 +1214,7 @@ The team-foundry files are the index. ${featureQueryIndexNote}
 
 ## Behaviors
 
-Behaviors run in priority order (B1\u2192B12, then discovery and strategy behaviors). In explicit mode, run all of them.
+Behaviors run in priority order (B1\u2192B12, then discovery and strategy behaviors; B18\u2013B20 full profile only). In explicit mode, run all of them.
 In inline mode, run only the highest-priority behavior whose inline trigger condition
 is met for the user's current question. If multiple triggers apply, pick the
 highest-priority one \u2014 do not surface multiple behaviors in a single inline nudge.
@@ -1475,12 +1835,98 @@ offer to retire it: move it from Active rules to Retired rules with today's date
 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.
 
+**Knowledge routing:** B17 handles team process patterns only \u2014 things that should shape future coaching.
+For other types of learning surfaced in a session, route to the right file:
+
+| What was learned | Where it goes | How |
+|---|---|---|
+| A team process pattern | \`.team-foundry/team-lessons.md\` | B17 (this behavior) |
+| A validated claim or customer insight | \`team-foundry/product/outcomes.md\` or \`customers.md\` | Offer \`/team-foundry-capture\` (B20) |
+| An architectural decision | \`team-foundry/engineering/decisions/\` (full profile only) | Offer \`/team-foundry-decision\` |
+| A tested assumption | \`team-foundry/product/assumptions.md\` (full profile only) | Offer \`/team-foundry-capture\` (B20) |
+| A new risk | \`team-foundry/product/risks.md\` (full profile only) | Offer \`/team-foundry-capture\` (B20) |
+
+Do not mix routing: if the user names a pattern, use B17. If the session surfaces validated data, use B20.
+
 **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
+${!isSolo ? `### Behavior 18: Unsourced quantitative claim
+
+**Severity:** Low \u2014 flag once, do not repeat in the same conversation.
+
+**Trigger condition:** A team-foundry file contains a number, percentage, or currency figure
+(e.g. "62% win rate", "saves 4 hours/week", "$1.2M ARR") without either:
+- a \`source:\` frontmatter field that is not \`~\`, or
+- an inline source reference in the form \`(source, date)\` near the claim.
+
+**What to say:**
+> "I noticed a quantitative claim in [filename]: '[the claim]'. I don't see a source for it.
+> If this comes from data, add a \`source:\` value to the frontmatter or an inline note like
+> \`(source, date)\` next to the figure. If it's an estimate or assumption, consider moving
+> it to assumptions.md so the team knows it hasn't been validated."
+
+**What not to do:**
+- Do not flag every file on every review \u2014 one pass per file per session.
+- Do not treat the absence of a source as an error; it's a signal to investigate, not a blocker.
+- Do not ask for sources on qualitative statements (opinions, framings, examples).
+
+---
+
+### Behavior 19: Validated entry without evidence
+
+**Severity:** Medium \u2014 the word "Validated" makes an implicit promise to readers.
+
+**Trigger condition:** An entry appears under a validated section in any of the three target files
+but contains no source reference \u2014 neither an inline \`(source, date)\` near the entry, nor a
+populated \`source:\` frontmatter field in the same file.
+
+The validated section headers are file-specific:
+- \`customers.md\` \u2192 \`## Validated\`
+- \`outcomes.md\` \u2192 \`## Validated outcomes\`
+- \`now-next-later.md\` \u2192 \`## Now (validated outcomes)\`
+
+**What to say:**
+> "[filename] has an entry in the validated section that doesn't cite evidence:
+> '[the entry]'. Validated sections carry an implicit promise \u2014 readers trust them more.
+> If this is backed by data, add a source reference inline \`(source, date)\` or in the
+> file's \`source:\` frontmatter. If it's still an assumption, move it to the hypothesized
+> section so the team reads it with the right level of trust."
+
+**What not to do:**
+- Do not flag entries in hypothesized sections \u2014 those explicitly signal unvalidated beliefs.
+- Do not demand a specific source format \u2014 any inline note or frontmatter value is sufficient.
+- Do not block work; surface the gap and offer to help relocate the entry if the team prefers.
+
+---
+
+### Behavior 20: Session-end knowledge capture
+
+**Severity:** Low \u2014 this is an offer, not a finding.
+
+**Trigger condition:** The session included at least one of:
+- A claim that was confirmed or invalidated by data, research, or a real event
+- A decision the team made (what to build, what to cut, what approach to take)
+- A risk or blocker that surfaced and was not previously documented
+
+Do not trigger if the session was purely a coding or debugging session with no product/team learning.
+
+**What to say:**
+> "Before we close \u2014 this session surfaced [brief summary: e.g., 'a validated customer segment' / 'a decision about X' / 'a new risk around Y']. Want me to run \`/team-foundry-capture\` to save it to the right files? It takes about two minutes and keeps the context current for future sessions."
+
+Only proceed after the user explicitly confirms. The conversation-as-update confirmation rules apply \u2014 silence or an ambiguous response is not a yes.
+
+**What not to do:**
+- Do not trigger on every session \u2014 only when there is something clearly worth preserving.
+- Do not run \`/team-foundry-capture\` without the team saying yes.
+- Do not summarize the entire conversation \u2014 name the specific learnable item only.
+- Do not offer if the user has already run \`/team-foundry-capture\` in this session.
+
+---
+
+` : ""}## Quarterly retrospective
 
 ### Trigger
 
@@ -1685,10 +2131,21 @@ fields. If the user says "looks good," proceed immediately to Step 4.
 
 ### Step 4 \u2014 Write files
 
-Write all team-foundry files using confirmed data. For any field with no signal and
-no user-provided answer, write a \`<!-- GAP: ... -->\` marker. Follow the
-conversation-as-update protocol \u2014 show each file draft and wait for confirmation
-before writing.
+Write **all** team-foundry files that have at least one confirmed signal. Do not skip
+files just because they were not mentioned in the pre-fill summary \u2014 if the repo scan
+gave you data for a file, populate it now.
+
+Signal-to-file mapping (use this to decide what to write):
+- Stack (language, framework, dependencies from manifest file) \u2192 \`team-foundry/engineering/stack.md\`
+- Product name + what it does (README) \u2192 \`team-foundry/product/north-star.md\` (name field)
+- Recent commit messages \u2192 \`team-foundry/product/outcomes.md\` (inferred focus areas \u2014 frame as customer outcomes, not shipped features)
+- Open issues / PRs \u2192 \`team-foundry/product/assumptions.md\` (open bets, if full profile)
+- \`team-foundry/product/customers.md\` \u2014 no repo signal; write gap marker, surface in Step 5
+- Root instruction file \u2014 always write/update with product name and stack summary
+
+For any field with no signal and no user-provided answer, write a \`<!-- GAP: ... -->\`
+marker. Follow the conversation-as-update protocol \u2014 show each file draft and wait
+for confirmation before writing.
 
 **No silent writes.** Even high-confidence pre-filled answers require explicit
 confirmation before being written to disk. "Looks good" or "yes" is confirmation.
@@ -1887,7 +2344,7 @@ outdated. Every answer needs the user's confirmation before it becomes a file.
 
 **Opening framing** (say this verbatim \u2014 the question count, time estimate, and file-writing detail are load-bearing):
 
-> "We're going to set up your team-foundry \u2014 ${questionCount} questions across
+> "We're going to set up your team-foundry \u2014 ${questionCount2} questions across
 > 9 themes. Each answer goes directly into a file as we go,
 > so you'll see the files populate in real time. You can skip anything you don't
 > have an answer to right now \u2014 I'll mark it as a gap instead of leaving it blank.
@@ -2232,8 +2689,8 @@ After the last question, do the following:
    \u2192 north star (grounds the coach) \u2192 stack (engineering context).
    Wait for the user to say yes or choose a different file. If they say yes, proceed
    directly to the interview questions for that file as defined in the interview section
-   above \u2014 do not re-run the full interview. If they decline, proceed to step 4.
-   If all files are populated, skip this offer and proceed directly to step 4.
+   above \u2014 do not re-run the full interview. If they decline, proceed to the "Offer the coach" step below.
+   If all files are populated, skip this offer and proceed directly to the "Offer the coach" step below.
 
 4. **Offer the coach.** End with:
    > "Your team-foundry is set up. You can ask me to review it any time by saying
@@ -2306,7 +2763,9 @@ 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: 
+last_validated: ~
+source: ~
+owner:
 ---
 
 # Outcomes
@@ -2325,7 +2784,24 @@ owner:
      "Write your outcomes in the form 'we want X to change for Y customer segment.'
      What does winning this quarter look like for your customers, not your roadmap?" -->
 
-## This quarter
+${ctx.profile === "full" ? `## Validated outcomes
+
+<!-- Outcomes confirmed by data: cohort analysis, retention curves, usage metrics, or direct
+     customer evidence. Each entry needs a source \u2014 inline (source, date) or in the frontmatter.
+     If you can't name the evidence, move it to Hypothesized.
+
+     Format: outcome statement + evidence reference + date confirmed.
+     Example: "New sellers list their first item within 48h of signup (cohort data, Q1 2026)" -->
+
+## Hypothesized outcomes
+
+<!-- Outcomes you believe are worth pursuing but haven't yet validated with data.
+     State the assumption and what would confirm it.
+
+     Format: outcome statement + assumption + validation signal.
+     Example: "Ops managers close reconciliation in <30 min \u2014 assumed from 3 sales calls.
+     Validate: measure time-on-task for 5 ops managers over one cycle." -->
+` : `## This quarter
 
 <!-- List 2\u20134 outcome statements. Each should be falsifiable \u2014 you'll know at quarter-end
      whether it happened.
@@ -2340,6 +2816,7 @@ owner:
      - "Ship the new dashboard" (feature, not behavior change)
      - "Complete the API integration" (milestone, not customer outcome)
      - "Improve retention" (direction, not a measurable change) -->
+`}
 `;
 }
 
@@ -2350,7 +2827,9 @@ 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: 
+last_validated: ~
+source: ~
+owner:
 ---
 
 # Customers
@@ -2374,7 +2853,40 @@ ${visibilityNote}
      "Name three customers you've spoken to directly. For each: what did you learn,
      and when was the last time you talked to them?" -->
 
-## Personas
+${ctx.profile === "full" ? `## Validated
+
+<!-- Customers confirmed by cohort data, win-rate analysis, or direct evidence.
+     Every entry here needs a source \u2014 inline (source, date) or in the file's source: frontmatter.
+     If you can't name the evidence, move the entry to Hypothesized.
+
+     Format per entry:
+     ### [Segment name \u2014 e.g. "IT consultancies, 20\u201350 staff"]
+     **Win rate / evidence:** [e.g. "62% win rate (cohort data, Q4 2025)"]
+     **Job to be done:** When [situation], I want to [motivation], so I can [expected outcome].
+     **Last direct contact:** YYYY-MM-DD
+     **Quote:** "[Something a real customer said]" -->
+
+## Hypothesized
+
+<!-- Customers you believe are a fit but haven't validated with data.
+     State the assumption explicitly and what would confirm it.
+
+     Format per entry:
+     ### [Segment name]
+     **Why we believe this:** [reasoning \u2014 pattern from sales calls, founder intuition, etc.]
+     **What would validate it:** [specific signal \u2014 cohort analysis, X wins in segment, etc.]
+     **Last direct contact:** YYYY-MM-DD (or "never") -->
+
+## Anti-ICP
+
+<!-- Explicitly who this product is NOT for \u2014 with reasoning.
+     Anti-ICP entries prevent scope creep and help the AI avoid suggesting work
+     that serves the wrong customer. Be explicit about why they're excluded.
+
+     Format per entry:
+     ### [Segment name]
+     **Why excluded:** [specific reason \u2014 wrong pain, wrong scale, misaligned incentives, etc.] -->
+` : `## Personas
 
 <!-- For each persona below:
      - Give them a name or a specific role (not a label like "power user")
@@ -2395,6 +2907,7 @@ ${visibilityNote}
 **Quote:** "[Something they actually said]"
 **What we learned:** [The non-obvious thing \u2014 the thing that would surprise an outsider]
 -->
+`}
 `;
 }
 
@@ -2404,7 +2917,9 @@ 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: 
+last_validated: ~
+source: ~
+owner:
 ---
 
 # Now / Next / Later
@@ -2431,7 +2946,39 @@ owner:
      What have you committed to doing after that?
      What's directional but not yet committed?" -->
 
-## Now
+${ctx.profile === "full" ? `## Now (validated outcomes)
+
+<!-- Active work connected to a validated outcome \u2014 something backed by data or direct
+     customer evidence. Each item has an outcome reference and a source.
+
+     Format: item \u2192 outcome reference | evidence | owner | started date.
+     Example:
+     - **Self-serve report fix flow** \u2192 "ops managers close reconciliation in <30 min"
+       Evidence: usability study (March 2026) | Owner: [name] | Started: [date] -->
+
+## Now (hypothesized outcomes)
+
+<!-- Active work connected to a hypothesized outcome \u2014 believed to matter but not yet
+     validated. These are bets, not commitments. The outcome link should be explicit so the
+     AI can flag it when the hypothesis is later confirmed or invalidated.
+
+     Format: item \u2192 hypothesis | what would validate | owner.
+     Example:
+     - **Onboarding redesign** \u2192 hypothesis: "new sellers list first item within 48h"
+       Validate: track time-to-first-listing for next cohort | Owner: [name] -->
+
+## Next
+
+<!-- Committed work, sequenced. Whether linked to a validated or hypothesized outcome,
+     the commitment is real \u2014 there's a reason this follows from what's in Now.
+
+     If everything in Next could plausibly be first, it isn't sequenced \u2014 it's a list. -->
+
+## Later
+
+<!-- Directional bets. Not scheduled, not promised. Label each with its outcome hypothesis
+     so the AI can flag it if that hypothesis is validated or invalidated before you get here. -->
+` : `## Now
 
 <!-- Active work. For each item: what it is, which outcome it serves, who owns it.
 
@@ -2455,6 +3002,7 @@ owner:
 
      It's okay for "later" to be short. A short, honest "later" is better than a long,
      wishful one. -->
+`}
 `;
 }
 
@@ -2464,7 +3012,9 @@ 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: 
+last_validated: ~
+source: ~
+owner:
 ---
 
 # Assumptions
@@ -3026,7 +3576,9 @@ 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: 
+last_validated: ~
+source: ~
+owner:
 ---
 
 # Metrics
@@ -3276,6 +3828,13 @@ See \`team-foundry/engineering/quality-bar.md\` for the quality bar, bug triage
 - **Private folder** \u2014 \`team-foundry/private/\` is gitignored. Do not read from or write to it.${isSolo ? "" : `
 - **ADR commitments** \u2014 architecture decisions in \`team-foundry/engineering/decisions/\` represent committed choices. Treat them as constraints unless the user explicitly opens a discussion.`}
 
+## Claude Code skills
+
+If you are running as Claude Code, pre-built skills are available in \`.claude/skills/\`:
+\`/team-foundry-intro\`, \`/team-foundry-status\`, \`/team-foundry-review\`,
+\`/team-foundry-capture\`, \`/team-foundry-decision\`, \`/team-foundry-feature\`.
+See CLAUDE.md for the full skill table.
+
 ## Working with the team-foundry coach
 
 The coach runs in three modes \u2014 inline (always on, surfaces one-sentence nudges), explicit (triggered by "coach mode" or "let's do a team-foundry review"), and scheduled (weekly check-in, top 3 findings). See CLAUDE.md or GEMINI.md for the full trigger phrase table and loading instructions.
@@ -3288,6 +3847,165 @@ See \`team-foundry/context/glossary.md\` for domain terms, acronyms, and known n
 `}`;
 }
 
+// src/templates/hierarchy.ts
+function hierarchyTemplate(ctx) {
+  return `---
+purpose: Trust precedence rules the coach applies when context conflicts across files
+read_when: Before reconciling conflicting signals; when claims in different files disagree
+last_updated: ${ctx.date}
+owner: team
+---
+
+# Context Hierarchy
+
+When signals conflict across team-foundry files, apply these precedence rules in order.
+Do not average conflicting data \u2014 name the conflict and state which source wins and why.
+
+## File Precedence
+
+1. **Constitution** \u2014 CLAUDE.md / GEMINI.md (always-loaded rules and routing)
+2. **Context files** \u2014 team-foundry/ files (the substance of what the team knows)
+3. **Memory / notes** \u2014 session notes, conversation history
+4. **Project logs** \u2014 git log, CI output, issue trackers
+
+*When a context file contradicts a memory note, the context file wins.*
+
+## Data Source Precedence
+
+1. **Measured live data** \u2014 dashboards, analytics, cohort exports with a date
+2. **Own assessment** \u2014 team's direct analysis with reasoning
+3. **Own notes** \u2014 meeting notes, interview summaries
+4. **Automatic notes** \u2014 AI-generated summaries, auto-transcripts
+5. **Customer claims** \u2014 what customers say (without corroborating data)
+
+*When cohort data disagrees with a customer claim, cohort data wins.*
+*Always note which source tier a claim comes from.*
+
+## Expertise Precedence
+
+1. **Domain expert** \u2014 someone with direct, validated experience in this area
+2. **Team** \u2014 collective judgment based on what the team has observed
+3. **AI general knowledge** \u2014 the model's training knowledge (no team-specific context)
+4. **Web search** \u2014 external sources with no team context
+
+*When your domain expert's view conflicts with AI general knowledge, the expert wins.*
+
+## Version Authority
+
+- **Working docs** (team-foundry/ files, CLAUDE.md): latest commit wins
+- **Research** (customer interviews, experiments, market data): newer does not supersede older \u2014
+  it adds a data point. A 2026 interview does not erase a 2025 cohort result; it adds signal.
+  Surface both and name the gap.
+
+## How to Apply
+
+When you see conflicting signals:
+1. Name the conflict explicitly \u2014 do not silently pick one
+2. State which source wins per the hierarchy above
+3. Note what evidence would resolve the conflict
+`;
+}
+
+// src/templates/instructions/hooks.ts
+function hooksTemplate(ctx) {
+  return `---
+purpose: Enforced behavioral instructions \u2014 the AI must follow these before acting
+read_when: Before editing any team-foundry file; before using external tools or paid APIs
+last_updated: ${ctx.date}
+owner: team
+---
+
+# Hooks
+
+These are markdown conventions, not executable scripts. They define behaviors the AI
+must treat as enforced \u2014 not suggestions to weigh against convenience.
+
+In v3.1, an optional \`--with-hooks\` flag will generate real Claude Code hook scripts
+wired to \`.claude/settings.json\`. For now, treat this file as the enforcement layer.
+
+---
+
+## Before reconciling conflicting signals
+
+Read \`.team-foundry/hierarchy.md\` first.
+Do not average conflicting claims. Name the conflict, state which source wins per the
+hierarchy, and note what evidence would resolve it.
+
+**Never do:** silently pick the more recent or more confident-sounding claim without
+stating which hierarchy tier it comes from.
+
+---
+
+## Before editing any team-foundry file
+
+Follow the conversation-as-update protocol in \`.team-foundry/coach.md\`.
+
+1. Surface the finding and name the gap (diagnosis message)
+2. Draft the proposed change in a separate message
+3. Wait for explicit confirmation before writing
+
+**Never do:** edit team-foundry files without showing the draft and receiving
+a clear "yes", "looks good", "go ahead", or equivalent. Silence is not confirmation.
+
+---
+
+## Before using paid tools or external MCPs
+
+Ask first. Paid tools include: web search APIs, external MCP servers billed per call,
+AI image generation, or any tool that incurs a cost outside this session.
+
+State: what tool you want to use, why, and what the alternative is if the user declines.
+
+**Never do:** trigger a paid or external tool call without the user's explicit approval
+in the current session.
+`;
+}
+
+// src/templates/instructions/rules.ts
+function rulesTemplate(ctx) {
+  return `---
+purpose: Always-loaded behavioral rules \u2014 kept minimal so they actually get followed
+read_when: Every coach session (explicit, scheduled, inline). Load before any coaching action.
+last_updated: ${ctx.date}
+owner: team
+---
+
+# Rules
+
+Behavioral rules for the team-foundry coach. These are always loaded \u2014 keep this file
+minimal. If a rule applies to fewer than 80% of sessions, move it to a reference file
+and add a pointer here instead.
+
+---
+
+1. **Diagnostic-first.** Name the gap before suggesting a fix. Do not open with advice.
+   "Your outcomes look like outputs" before "Here's how to reframe them."
+
+2. **Source every quantitative claim.** Any number, percentage, or currency figure in a
+   team-foundry file needs a \`source:\` frontmatter value or an inline \`(source, date)\`.
+   Flag unsourced claims \u2014 do not silently accept them.
+
+3. **Separate validated from hypothesized.** A claim in a Validated section without a
+   \`source:\` reference or inline \`(source, date)\` is a hypothesis. Say so. \`last_validated:\`
+   tracks staleness \u2014 it does not substitute for a source.
+
+4. **No silent writes.** Follow the conversation-as-update protocol. Draft \u2192 confirm \u2192
+   write. Silence is not confirmation.
+
+5. **Hell-yes standard.** Every file, coaching nudge, and onboarding question must be
+   obviously essential or it gets cut. Flag padding \u2014 don't add to it.
+
+6. **One nudge per response in inline mode.** Surface the single most important gap.
+   Do not stack multiple coaching observations in the same inline message.
+
+7. **Respect nudge memory.** If the team has declined a finding in the last 7 days,
+   do not resurface it unless they explicitly ask.
+
+8. **Never block work.** Coaching is observational. Note the gap, offer to help, then
+   let the team proceed. Do not gate work on a coaching fix.
+`;
+}
+
 // src/scaffold.ts
 var ALWAYS_ROOT_ENTRIES = [
   { relativePath: "AGENTS.md", content: rootAgentsTemplate }
@@ -3316,7 +4034,10 @@ var FULL_ONLY_ENTRIES = [
   { relativePath: "team-foundry/data/metrics.md", content: metricsTemplate },
   { relativePath: "team-foundry/context/glossary.md", content: glossaryTemplate },
   { relativePath: "team-foundry/context/stakeholders.md", content: stakeholdersTemplate },
-  { relativePath: "team-foundry/product/strategy.md", content: strategyTemplate }
+  { relativePath: "team-foundry/product/strategy.md", content: strategyTemplate },
+  { relativePath: ".team-foundry/hierarchy.md", content: hierarchyTemplate },
+  { relativePath: ".team-foundry/instructions/hooks.md", content: hooksTemplate },
+  { relativePath: ".team-foundry/instructions/rules.md", content: rulesTemplate }
 ];
 var FEDERATED_ENTRIES = [
   { relativePath: "team-foundry/product/CLAUDE.md", content: federatedProductTemplate },
@@ -3326,6 +4047,14 @@ var FEDERATED_ENTRIES = [
   { relativePath: "team-foundry/data/CLAUDE.md", content: federatedDataTemplate },
   { relativePath: "team-foundry/context/CLAUDE.md", content: federatedContextTemplate }
 ];
+var CLAUDE_SKILLS_ENTRIES = [
+  { relativePath: ".claude/skills/team-foundry-intro.md", content: introSkillTemplate },
+  { relativePath: ".claude/skills/team-foundry-status.md", content: statusSkillTemplate },
+  { relativePath: ".claude/skills/team-foundry-review.md", content: reviewSkillTemplate },
+  { relativePath: ".claude/skills/team-foundry-capture.md", content: captureSkillTemplate },
+  { relativePath: ".claude/skills/team-foundry-decision.md", content: decisionSkillTemplate },
+  { relativePath: ".claude/skills/team-foundry-feature.md", content: featureSkillTemplate }
+];
 function rootEntries(tool) {
   if (tool === "claude") {
     return [{ relativePath: "CLAUDE.md", content: rootClaudeTemplate }];
@@ -3344,13 +4073,16 @@ function rootEntries(tool) {
 async function scaffold(options) {
   const { targetDir, profile, tool, repoVisibility, date, ingestionPath, ingestion, federated } = options;
   const ctx = { profile, tool, repoVisibility, date, ingestionPath, ingestion };
+  const includesSkills = tool === "claude" || tool === "both";
   const entries = [
     ...ALWAYS_ROOT_ENTRIES,
     ...rootEntries(tool),
     ...SOLO_ENTRIES,
     ...profile === "full" ? FULL_ONLY_ENTRIES : [],
-    ...profile === "full" && federated ? FEDERATED_ENTRIES : []
+    ...profile === "full" && federated ? FEDERATED_ENTRIES : [],
+    ...includesSkills ? CLAUDE_SKILLS_ENTRIES : []
   ];
+  const written = [];
   for (const entry of entries) {
     const fullPath = path.join(targetDir, entry.relativePath);
     const dir = path.dirname(fullPath);
@@ -3361,7 +4093,23 @@ async function scaffold(options) {
     } catch {
     }
     await fs.writeFile(fullPath, entry.content(ctx), "utf-8");
+    written.push(entry.relativePath);
   }
+  return written;
+}
+function gitAddCommand(tool) {
+  const toolFiles = [];
+  if (tool === "claude" || tool === "both") toolFiles.push("CLAUDE.md", ".claude/");
+  if (tool === "gemini" || tool === "both") toolFiles.push("GEMINI.md");
+  if (tool === "cursor") toolFiles.push(".cursor/");
+  const paths = [
+    "team-foundry/",
+    ".team-foundry/",
+    "AGENTS.md",
+    "GETTING_STARTED.md",
+    ...toolFiles
+  ].join(" ");
+  return `git add ${paths} && git commit -m "Add team-foundry"`;
 }
 
 // src/gitignore.ts
@@ -3801,7 +4549,131 @@ async function runStatus(targetDir) {
   }
 }
 
+// src/migrate.ts
+import fs4 from "fs/promises";
+import path4 from "path";
+import { confirm, log, outro as outro2 } from "@clack/prompts";
+async function detectTool(targetDir) {
+  const checks = [
+    [".cursor/rules/team-foundry.mdc", "cursor"],
+    ["GEMINI.md", "gemini"],
+    ["CLAUDE.md", "claude"]
+  ];
+  for (const [relPath, tool] of checks) {
+    try {
+      await fs4.access(path4.join(targetDir, relPath));
+      return tool;
+    } catch {
+    }
+  }
+  return "claude";
+}
+async function detectMigrateState(targetDir) {
+  const tfDir = path4.join(targetDir, ".team-foundry");
+  try {
+    await fs4.access(tfDir);
+  } catch {
+    return "none";
+  }
+  try {
+    await fs4.access(path4.join(tfDir, "hierarchy.md"));
+    return "v3";
+  } catch {
+    return "v2";
+  }
+}
+async function writeIfAbsent(filePath, content) {
+  await fs4.mkdir(path4.dirname(filePath), { recursive: true });
+  try {
+    await fs4.writeFile(filePath, content, { flag: "wx", encoding: "utf-8" });
+  } catch (err) {
+    if (err.code !== "EEXIST") throw err;
+  }
+}
+async function appendFrontmatterFields(filePath) {
+  let content;
+  try {
+    content = await fs4.readFile(filePath, "utf-8");
+  } catch {
+    return;
+  }
+  if (!content.startsWith("---")) return;
+  const closeIdx = content.indexOf("\n---", 3);
+  if (closeIdx === -1) return;
+  const frontmatter = content.slice(0, closeIdx);
+  const rest = content.slice(closeIdx);
+  let updated = frontmatter;
+  if (!frontmatter.includes("last_validated:")) {
+    updated += "\nlast_validated: ~";
+  }
+  if (!frontmatter.includes("source:")) {
+    updated += "\nsource: ~";
+  }
+  if (updated === frontmatter) return;
+  await fs4.writeFile(filePath, updated + rest, "utf-8");
+}
+var DATA_HEAVY_FILES = [
+  "team-foundry/product/outcomes.md",
+  "team-foundry/product/customers.md",
+  "team-foundry/data/metrics.md",
+  "team-foundry/product/assumptions.md",
+  "team-foundry/product/now-next-later.md"
+];
+async function runMigrate(targetDir) {
+  const state = await detectMigrateState(targetDir);
+  if (state === "none") {
+    log.error("No existing team-foundry found. Run npx create-team-foundry to scaffold v3.");
+    process.exit(1);
+  }
+  if (state === "v3") {
+    outro2("Already on v3. Nothing to migrate.");
+    return;
+  }
+  log.info(
+    "v2 team-foundry detected. Migration will add:\n\n  .team-foundry/hierarchy.md\n  .team-foundry/instructions/hooks.md\n  .team-foundry/instructions/rules.md\n\nAnd append source: / last_validated: to frontmatter of:\n\n" + DATA_HEAVY_FILES.map((f) => `  ${f}`).join("\n") + "\n\nExisting files are never overwritten."
+  );
+  const ok = await confirm({ message: "Proceed with migration?" });
+  if (!ok) {
+    outro2("Migration cancelled. No files were changed.");
+    return;
+  }
+  const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const tool = await detectTool(targetDir);
+  const ctx = {
+    profile: "full",
+    tool,
+    repoVisibility: "internal",
+    date
+  };
+  const tfDir = path4.join(targetDir, ".team-foundry");
+  await writeIfAbsent(path4.join(tfDir, "hierarchy.md"), hierarchyTemplate(ctx));
+  await writeIfAbsent(path4.join(tfDir, "instructions", "hooks.md"), hooksTemplate(ctx));
+  await writeIfAbsent(path4.join(tfDir, "instructions", "rules.md"), rulesTemplate(ctx));
+  for (const relPath of DATA_HEAVY_FILES) {
+    const filePath = path4.join(targetDir, relPath);
+    await appendFrontmatterFields(filePath);
+  }
+  outro2(
+    `Migration complete.
+
+New files added to .team-foundry/. Your existing content is untouched.
+
+Open your AI tool and say: "Read .team-foundry/hierarchy.md and let's review
+what changed in v3."`
+  );
+}
+
 // src/index.ts
+function groupByFolder(paths) {
+  const groups = {};
+  for (const p of paths) {
+    const parts = p.split("/");
+    const folder = parts.length > 1 ? parts[0] : ".";
+    const file = parts.length > 1 ? parts.slice(1).join("/") : p;
+    (groups[folder] ??= []).push(file);
+  }
+  return groups;
+}
 var TOOL_LABEL = {
   claude: "Claude Code",
   gemini: "Gemini CLI",
@@ -3823,69 +4695,119 @@ 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 = path4.join(targetDir, "team-foundry-prd-v2.md");
-  const scaffoldPath = path4.join(targetDir, "src", "scaffold.ts");
+  const prdPath = path5.join(targetDir, "team-foundry-prd-v2.md");
+  const scaffoldPath = path5.join(targetDir, "src", "scaffold.ts");
   let isSourceRepo = false;
   try {
-    await fs4.access(prdPath);
+    await fs5.access(prdPath);
     isSourceRepo = true;
   } catch {
   }
   try {
-    await fs4.access(scaffoldPath);
+    await fs5.access(scaffoldPath);
     isSourceRepo = true;
   } catch {
   }
   if (isSourceRepo) {
-    log.error(
+    log2.error(
       "You're running create-team-foundry inside the team-foundry source repo.\nThis will overwrite development files.\n\ncd to your product repo first, then run this command again."
     );
     process.exit(1);
   }
-  const pkgPath = path4.join(targetDir, "package.json");
-  const srcPath = path4.join(targetDir, "src");
+  const pkgPath = path5.join(targetDir, "package.json");
+  const srcPath = path5.join(targetDir, "src");
   let hasPkg = false;
   let hasSrc = false;
   try {
-    await fs4.access(pkgPath);
+    await fs5.access(pkgPath);
     hasPkg = true;
   } catch {
   }
   try {
-    await fs4.access(srcPath);
+    await fs5.access(srcPath);
     hasSrc = true;
   } catch {
   }
   if (hasPkg && hasSrc) {
-    log.warn(
+    log2.warn(
       "This directory has a package.json and src/ \u2014 it looks like a Node.js project.\nteam-foundry works best in your product repo, not inside a library or CLI repo.\nIf this is the right place, continue. Otherwise Ctrl-C and cd to your product repo."
     );
-    const ok = await confirm({ message: "Continue anyway?" });
+    const ok = await confirm2({ message: "Continue anyway?" });
     if (!ok) {
-      outro2("Cancelled. cd to your product repo and try again.");
+      outro3("Cancelled. cd to your product repo and try again.");
       process.exit(0);
     }
   }
 }
+async function checkExistingInstall(targetDir) {
+  try {
+    await fs5.access(path5.join(targetDir, "team-foundry"));
+  } catch {
+    return null;
+  }
+  log2.warn(
+    "team-foundry is already set up in this directory.\nWhat would you like to do?"
+  );
+  const choice = await select2({
+    message: "Choose an option:",
+    options: [
+      { value: "status", label: "Run status \u2014 see which files are stale or missing" },
+      { value: "migrate", label: "Run migrate \u2014 upgrade to the latest profile" },
+      { value: "continue", label: "Continue anyway \u2014 re-run setup (adds any missing files)" }
+    ]
+  });
+  if (isCancel2(choice)) {
+    outro3("Cancelled.");
+    process.exit(0);
+  }
+  return choice;
+}
 async function main() {
   const targetDir = process.cwd();
   if (process.argv[2] === "status") {
     await runStatus(targetDir);
     return;
   }
+  if (process.argv[2] === "migrate") {
+    await runMigrate(targetDir);
+    return;
+  }
   await checkDirectory(targetDir);
+  const installChoice = await checkExistingInstall(targetDir);
+  if (installChoice === "status") {
+    await runStatus(targetDir);
+    return;
+  }
+  if (installChoice === "migrate") {
+    await runMigrate(targetDir);
+    return;
+  }
   const answers = await runPrompts();
   const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  await scaffold({ ...answers, targetDir, date });
+  const writtenPaths = await scaffold({ ...answers, targetDir, date });
   await writeGitignore(targetDir);
   if (answers.ingestion === "paste" || answers.ingestion === "repo+paste") {
-    const pastePath = path4.join(targetDir, ".team-foundry", "paste-content.md");
+    const pastePath = path5.join(targetDir, ".team-foundry", "paste-content.md");
     try {
-      await fs4.access(pastePath);
+      await fs5.access(pastePath);
     } catch {
-      await fs4.writeFile(pastePath, PASTE_PLACEHOLDER, "utf-8");
+      await fs5.writeFile(pastePath, PASTE_PLACEHOLDER, "utf-8");
+      writtenPaths.push(".team-foundry/paste-content.md");
     }
   }
+  if (writtenPaths.length > 0) {
+    const grouped = groupByFolder(writtenPaths);
+    const lines = ["", "Files created:"];
+    for (const [folder, files] of Object.entries(grouped)) {
+      lines.push(`  ${folder}/`);
+      for (const file of files) lines.push(`    ${file}`);
+    }
+    lines.push("", "Commit when ready:");
+    lines.push(`  ${gitAddCommand(answers.tool)}`);
+    log2.info(lines.join("\n"));
+  } else {
+    log2.info("No new files created \u2014 all files already exist.");
+  }
   const tool = TOOL_LABEL[answers.tool];
   let ingestionNote;
   if (answers.ingestion === "repo") {
@@ -3998,7 +4920,7 @@ Next steps:
   You can add existing docs later by editing .team-foundry/paste-content.md.
 `;
   }
-  outro2(
+  outro3(
     `Done! Your files are in:
 
   ${targetDir}
@@ -4010,6 +4932,6 @@ team commits to, so everyone's AI tool gets the same context.`
   );
 }
 main().catch((err) => {
-  log.error(err instanceof Error ? err.message : String(err));
+  log2.error(err instanceof Error ? err.message : String(err));
   process.exit(1);
 });