create-battle-plan 1.0.0

package/template/tools/init-project.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+# init-project.sh — Scaffolds a new project from onboarding wizard answers.
+# Called by the LLM after the 5-question interview.
+#
+# Usage: tools/init-project.sh \
+#   --name "Project Name" \
+#   --horizon "3 weeks" \
+#   --metrics "metric1,metric2,metric3" \
+#   --domains "market,validation,strategy" \
+#   --people "Name1:Role1,Name2:Role2"
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Parse arguments
+PROJECT_NAME=""
+HORIZON=""
+METRICS=""
+DOMAINS=""
+PEOPLE=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --name) PROJECT_NAME="$2"; shift 2 ;;
+    --horizon) HORIZON="$2"; shift 2 ;;
+    --metrics) METRICS="$2"; shift 2 ;;
+    --domains) DOMAINS="$2"; shift 2 ;;
+    --people) PEOPLE="$2"; shift 2 ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+if [ -z "$PROJECT_NAME" ] || [ -z "$METRICS" ] || [ -z "$DOMAINS" ]; then
+  echo "ERROR: --name, --metrics, and --domains are required."
+  echo "Usage: tools/init-project.sh --name \"...\" --horizon \"...\" --metrics \"m1,m2\" --domains \"d1,d2\" --people \"N1:R1,N2:R2\""
+  exit 1
+fi
+
+TODAY=$(date +%Y-%m-%d)
+
+echo "=== Initializing project: $PROJECT_NAME ==="
+
+# Step 1: Move demo content to examples/
+echo "Moving demo content to examples/startup-validation/..."
+mkdir -p "$REPO_ROOT/examples/startup-validation"
+
+if [ -d "$REPO_ROOT/docs" ]; then
+  # Preserve the docs/README.md (vault rules) — it's generic
+  cp "$REPO_ROOT/docs/README.md" /tmp/cascade-vault-rules.md 2>/dev/null || true
+
+  # Move all docs to examples
+  cp -r "$REPO_ROOT/docs/"* "$REPO_ROOT/examples/startup-validation/" 2>/dev/null || true
+  rm -rf "$REPO_ROOT/docs/"*/
+  rm -f "$REPO_ROOT/docs/"*.md
+
+  # Restore vault rules
+  cp /tmp/cascade-vault-rules.md "$REPO_ROOT/docs/README.md" 2>/dev/null || true
+fi
+
+# Also preserve the demo metrics.yml
+cp "$REPO_ROOT/metrics.yml" "$REPO_ROOT/examples/startup-validation/metrics.yml" 2>/dev/null || true
+
+# Step 2: Create domain directories and initial docs
+IFS=',' read -ra DOMAIN_ARRAY <<< "$DOMAINS"
+for domain in "${DOMAIN_ARRAY[@]}"; do
+  domain=$(echo "$domain" | tr -d ' ')
+  mkdir -p "$REPO_ROOT/docs/$domain"
+
+  # Create an initial doc for each domain
+  cat > "$REPO_ROOT/docs/$domain/${domain}-overview.md" << DOCEOF
+# ${domain^} Overview
+
+**Last Updated:** $TODAY
+**Status:** Draft
+**Role:** cascade-target
+**Compression:** amended
+
+**TL;DR:** Initial ${domain} document for $PROJECT_NAME. To be filled in as the project progresses.
+
+---
+
+## Notes
+
+_Start adding content here._
+DOCEOF
+
+  echo "Created: docs/$domain/${domain}-overview.md"
+done
+
+# Step 3: Create metrics.yml
+echo "Creating metrics.yml..."
+cat > "$REPO_ROOT/metrics.yml" << METRICSEOF
+# metrics.yml — project-wide metrics registry for $PROJECT_NAME
+# The LLM updates this file FIRST in any cascade, before touching docs.
+# Scripts verify all (→ metrics.yml#field) references against these values.
+
+last_updated: $TODAY
+
+METRICSEOF
+
+IFS=',' read -ra METRIC_ARRAY <<< "$METRICS"
+for metric in "${METRIC_ARRAY[@]}"; do
+  metric_key=$(echo "$metric" | tr -d ' ' | tr '[:upper:]' '[:lower:]' | tr ' ' '_' | tr -cd 'a-z0-9_')
+  echo "${metric_key}: 0" >> "$REPO_ROOT/metrics.yml"
+done
+
+echo "Created: metrics.yml with ${#METRIC_ARRAY[@]} metrics"
+
+# Step 4: Create battle plan
+echo "Creating battle plan..."
+cat > "$REPO_ROOT/docs/battle-plan.md" << BPEOF
+# Battle Plan — $PROJECT_NAME
+
+**Last Updated:** $TODAY
+**Status:** Active
+**Role:** source-of-truth
+**Compression:** chronological
+
+**TL;DR:** $PROJECT_NAME — just initialized. Time horizon: ${HORIZON:-"not set"}. All metrics at 0. First priority: fill in the battle plan with real tasks and targets.
+
+---
+
+## Rules for This Document
+
+1. Every task has an assigned date — no "sometime this week"
+2. Tasks move, never disappear — if slipped, add new date + reason
+3. New info updates the battle plan FIRST, before any other doc
+4. Everything links — tasks reference the doc they depend on or produce
+
+---
+
+## Key Metrics
+
+| Metric | Target | Current |
+|--------|--------|---------|
+BPEOF
+
+for metric in "${METRIC_ARRAY[@]}"; do
+  metric_key=$(echo "$metric" | tr -d ' ' | tr '[:upper:]' '[:lower:]' | tr ' ' '_' | tr -cd 'a-z0-9_')
+  metric_display=$(echo "$metric" | sed 's/^[[:space:]]*//')
+  echo "| $metric_display | _set target_ | **0** (→ metrics.yml#${metric_key}) |" >> "$REPO_ROOT/docs/battle-plan.md"
+done
+
+cat >> "$REPO_ROOT/docs/battle-plan.md" << 'BPEOF2'
+
+---
+
+## Today's Priorities
+
+- [ ] Set targets for each metric
+- [ ] Fill in this week's tasks
+- [ ] Record any existing conversations in external-insights.md
+
+---
+
+## This Week
+
+_Add day-by-day tasks here._
+
+---
+
+## Daily Log
+
+_Append-only. Three lines per day._
+BPEOF2
+
+echo "Created: docs/battle-plan.md"
+
+# Step 5: Create external-insights.md with people sections
+echo "Creating external-insights.md..."
+cat > "$REPO_ROOT/docs/external-insights.md" << EIEOF
+# External Insights
+
+**Last Updated:** $TODAY
+**Status:** Active
+**Role:** cascade-target
+**Compression:** chronological
+
+**TL;DR:** All external conversations, calls, and meetings for $PROJECT_NAME. 0 sessions recorded so far.
+
+---
+
+## How to Use This Document
+
+Every conversation gets appended as a dated session. Record everything — even "small" chats contain signal.
+
+### Template
+
+\`\`\`markdown
+## Session N (YYYY-MM-DD) — [Person Name], [Role/Company]
+
+### Context
+[Why this conversation happened]
+
+### Key insights
+1. **Insight title.** Detail. \`Confidence: [level]\`
+
+### Raw quotes (if available)
+> "Quote here"
+
+### Action items
+- [ ] Follow-up X
+\`\`\`
+
+---
+
+## People
+
+EIEOF
+
+if [ -n "$PEOPLE" ]; then
+  IFS=',' read -ra PEOPLE_ARRAY <<< "$PEOPLE"
+  for person in "${PEOPLE_ARRAY[@]}"; do
+    name=$(echo "$person" | cut -d: -f1 | sed 's/^[[:space:]]*//')
+    role=$(echo "$person" | cut -d: -f2 | sed 's/^[[:space:]]*//')
+    cat >> "$REPO_ROOT/docs/external-insights.md" << PERSONEOF
+### $name — $role
+_No sessions recorded yet._
+
+PERSONEOF
+    echo "  Added person: $name ($role)"
+  done
+fi
+
+echo "Created: docs/external-insights.md"
+
+# Step 6: Install hooks
+echo ""
+"$REPO_ROOT/tools/setup-hooks.sh"
+
+# Step 7: Create initialized flag
+touch "$REPO_ROOT/.battle-plan-initialized"
+
+echo ""
+echo "=== Project initialized! ==="
+echo "Project: $PROJECT_NAME"
+echo "Domains: $DOMAINS"
+echo "Metrics: $METRICS"
+echo "Demo content preserved in: examples/startup-validation/"
+echo ""
+echo "Next steps:"
+echo "  1. Open docs/battle-plan.md and set your targets"
+echo "  2. Tell your LLM about your project context"
+echo "  3. Start working — the cascade will keep docs in sync"

package/template/tools/setup-hooks.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# setup-hooks.sh — Installs the Battle Plan git hooks.
+# Usage: tools/setup-hooks.sh
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+git -C "$REPO_ROOT" config core.hooksPath .githooks
+echo "Git hooks installed. Pre-commit will run verify-cascade.sh on docs changes."
+echo ""
+echo "Configuration:"
+echo "  Default: warn only (commits proceed despite warnings)"
+echo "  Strict:  copy .cascaderc.example to .cascaderc and set CASCADE_STRICT=1"

package/template/tools/sync-metrics.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# sync-metrics.sh — Propagates metrics.yml values to all docs that reference them.
+# Finds [**N**](metrics.yml#field) links and updates N to match metrics.yml.
+# Also handles legacy format: **N** (→ metrics.yml#field)
+# Usage: tools/sync-metrics.sh
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+METRICS_FILE="$REPO_ROOT/metrics.yml"
+DOCS_DIR="$REPO_ROOT/docs"
+
+if [ ! -f "$METRICS_FILE" ]; then
+  echo "ERROR: metrics.yml not found at $METRICS_FILE"
+  exit 1
+fi
+
+UPDATED=0
+FILES_CHANGED=0
+
+# Parse metrics.yml into key=value pairs (skip comments, blank lines, string values)
+while IFS= read -r line; do
+  [[ "$line" =~ ^[[:space:]]*# ]] && continue
+  [[ -z "$line" ]] && continue
+  [[ "$line" =~ \" ]] && continue
+
+  key=$(echo "$line" | cut -d: -f1 | tr -d ' ')
+  value=$(echo "$line" | cut -d: -f2 | tr -d ' ')
+
+  [[ "$key" == "last_updated" ]] && continue
+
+  # Find docs with references to this metric
+  pattern="metrics\.yml#${key}"
+  while IFS= read -r match_file; do
+    [ -z "$match_file" ] && continue
+
+    changed=false
+
+    # Link format: [**N**](metrics.yml#field) → [**value**](metrics.yml#field)
+    if grep -q "\[\*\*[0-9]*\*\*\](metrics\.yml#${key})" "$match_file"; then
+      if [[ "$OSTYPE" == "darwin"* ]]; then
+        sed -i '' "s/\[\*\*[0-9]*\*\*\](metrics\.yml#${key})/[\*\*${value}\*\*](metrics.yml#${key})/g" "$match_file"
+      else
+        sed -i "s/\[\*\*[0-9]*\*\*\](metrics\.yml#${key})/[\*\*${value}\*\*](metrics.yml#${key})/g" "$match_file"
+      fi
+      changed=true
+    fi
+
+    # Link format without bold: [N](metrics.yml#field) → [value](metrics.yml#field)
+    if grep -q "\[[0-9]*\](metrics\.yml#${key})" "$match_file"; then
+      if [[ "$OSTYPE" == "darwin"* ]]; then
+        sed -i '' "s/\[[0-9]*\](metrics\.yml#${key})/[${value}](metrics.yml#${key})/g" "$match_file"
+      else
+        sed -i "s/\[[0-9]*\](metrics\.yml#${key})/[${value}](metrics.yml#${key})/g" "$match_file"
+      fi
+      changed=true
+    fi
+
+    # Legacy format: **N** (→ metrics.yml#field) → **value** (→ metrics.yml#field)
+    if grep -q "\*\*[0-9]*\*\* (→ metrics\.yml#${key})" "$match_file"; then
+      if [[ "$OSTYPE" == "darwin"* ]]; then
+        sed -i '' "s/\*\*[0-9]*\*\* (→ metrics\.yml#${key})/\*\*${value}\*\* (→ metrics.yml#${key})/g" "$match_file"
+      else
+        sed -i "s/\*\*[0-9]*\*\* (→ metrics\.yml#${key})/\*\*${value}\*\* (→ metrics.yml#${key})/g" "$match_file"
+      fi
+      changed=true
+    fi
+
+    if [ "$changed" = true ]; then
+      UPDATED=$((UPDATED + 1))
+      echo "Synced: $key=$value in $match_file"
+    fi
+  done < <(grep -rl "$pattern" "$DOCS_DIR" 2>/dev/null | grep -v '/examples/' || true)
+done < "$METRICS_FILE"
+
+echo ""
+echo "=== Metrics Sync ==="
+echo "References updated: $UPDATED"
+
+if [ $UPDATED -gt 0 ]; then
+  echo "Run tools/touch-date.sh on modified files to update their dates."
+fi

package/template/tools/touch-date.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# touch-date.sh — Updates the "Last Updated:" line in a markdown file to today's date.
+# Usage: tools/touch-date.sh <file> [<file2> ...]
+
+set -euo pipefail
+
+TODAY=$(date +%Y-%m-%d)
+
+if [ $# -eq 0 ]; then
+  echo "Usage: tools/touch-date.sh <file> [<file2> ...]"
+  echo "Updates the 'Last Updated:' line to today's date ($TODAY)."
+  exit 1
+fi
+
+for file in "$@"; do
+  if [ ! -f "$file" ]; then
+    echo "WARNING: File not found: $file"
+    continue
+  fi
+
+  if grep -q '^\*\*Last Updated:\*\*' "$file"; then
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+      sed -i '' "s/^\*\*Last Updated:\*\*.*/\*\*Last Updated:\*\* $TODAY/" "$file"
+    else
+      sed -i "s/^\*\*Last Updated:\*\*.*/\*\*Last Updated:\*\* $TODAY/" "$file"
+    fi
+    echo "Updated: $file → $TODAY"
+  else
+    echo "WARNING: No 'Last Updated:' line found in $file"
+  fi
+done

package/template/tools/verify-cascade.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# verify-cascade.sh — Full verification of the Battle Plan cascade system.
+# Checks: dates, metrics, staleness, battle plan freshness.
+# Usage: tools/verify-cascade.sh
+# Exit 0 if clean, exit 1 if issues found.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+DOCS_DIR="$REPO_ROOT/docs"
+METRICS_FILE="$REPO_ROOT/metrics.yml"
+TODAY=$(date +%Y-%m-%d)
+
+WARNINGS=0
+ERRORS=0
+
+echo "=== Battle Plan Verification ==="
+echo "Date: $TODAY"
+echo ""
+
+# --- Check 1: Last Updated dates ---
+echo "--- Check 1: Last Updated Dates ---"
+
+while IFS= read -r doc; do
+  [ -z "$doc" ] && continue
+
+  # Skip docs/README.md (vault rules, not a cascade doc)
+  [[ "$doc" == "$DOCS_DIR/README.md" ]] && continue
+
+  status=$(grep '^\*\*Status:\*\*' "$doc" | head -1 | sed 's/\*\*Status:\*\* //' || true)
+
+  # Skip archived and draft docs
+  [[ "$status" == "Archived" ]] && continue
+
+  last_updated=$(grep '^\*\*Last Updated:\*\*' "$doc" | head -1 | sed 's/\*\*Last Updated:\*\* //' || true)
+
+  if [ -z "$last_updated" ]; then
+    echo "WARNING: No Last Updated line in $doc"
+    WARNINGS=$((WARNINGS + 1))
+  fi
+done < <(find "$DOCS_DIR" -name "*.md" -not -path "*/examples/*" 2>/dev/null)
+
+# --- Check 2: Metrics consistency ---
+echo ""
+echo "--- Check 2: Metrics Consistency ---"
+
+if [ -f "$METRICS_FILE" ]; then
+  if ! "$REPO_ROOT/tools/check-metrics.sh" 2>&1; then
+    ERRORS=$((ERRORS + 1))
+  fi
+else
+  echo "WARNING: metrics.yml not found"
+  WARNINGS=$((WARNINGS + 1))
+fi
+
+# --- Check 3: Battle plan freshness ---
+echo ""
+echo "--- Check 3: Battle Plan Freshness ---"
+
+BATTLE_PLAN="$DOCS_DIR/battle-plan.md"
+if [ -f "$BATTLE_PLAN" ]; then
+  bp_date=$(grep '^\*\*Last Updated:\*\*' "$BATTLE_PLAN" | head -1 | sed 's/\*\*Last Updated:\*\* //' || true)
+
+  while IFS= read -r doc; do
+    [ -z "$doc" ] && continue
+    [[ "$doc" == "$BATTLE_PLAN" ]] && continue
+    [[ "$doc" == "$DOCS_DIR/README.md" ]] && continue
+
+    doc_date=$(grep '^\*\*Last Updated:\*\*' "$doc" | head -1 | sed 's/\*\*Last Updated:\*\* //' || true)
+    [ -z "$doc_date" ] && continue
+
+    if [[ "$doc_date" > "$bp_date" ]]; then
+      echo "WARNING: $doc ($doc_date) is newer than battle plan ($bp_date)"
+      WARNINGS=$((WARNINGS + 1))
+    fi
+  done < <(find "$DOCS_DIR" -name "*.md" -not -path "*/examples/*" 2>/dev/null)
+else
+  echo "WARNING: Battle plan not found at $BATTLE_PLAN"
+  WARNINGS=$((WARNINGS + 1))
+fi
+
+# --- Check 4: TL;DR existence ---
+echo ""
+echo "--- Check 4: TL;DR Presence ---"
+
+while IFS= read -r doc; do
+  [ -z "$doc" ] && continue
+
+  # Skip docs/README.md (vault rules, not a cascade doc)
+  [[ "$doc" == "$DOCS_DIR/README.md" ]] && continue
+
+  status=$(grep '^\*\*Status:\*\*' "$doc" | head -1 | sed 's/\*\*Status:\*\* //' || true)
+  [[ "$status" == "Archived" ]] && continue
+
+  if ! grep -q '^\*\*TL;DR:\*\*' "$doc"; then
+    echo "WARNING: No TL;DR in $doc"
+    WARNINGS=$((WARNINGS + 1))
+  fi
+done < <(find "$DOCS_DIR" -name "*.md" -not -path "*/examples/*" 2>/dev/null)
+
+# --- Check 5: Stale inline references ---
+echo ""
+echo "--- Check 5: Inline Reference Staleness ---"
+
+while IFS= read -r doc; do
+  [ -z "$doc" ] && continue
+
+  # Skip docs/README.md (vault rules, contains example syntax)
+  [[ "$doc" == "$DOCS_DIR/README.md" ]] && continue
+
+  doc_date=$(grep '^\*\*Last Updated:\*\*' "$doc" | head -1 | sed 's/\*\*Last Updated:\*\* //' || true)
+  [ -z "$doc_date" ] && continue
+
+  while IFS= read -r ref; do
+    [ -z "$ref" ] && continue
+    ref_file=$(echo "$ref" | grep -oE '[a-zA-Z0-9_-]+\.md' || true)
+    [ -z "$ref_file" ] && continue
+
+    # Skip metrics.yml references (handled by check-metrics)
+    [[ "$ref" == *"metrics.yml"* ]] && continue
+
+    ref_path=$(find "$DOCS_DIR" -name "$ref_file" -not -path "*/examples/*" 2>/dev/null | head -1)
+    if [ -z "$ref_path" ]; then
+      echo "WARNING: Referenced file $ref_file not found (from $doc)"
+      WARNINGS=$((WARNINGS + 1))
+      continue
+    fi
+
+    ref_date=$(grep '^\*\*Last Updated:\*\*' "$ref_path" | head -1 | sed 's/\*\*Last Updated:\*\* //' || true)
+    [ -z "$ref_date" ] && continue
+
+    if [[ "$ref_date" > "$doc_date" ]]; then
+      echo "WARNING: $doc references $ref_file, but $ref_file ($ref_date) is newer than $doc ($doc_date) — reference may be stale"
+      WARNINGS=$((WARNINGS + 1))
+    fi
+  done < <(grep -oE '\(→ [^)]+\)' "$doc" 2>/dev/null || true)
+done < <(find "$DOCS_DIR" -name "*.md" -not -path "*/examples/*" 2>/dev/null)
+
+# --- Summary ---
+echo ""
+echo "========================="
+echo "Warnings: $WARNINGS"
+echo "Errors:   $ERRORS"
+
+if [ $ERRORS -gt 0 ]; then
+  echo "RESULT: FAIL"
+  exit 1
+elif [ $WARNINGS -gt 0 ]; then
+  echo "RESULT: PASS with warnings"
+  exit 0
+else
+  echo "RESULT: CLEAN"
+  exit 0
+fi