playbook-ai 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable updates to Playbook are documented here. Only impactful changes are listed — new commands, upgraded behavior, and things that make your workflow better. Cosmetic fixes and internal housekeeping are omitted.
 
+## [1.5.0] — 2026-05-27
+
+### Strategy
+- **New `/future` command** — scenario planning via three futures (The Win, The Unraveling, The Headwind). Reads project context silently, runs a short intake, then writes three past-tense narratives rewound month by month to today. Synthesizes them via quadrant analysis to surface double-confirmed critical actions, swing-state decisions, and failure drivers. Output is one screen: a thesis, 3 load-bearing decisions (ordered by when they must be made), 3 anti-patterns to avoid (with why they're tempting and the early signal you're sliding in), and your move this week. Full narratives available in appendix on request. Ends with an optional 30-day ClickUp or WORK_LOG check-in. The third scenario (The Headwind) is the one most people skip — it surfaces external forces you need to be resilient against, not just what you did right or wrong.
+
+## [1.4.3] — 2026-05-25
+
+### Performance
+- **`/start` context reduction** — removed redundant `CLAUDE.md` read (already injected automatically into every session via system context). Added daily throttle on the Playbook update check: after the first check of the day, subsequent `/start` calls skip the git fetch + curl + CHANGELOG read entirely. Timestamp stored in `~/.claude/.playbook-last-update-check`.
+
+## [1.4.2] — 2026-05-17
+
+### Reliability
+- **PreCompact hook** — automatically appends a timestamped marker to `WORK_LOG.md` whenever Claude Code hits the context limit and auto-compaction fires. No more silent mid-session state loss. The marker flags that state above the line may be incomplete and prompts starting a new session. Installed via `hooks/precompact-save.sh`; wired into `settings.json` at install time (additive merge for users who already have a settings.json).
+
 ## [1.4.1] — 2026-05-03
 
 ### Strategy

package/CLAUDE.md

@@ -114,6 +114,11 @@
 - Propose parallel work when independent tasks can run simultaneously
 - Never overlap files/tables/workflows between parallel sessions
 
+## Writing Style
+- **No em dashes.** Use a colon, a comma, or restructure the sentence.
+- Avoid AI writing tells: "delve," "leverage," "utilize," "comprehensive," "robust," "nuanced," "crucial," "pivotal," "it's worth noting," "in conclusion"
+- No filler openers: "Certainly!", "Of course!", "Great question!", "Absolutely!"
+
 ## Plugins
 - **Frontend Design** (`frontend-design@claude-plugins-official`) is installed by default. It generates distinctive, production-grade frontend interfaces with bold typography, unique color palettes, and creative layouts. No action needed — it's active automatically.
 - **Code Review Agents** (`code-review@claude-plugins-official`) is recommended for PR-based workflows. Install with: `/plugin install code-review@claude-plugins-official`. It runs multiple specialized review agents in parallel (comment analysis, test coverage, silent failure detection, type design, code quality, simplification) with confidence-based scoring.

package/VERSION

@@ -1 +1 @@
-1.4.1
+1.5.0

package/commands/end.md

@@ -12,11 +12,13 @@ Session closeout. Do everything needed so the user can walk away without taking
    - Update "Known Issues / Next Steps" — remove anything completed, add anything new discovered, reprioritize if needed. Be explicit about what's next and what's blocked
    - If any task is partially done, document exactly where it was left off and what remains
 
-3. **Trim WORK_LOG.md if needed.** Count the number of dated session entries (lines matching `## YYYY-MM-DD` or `### YYYY-MM-DD`). If there are more than 100 sessions:
+3. **Compress WORK_LOG.md if needed.** Count the number of entries — dated session headers (`## YYYY-MM-DD` or `### YYYY-MM-DD`) plus any existing `## Compressed:` blocks. If the total exceeds 100:
+   - Read the 10 oldest entries (whether raw sessions or prior compressed blocks)
+   - Summarize each to 2-3 bullets: what was done, what changed, what was decided
+   - Replace those 10 entries with a single block at the bottom: `## Compressed: [earliest date] – [latest date]` followed by the bullet summaries
    - Keep the Overall State / header section intact
