playbook-ai 1.4.0 → 1.4.2

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.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
+- **`/chess` System Mode** — `/chess` now has two modes. Human Mode is unchanged (parallel Opus 4.6 session, move-tree analysis, adversary modeling). New System Mode handles the case where there's no human adversary but a technical plan needs rigorous stress-testing. System Mode runs inline on Sonnet, enumerates every assumption in the plan, attacks each one, and produces verdicts (✅ / ⚠️ / ❌) plus a minimal list of required changes. Escalates to Opus 4.6 inline (no parallel session) for genuinely complex systems. Pre-flight now routes to three paths: Human Mode, System Mode, or `/plan`.
+
 ## [1.4.0] — 2026-05-01
 
 ### 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.0
+1.4.3

package/commands/chess.md

@@ -1,28 +1,28 @@
-Adversarial strategy analysis — multi-move, opponent-modeled, branch-traced. Runs intake in the primary session (Sonnet), then generates a self-contained handoff prompt for a parallel Opus 4.6 session that does the heavy reasoning.
+Adversarial strategy analysis and technical stress-testing. Two modes: Human Mode (opponent-modeled, branch-traced) for situations with a real adversary; System Mode (assumption-attack, failure-traced) for technical plans with no human counterparty. Intake runs in the primary session (Sonnet). Human Mode generates a parallel Opus 4.6 handoff; System Mode runs inline.
 
 ---
 
-## Pre-flight: Is this a /chess situation?
+## Pre-flight: Route the situation
 
-Before intake, assess the situation. Ask yourself:
+Three routes. Assess before doing anything else.
 
-- Is there a real adversary — a person or party with competing interests and their own move set?
-- Does the outcome depend on what that adversary does in response to your moves?
-- Are the stakes material — money, a key relationship, legal exposure, or a make-or-break decision?
+**Route 1 — Human Mode:** There's a real adversary — a person or party with competing interests and their own move set. The outcome depends on what they do in response to your moves. Stakes are material (money, a key relationship, legal exposure, a make-or-break decision). → Confirm to the user and proceed to Human Mode intake.
 
-**All three yes:** Confirm to the user that /chess is the right call and proceed to intake.
+**Route 2 — System Mode:** No human adversary, but there IS a technical plan, implementation, or system being challenged. The question is: what could break, and how does the system respond to each move? → Confirm to the user and proceed to System Mode intake.
 
-**No real adversary:** Tell the user directly — *"/plan is the right tool here — this is a tradeoffs decision, not a strategic scenario with a counterparty."* Offer to invoke /plan instead.
+**Route 3 — /plan:** No adversary, no system to stress-test. This is a pure tradeoffs decision or planning question. → Tell the user: *"/plan is the right tool here — this is a tradeoffs decision, not a strategic scenario."* Offer to invoke /plan instead.
 
 **Borderline:** Name what makes it ambiguous. Ask the user to confirm before proceeding.
 
-The pre-flight runs on Sonnet. Do not begin intake until the situation is confirmed as a /chess scenario.
+The pre-flight runs on Sonnet. Do not begin intake until the route is confirmed.
 
 ---
 
-## Intake: Build the chess brief
+## Human Mode
 
-Run this in the primary session on Sonnet. Ask these questions conversationally — not as a numbered list. Group related questions naturally. Use follow-ups where the answer is thin. The goal is a complete picture before the chess engine runs, so the parallel session can work without stopping.
+### Intake: Build the chess brief
+
+Run in the primary session on Sonnet. Ask these questions conversationally — not as a numbered list. Group related questions naturally. Use follow-ups where the answer is thin. The goal is a complete picture before the chess engine runs.
 
 **The situation**
 - What is the decision, negotiation, or situation you're navigating?
@@ -53,7 +53,7 @@ Once intake is complete, read the summary back to the user and confirm it's accu
 
 ---
 
-## Generate the handoff prompt
+### Generate the handoff prompt
 
 Compile everything from intake into a self-contained chess brief. Fill in all [BRACKETS] with real values — current date, actual repo path (use the current working directory), and a short topic slug derived from the situation (e.g., `hilldun-negotiation`, `board-vote`, `vendor-renewal`).
 
@@ -65,7 +65,7 @@ Present the completed handoff prompt to the user in a clearly labeled block:
 
 ---
 
-### Handoff prompt (embed verbatim — this is what runs in the parallel session)
+#### Handoff prompt (embed verbatim — this is what runs in the parallel session)
 
 ---
 
@@ -166,3 +166,55 @@ End of handoff prompt.
 After presenting the handoff prompt to the user, say:
 
 > *"Open a new terminal, paste the block above, and watch the chess engine work. When it's done, use the return prompt to bring the debrief back into this session."*
+
+---
+
+## System Mode
+
+### Intake: Build the stress-test brief
+
+If the system, plan, and constraints are already established in the conversation, skip directly to the stress-test. Only ask for information that's genuinely missing.
+
+If context is thin, ask conversationally — not as a numbered list. Use follow-ups where the answer is thin. The goal is a complete picture before the stress-test runs.
+
+**The system**
+- What are you trying to build, fix, or change?
+- What does the current system look like? (components, dependencies, environment, constraints)
+- What's already been decided or built that the plan must work around?
+
+**The plan**
+- What's the sequence of moves you're planning?
+- What outcome are you trying to guarantee?
+- What's an acceptable failure mode vs. an unacceptable one?
+
+Once you have sufficient context, proceed directly — no need to read it back unless something is ambiguous.
+
+---
+
+### System stress-test framework
+
+Default: run inline on Sonnet. Escalate to Opus 4.6 inline (no parallel session) when the system is complex enough that a shallow pass would miss real risks — multiple interacting services, deep dependency chains, complex state machines. Surface your reasoning in chat as you go.
+
+**Step 1 — Map the assumptions**
+
+List every assumption embedded in the plan. These are the places where "this works if..." is implicit. Be exhaustive — surface assumptions about environment, dependencies, timing, state, permissions, behavior under failure. Name them all before attacking any.
+
+**Step 2 — Attack each vector**
+
+Work through the assumption list. For each one:
+- **State the risk:** what breaks if this assumption is wrong?
+- **Reason through the system's response:** how does the environment, dependency, or component actually behave in this case? Trace the actual mechanics, not the happy path.
+- **Verdict:**
+  - ✅ — assumption holds, no change needed
+  - ⚠️ → [specific mitigation] — risk is real but manageable; state the required change
+  - ❌ — plan-breaker; must resolve before building
+
+Don't pad. If an assumption clearly holds, say so and move on. Depth where there's actual risk.
+
+**Step 3 — Surface what changed**
+
+List only the changes the stress-test produced. Not every risk — only the ones with a ⚠️ or ❌ verdict that require action. For each: what changes, and why.
+
+**Step 4 — Ready to build?**
+
+State clearly: the plan is sound as-is / the plan needs these N changes before it's sound. If changes are needed, offer to incorporate them and proceed.

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/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.0",
+  "version": "1.4.2",
   "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
   },