axel-setup 0.2.0

package/hooks/validate-commit-format.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Validates commit message format: tipo (Modelo/Archivo): Mensaje
+# Reads $TOOL_INPUT as JSON, extracts the command, then validates the commit message
+# Valid types: feat|fix|chore|refactor|test|docs|style|perf|ci|build|revert
+
+TOOL_JSON="$TOOL_INPUT"
+
+# Extract the command field from the Bash tool JSON input
+CMD=$(echo "$TOOL_JSON" | jq -r '.command // empty' 2>/dev/null)
+[ -z "$CMD" ] && CMD="$TOOL_JSON"
+
+# Only check git commit commands
+echo "$CMD" | grep -qE 'git commit' || exit 0
+
+# Extract commit message from -m flag
+# Handles: -m "msg", -m 'msg', -m "$(cat <<'EOF'\nmsg\nEOF\n)"
+MSG=$(echo "$CMD" | sed -n 's/.*-m[[:space:]]*["'\'']\{0,1\}\(.*\)/\1/p' | sed 's/["'\'']\{0,1\}[[:space:]]*$//' | head -1)
+
+# For heredoc pattern: extract the first content line
+if echo "$MSG" | grep -q '<<'; then
+  MSG=$(echo "$CMD" | tr '\n' '|' | sed 's/.*<<[^|]*|//' | sed 's/|.*//' | sed 's/^[[:space:]]*//')
+fi
+
+# If we couldn't extract a message, skip validation (might be --amend or interactive)
+[ -z "$MSG" ] && exit 0
+
+# Validate format: tipo (Scope): message
+if ! echo "$MSG" | grep -qE '^(feat|fix|chore|refactor|test|docs|style|perf|ci|build|revert)\s*\('; then
+  echo "BLOCKED: Commit format is incorrect." >&2
+  echo "Required: type (Scope): Descriptive message" >&2
+  echo "Canonical example: feat (AuthController): add OAuth2 login flow" >&2
+  echo "Valid types: feat|fix|chore|refactor|test|docs|style|perf|ci|build|revert" >&2
+  echo "Do not use --no-verify to bypass this check. Fix the message instead." >&2
+  echo "Got: $MSG" >&2
+  exit 1
+fi
+
+exit 0

package/hooks/weekly-priority-map-review.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# Weekly priority-map review — intended to run every Monday 9am via LaunchAgent/cron.
+# Analyzes git activity from the last 7 days + current priority-map and writes
+# an update proposal. Does not modify priority-map directly — user reviews and applies.
+#
+# Configuration (env vars):
+#   PRIORITY_MAP_REPOS — space-separated list of absolute repo paths to scan.
+#                        Example: "$HOME/work/api $HOME/work/web"
+#                        If unset/empty, the git-evidence section is skipped.
+
+set -e
+
+MEMORY_DIR="$HOME/.claude/memory"
+PRIORITY_MAP="$MEMORY_DIR/priority-map.md"
+ARCHIVE="$MEMORY_DIR/MEMORY-archive.md"
+LOG_DIR="$HOME/.claude/logs"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/priority-map-review.log"
+
+TIMESTAMP=$(date +%Y-%m-%d)
+PROPOSAL_FILE="$MEMORY_DIR/priority-map.proposed-${TIMESTAMP}.md"
+REVIEW_SUMMARY="$MEMORY_DIR/priority-map-review-${TIMESTAMP}.md"
+
+echo "=== priority-map review $(date) ===" >> "$LOG_FILE"
+
+if [[ ! -f "$PRIORITY_MAP" ]]; then
+  echo "ERROR: priority-map.md does not exist at $MEMORY_DIR" >> "$LOG_FILE"
+  exit 1
+fi
+
+# Anti-recursion guard: prevents infinite loops if this hook is wired into a
+# lifecycle event that fires during the claude -p subprocess below.
+if [[ -n "$CLAUDE_HOOK_RUNNING" ]]; then
+  echo "SKIP: CLAUDE_HOOK_RUNNING set — avoiding recursion" >> "$LOG_FILE"
+  exit 0
+fi
+export CLAUDE_HOOK_RUNNING=1
+
+# Isolated JSONL session to avoid polluting /resume history.
+ISOLATED_SESSION_DIR=$(mktemp -d)
+export CLAUDE_SESSION_DIR="$ISOLATED_SESSION_DIR"
+
+# Collect git evidence from the last 7 days across configured repos.
+REPOS="${PRIORITY_MAP_REPOS:-}"
+GIT_EVIDENCE=$(
+  if [[ -z "$REPOS" ]]; then
+    echo "(PRIORITY_MAP_REPOS not set — skipping git evidence collection)"
+  else
+    for repo in $REPOS; do
+      [ -d "$repo/.git" ] || continue
+      repo_name=$(basename "$repo")
+      echo "## $repo_name"
+      cd "$repo" 2>/dev/null && {
+        git fetch origin --quiet 2>/dev/null || true
+        echo "### Merged PRs last 7 days"
+        git log --first-parent origin/main --since="7 days ago" --pretty=format:'- %s' 2>/dev/null | head -30
+        echo ""
+        echo "### New branches (not merged to main)"
+        if [[ "$(uname)" == "Darwin" ]]; then
+          SEVEN_DAYS_AGO=$(date -v-7d +%Y-%m-%d)
+        else
+          SEVEN_DAYS_AGO=$(date -d '7 days ago' +%Y-%m-%d)
+        fi
+        git for-each-ref --sort=-committerdate --format='%(refname:short) %(committerdate:short)' refs/remotes/origin 2>/dev/null | awk -v d="$SEVEN_DAYS_AGO" '$2 >= d {print "- " $0}' | head -20
+        echo ""
+      }
+    done
+  fi
+)
+
+PROMPT=$(cat <<PROMPT_EOF
+It is Monday morning. Your task: review the user priority-map.md and propose an update based on recent git activity.
+
+**Input 1 — current priority-map:**
+\`\`\`
+$(cat "$PRIORITY_MAP")
+\`\`\`
+
+**Input 2 — git activity last 7 days (tracked repos):**
+\`\`\`
+$GIT_EVIDENCE
+\`\`\`
+
+**Input 3 — current archive:**
+\`\`\`
+$(cat "$ARCHIVE" 2>/dev/null || echo "empty")
+\`\`\`
+
+**Expected output — write TWO files:**
+
+1. \`$REVIEW_SUMMARY\` — short analysis summary:
+   - P0 items in the priority-map that look CLOSED based on git (matching merged PR)
+   - P1 items in the priority-map that look CLOSED based on git
+   - New items detected in git that should be promoted to P0/P1 (large features, recent PRs with no card in the map)
+   - P0/P1 items with NO activity in 7 days → flag as stale
+   - Concrete question at the end: "Confirm moving items [X, Y, Z] to archive and adding [A, B] to P0/P1?"
+
+2. \`$PROPOSAL_FILE\` — full proposal for the new priority-map.md:
+   - Same structure as current
+   - Closed items removed
+   - New items added in the matching bucket
+   - Updated field set to $TIMESTAMP
+   - Sprint field only if you can infer it from context, otherwise leave it
+   - Do NOT overwrite \`$PRIORITY_MAP\` directly — only the .proposed file
+
+**Rules:**
+- Conservative: if an item does not clearly match a merged PR, do NOT move it to the archive.
+- If there is not enough evidence to propose changes → write "No changes suggested — priority-map looks up to date" in the review summary.
+- Do not invent new P0s without git evidence.
+PROMPT_EOF
+)
+
+# Resolve claude CLI: prefer PATH, fall back gracefully if not found.
+CLAUDE_BIN=$(command -v claude || true)
+if [[ -z "$CLAUDE_BIN" ]]; then
+  echo "ERROR: claude CLI not found in PATH" >> "$LOG_FILE"
+  rm -rf "$ISOLATED_SESSION_DIR"
+  exit 1
+fi
+
+echo "Running claude -p..." >> "$LOG_FILE"
+"$CLAUDE_BIN" -p "$PROMPT" \
+  --allowed-tools "Read,Write,Edit,Bash,Glob,Grep" \
+  >> "$LOG_FILE" 2>&1 || {
+  echo "ERROR: claude -p failed" >> "$LOG_FILE"
+  /usr/bin/osascript -e 'display notification "claude -p failed — check ~/.claude/logs/priority-map-review.log" with title "Priority Map Review"' 2>/dev/null || true
+  rm -rf "$ISOLATED_SESSION_DIR"
+  exit 1
+}
+
+rm -rf "$ISOLATED_SESSION_DIR"
+
+# Notify via macOS notification center (no-op on Linux).
+if [[ -f "$REVIEW_SUMMARY" ]]; then
+  /usr/bin/osascript -e "display notification \"Review $REVIEW_SUMMARY and $PROPOSAL_FILE\" with title \"Priority Map Review — Monday\" sound name \"Purr\"" 2>/dev/null || true
+  echo "OK — files generated: $REVIEW_SUMMARY, $PROPOSAL_FILE" >> "$LOG_FILE"
+else
+  /usr/bin/osascript -e 'display notification "Review produced no files — check ~/.claude/logs/priority-map-review.log" with title "Priority Map Review"' 2>/dev/null || true
+  echo "WARNING: claude -p finished but $REVIEW_SUMMARY is missing" >> "$LOG_FILE"
+fi
+
+echo "=== end $(date) ===" >> "$LOG_FILE"
+exit 0

package/install.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env sh
+set -eu
+
+AXEL_PACKAGE="${AXEL_SETUP_PACKAGE:-axel-setup@latest}"
+AXEL_NPX="${AXEL_SETUP_NPX:-npx}"
+
+die() {
+  printf '%s\n' "AXEL install error: $*" >&2
+  exit 1
+}
+
+require_command() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    die "$2"
+  fi
+}
+
+uses_non_claude_target() {
+  target="claude"
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --target=*)
+        target="${1#*=}"
+        ;;
+      --target)
+        shift
+        target="${1:-claude}"
+        ;;
+    esac
+    [ "$#" -gt 0 ] || break
+    shift
+  done
+
+  [ "$target" = "codex" ] || [ "$target" = "generic" ]
+}
+
+require_command zsh "zsh is required. Install Xcode Command Line Tools or a zsh package before running AXEL."
+require_command jq "jq is required. On macOS, install it with: brew install jq"
+require_command node "Node.js is required because the packaged AXEL CLI runs through npx. Install Node 18 or newer."
+require_command "$AXEL_NPX" "npx is required. Install npm with Node.js, then rerun this installer."
+
+if ! uses_non_claude_target "$@" && [ "${AXEL_SETUP_SKIP_CLAUDE_CHECK:-false}" != "true" ]; then
+  require_command claude "Claude Code CLI is required for the default target. Install Claude Code, pass --target codex or --target generic, or set AXEL_SETUP_SKIP_CLAUDE_CHECK=true."
+fi
+
+exec "$AXEL_NPX" -y "$AXEL_PACKAGE" "$@"

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "axel-setup",
+  "version": "0.2.0",
+  "description": "Claude Code-first team configuration package with hooks, agents, commands, skills, plugins, and repeatable bootstrap tooling.",
+  "license": "MIT",
+  "author": {
+    "name": "Cristian Vera Lyon",
+    "url": "https://github.com/cveralyon"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "developer-tools",
+    "automation",
+    "devex",
+    "mcp",
+    "agentic-engineering",
+    "codex",
+    "multi-runtime",
+    "bootstrap"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cveralyon/axel-setup.git"
+  },
+  "homepage": "https://github.com/cveralyon/axel-setup#readme",
+  "bugs": {
+    "url": "https://github.com/cveralyon/axel-setup/issues"
+  },
+  "bin": {
+    "axel-setup": "bin/axel-setup.js"
+  },
+  "files": [
+    "agents",
+    "commands",
+    "hooks",
+    "scripts",
+    "skills",
+    "templates",
+    "tools",
+    "docs",
+    "bin",
+    "tests/fixtures",
+    "install.sh",
+    "bootstrap.sh",
+    "axel-manifest.json",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "README.md",
+    "!skills/**/__pycache__",
+    "!skills/**/*.pyc"
+  ],
+  "scripts": {
+    "check": "bash scripts/ci/check.sh",
+    "smoke": "bash scripts/ci/bootstrap-dry-run.sh",
+    "pack:dry-run": "npm pack --dry-run",
+    "publish:dry-run": "npm publish --dry-run",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/ci/bootstrap-dry-run.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+TMP_HOME="$(mktemp -d)"
+TMP_BIN="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "$TMP_HOME" "$TMP_BIN"
+}
+trap cleanup EXIT
+
+cat >"$TMP_BIN/claude" <<'STUB'
+#!/usr/bin/env bash
+case "${1:-}" in
+  --version)
+    echo "Claude Code 1.0.0"
+    ;;
+  plugins)
+    exit 0
+    ;;
+  *)
+    echo "claude stub"
+    ;;
+esac
+STUB
+chmod +x "$TMP_BIN/claude"
+
+PATH="$TMP_BIN:$PATH" \
+  HOME="$TMP_HOME" \
+  bash "$ROOT/bootstrap.sh" \
+  --dry-run \
+  --user-name "CI Bot" \
+  --user-context "CI smoke test" \
+  --language english
+
+if [ -e "$TMP_HOME/.claude" ]; then
+  echo "Dry run created $TMP_HOME/.claude" >&2
+  exit 1
+fi

package/scripts/ci/check.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT"
+
+echo "Checking shell syntax"
+while IFS= read -r -d '' file; do
+  if head -n 1 "$file" | grep -q "zsh"; then
+    zsh -n "$file"
+  else
+    bash -n "$file"
+  fi
+done < <(find . -path ./.git -prune -o -type f -name "*.sh" -print0)
+
+if command -v shellcheck >/dev/null 2>&1; then
+  echo "Running shellcheck"
+  while IFS= read -r -d '' file; do
+    if head -n 1 "$file" | grep -q "zsh"; then
+      continue
+    fi
+    shellcheck -S error "$file"
+  done < <(find . -path ./.git -prune -o -type f -name "*.sh" -print0)
+else
+  echo "Skipping shellcheck (not installed)"
+fi
+
+if command -v shfmt >/dev/null 2>&1; then
+  echo "Checking shell formatting"
+  shfmt -d -i 2 -ci scripts/ci/*.sh tests/*.sh
+else
+  echo "Skipping shfmt (not installed)"
+fi
+
+echo "Checking Node CLI syntax"
+node --check bin/axel-setup.js
+
+echo "Checking jq filters"
+while IFS= read -r -d '' file; do
+  jq -n -f "$file" >/dev/null
+done < <(find . -path ./.git -prune -o -type f -name "*.jq" -print0)
+
+echo "Checking JSON files"
+jq empty package.json axel-manifest.json templates/settings.json templates/keybindings.json
+
+echo "Running bootstrap dry run smoke test"
+bash scripts/ci/bootstrap-dry-run.sh
+
+echo "Running bootstrap behavior tests"
+bash tests/bootstrap-behavior.sh
+
+echo "Running one-line installer tests"
+bash tests/install-one-line.sh
+
+echo "Running hook harness tests"
+bash tests/hook-harness.sh
+
+echo "Running CLI doctor tests"
+bash tests/cli-doctor.sh
+
+echo "Running settings merge fixture tests"
+bash tests/merge-settings.sh
+
+echo "Checking npm package contents"
+npm pack --dry-run >/dev/null

package/scripts/posthog-snapshot-loader.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+# posthog-snapshot-loader.sh
+# Reads ~/.claude/cache/posthog-snapshot.json and prints a markdown summary
+# for inclusion in larger reports (e.g. /sprint-status, /eod-review, /daily).
+#
+# Output contract:
+# - If snapshot does not exist: prints a one-line nudge ("📊 No PostHog snapshot…").
+# - If snapshot exists and is < 14 days old: prints a structured markdown block
+#   with critical findings, wins, and improvements.
+# - If snapshot exists and is > 14 days old: prints a stale warning instead of
+#   the full block, so callers don't quote outdated insights at users.
+#
+# The snapshot is generated by the /posthog-weekly skill. This loader is
+# read-only: it never refreshes data. To refresh, the user runs /posthog-weekly.
+#
+# Output format is plain markdown so callers can either include it verbatim
+# in a larger report or pipe it to another tool. Exit code is always 0 — this
+# script never blocks the caller, even when the snapshot is missing or stale.
+
+set -e
+
+SNAPSHOT="$HOME/.claude/cache/posthog-snapshot.json"
+STALE_DAYS="${POSTHOG_SNAPSHOT_STALE_DAYS:-14}"
+
+# Case 1: no snapshot at all → silent nudge, single line
+if [ ! -f "$SNAPSHOT" ]; then
+  echo "📊 _No PostHog snapshot yet — run \`/posthog-weekly\` to generate one._"
+  exit 0
+fi
+
+# Case 2: snapshot exists but is unreadable / not valid JSON
+if ! jq empty "$SNAPSHOT" 2>/dev/null; then
+  echo "⚠️ _PostHog snapshot at \`$SNAPSHOT\` is not valid JSON — re-run \`/posthog-weekly\` to regenerate._"
+  exit 0
+fi
+
+# Compute snapshot age in days. The snapshot stores its timestamp as ISO 8601
+# UTC. macOS `date -j -f` parses it; Linux `date -d` is the GNU equivalent.
+TS=$(jq -r '.timestamp // empty' "$SNAPSHOT")
+if [ -z "$TS" ]; then
+  echo "⚠️ _PostHog snapshot has no timestamp — re-run \`/posthog-weekly\` to regenerate._"
+  exit 0
+fi
+
+NOW_EPOCH=$(date +%s)
+SNAP_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$TS" +%s 2>/dev/null \
+          || date -d "$TS" +%s 2>/dev/null \
+          || echo 0)
+
+if [ "$SNAP_EPOCH" -eq 0 ]; then
+  echo "⚠️ _PostHog snapshot timestamp \`$TS\` could not be parsed — re-run \`/posthog-weekly\`._"
+  exit 0
+fi
+
+AGE_DAYS=$(( (NOW_EPOCH - SNAP_EPOCH) / 86400 ))
+
+# Case 3: stale snapshot → short warning, no quoted findings
+if [ "$AGE_DAYS" -gt "$STALE_DAYS" ]; then
+  echo "⚠️ _PostHog snapshot is **${AGE_DAYS} days old** (stale > ${STALE_DAYS}d). Run \`/posthog-weekly\` to refresh before quoting._"
+  exit 0
+fi
+
+# Case 4: fresh snapshot → full block
+PROJECT_NAME=$(jq -r '.project_name // "PostHog"' "$SNAPSHOT")
+PROJECT_URL=$(jq -r '.project_url // empty' "$SNAPSHOT")
+
+echo "## 📊 PostHog Insights — ${PROJECT_NAME}"
+echo ""
+echo "_Snapshot from ${AGE_DAYS} day(s) ago — generated by \`/posthog-weekly\`_"
+echo ""
+
+# Critical findings — most important, always shown first
+CRITICAL_COUNT=$(jq -r '.critical_findings | length' "$SNAPSHOT")
+if [ "$CRITICAL_COUNT" -gt 0 ]; then
+  echo "### 🚨 Critical findings"
+  jq -r '.critical_findings[] | "- \(.)"' "$SNAPSHOT"
+  echo ""
+fi
+
+# Regressions / anomalies
+REGRESSION_COUNT=$(jq -r '.regressions // [] | length' "$SNAPSHOT")
+if [ "$REGRESSION_COUNT" -gt 0 ]; then
+  echo "### 📉 Regressions & anomalies"
+  jq -r '.regressions[] | "- \(.)"' "$SNAPSHOT"
+  echo ""
+fi
+
+# Wins
+WIN_COUNT=$(jq -r '.wins // [] | length' "$SNAPSHOT")
+if [ "$WIN_COUNT" -gt 0 ]; then
+  echo "### ✅ Wins"
+  jq -r '.wins[] | "- \(.)"' "$SNAPSHOT"
+  echo ""
+fi
+
+# Improvement opportunities
+IMPROVEMENT_COUNT=$(jq -r '.improvements // [] | length' "$SNAPSHOT")
+if [ "$IMPROVEMENT_COUNT" -gt 0 ]; then
+  echo "### 🎯 Improvement opportunities"
+  jq -r '.improvements[] | "- \(.)"' "$SNAPSHOT"
+  echo ""
+fi
+
+# Project link if available
+if [ -n "$PROJECT_URL" ]; then
+  echo "_Project: <${PROJECT_URL}>_"
+  echo ""
+fi
+
+echo "_For deeper analysis, run \`/posthog-weekly\` to refresh this snapshot._"
+
+exit 0

package/skills/context-budget/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: context-budget
+description: Audits Claude Code context consumption across agents, skills, commands, hooks, MCP servers, and the CLAUDE.md/MEMORY chain. Identifies bloat and redundancy, then produces prioritized token-savings recommendations. Backs the /context-budget command.
+origin: ECC (adapted)
+---
+
+# Context Budget
+
+Estimate the token overhead of everything loaded into a Claude Code session and surface concrete ways to reclaim context space. Adapted from ECC's context-budget for a single-runtime (Claude Code) setup on a large Opus window.
+
+## When to Use
+
+- The setup has grown (many agents, hooks, skills, MCP servers) and you want the real load cost.
+- Output quality degrades, or the context monitor fires earlier than expected.
+- Before adding more agents, skills, or MCP servers: check headroom first.
+- Running the `/context-budget` command (this skill backs it).
+
+## How It Works
+
+Token estimation: prose uses `words × 1.3`, code or JSON uses `chars / 4`.
+
+### Phase 1 — Inventory
+
+Scan each source and estimate tokens.
+
+- **Agents** (`~/.claude/agents/*.md`): tokens per file. Flag files over 200 lines (heavy) and a `description` over 30 words (it loads into every Task tool invocation, even for agents never spawned).
+- **Skills** (`~/.claude/skills/*/SKILL.md`): tokens per SKILL.md. Flag over 400 lines.
+- **Commands** (`~/.claude/commands/*.md`): tokens per file. Flag stale or duplicated entries.
+- **Hooks** (`~/.claude/hooks/` plus the wiring in `settings.json`): count active hooks. Flag heavy or overlapping ones.
+- **MCP servers** (active MCP config): count servers and total tools. Estimate ~500 tokens per tool schema. Flag servers over 20 tools, and servers that wrap a CLI already available for free (gh, git, vercel, supabase).
+- **CLAUDE.md and memory chain** (`~/CLAUDE.md`, `~/.claude/memory/MEMORY.md`, any project CLAUDE.md): tokens per file. Flag a combined total over 400 lines, or a MEMORY index that carries detail instead of one-line pointers.
+
+Note on RTK: it compresses Bash OUTPUT at runtime. It does not reduce the LOAD cost of this setup. Measure the load cost (the files above), not RTK-filtered command output.
+
+### Phase 2 — Classify
+
+| Bucket | Criteria | Action |
+|--------|----------|--------|
+| Always needed | Referenced in CLAUDE.md, backs an active command, or matches current work | Keep |
+| Sometimes needed | Domain-specific, not referenced in CLAUDE.md | On-demand or lazy-load |
+| Rarely needed | No reference, overlapping content, no project match | Remove or archive |
+
+### Phase 3 — Detect Issues
+
+- Bloated agent descriptions (over 30 words): present in every Task tool context.
+- Heavy agents (over 200 lines): inflate Task context on every spawn.
+- Redundant components: skills that duplicate agent logic, memory entries that duplicate CLAUDE.md rules.
+- MCP over-subscription: many servers, or servers wrapping free CLI tools.
+- CLAUDE.md or MEMORY bloat: verbose sections, stale rules, MEMORY entries carrying detail instead of a one-line hook.
+
+### Phase 4 — Report
+
+```
+Context Budget Report
+═══════════════════════════════════════
+Window: Opus (1M tokens)
+Total estimated setup overhead: ~XX,XXX tokens (XX% of 1M)
+Effective working context: ~XXX,XXX tokens
+
+Component Breakdown:
+┌───────────────┬───────┬──────────┐
+│ Component     │ Count │ Tokens   │
+├───────────────┼───────┼──────────┤
+│ Agents        │ N     │ ~X,XXX   │
+│ Skills        │ N     │ ~X,XXX   │
+│ Commands      │ N     │ ~X,XXX   │
+│ Hooks         │ N     │ ~X,XXX   │
+│ MCP tools     │ N     │ ~XX,XXX  │
+│ CLAUDE+memory │ N     │ ~X,XXX   │
+└───────────────┴───────┴──────────┘
+
+Top 3 Optimizations (ranked by savings):
+1. [action] → ~X,XXX tokens
+2. [action] → ~X,XXX tokens
+3. [action] → ~X,XXX tokens
+```
+
+In verbose mode, add per-file token counts, the heaviest files line-counted, and the MCP tool list with per-tool schema estimates.
+
+## Best Practices
+
+- MCP is usually the biggest lever. One 30-tool server can cost more than every skill combined.
+- Agent descriptions load always, even for agents never invoked. Keep them tight.
+- On a 1M window the absolute overhead matters less than redundancy and menu noise. Prioritize removing stale or duplicated surface over shaving raw tokens.
+- Re-audit after adding any agent, skill, or MCP server to catch creep early.
+- Pairs with the `harness-optimizer` agent, which consumes this report as its baseline.