-   - Keep the 100 most recent session entries
-   - Remove everything older — those sessions have served their purpose and the important bits should already be captured in Overall State and auto-memory
-   - Do NOT archive to a separate file — just delete. Git history has the full log if ever needed.
+   - Result: you drop from 101+ entries to ~92, with history preserved in compressed form
+   - This fires roughly once every 9-10 sessions — not every session after the limit
 
 4. **Update PM tool** (if MCP is connected). Mark completed tasks as done. Update in-progress tasks with status notes. Create new tasks for anything discovered during the session that needs tracking.
 

package/commands/future.md

@@ -0,0 +1,181 @@
+Scenario planning via three futures. Rewinds each path month by month to today, synthesizes the decisions that mattered most, and delivers a one-screen action guide with a clear first move.
+
+---
+
+## Pre-flight: Read context
+
+Silently read the following before doing anything else:
+- `WORK_LOG.md` in the current project
+- `CLAUDE.md` in the current project
+- Recent git log (last 20 commits) if available
+- Any open/in-progress PM tasks if a PM MCP is connected
+
+Do not summarize this to the user. Use it to ground the scenarios in the actual project — real constraints, real state, real recent decisions. Generic startup scenarios are useless.
+
+---
+
+## Intake
+
+Ask these questions conversationally — not as a numbered list. One at a time, naturally. Use follow-ups where an answer is thin. The goal is enough material to write scenarios that are specific, not vague.
+
+**Question 1 — The north star**
+What does massive success look like in concrete terms? Not "we grew a lot" — what's the specific outcome, 12 months from now, that you'd genuinely be proud of? Name it as if it already happened.
+
+**Question 2 — The fear**
+What's the specific failure that keeps you up at night? The scenario you'd be embarrassed to explain to someone who believed in you. Be direct.
+
+**Question 3 — The constraints**
+What are the hard limits right now? Runway, team size, a deadline that isn't moveable, a dependency you're waiting on. What are you working around?
+
+**Timeframe**
+Based on the project context and what the user just described, propose a timeframe. Default is 12 months, but:
+- Shorter (3–6 months) for a specific launch, campaign, or sprint with a hard end date
+- Longer (18–24 months) for platforms, infrastructure, or ventures still finding product-market fit
+- Say: *"Based on what you've described, I'd suggest a [N]-month horizon — does that feel right, or should we adjust?"*
+
+Confirm the timeframe before proceeding.
+
+---
+
+## Three scenarios
+
+Write all three. Past tense throughout. The narrative voice is: you're explaining what happened to someone who loves you and won't let you bullshit them — honest, specific, no spin. This isn't a case study or a consultant's report. It's a candid debrief.
+
+For each scenario, start at the end of the timeframe and rewind month by month to today. Name specific decisions, not themes. Name the moments where the path forked. Name what was done and what wasn't.
+
+---
+
+### Scenario A: The Win
+
+Massive success landed. Rewind from the end state to today.
+
+What happened? Not just what worked — what *decisions* and *actions* were instrumental? What did you do in month 2 that set up month 8? What did you resist that would have derailed you? What was the moment where it could have gone either way, and what made it go right?
+
+Be specific about:
+- The decisions that compounded (small early, large later)
+- The things you *didn't* do that turned out to matter
+- The external factors that helped — and what you did to be positioned to benefit from them
+
+---
+
+### Scenario B: The Unraveling
+
+Massive failure. Rewind from the end state to today.
+
+What happened? Not just "we ran out of money" or "we lost momentum" — what specific decisions, delays, and patterns led there? What looked reasonable at the time but wasn't? What was done instead of what actually mattered? When did you first know something was wrong, and what did you do (or not do) about it?
+
+Be specific about:
+- What was tempting but harmful (the anti-patterns that looked like good ideas)
+- What was delayed past the point of recovery
+- What the earliest warning sign was — before it became obvious
+- What you'd tell yourself in month 2 if you could
+
+---
+
+### Scenario C: The Headwind
+
+You did almost everything right. The universe didn't cooperate. Rewind from the end state to today.
+
+This is the scenario most people don't think about because it's uncomfortable — you can't control it, and it feels like an excuse. But naming it clearly is the difference between being blindsided and being resilient.
+
+What external forces hit that you couldn't have fully predicted? A market shift, a competitor move, a platform change, a regulatory event, a macro condition, a key relationship that fell through. What was the real ceiling on what could be achieved even with strong execution?
+
+Be specific about:
+- What you were exposed to that you didn't need to be
+- What resilience you had built — and what you wish you'd built
+- The difference between "bad luck" and "we were fragile in a way we could have fixed"
+- What "doing everything right" actually looked like in this world
+
+---
+
+## Synthesis
+
+Do this internally before writing the final output. Do not show the synthesis process to the user — only the output.
+
+**Quadrant analysis**
+Classify decisions and actions across the three scenarios:
+
+- **Double-confirmed critical** — appears in The Win AND its absence appears in The Unraveling. These are the highest-confidence levers.
+- **Swing-state decisions** — present in The Win but also present (differently executed) in The Unraveling. These are hard calls, not obvious moves. Flag them explicitly.
+- **Failure drivers** — appear in The Unraveling and are absent from The Win. The anti-patterns.
+- **Resilience gaps** — surface from The Headwind. Things within your control that would have changed your exposure to external forces.
+
+**Leading indicators**
+For each critical decision or turning point in The Unraveling: what was the *earliest signal* that this was coming? Not month 8 when it was obvious — month 2, when there was still time. Extract these from the narrative, don't ask the user. They're already embedded in the story.
+
+**Irreversibility flag**
+Tag each load-bearing decision as:
+- **Hard to reverse** — hiring, pricing model, core tech choices, pivots, strategic commitments
+- **Iterable** — things you can course-correct on without major cost
+
+Hard-to-reverse decisions deserve more upfront thought and appear earlier in the output.
+
+**Order by when, not importance**
+Sort all output items by *when* the decision needs to be made, not by abstract importance. Timing drives action; importance doesn't.
+
+---
+
+## Output
+
+Present the primary output in full. Then offer the appendix.
+
+---
+
+**The thesis**
+
+One paragraph. The single most important variable — the fork in the road that, more than anything else, separates The Win from The Unraveling. Don't list three things. Name the one.
+
+---
+
+**3 load-bearing decisions**
+
+The decisions that cascade if you get them wrong or delay them. For each:
+- **The decision** — what it is, stated plainly
+- **When it needs to be made** — a specific window ("before month 3," "within the next 6 weeks"), not "eventually"
+- **Early warning sign** — the earliest signal that this is going wrong, before it's obvious
+- Mark hard-to-reverse decisions with *(irreversible)*
+
+Ordered by when, not importance. Three max. If more surfaced, put the rest in the appendix.
+
+---
+
+**3 things not to do**
+
+From The Unraveling. For each:
+- **The anti-pattern** — what it is
+- **Why it's tempting** — if it weren't tempting, you wouldn't need the warning
+- **The signal you're sliding into it** — the earliest sign, before it becomes entrenched
+
+Three max. The most dangerous ones — the ones that looked like good ideas.
+
+---
+
+**Your move this week**
+
+One or two specific actions, this week. Not "eventually" — this week. These are the entry point into the critical path. Everything else can wait until these are done.
+
+---
+
+*Full narratives, complete quadrant synthesis, and everything else the exercise surfaced are in the appendix. Type "show appendix" to read.*
+
+---
+
+**Follow-up**
+
+After presenting the output, offer one of the following (based on what tools are connected):
+- If ClickUp MCP is connected: *"Want me to create a ClickUp task to review the load-bearing decisions 30 days from now?"*
+- Otherwise: *"Want me to add a reminder to WORK_LOG.md to revisit these decisions in 30 days?"*
+
+This is a one-line offer. Don't push it.
+
+---
+
+## Appendix (on request)
+
+If the user types "show appendix" or asks to see more:
+
+1. **Full narratives** — all three scenarios in full
+2. **Quadrant synthesis** — the full classification of every decision/action that surfaced
+3. **Everything else** — items that didn't make the top 3 in either output section, labeled "worth knowing, not the priority right now"
+
+Present the appendix cleanly, clearly separated from the primary output.

