create-battle-plan 1.4.3 → 1.5.0

package/bin/cli.js

@@ -71,14 +71,6 @@ function ask(question) {
   });
 }
 
-async function askRequired(question, errorMsg) {
-  while (true) {
-    const answer = await ask(question);
-    if (answer) return answer;
-    console.log(`${YELLOW}   ${errorMsg}${RESET}`);
-  }
-}
-
 // ── Interactive folder picker (raw mode) ─────────────────
 
 function getDirs(dir) {
@@ -317,65 +309,155 @@ async function main() {
 
   initReadline();
 
-  // Question 1: Project description (one sentence — used for context, not the folder name)
-  const projectName = await askRequired(
-    `${DIM}[1/7]${RESET} ${BOLD}What's your project in one sentence?${RESET}\n> `,
-    'A one-sentence description is required — even rough is fine. Try again:'
-  );
+  // Type `:back` (or `:b`) at any prompt to revise the previous answer.
+  console.log(`${DIM}   tip: type ${BOLD}:back${RESET}${DIM} at any prompt to revise the previous answer${RESET}`);
   console.log('');
 
-  // Question 2: Short name (the actual folder slug). Default = cwd basename when sensible.
-  const cwdBasename = path.basename(process.cwd());
-  const cwdSlug = slugify(cwdBasename);
-  const cwdIsEmpty = (() => {
-    try { return fs.readdirSync(process.cwd()).length === 0; } catch { return false; }
-  })();
-  const sentenceSlug = slugify(projectName);
-  const truncatedSentenceSlug = sentenceSlug.split('-').slice(0, 3).join('-');
-  const genericNames = new Set(['projects', 'code', 'src', 'work', 'dev', 'repos', 'workspace', 'documents', 'desktop']);
-  const defaultShortName = (cwdIsEmpty && cwdSlug && !genericNames.has(cwdSlug))
-    ? cwdSlug
-    : (truncatedSentenceSlug || 'my-battle-plan');
-  const shortNameRaw = await ask(
-    `${DIM}[2/7]${RESET} ${BOLD}Short name for the folder?${RESET} ${DIM}(default: ${defaultShortName})${RESET}\n> `
-  );
-  const shortName = slugify(shortNameRaw) || defaultShortName;
-  console.log('');
+  const isBack = (s) => {
+    const t = s.trim().toLowerCase();
+    return t === ':back' || t === ':b';
+  };
+
+  // Each step reads `a` (answers so far) and writes its key. Returns {back:true}
+  // to step backwards, or {value} to advance. When `a[key]` already has a value
+  // (revisit), prompts show "press enter to keep" and accept empty input.
+  const a = {};
+
+  async function stepProject() {
+    const prior = a.projectName;
+    const hint = prior ? ` ${DIM}(currently: "${prior.length > 40 ? prior.slice(0, 40) + '…' : prior}" — enter to keep)${RESET}` : '';
+    while (true) {
+      const raw = await ask(`${DIM}[1/7]${RESET} ${BOLD}What's your project in one sentence?${RESET}${hint}\n> `);
+      if (isBack(raw)) return { back: true };
+      const v = raw.trim() || prior;
+      if (!v) {
+        console.log(`${YELLOW}   A one-sentence description is required — even rough is fine. Try again:${RESET}`);
+        continue;
+      }
+      return { value: v };
+    }
+  }
 
-  // Question 3: Time horizon
-  const horizon = await ask(
-    `${DIM}[3/7]${RESET} ${BOLD}What's your time horizon?${RESET} ${DIM}(e.g., "3 weeks to demo day", "6 months to launch", "ongoing")${RESET}\n> `
-  );
-  console.log('');
+  async function stepShortName() {
+    const cwdBasename = path.basename(process.cwd());
+    const cwdSlug = slugify(cwdBasename);
+    const cwdIsEmpty = (() => {
+      try { return fs.readdirSync(process.cwd()).length === 0; } catch { return false; }
+    })();
+    const sentenceSlug = slugify(a.projectName);
+    const truncatedSentenceSlug = sentenceSlug.split('-').slice(0, 3).join('-');
+    const genericNames = new Set(['projects', 'code', 'src', 'work', 'dev', 'repos', 'workspace', 'documents', 'desktop']);
+    const defaultShortName = (cwdIsEmpty && cwdSlug && !genericNames.has(cwdSlug))
+      ? cwdSlug
+      : (truncatedSentenceSlug || 'my-battle-plan');
+    const prior = a.shortName;
+    const hint = prior
+      ? `${DIM}(currently: "${prior}" — enter to keep)${RESET}`
+      : `${DIM}(default: ${defaultShortName})${RESET}`;
+    const raw = await ask(`${DIM}[2/7]${RESET} ${BOLD}Short name for the folder?${RESET} ${hint}\n> `);
+    if (isBack(raw)) return { back: true };
+    const trimmed = raw.trim();
+    const value = trimmed
+      ? (slugify(trimmed) || defaultShortName)
+      : (prior || defaultShortName);
+    return { value };
+  }
 
-  // Question 4: Metrics
-  const metricsRaw = await askRequired(
-    `${DIM}[4/7]${RESET} ${BOLD}What are the 3-5 key metrics you want to track?${RESET} ${DIM}(comma-separated, e.g., "outreach sent, calls booked, LOIs signed")${RESET}\n> `,
-    'At least one metric is required — pick anything quantifiable you care about. You can rename or add more later in metrics.yml. Try again:'
-  );
-  const metrics = metricsRaw.split(',').map((m) => m.trim()).filter(Boolean);
-  console.log('');
+  async function stepHorizon() {
+    const prior = a.horizon;
+    const hint = prior
+      ? `${DIM}(currently: "${prior}" — enter to keep)${RESET}`
+      : `${DIM}(e.g., "3 weeks to demo day", "6 months to launch", "ongoing")${RESET}`;
+    const raw = await ask(`${DIM}[3/7]${RESET} ${BOLD}What's your time horizon?${RESET} ${hint}\n> `);
+    if (isBack(raw)) return { back: true };
+    const trimmed = raw.trim();
+    return { value: trimmed || prior || '' };
+  }
 
-  // Question 5: Domains
-  const suggested = suggestDomains(projectName);
-  const domainsRaw = await askRequired(
-    `${DIM}[5/7]${RESET} ${BOLD}What domains does your work cover?${RESET} ${DIM}(comma-separated)\nSuggested based on your project: ${suggested}${RESET}\n> `,
-    `At least one domain is required — try the suggestions (${suggested}) or any topic area. Try again:`
-  );
-  const domains = domainsRaw.split(',').map((d) => d.trim().toLowerCase()).filter(Boolean);
-  console.log('');
+  async function stepMetrics() {
+    const prior = a.metrics;
+    const priorDisplay = prior && prior.length ? prior.join(', ') : '';
+    const hint = priorDisplay
+      ? `${DIM}(currently: "${priorDisplay}" — enter to keep, type "none" to clear)${RESET}`
+      : `${DIM}(comma-separated, e.g., "outreach sent, calls booked, LOIs signed" — or press enter to skip)${RESET}`;
+    const raw = await ask(`${DIM}[4/7]${RESET} ${BOLD}Any metrics to track?${RESET} ${hint}\n> `);
+    if (isBack(raw)) return { back: true };
+    const trimmed = raw.trim();
+    if (trimmed.toLowerCase() === 'none') return { value: [] };
+    if (!trimmed) return { value: prior || [] };
+    return { value: trimmed.split(',').map((m) => m.trim()).filter(Boolean) };
+  }
 
-  // Question 6: People
-  const peopleRaw = await ask(
-    `${DIM}[6/7]${RESET} ${BOLD}Who are the key people you'll be working with?${RESET} ${DIM}(format: "Name:Role, Name:Role" — or press enter to skip)${RESET}\n> `
-  );
-  const people = peopleRaw
-    ? peopleRaw.split(',').map((p) => {
+  async function stepDomains() {
+    const prior = a.domains;
+    const suggested = suggestDomains(a.projectName);
+    const priorDisplay = prior && prior.length ? prior.join(', ') : '';
+    const hint = priorDisplay
+      ? `${DIM}(currently: "${priorDisplay}" — enter to keep)${RESET}`
+      : `${DIM}(comma-separated)\nSuggested based on your project: ${suggested}${RESET}`;
+    while (true) {
+      const raw = await ask(`${DIM}[5/7]${RESET} ${BOLD}What domains does your work cover?${RESET} ${hint}\n> `);
+      if (isBack(raw)) return { back: true };
+      const trimmed = raw.trim();
+      if (!trimmed) {
+        if (prior && prior.length) return { value: prior };
+        console.log(`${YELLOW}   At least one domain is required — try the suggestions (${suggested}) or any topic area. Try again:${RESET}`);
+        continue;
+      }
+      return { value: trimmed.split(',').map((d) => d.trim().toLowerCase()).filter(Boolean) };
+    }
+  }
+
+  async function stepPeople() {
+    const prior = a.people;
+    const priorDisplay = prior && prior.length ? prior.map((p) => `${p.name}:${p.role}`).join(', ') : '';
+    const hint = priorDisplay
+      ? `${DIM}(currently: "${priorDisplay}" — enter to keep, type "none" to clear)${RESET}`
+      : `${DIM}(format: "Name:Role, Name:Role" — or press enter to skip)${RESET}`;
+    const raw = await ask(`${DIM}[6/7]${RESET} ${BOLD}Who are the key people you'll be working with?${RESET} ${hint}\n> `);
+    if (isBack(raw)) return { back: true };
+    const trimmed = raw.trim();
+    if (trimmed.toLowerCase() === 'none') return { value: [] };
+    if (!trimmed) return { value: prior || [] };
+    return {
+      value: trimmed.split(',').map((p) => {
         const [name, role] = p.split(':').map((s) => s.trim());
         return { name: name || '', role: role || '' };
-      }).filter((p) => p.name)
-    : [];
-  console.log('');
+      }).filter((p) => p.name),
+    };
+  }
+
+  const steps = [
+    { key: 'projectName', run: stepProject },
+    { key: 'shortName', run: stepShortName },
+    { key: 'horizon', run: stepHorizon },
+    { key: 'metrics', run: stepMetrics },
+    { key: 'domains', run: stepDomains },
+    { key: 'people', run: stepPeople },
+  ];
+
+  let i = 0;
+  while (i < steps.length) {
+    const r = await steps[i].run();
+    if (r.back) {
+      if (i === 0) {
+        console.log(`${YELLOW}   Already at the first question.${RESET}`);
+        continue;
+      }
+      i--;
+      continue;
+    }
+    a[steps[i].key] = r.value;
+    console.log('');
+    i++;
+  }
+
+  const projectName = a.projectName;
+  const shortName = a.shortName;
+  const horizon = a.horizon;
+  const metrics = a.metrics;
+  const domains = a.domains;
+  const people = a.people;
 
   // Question 7: Interactive folder picker
   const targetDir = await pickFolder(shortName);
@@ -454,7 +536,11 @@ _Start adding content here._
 
   console.log(`${DIM}   + docs/ (${domains.length} domain${domains.length > 1 ? 's' : ''})${RESET}`);
 
-  // Create metrics.yml
+  // Create metrics.yml — file always exists so scripts have a target, even if no
+  // metrics were declared (journal-style projects). The LLM can add metrics later.
+  const metricsBody = metrics.length
+    ? metrics.map((m) => `${metricKey(m)}: 0`).join('\n') + '\n'
+    : '# No metrics declared yet. Add them as `key: value` below when ready.\n';
   const metricsContent = [
     `# metrics.yml — project-wide metrics registry for ${projectName}`,
     '# The LLM updates this file FIRST in any cascade, before touching docs.',
@@ -462,16 +548,33 @@ _Start adding content here._
     '',
     `last_updated: ${today}`,
     '',
-    ...metrics.map((m) => `${metricKey(m)}: 0`),
-    '',
+    metricsBody,
   ].join('\n');
   fs.writeFileSync(path.join(targetDir, 'metrics.yml'), metricsContent);
-  console.log(`${DIM}   + metrics.yml (${metrics.length} metric${metrics.length > 1 ? 's' : ''})${RESET}`);
+  console.log(
+    `${DIM}   + metrics.yml (${metrics.length === 0 ? 'no metrics yet' : `${metrics.length} metric${metrics.length > 1 ? 's' : ''}`})${RESET}`
+  );
+
+  // Create battle plan — conditionally include Key Metrics section
+  const metricsSection = metrics.length
+    ? `## Key Metrics
+
+| Metric | Target | Current |
+|--------|--------|---------|
+${metrics.map((m) => `| ${m} | _set target_ | **0** (→ metrics.yml#${metricKey(m)}) |`).join('\n')}
 
-  // Create battle plan
-  const metricsTable = metrics
-    .map((m) => `| ${m} | _set target_ | **0** (→ metrics.yml#${metricKey(m)}) |`)
-    .join('\n');
+---
+
+`
+    : '';
+
+  const tldr = metrics.length
+    ? `${projectName} — just initialized. Time horizon: ${horizon || 'not set'}. All metrics at 0. First priority: fill in the battle plan with real tasks and targets.`
+    : `${projectName} — just initialized. Time horizon: ${horizon || 'not set'}. No metrics tracked yet (journal-style project). First priority: fill in the battle plan with real tasks.`;
+
+  const firstPriority = metrics.length
+    ? '- [ ] Set targets for each metric\n- [ ] Fill in this week\'s tasks\n- [ ] Record any existing conversations in external-insights.md'
+    : '- [ ] Fill in this week\'s tasks\n- [ ] Record any existing conversations in external-insights.md';
 
   fs.writeFileSync(
     path.join(targetDir, 'docs', 'battle-plan.md'),
@@ -482,7 +585,7 @@ _Start adding content here._
 **Role:** source-of-truth
 **Compression:** chronological
 
-**TL;DR:** ${projectName} — just initialized. Time horizon: ${horizon || 'not set'}. All metrics at 0. First priority: fill in the battle plan with real tasks and targets.
+**TL;DR:** ${tldr}
 
 ---
 
@@ -495,19 +598,9 @@ _Start adding content here._
 
 ---
 
-## Key Metrics
-
-| Metric | Target | Current |
-|--------|--------|---------|
-${metricsTable}
-
----
-
-## Today's Priorities
+${metricsSection}## Today's Priorities
 
-- [ ] Set targets for each metric
-- [ ] Fill in this week's tasks
-- [ ] Record any existing conversations in external-insights.md
+${firstPriority}
 
 ---
 
@@ -574,7 +667,7 @@ ${peopleSections}
   console.log(`${DIM}   + docs/battle-plan.md${RESET}`);
   console.log(`${DIM}   + docs/external-insights.md${RESET}`);
 
-  // Save onboarding answers for Claude to read on first /good-morning
+  // Save onboarding answers for Claude to read on first /welcome
   fs.writeFileSync(
     path.join(targetDir, '.battle-plan-onboarding.json'),
     JSON.stringify(
@@ -637,10 +730,13 @@ ${peopleSections}
   console.log(`${DIM}   │${RESET}  ${BOLD}cd ${relPath} && claude${RESET}${DIM}${' '.repeat(Math.max(0, 37 - relPath.length - 12))}│${RESET}`);
   console.log(`${DIM}   └─────────────────────────────────────────┘${RESET}`);
   console.log('');
-  console.log(`   Once Claude is running, type ${GREEN}${BOLD}/good-morning${RESET}`);
-  console.log(`   to start your first session. Claude will`);
-  console.log(`   introduce itself, explain how everything`);
-  console.log(`   works, and help you set your first targets.`);
+  console.log(`   Once Claude is running, type ${GREEN}${BOLD}/welcome${RESET}`);
+  console.log(`   for a guided tour — Claude will introduce`);
+  console.log(`   itself, walk you through how the system works,`);
+  console.log(`   and tailor things to how you want to use it.`);
+  console.log('');
+  console.log(`   ${DIM}(After that, use ${BOLD}/good-morning${RESET}${DIM} to start each day${RESET}`);
+  console.log(`   ${DIM}and ${BOLD}/wrap-up${RESET}${DIM} to close it out.)${RESET}`);
   console.log('');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-battle-plan",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "description": "Scaffold a Battle Plan project — a markdown-based context system for LLM-powered project management",
   "bin": {
     "create-battle-plan": "./bin/cli.js"

package/template/.claude/commands/good-morning.md

@@ -6,63 +6,18 @@ description: Morning standup — status briefing, metrics snapshot, and today's
 
 Run these steps in order.
 
-## Step 0: First-Run Welcome (one time only)
+## Step 0: First-run gate
 
-Check if `.battle-plan-onboarding.json` exists in the repo root. If it does, this is the user's **FIRST session** after running `npx create-battle-plan`. This is a special moment — the user just installed this and wants to understand what they've got. Make them feel like their project is in good hands.
+If `.battle-plan-onboarding.json` exists in the repo root, the user hasn't run `/welcome` yet. Don't run the standup — tell them:
 
-**Read `.battle-plan-onboarding.json`** to get their project context. Then write a warm, personal welcome that covers ALL of the following. This should feel like a knowledgeable co-pilot introducing itself, not a product manual.
+> Hey — looks like this is a fresh install and you haven't gone through the welcome yet. Run `/welcome` first to get the proper tour, then come back to `/good-morning` tomorrow (or whenever you start your next session).
 
-### Part 1: Personal welcome (reflect their project back to them)
+Stop here. Don't proceed to Step 1.
 
-Greet them warmly. Show them you already know their project by name, their time horizon, their metrics, their domains, and their people. Reference these specifics naturally — don't just list them. The user should feel like they're continuing a conversation, not configuring a tool.
-
-Example tone: "Welcome to your battle plan for [project]. You've got [horizon] and you're tracking [metrics] — I've got all of that loaded and ready to go."
-
-### Part 2: What this is (the big picture)
-
-Explain what they now have, in plain language:
-
-- **This is your project's memory.** Every conversation, decision, metric, and insight lives here in markdown files. When you close this chat and come back tomorrow — or next week — I read these files and pick up exactly where we left off. Nothing gets lost between sessions.
-- **You don't organize anything.** When you tell me something new — a call you had, research you found, a number that changed, a reply you got — I update the right files in the right order automatically. That's called the cascade.
-- **The cascade works like this:** new info flows into `metrics.yml` first (if a number changed), then into your battle plan (the operating doc that tracks where you are), then into the source docs for each domain. At the end, a verification script checks that everything is consistent.
-- **Think of it as dumping context.** You can paste a full call transcript, a messy list of notes, a forwarded email, a research summary — anything. You don't need to format it or tell me where it goes. Just dump it in and I'll cascade it to the right places.
-
-### Part 3: How to use it day to day
-
-Explain the rhythm:
-
-- **Start each session** with `/good-morning` (what you just ran). I'll brief you on where you stand — metrics, priorities, what's stuck, what's next. Think of it as a daily standup with your AI co-pilot.
-- **During the day**, just talk to me. Tell me what happened, paste in notes, ask me to update things. Every piece of new info triggers the cascade automatically.
-- **End each session** with `/wrap-up`. I'll review the day, show you what changed, sync everything, and offer to commit. This is how you close out clean without forgetting to log something.
-- **When docs get long**, run `/distill`. Over time, your daily logs and conversation journals will grow. `/distill` compresses older content into a thorough summary and archives the raw text — nothing is ever deleted, but I can read the docs faster.
-
-### Part 4: How metrics work
-
-- Your key metrics live in `metrics.yml` — it's the single numeric source of truth for the whole project.
-- Every number that appears in any doc traces back to that file via source annotations. When a metric changes, the cascade propagates the new value everywhere it's referenced.
-- Shell scripts verify the numbers stay in sync. You'll never have a stale "42" in one doc when the real number is "47" in another.
-- Right now all your metrics are at zero. One of the first things we'll do is set targets.
-
-### Part 5: What to do right now
-
-Transition into action:
-
-- "Let's start by getting some real data into the system. Here's what I'd suggest..."
-- Prompt them to set targets for their metrics
-- Ask if there's any existing context they already have — calls they've had, research they've done, decisions they've already made. Anything they can tell you now will make the battle plan immediately useful.
-
-### After the welcome
-
-Rename `.battle-plan-onboarding.json` to `.battle-plan-onboarding-done.json` so this welcome doesn't repeat.
-
-Then show a **compact metrics table** (all zeros, no targets yet) and transition into the onboarding questions naturally. Don't run the full standup format (Steps 1-4 below) on the first run — there's nothing to report yet. Instead, go straight to helping them populate the battle plan.
-
----
+If neither `.battle-plan-onboarding.json` nor `.battle-plan-onboarding-done.json` exists, continue normally — the project may have been bootstrapped without the create-battle-plan CLI.
 
 ## Step 1: Gather State (parallel reads)
 
-*Skip this on first run (Step 0 handles it). On all subsequent runs, start here.*
-
 Run these in parallel:
 - `node tools/tasks/render-today.js --quiet` — regenerate `docs/today.md` from `tasks.yml`
 - Read `metrics.yml` — current numbers
@@ -122,6 +77,4 @@ After the user answers:
 
 ## Tone
 
-On first run: warm, confident, thorough. The user should feel like they just hired a great project manager who already read the brief.
-
-On subsequent runs: direct, no fluff. Think military briefing, not newsletter.
+Direct, no fluff. Think military briefing, not newsletter. The user is starting a work session — they want their position and their next move, not a pep talk. (First-session warmth lives in `/welcome`, not here.)

package/template/.claude/commands/welcome.md

@@ -0,0 +1,112 @@
+---
+description: First-session welcome — introduces the system, asks about project archetype, tailors onboarding. Runs ONCE after install. Use /good-morning for daily standups thereafter.
+---
+
+# Welcome
+
+Run this ONCE, on the user's very first session after `npx create-battle-plan`.
+
+## Has welcome already run?
+
+Check the repo root:
+- If `.battle-plan-onboarding-done.json` exists → welcome already completed. Tell the user: `/welcome` is for first-time setup only. Suggest `/good-morning` (start of day) or `/wrap-up` (end of day) instead. Don't run the rest of this skill.
+- If neither `.battle-plan-onboarding.json` nor `.battle-plan-onboarding-done.json` exists → the project wasn't scaffolded via `create-battle-plan`. Tell the user `/welcome` is meant for first-run after install and there's no onboarding context to load. Offer to walk through the system manually if they want.
+- If `.battle-plan-onboarding.json` exists → continue.
+
+Read `.battle-plan-onboarding.json` for project context (name, horizon, metrics, domains, people). Keep these handy — you'll reference them throughout.
+
+---
+
+## Step 1 — Personal welcome (one message)
+
+Greet by name. Show you already know their project — reference their horizon, the specific domains they picked, the people they named. Do this naturally, not as a recital. The user should feel like they're continuing a conversation, not booting up a tool.
+
+If they declared metrics, mention them. If they didn't (`metrics: []` in the json), don't pretend they did — acknowledge this is a journal-style or open-ended project. Example: "I see you didn't declare specific metrics — that's fine, plenty of projects don't need them upfront. We can stay narrative and add them later if patterns emerge."
+
+End this message with: "Before we go anywhere, let me show you around — and then I want to ask you a couple of things about how you want to use this."
+
+---
+
+## Step 2 — Plain-language tour (one message, no jargon dumps)
+
+Explain what they actually have. Cover, in this order, in your own words:
+
+1. **It's your project's memory.** Markdown files in `docs/`, plus three structured YAML files (`metrics.yml`, `tasks.yml`, `events.yml`). When the user closes the session and comes back next week, you read these and pick up exactly where you left off. Nothing gets lost.
+2. **They don't organize anything.** When the user tells you something new — a call they had, an article they read, a number that changed, an idea, a forwarded email — you update the right files in the right order. That's the cascade.
+3. **The cascade flows top-down.** Raw state (metrics / events / tasks) → `battle-plan.md` (current state) → source docs per domain → verification script. The user never has to know this exists — they just dump stuff in chat.
+4. **The chat is the UI.** The cascade is your memory, not theirs. `docs/today.md` is the only file they should ever need to open — it's a thin clickable surface they can tick through in Obsidian or any markdown viewer.
+5. **Compression keeps it readable.** Daily logs and conversation journals grow over time. `/distill` collapses old content into a thorough summary, archives the raw text, nothing is ever deleted.
+
+Keep this to ~6–10 sentences total. Don't enumerate every file. Don't show code. The goal is to land the *shape* of the system, not the schema.
+
+End with: "Now — quick question so I can tailor this to you."
+
+---
+
+## Step 3 — Detect the archetype (ASK, don't assume)
+
+The system was originally built for founders validating an idea (metric-heavy: outreach, calls booked, conversion). But it works just as well for several other shapes. Ask:
+
+> "Which of these sounds closest to what you're doing here? You can pick one, or say 'mix' if it's blended.
+>
+> **(a) Founder / operator validating an idea.** Metric-driven. Outreach, calls, replies, conversion. You want to know if this idea is real.
+> **(b) Metric-heavy ops project.** Compliance work, sales pipeline, a specific build. Clear numbers to track, deadlines, deliverables.
+> **(c) Journal / second-brain.** Dream journal, life admin, ongoing context layer. Few or no metrics — just want to dump stuff and have it organized.
+> **(d) Something else.** Tell me about it."
+
+Wait for the answer.
+
+### How to tailor based on the archetype
+
+| Archetype | Tailoring |
+|---|---|
+| **(a) founder-validation** | Default behavior. Push toward setting outreach/conversion targets. Expect them to track leads (suggest the outreach add-on if they don't have it — see `outreach/README.md`). Daily rhythm: `/good-morning` → work → `/wrap-up`. Weekly: `/weekly-triage`. |
+| **(b) metric-heavy ops** | Same daily rhythm. Help them define the right metrics for their domain (deadlines, deliverables, throughput, error rate, whatever). Suggest setting `events.yml` for any scheduled meetings or deadlines. |
+| **(c) journal / second-brain** | Lower-touch. They probably don't need `/wrap-up` daily — once a week is fine. The cascade still works, but the value is in *querying* the dump later, not in metric drift. Tell them: just talk to you in chat, and you'll keep the docs organized. They can rerun `/distill` when things get long. |
+| **(d) other / mix** | Ask 1–2 follow-up questions to figure out the shape, then map to (a)/(b)/(c) or invent a hybrid. |
+
+After they answer, give them a short, archetype-specific reflection: "Got it — so for you, the rhythm is going to look like X. Here's what I'd suggest as a starting point…"
+
+---
+
+## Step 4 — Tour the slash commands (one message)
+
+Show the four daily/weekly commands with one-line descriptions, tailored to their archetype:
+
+- **`/good-morning`** — start of session. I brief you on where you stand, what's open, what to push on today. Use every day you sit down with this. *(Mention this is the one they'll run tomorrow.)*
+- **`/wrap-up`** — end of session. I reconcile the day, run the cascade, show what changed, offer to commit. *(For journal-style users: "Every few days is fine, doesn't have to be daily.")*
+- **`/weekly-triage`** — weekly sweep of `tasks.yml`. Catches stale tasks, drift, overdue items. *(Skip if they're archetype (c).)*
+- **`/distill`** — when a doc gets long. Compresses old content, archives raw, keeps recent. Run when you notice me being slow to load a file.
+
+Don't dump the full skill list. The user can discover the others later.
+
+---
+
+## Step 5 — Seed the system with existing context
+
+Ask:
+
+> "One last thing before we close this out: is there anything you already know about this project that I should have? Past calls, research you've read, decisions you've made, key contacts, anything. You don't need to structure it — just dump it and I'll cascade it into the right docs."
+
+If they share anything, run the full cascade (Steps 0–4 from `CLAUDE.md`). If they say "nothing yet," skip.
+
+For archetype (a) or (b): if they declared metrics in onboarding but didn't set targets, prompt them now: "What would success look like for [metric]? Even a rough number is fine." Update `battle-plan.md` with the targets.
+
+---
+
+## Step 6 — Mark welcome complete
+
+Rename `.battle-plan-onboarding.json` → `.battle-plan-onboarding-done.json` so this skill doesn't trigger again. Use the `mv` command via Bash, or the `Write` + delete pattern if `mv` isn't permitted.
+
+Tell the user:
+- "You're set up. Welcome doesn't run again."
+- "Tomorrow, start with `/good-morning`. End with `/wrap-up` whenever you wind down."
+- "Anything you tell me in between just gets cascaded — no special commands needed."
+
+---
+
+## Tone
+
+Warm, thorough, but not preachy. The user just installed something — they're curious and a little uncertain. You're a knowledgeable co-pilot introducing themselves, not a product tour with arrows and tooltips. Default to plain English; reach for terminology (cascade, distill, compression mode) only after you've explained what it means. Never read the user a list of internal filenames unless they ask.
+
+It's fine to take 4–6 messages to get through this — don't try to compress it into one wall of text.

package/template/CLAUDE.md

@@ -197,7 +197,8 @@ Tags grow forward with `, ` separator. Notes grow forward with `| ` separator
 **Outreach scripts (Profile B):** `tools/outreach/` — `daily-targets.js`, `flush-targets.js`, `flush-updates.js`, `flush-accepts.js`, `flush-inbox.js`, `sync-metrics.js`, `update-dashboard.js`, `stats.js`, `lookup.js`, `stale-invitations.js`.
 
 **Skills (`.claude/commands/`):**
-- `good-morning` — morning standup (metrics + today.md + events context-debt check)
+- `welcome` — first-session tour (runs once, after `npx create-battle-plan`). Introduces the system, detects project archetype, tailors onboarding.
+- `good-morning` — morning standup (metrics + today.md + events context-debt check). Refuses to run until `/welcome` has completed.
 - `wrap-up` — end-of-day reconciliation + task hygiene + events gate
 - `weekly-triage` — task-pile sweep
 - `distill` — compress chronological / amended doc history