create-battle-plan 1.0.0

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

@@ -0,0 +1,74 @@
+---
+description: Morning standup — status briefing, metrics snapshot, and today's priorities. Run at the start of each work day.
+---
+
+# Morning Standup
+
+Run these steps in order. Be concise — the user wants a briefing, not an essay.
+
+## Step 0: First-Run Welcome (one time only)
+
+Check if `.battle-plan-onboarding.json` exists. If it does, this is the user's FIRST session after running `npx create-battle-plan`. Do the following:
+
+1. Read `.battle-plan-onboarding.json` to get their project context
+2. **Welcome them by reflecting what they told the installer** — project name, horizon, metrics, domains, people. Show them you already have full context. Make them feel like they're picking up mid-conversation, not starting from scratch.
+3. **Explain what Battle Plan is and how it works**, briefly:
+   - "Battle Plan keeps your project context in markdown files that stay in sync. When you tell me something new — a call, a reply, a metric change — I update a chain of docs in a fixed order so nothing gets dropped."
+   - Mention the cascade: metrics.yml → battle plan → source docs → verification
+   - Mention: "Just dump context into the chat. Call transcripts, research, meeting notes, replies — I'll cascade it into the right docs."
+4. **Explain the commands:**
+   - `/good-morning` — start each session with a status briefing (what you're running now)
+   - `/wrap-up` — end each session cleanly: status review, cascade, metrics report, commit
+   - `/distill` — compress docs when they get too long for me to read efficiently
+5. **Explain metrics:** "Your metrics live in `metrics.yml`. Every number in every doc traces back to that file. Scripts verify they stay in sync. You never have to worry about stale numbers."
+6. **Explain what to do next:** "Set targets for your metrics in the battle plan, then start working. Tell me about any calls, research, or updates and I'll keep everything current."
+7. Rename `.battle-plan-onboarding.json` to `.battle-plan-onboarding-done.json` so this welcome doesn't repeat.
+
+Then proceed to the normal standup flow below (Steps 1-4).
+
+---
+
+## Step 1: Gather State (parallel reads)
+
+Read all of these in parallel:
+- `metrics.yml` — current numbers
+- `docs/battle-plan.md` — TL;DR + latest day log (find today or the most recent day entry)
+- Run `git log --oneline -15` — what changed since last session
+
+## Step 2: Present the Briefing
+
+Print a compact morning report with these sections:
+
+### Sprint Position
+- Where you are in the timeline (calculate from battle plan dates if available)
+- One-line status from TL;DR
+
+### Key Metrics (from metrics.yml)
+Show as a compact table:
+| Metric | Value | Target | Gap |
+Pull all defined metrics from `metrics.yml`. If targets are defined in the battle plan, include them.
+
+### Yesterday's Unfinished Business
+- Scan the most recent day log for unchecked `[ ]` items — list them
+- Flag any that have been carried forward 2+ days
+
+### Today's Agenda
+- If there's already a day entry for today in the battle plan, show its tasks
+- If not, suggest one based on yesterday's carryovers + sprint priorities
+
+## Step 3: Ask Directed Questions
+
+End with 2-3 short questions:
+- "Anything happen since we last talked? Replies, updates, new info?"
+- If there are stale items (no progress for 2+ days), ask about them specifically
+- If a key deliverable is outstanding, ask about it
+
+## Step 4: Prep the Day
+
+After the user answers:
+- If they report any updates → run the full cascade (Steps 0-4 from CLAUDE.md)
+- Update the battle plan day log with today's plan
+
+## Tone
+
+Direct, no fluff. Think military briefing, not newsletter.

package/template/.claude/commands/wrap-up.md

@@ -0,0 +1,61 @@
+---
+description: End-of-day wrap-up — status check, final cascade, metrics report, and commit. Run at the end of each work day.
+---
+
+# End-of-Day Wrap-Up
+
+Run these steps in order. Be concise.
+
+## Step 1: Scan
+
+Read `docs/battle-plan.md` and `metrics.yml`. Find today's day section. Categorize all tasks:
+- Done
+- Partially done
+- Not started
+- New (added during the day but not in the morning plan)
+
+## Step 2: Present
+
+Show the user:
+```
+Today's status:
+[x] [done tasks]
+[~] [partial tasks]
+[ ] [not started]
+[+] [new things that happened]
+```
+
+Ask: "Does this look right?"
+
+## Step 3: Prompt
+
+Ask: "Anything else happen today? Even small things — a reply, an update, a thought, a link. Everything counts."
+
+Wait for the user's answer before proceeding.
+
+## Step 4: Cascade
+
+With all info gathered, run the full cascade from CLAUDE.md:
+1. Update `metrics.yml` if any metric changed
+2. Update battle plan TL;DR + today's day log
+3. Update source docs (only what's relevant to today's changes)
+4. Run `tools/touch-date.sh` on every modified file
+5. Run `tools/verify-cascade.sh` — fix any errors
+
+## Step 5: Report
+
+Print:
+- **Metrics changed today** (before -> after, with deltas)
+- **Docs updated** (list of files touched)
+- **Verification warnings** (if any)
+- **Tomorrow's top priorities** (carry-forwards + known agenda items)
+
+## Step 6: Commit
+
+Ask: "Want me to commit today's updates?"
+
+If yes, commit with message: `eod YYYY-MM-DD: [one-line summary]`
+
+## Tone
+
+Direct. No fluff. Close out fast.

package/template/.claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

package/template/.githooks/pre-commit

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Pre-commit hook for Battle Plan.
+# Runs verify-cascade.sh when docs/ or metrics.yml are staged.
+# Default: warn only. Set CASCADE_STRICT=1 to block commits.
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+
+# Load config if it exists
+if [ -f "$REPO_ROOT/.cascaderc" ]; then
+  source "$REPO_ROOT/.cascaderc"
+fi
+
+CASCADE_STRICT="${CASCADE_STRICT:-0}"
+
+# Check if any docs or metrics.yml are staged
+STAGED_DOCS=$(git diff --cached --name-only -- 'docs/*.md' 'metrics.yml' 2>/dev/null || true)
+
+if [ -z "$STAGED_DOCS" ]; then
+  exit 0
+fi
+
+echo "=== Battle Plan: Pre-commit check ==="
+echo "Staged files:"
+echo "$STAGED_DOCS" | sed 's/^/  /'
+echo ""
+
+# Run verification
+if ! "$REPO_ROOT/tools/verify-cascade.sh"; then
+  if [ "$CASCADE_STRICT" = "1" ]; then
+    echo ""
+    echo "BLOCKED: Verification failed and CASCADE_STRICT=1."
+    echo "Fix the issues above or set CASCADE_STRICT=0 in .cascaderc to warn only."
+    exit 1
+  else
+    echo ""
+    echo "WARNING: Verification found issues (see above). Committing anyway."
+    echo "Set CASCADE_STRICT=1 in .cascaderc to block commits with issues."
+  fi
+fi
+
+exit 0

package/template/CLAUDE.md

@@ -0,0 +1,154 @@
+# Battle Plan — System Prompt
+
+You are helping manage an interconnected documentation system. Every document stays in sync through a cascade protocol. Follow these rules exactly.
+
+---
+
+## The Cascade Protocol
+
+**Trigger:** Any incoming information that relates to the project — calls, messages, research, signals, status changes, decisions.
+
+When triggered, update in this exact order:
+
+### Step 0: Update `metrics.yml`
+If any key metric changed, update `metrics.yml` first. This is the numeric source of truth.
+
+### Step 1: Update Battle Plan (`docs/battle-plan.md`)
+- Update the **TL;DR** with current status
+- Update the **Key Metrics** table (numbers reference metrics.yml)
+- Update **Today's Priorities** if relevant
+- Append to **Daily Log** for today
+
+### Step 2: Update Cascade Docs
+Update only the docs relevant to the new information. Route new info to the appropriate domain doc under `docs/`. Common patterns:
+
+| Info type | Route to... |
+|-----------|------------|
+| Conversation, call, or meeting | `docs/external-insights.md` — append as new dated session |
+| Evidence for/against a hypothesis | The relevant domain doc — amend the claim with an `[UPDATE]` block |
+| Outreach sent/received | The relevant market or sales doc — update tracking tables |
+| Competitor intel | The relevant strategy or market doc |
+| New foundational knowledge | The relevant research or domain doc |
+
+If no doc exists for the info, append it to the closest domain overview doc. Only create a new file if the info doesn't fit anywhere.
+
+### Step 3: Update Dates
+Run `tools/touch-date.sh` on every file you modified in this session:
+
+```bash
+tools/touch-date.sh docs/battle-plan.md docs/validation/hypotheses.md [etc.]
+```
+
+### Step 4: Verify
+Run `tools/verify-cascade.sh` and fix any issues it reports:
+
+```bash
+tools/verify-cascade.sh
+```
+
+---
+
+## Source Reference Rules
+
+### Registry Metrics (Tier 1 — deterministic)
+Numbers defined in `metrics.yml`. Reference as: `[**N**](metrics.yml#field_name)`
+
+This renders as a bold clickable number. Example: `[**42**](metrics.yml#outreach_sent)`
+
+These are verified by exact numeric comparison via `tools/check-metrics.sh`.
+
+### Inline Metrics (Tier 2 — LLM-verified)
+Less common numbers from another doc. Reference as: `[**N**](source-doc.md#section-slug)`
+
+Example: `60% of time on evidence [**60**](external-insights.md#session-2-key-insights)`
+
+**Rule:** Every number referenced from another document MUST include a source annotation. Only numbers native to a doc (where they originate) have no annotation.
+
+---
+
+## Document Format
+
+Every doc in `docs/` must have this frontmatter:
+
+```markdown
+# Document Title
+
+**Last Updated:** 2026-04-07
+**Status:** Active | Draft | Archived
+**Role:** source-of-truth | cascade-target
+**Compression:** chronological | amended | none
+
+**TL;DR:** One paragraph summary with key numbers and source references.
+
+---
+```
+
+- **Last Updated** must match today's date on any file modified in the current session.
+- **Status:** `Active` = live, `Draft` = WIP, `Archived` = excluded from cascade.
+- **Role:** `source-of-truth` = authoritative for its numbers. `cascade-target` = references numbers from elsewhere.
+- **Compression:** required field. One of `chronological`, `amended`, or `none` (see Compression Modes section below).
+- **TL;DR** must exist and contain all key metrics that appear in the doc.
+
+---
+
+## Compression Modes & Timestamping Rules
+
+Every doc declares a `Compression:` mode in frontmatter. This tells the `/distill` command (and humans) how new info gets added to the doc and how old info gets compressed when it grows too long. The mode IS the timestamping rule for new info.
+
+### `Compression: chronological`
+The doc is an append-only log of dated entries. Each new piece of info goes in a new dated section.
+
+- **Timestamping rule:** every new entry MUST start with a dated heading: `## Session N (YYYY-MM-DD) — <title>`, `## YYYY-MM-DD — <title>`, or `## DD Month YYYY — <title>`. No exceptions.
+- **Examples:** `docs/battle-plan.md` (daily log), `docs/validation/external-insights.md` (conversation journal).
+- **`/distill` behavior:** keeps the N most recent dated sections verbatim, archives the rest into `docs/archive/<same-path>`, replaces them with a thorough summary.
+
+### `Compression: amended`
+The doc is a living reference. Claims are amended in place over time.
+
+- **Timestamping rule:** every new finding that revises an existing claim MUST be added as an inline `> **[UPDATE YYYY-MM-DD · Source: ...]**` block placed immediately above the claim it modifies. Brand-new claims with no prior version don't need a stamp; they're stamped implicitly by the doc's `Last Updated` date and git history.
+- **Examples:** `docs/validation/hypotheses.md`, `docs/market/icp-and-targets.md`, `docs/market/competitive-landscape.md`.
+- **`/distill` behavior:** collapses old `[UPDATE]` blocks into the body text (preserving their content as integrated current-state), archives the raw blocks verbatim. Keeps the N most recent amendments per section inline.
+
+### `Compression: none`
+The doc is a static thesis or reference. It gets rewritten, not amended. Git history is the timeline.
+
+- **Timestamping rule:** none. Just edit the doc and let `Last Updated` + git track changes.
+- **Examples:** `docs/strategy/product-thesis.md`, `docs/research/domain-101.md`.
+- **`/distill` behavior:** refuses to run. If a `none` doc has grown unwieldy, rewrite it manually or change its `Compression:` mode first.
+
+### Why this matters
+The TL;DR is current state, not history. It can't tell `/distill` what's new vs old. The `Compression:` mode + timestamping rule is the only mechanism that makes distillation deterministic. Skipping the timestamp on a new entry in a `chronological` or `amended` doc is a bug; it will get silently absorbed into the wrong era during distillation.
+
+When in doubt about which mode a new doc should use: chronological logs choose `chronological`, claim trackers choose `amended`, everything else is `none`.
+
+---
+
+## Vault Rules
+
+1. **Update, don't duplicate.** Amend with `> **[UPDATE YYYY-MM-DD · Source: ...]**`
+2. **Cross-link everything.** Claims reference their source doc.
+3. **Confidence levels:** `Unvalidated` | `Soft signal` | `Practitioner-validated` | `Data-validated`
+4. **Source everything.** Who said it, when, confidence level.
+5. **Minimize file count.** Append, don't create new files.
+
+---
+
+## The `/wrap-up` Protocol
+
+When the user says `/wrap-up`, run this end-of-day sequence:
+
+**Step 1 — Scan:** Read the battle plan. Identify all tasks for today. Categorize: done, partially done, not started, new.
+
+**Step 2 — Present:** Show the user: "Here's today's status: [list]. Does this look right?"
+
+**Step 3 — Prompt:** Ask: "Anything else happen today? Even small things — a reply, an accept, a thought, a link. Everything counts."
+
+**Step 4 — Cascade:** With all info gathered, run the full cascade (Steps 0-4 above).
+
+**Step 5 — Report:** Print:
+- Metrics changed today (before → after)
+- Docs updated
+- Verification warnings (if any)
+- Tomorrow's top priorities
+
+**Step 6 — Commit:** Ask: "Want me to commit today's updates?" If yes, commit with message: `eod YYYY-MM-DD: [summary]`

package/template/docs/README.md

@@ -0,0 +1,62 @@
+# Documentation Vault Rules
+
+These rules govern all documents in this vault. Follow them on every update.
+
+---
+
+## 1. Update, Don't Duplicate
+
+Amend existing docs with timestamped updates. Never create a new file that makes an old one obsolete.
+
+**Amendment format:**
+
+> **[UPDATE YYYY-MM-DD · Source: person/research/call]** New finding here.
+
+## 2. Cross-Link Everything
+
+Claims validated or invalidated by another doc must link to it. Use relative paths:
+`[Document Name](relative/path/to/doc.md)`
+
+## 3. Confidence Levels on Every Claim
+
+Mark every claim with one of:
+- `Unvalidated` — no evidence yet
+- `Soft signal` — directional but not confirmed (e.g., 1-2 anecdotes)
+- `Practitioner-validated` — confirmed by someone who does this work
+- `Data-validated` — confirmed by quantitative evidence
+
+Always include the source: who said it, when, in what context.
+
+## 4. Source Reference Format
+
+**Registry metrics** (defined in `metrics.yml`):
+`[**N**](metrics.yml#field_name)`
+
+**Inline metrics** (from another doc):
+`(→ source-doc.md#section-slug)`
+
+**Rule:** Every number referenced from another document MUST include a source annotation. Only numbers native to a doc (where they originate) have no annotation.
+
+## 5. Minimize File Count
+
+Notes from the same person go in ONE file, appended with dates. Don't create a new file per conversation — append to `external-insights.md`.
+
+## 6. Source Everything
+
+Every claim needs: who said it, when, and the confidence level. Unsourced claims get `Unvalidated` until sourced.
+
+## 7. Record and Transcribe Calls
+
+Every call, meeting, and significant conversation should be recorded (with consent), transcribed, and integrated into the relevant docs. External input is the highest-value content in this system.
+
+## 8. Standardized Frontmatter
+
+Every doc in `docs/` must have:
+
+```
+**Last Updated:** YYYY-MM-DD
+**Status:** Active | Draft | Archived
+**Role:** source-of-truth | cascade-target
+
+**TL;DR:** One paragraph summary with sourced numbers.
+```

package/template/tools/check-metrics.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# check-metrics.sh — Verifies that metrics.yml references in docs match actual values.
+# Supports two formats:
+#   Link format:  [**N**](metrics.yml#field)  or  [N](metrics.yml#field)
+#   Legacy format: **N** (→ metrics.yml#field)  or  N (→ metrics.yml#field)
+# Usage: tools/check-metrics.sh [docs_dir]
+# Exit 0 if all match, exit 1 if mismatches found.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+METRICS_FILE="$REPO_ROOT/metrics.yml"
+DOCS_DIR="${1:-$REPO_ROOT/docs}"
+
+if [ ! -f "$METRICS_FILE" ]; then
+  echo "ERROR: metrics.yml not found at $METRICS_FILE"
+  exit 1
+fi
+
+ERRORS=0
+CHECKED=0
+
+# Parse metrics.yml into key=value pairs (skip comments, blank lines, string values)
+while IFS= read -r line; do
+  # Skip comments, blank lines, and string values (quoted)
+  [[ "$line" =~ ^[[:space:]]*# ]] && continue
+  [[ -z "$line" ]] && continue
+  [[ "$line" =~ \" ]] && continue
+
+  key=$(echo "$line" | cut -d: -f1 | tr -d ' ')
+  value=$(echo "$line" | cut -d: -f2 | tr -d ' ')
+
+  # Skip the last_updated meta field
+  [[ "$key" == "last_updated" ]] && continue
+
+  # Find all docs referencing this metric (both link and legacy formats)
+  pattern="metrics\\.yml#${key}"
+  while IFS= read -r match_file; do
+    [ -z "$match_file" ] && continue
+    CHECKED=$((CHECKED + 1))
+
+    # Extract the number from the reference
+    while IFS= read -r match_line; do
+      ref_number=""
+
+      # Format 1 (link): [**N**](metrics.yml#field)
+      if [ -z "$ref_number" ]; then
+        ref_number=$(echo "$match_line" | grep -oE '\[\*\*[0-9]+\*\*\]\(metrics\.yml#'"$key"'\)' | grep -oE '[0-9]+' || true)
+      fi
+
+      # Format 2 (link, no bold): [N](metrics.yml#field)
+      if [ -z "$ref_number" ]; then
+        ref_number=$(echo "$match_line" | grep -oE '\[[0-9]+\]\(metrics\.yml#'"$key"'\)' | grep -oE '[0-9]+' || true)
+      fi
+
+      # Format 3 (legacy): **N** (→ metrics.yml#field)
+      if [ -z "$ref_number" ]; then
+        ref_number=$(echo "$match_line" | grep -oE '\*\*[0-9]+\*\*[[:space:]]*\(→ metrics\.yml#'"$key"'\)' | grep -oE '[0-9]+' || true)
+      fi
+
+      # Format 4 (legacy, no bold): N (→ metrics.yml#field)
+      if [ -z "$ref_number" ]; then
+        ref_number=$(echo "$match_line" | grep -oE '[0-9]+[[:space:]]*\(→ metrics\.yml#'"$key"'\)' | grep -oE '^[0-9]+' || true)
+      fi
+
+      if [ -z "$ref_number" ]; then
+        echo "WARNING: Could not parse number for $key in $match_file"
+        echo "  Line: $match_line"
+        ERRORS=$((ERRORS + 1))
+      elif [ "$ref_number" != "$value" ]; then
+        echo "MISMATCH: $key in $match_file"
+        echo "  metrics.yml: $value"
+        echo "  Document:    $ref_number"
+        echo "  Line: $match_line"
+        ERRORS=$((ERRORS + 1))
+      fi
+    done < <(grep "$pattern" "$match_file")
+  done < <(grep -rl "$pattern" "$DOCS_DIR" 2>/dev/null | grep -v '/examples/' || true)
+done < "$METRICS_FILE"
+
+echo ""
+echo "=== Metrics Check ==="
+echo "Checked: $CHECKED references"
+echo "Errors:  $ERRORS"
+
+if [ $ERRORS -gt 0 ]; then
+  exit 1
+else
+  echo "All metrics references match."
+  exit 0
+fi