package/commands/start.md

@@ -1,5 +1,3 @@
-Read CLAUDE.md to understand the project rules and conventions.
-
 Read WORK_LOG.md **efficiently** — do NOT read the entire file if it's long:
 - Read the **first 30 lines** (Overall State, current status headers)
 - Read the **most recent session section** only (the first dated session entry)
@@ -17,7 +15,8 @@ Before anything else, silently check if a newer version of Playbook is available
 ### Pre-flight (silent — no output to user)
 
 1. Check if `~/.claude/.playbook-version` exists. If not, skip the update check entirely.
-2. Read the installed version from `~/.claude/.playbook-version`.
+2. **Daily throttle:** Check if `~/.claude/.playbook-last-update-check` exists and contains today's date (format: `YYYY-MM-DD`). If it does, skip the entire update check and go straight to the normal briefing. If not (file missing or date is old), proceed and write today's date to that file after the check completes — whether or not an update was found.
+3. Read the installed version from `~/.claude/.playbook-version`.
 3. Try to fetch the latest version:
    - **If git is available and `~/.claude/.playbook/` is a git repo:** Run `git -C ~/.claude/.playbook fetch origin main --quiet` then read `VERSION` from the fetched main branch using `git -C ~/.claude/.playbook show origin/main:VERSION`.
    - **If git is not available or fails:** Use `curl -sf https://raw.githubusercontent.com/bluemax713/playbook/main/VERSION` to get the latest version.

package/install.sh

@@ -80,6 +80,49 @@ else
   echo "  Installed settings.json"
 fi
 
+# Install hooks script
+mkdir -p "$CLAUDE_DIR/hooks"
+cp "$PLAYBOOK_DIR/hooks/precompact-save.sh" "$CLAUDE_DIR/hooks/precompact-save.sh"
+chmod +x "$CLAUDE_DIR/hooks/precompact-save.sh"
+echo "  Installed hook: precompact-save"
+
+# Merge PreCompact hook into existing settings.json (additive — won't overwrite existing hooks)
+python3 - << 'EOF'
+import json, os, sys
+
+settings_path = os.path.expanduser("~/.claude/settings.json")
+if not os.path.exists(settings_path):
+    sys.exit(0)
+
+with open(settings_path) as f:
+    settings = json.load(f)
+
+hook_command = "bash ~/.claude/hooks/precompact-save.sh"
+
+# Check if already wired up
+existing = settings.get("hooks", {}).get("PreCompact", [])
+for group in existing:
+    for h in group.get("hooks", []):
+        if h.get("command") == hook_command:
+            print("  PreCompact hook already configured — skipping")
+            sys.exit(0)
+
+# Add it
+if "hooks" not in settings:
+    settings["hooks"] = {}
+if "PreCompact" not in settings["hooks"]:
+    settings["hooks"]["PreCompact"] = []
+settings["hooks"]["PreCompact"].append({
+    "hooks": [{"type": "command", "command": hook_command}]
+})
+
+with open(settings_path, "w") as f:
+    json.dump(settings, f, indent=2)
+    f.write("\n")
+
+print("  Wired PreCompact hook into settings.json")
+EOF
+
 # Copy tech_stack.md template (won't overwrite if exists — user populates this)
 if [ -f "$CLAUDE_DIR/tech_stack.md" ]; then
   echo "  tech_stack.md already exists — skipping"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playbook-ai",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Operating playbook for non-technical founders working with Claude Code",
   "bin": {
     "playbook-ai": "bin/cli.js"

package/settings.json

@@ -2,6 +2,18 @@
   "env": {
     "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
   },
+  "hooks": {
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/precompact-save.sh"
+          }
+        ]
+      }
+    ]
+  },
   "enabledPlugins": {
     "frontend-design@claude-plugins-official": true
   },