playbook-ai 1.2.1 → 1.3.5

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 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.3.5] — 2026-04-28
+
+### Planning
+- **Branch trace in `/plan`** — For high-stakes decisions (architecture choices, irreversible actions, multi-system impact), Phase 1 now traces each option 2-3 moves forward to a labeled terminal state. You compare where each path *lands*, not just how it starts. Gated on decision stakes — fires only when the cost of picking wrong is high. Max 3 branches, 3 moves deep.
+- **Phase reorder: harden before you write** — Phase 2 (stress test) now runs *before* Phase 3 (implementation steps). Assumption audit and risk war-game validate the chosen direction first; steps are written once, correctly, with all risks already surfaced. Eliminates the rework loop of writing steps then discovering a wrong assumption.
+- **Build blockers moved into per-step notation** — Build roadblock scan is now embedded in each implementation step rather than a separate Phase 3 section. Closer to the code that needs it.
+
+## [1.3.4] — 2026-04-23
+
+### Model Routing
+- **Concrete Haiku routing table** — replaces vague "mechanical work" guidance with explicit rules: Haiku for Explore subagents, simple Perplexity lookups, file transforms; Sonnet for Agent team members, research synthesis, and everything else. Prevents the incorrect assumption that "parallel = Haiku."
+
+## [1.3.3] — 2026-04-23
+
+### Model Routing (breaking behavior change)
+- **Sonnet 4.6 is now the default model.** Previous policy said "default to the stronger model" — this caused Claude to pick Opus for most tasks, producing significant unnecessary API spend. Sonnet 4.6 handles the vast majority of real-world work (config, scripts, debugging, research, documentation) at ~1/5 the cost.
+- **Opus 4.6 is the explicit escalation target** (not Opus 4.7, which carries a 1M context premium). Claude must tell you when it escalates and why — you can push back if it's overkill.
+- **Haiku 4.5 added for mechanical subagent work** — grep, simple file reads, lookups, transforms.
+- **`[1m]` context window variants are banned as defaults.** The 1M window doubles input costs — opt in only for sessions that genuinely need giant context.
+- **Cost awareness rule added**: Claude must surface scope before diving into tasks requiring many tool calls, multiple subagents, or a long session.
+
+To complete the switch: add `"model": "claude-sonnet-4-6"` to your `~/.claude/settings.json` (or run `/model sonnet` in any session).
+
+## [1.3.2] — 2026-04-15
+
+### New
+- **Inbox folder** — Every project now supports an `inbox/` drop zone for files you want Claude to read. Added to `.gitignore` by default — nothing in it gets committed.
+- **Awesome Design MD** — Added to README and Guide as a recommended design reference. 60+ brand design systems (Apple, Stripe, Linear, Notion, etc.) in DESIGN.md format Claude reads directly. Pairs with the Frontend Design plugin. Install with `npx getdesign@latest add <brand>`.
+
+### Guide
+- **"Let Claude organize your research"** — New ops tip: dump raw material into inbox/, tell Claude what you need, let it synthesize. You don't have to pre-organize anything.
+- **"Match your UI to a brand you admire"** — New ops tip: use Awesome Design MD to make any interface look like a real product.
+
+## [1.3.1] — 2026-04-15
+
+### Improvements
+- **`/plan` stress test phase** — Plans now include an automatic Phase 3 that pressure-tests the plan before presenting it for approval. Validates assumptions against actual code/docs, war-games risks with mitigations, and scans for build roadblocks. Scales depth to plan complexity — lightweight for simple changes, thorough for multi-system features. No more manually asking Claude to "validate your assumptions."
+
+## [1.3.0] — 2026-03-30
+
+### Plugins
+- **Frontend Design** — installed by default for all users. Generates distinctive, production-grade frontend interfaces with bold typography, unique color palettes, and creative layouts. No opt-in needed.
+- **Code Review Agents** — recommended plugin for PR-based workflows. Automated multi-agent code review with confidence-based scoring. Install with `/plugin install code-review@claude-plugins-official`.
+
+### Model Routing
+- **Task-complexity model selection** — Claude now chooses which model to use based on task complexity, not role. Defaults to the stronger model; only drops to lighter models for genuinely mechanical work. Replaces the rigid "Opus for lead, Sonnet for teammates" rule.
+
+### New MCP Server
+- **Context7** — added to recommended MCP servers. Pulls version-specific, up-to-date library documentation directly into Claude's context. Solves stale-docs problems when working with external libraries.
+
+### Infrastructure
+- **`install.sh` installs plugins** — the installer now automatically installs the Frontend Design plugin during setup.
+- **`settings.json` includes `enabledPlugins`** — Frontend Design is pre-enabled in the default settings template.
+
 ## [1.2.1] — 2026-03-15
 
 ### Improvements

package/CLAUDE.md

@@ -58,7 +58,7 @@
 - **Don't propose teams for**: single-file changes, sequential tasks, same-file edits, or when on a tight token budget
 - **Do propose teams for**: cross-layer features, large refactors with parallelizable chunks, debugging with multiple hypotheses
 - Claude won't create a team without your approval
-- Prefer Opus for team lead, Sonnet for teammates (cost efficiency)
+- Match model to task complexity (see Model Selection below), not to role
 
 ### Ralph Loop rules
 - **Only use for**: tasks with binary success criteria (tests pass, linter clean, migration complete)
@@ -66,6 +66,17 @@
 - Always set `--max-iterations` to prevent runaway token usage
 - Start conservative (10-20 iterations), increase if needed
 
+### Model Selection
+- **Default to Sonnet 4.6** (`claude-sonnet-4-6`) for all work. It handles config edits, scripts, agent setup, debugging, research, and documentation at ~1/5 the cost of Opus.
+- **Escalate to Opus 4.6** (`claude-opus-4-6`) only when the task clearly demands it: complex architectural decisions, multi-step reasoning across large contexts, financial modeling, or when Sonnet has produced incorrect/insufficient output. Never escalate to Opus 4.7 — 4.6 is the correct escalation target.
+- **Use Haiku 4.5** (`claude-haiku-4-5`) when Claude is the transport layer, not the reasoning layer. Concrete routing:
+  - Haiku: Explore subagents (grep, file discovery, pattern matching), simple Perplexity lookups (find a URL, confirm a version), file transforms, boilerplate from a clear template
+  - Sonnet: everything else — including all Agent team members (they do real implementation), Perplexity research requiring synthesis or comparison, debugging, config, architecture
+- **Never pin aliases or `[1m]` variants.** Always use explicit model IDs. The 1M context window doubles input costs — only opt in for sessions that genuinely need giant context.
+- Model choice is per-task, not per-role. A subagent doing financial analysis escalates to Opus 4.6; a subagent doing a simple grep stays on Haiku.
+- When escalating to Opus, tell the user first in one line ("Escalating to Opus 4.6 because X") so they can push back if it's overkill.
+- **Cost awareness:** If a task will require many tool calls, multiple subagents, or a long session, surface the scope before diving in.
+
 ### Context health
 - **Proactive saves**: In long sessions, save critical state to WORK_LOG.md incrementally — don't wait for `/end`. Decisions, findings, and intermediate results should be written to disk as they happen, so nothing is lost if auto-compaction occurs.
 - **Context health warning**: When context is getting heavy AND substantial work remains, proactively warn you. Save current state to WORK_LOG.md first, then present options: wrap up and `/end`, hand off remaining work via `/handoff`, or start a fresh session. Don't warn if the session is almost done — just finish.
@@ -103,6 +114,10 @@
 - Propose parallel work when independent tasks can run simultaneously
 - Never overlap files/tables/workflows between parallel sessions
 
+## 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.
+
 ## Decision Tracking
 - When making non-trivial architectural or design decisions, save them to `docs/decisions/` in the relevant project repo
 - Format: `YYYY-MM-DD-<topic>.md` (e.g., `2026-03-01-auth-approach.md`)

package/README.md

@@ -14,13 +14,49 @@ Most Claude Code configs are built for developers. This one is built for operato
 | `commands/plan.md` | `/plan` — brainstorm + plan in one command (auto-detects complexity) |
 | `commands/debug.md` | `/debug` — 4-step systematic debugging |
 | `commands/quick.md` | `/quick` — lightweight mode for small fixes |
+| `commands/new-project.md` | `/new-project` — full project setup with guided interview |
 | `commands/handoff.md` | `/handoff` — generates parallel session prompts (Claude invokes this, not you) |
 | `settings.json` | Permission allowlist for common tools |
 | `update.sh` | Handles updates when a new Playbook version is available |
 | `VERSION` | Current Playbook version number |
 | `CHANGELOG.md` | What changed in each version (only impactful updates) |
 
-## Install
+## Prerequisites
+
+Before installing Playbook, you need Claude Code — Anthropic's command-line tool that lets Claude work directly on your computer.
+
+**How is this different from the Claude app?** The Claude chat app (claude.ai) only sees what you paste into it and forgets everything between conversations. Claude Code can see your entire project, run commands, make changes to files, and — with Playbook — pick up exactly where you left off between sessions. It's the difference between texting a contractor photos vs. handing them the keys to the building.
+
+### Mac
+
+1. **Open Terminal** — it's already on your Mac. Press `Cmd + Space`, type "Terminal", and hit Enter.
+2. **Install Claude Code** — paste this into Terminal and press Enter:
+   ```
+   curl -fsSL https://claude.ai/install.sh | bash
+   ```
+   That's it. No other software needed.
+
+### Windows
+
+1. **Install VS Code** — download it free from [code.visualstudio.com](https://code.visualstudio.com)
+2. **Install the Claude Code extension** — open VS Code, click the Extensions icon in the left sidebar, search "Claude Code", and install the official Anthropic extension.
+
+Alternatively, open PowerShell and run:
+```
+irm https://claude.ai/install.ps1 | iex
+```
+
+### Account
+
+You need an Anthropic account with a Claude Pro ($20/month), Max, Teams, or Enterprise subscription. Sign up at [claude.ai](https://claude.ai) if you don't have one.
+
+When you first launch Claude Code, it will open your browser to log in. After that, you're authenticated automatically.
+
+For full details, see [Anthropic's Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code).
+
+---
+
+## Install Playbook
 
 ### Option 1: npm (recommended)
 
@@ -53,9 +89,11 @@ chmod +x install.sh
 
 1. **Edit `~/.claude/CLAUDE.md`** — Replace generic references with your name and preferences
 2. **Set up MCP servers** — Connect your project management tool (ClickUp, Linear, etc.), database, and any other services in `~/.claude.json`
-3. **Create `WORK_LOG.md`** in your project root — this is the cross-session handoff document
+3. **Run `/new-project`** to set up your first project — Claude will interview you and create everything you need
 4. **Run `/start`** in Claude Code to verify everything works
 
+**New to all of this?** Read the [Beginner's Guide](GUIDE.md) — a plain-English walkthrough of how to use Claude Code and Playbook, with examples.
+
 ## Updates
 
 Playbook checks for updates automatically every time you run `/start`. If a new version is available, you'll see a summary of what's new and can choose to update or skip. No surprises — you're always in control.
@@ -83,6 +121,7 @@ Every session follows a consistent pattern:
 - **`/plan`** — Before complex work. Claude assesses whether brainstorming is needed (multiple approaches? tradeoffs?) and either explores options first or jumps straight to an implementation plan. Always waits for your approval.
 - **`/debug`** — When something is broken. Follows: reproduce, isolate root cause, fix, verify. No guessing.
 - **`/quick`** — For small fixes that don't need the full session ceremony.
+- **`/new-project`** — Sets up a new project from scratch. Claude interviews you — what's the project about, do you have an existing repo or need a new one, do you want to connect a PM tool? Then it creates the repo, wires your terminal shortcut, and generates a comprehensive CLAUDE.md (the rules file) based on what it learned about your project and how you want to work. One command, everything ready.
 - **`/handoff`** — Claude uses this (not you) when a task should run in a separate terminal with fresh context.
 
 ### Context management
@@ -92,6 +131,28 @@ Claude proactively manages session quality:
 - Uses subagents for parallel work automatically
 - Generates parallel session prompts when a fresh context would produce better results
 
+### What is a project?
+
+A **project** is a folder on your computer where Playbook keeps everything organized. Each project is a self-contained hub — it has its own rules (CLAUDE.md), session history (WORK_LOG.md), and file drop zone (inbox/).
+
+A project can hold multiple areas of work. For example, a small business might have one project with separate folders inside it for store setup, inventory management, and marketing automations. A corporate team might use one project per department. It's up to you — whatever makes sense for how you organize your work.
+
+Inside a project, Claude organizes work into folders as the scope grows:
+
+```
+my-business/
+├── store-setup/         — e-commerce configuration
+├── inventory/           — stock tracking and reconciliation
+├── automations/         — email workflows, notifications
+├── docs/decisions/      — architectural and business decisions
+├── CLAUDE.md            — project rules (Claude reads this every session)
+└── WORK_LOG.md          — session history and handoff notes
+```
+
+**Important:** context and connected data sources (databases, PM tools, etc.) are shared within a project but **isolated between projects**. Claude won't accidentally mix up information from different projects unless you explicitly tell it to. This is by design — it keeps your work clean and separated.
+
+**You don't need GitHub.** Projects can live entirely on your computer as local folders. GitHub is optional — useful for backup and collaboration, but not required to get started. The `/new-project` command gives you the choice.
+
 ## Recommended MCP Servers
 
 MCP (Model Context Protocol) servers give Claude direct access to your tools — no copy-pasting between apps. Install the ones that match your stack:
@@ -106,6 +167,7 @@ MCP (Model Context Protocol) servers give Claude direct access to your tools —
 | **Code Hosting** | [GitHub](https://github.com/github/github-mcp-server) | PRs, issues, code review |
 | **Communication** | [Slack](https://github.com/modelcontextprotocol/servers/tree/main/src/slack), Discord | Read/send messages, monitor channels |
 | **Research** | [Perplexity](https://github.com/ppl-ai/modelcontextprotocol) | Real-time web search, deep research, current best practices |
+| **Library Docs** | [Context7](https://github.com/upstash/context7) | Pulls version-specific, up-to-date documentation for any library directly into Claude's context |
 
 **Authorize broadly, expose everything.** When setting up an MCP server that uses OAuth (like Google Workspace), grant all the scopes/permissions upfront — even for services you don't plan to use immediately. Re-authorizing mid-session requires a browser flow and breaks your workflow. For the Google Workspace CLI specifically, use `-s all --tool-mode compact` to expose every service while keeping the tool list manageable. You can always ask Claude which services are available if you're not sure what's possible.
 
@@ -113,6 +175,41 @@ MCP (Model Context Protocol) servers give Claude direct access to your tools —
 
 MCP servers are configured in `~/.claude.json` (global) or in project-level settings. See [Anthropic's MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for setup instructions.
 
+## Plugins
+
+Claude Code plugins add specialized capabilities on top of Playbook. Playbook includes one default plugin and recommends others you can add based on your workflow.
+
+### Default (installed automatically)
+
+| Plugin | What it does |
+|--------|-------------|
+| **Frontend Design** | Generates distinctive, production-grade frontend interfaces with bold typography, unique color palettes, and creative layouts. You don't need to know you need better UI — this plugin ensures Claude produces polished interfaces by default. |
+
+The Frontend Design plugin is installed automatically by `install.sh`. If you installed via npm or plugin, run this inside Claude Code to add it manually:
+```
+/plugin install frontend-design@claude-plugins-official
+```
+
+### Recommended (opt-in)
+
+| Plugin | What it does | Install |
+|--------|-------------|---------|
+| **Code Review Agents** | Automated PR code review using multiple specialized agents in parallel. Analyzes comments, test coverage, silent failures, type design, code quality, and simplification with confidence-based scoring. Great if your workflow involves PRs (which Playbook encourages). | `/plugin install code-review@claude-plugins-official` |
+
+### Design References
+
+When building UIs — dashboards, internal tools, customer-facing pages — the Frontend Design plugin gives Claude the *skill* to produce quality interfaces. **[Awesome Design MD](https://github.com/VoltAgent/awesome-design-md)** gives it the *reference material* to match a specific brand's look and feel.
+
+It's a collection of 60+ DESIGN.md files capturing real design systems (Apple, Stripe, Linear, Notion, Airbnb, Shopify, and more) — every color, font, spacing value, and component style, in a format Claude can read directly. To add one to your project:
+
+```
+npx getdesign@latest add stripe
+```
+
+This drops a DESIGN.md file into your project. Then just tell Claude "build this to look like Stripe" and it has every design token it needs. Combine with the Frontend Design plugin for best results.
+
+**When to use this:** Any time you're building a UI and want it to look polished and familiar rather than generic. "Make my dashboard look like Linear" or "style this like Apple" becomes a one-liner that actually works.
+
 ## Troubleshooting
 
 **Sessions are slow or timing out?** It might be your connection, not Claude. Install the [Speedtest CLI](https://www.speedtest.net/apps/cli) to rule out network issues:

package/VERSION

@@ -1 +1 @@
-1.2.1
+1.3.5

package/commands/end.md

@@ -12,9 +12,9 @@ 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 25 sessions:
+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:
    - Keep the Overall State / header section intact
-   - Keep the 25 most recent session entries
+   - 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.
 
@@ -46,3 +46,7 @@ Session closeout. Do everything needed so the user can walk away without taking
    - **Action items** — anything that requires action outside of Claude Code
 
 Keep it concise. The goal is zero information loss between sessions.
+
+9. **Sign off.** After everything above is complete, end your response with a clear, unmissable closing line so the user knows the session is fully wrapped — even if they scroll back later:
+
+   > **Session complete. You can close this window.**

package/commands/plan.md

@@ -6,20 +6,41 @@ Read all relevant files first. Then determine:
 - **Is this straightforward?** (One obvious approach, clear requirements) → Skip to Phase 2.
 - **Are there meaningful tradeoffs?** (Multiple approaches, architectural choices, unclear requirements) → Brainstorm first:
   - Present 2-3 approaches with pros/cons in short, scannable sections
+  - **For high-stakes decisions** (architecture choices, irreversible actions, multi-system impact, high cost-of-being-wrong): run a **branch trace** — trace each option forward 2-3 moves to its terminal state. Compare endpoints, not just opening positions:
+    ```
+    Option A → requires X → leads to Y  →  Terminal: [favorable / acceptable / problematic]
+                           → Risk branch: if Z happens instead  →  Terminal: [recovery cost]
+    Option B → ...
+    ```
+    Max 3 branches, max 3 moves deep. Label each terminal state. Recommend based on where each path actually *lands*, not just how it starts.
   - Flag which approach you'd recommend and why
-  - Wait for approval of a direction before proceeding to Phase 2
+  - Wait for approval of a direction before proceeding
   - Save the decision to `docs/decisions/YYYY-MM-DD-<topic>.md` if it's non-trivial
 
-## Phase 2: Implementation Plan
+## Phase 2: Harden the Direction
 
-1. **Scope** — What's in scope, what's NOT. State assumptions.
+Before writing implementation steps, stress-test the chosen direction. Scale depth to complexity — a one-file change gets a quick paragraph, a multi-system feature gets the full treatment.
+
+1. **Assumption audit** — List every assumption the direction makes. Validate each one against actual code, docs, APIs, or data. Flag any that are unverified or risky.
+2. **Risk war-game** — For each meaningful risk:
+   - What specifically fails and what's the blast radius?
+   - How likely is it?
+   - Mitigation: what prevents it, or makes it self-healing?
+   - If it still happens: what's the recovery path?
+
+Fold the results back: drop wrong assumptions and adjust the direction before writing steps. Add a **Risks & Mitigations** summary — a scannable table or bullet list.
+
+## Phase 3: Implementation Steps
+
+Direction is hardened. Write the execution plan once, correctly.
+
+1. **Scope** — What's in scope, what's NOT. State remaining assumptions.
 2. **Steps** — Ordered steps. For each:
    - What file(s) to change
    - What the change does
-   - What could go wrong
+   - Build blockers to anticipate: missing dependencies, version conflicts, permission issues, API limits, edge cases — and how to get past each
    - How to verify it worked
 3. **Dependencies** — What must happen in order vs. can be parallelized.
-4. **Risks** — Highest-risk changes and rollback plan.
 
-Present the plan and WAIT for approval before making any changes.
+Present the hardened plan and WAIT for approval before making any changes.
 Keep it concise — bullet points, not essays.

package/install.sh

@@ -90,6 +90,17 @@ else
   fi
 fi
 
+# --- Install default plugins ---
+if command -v claude &> /dev/null; then
+  echo "  Installing default plugins..."
+  claude plugin install frontend-design@claude-plugins-official --scope user 2>/dev/null && \
+    echo "  Installed plugin: Frontend Design" || \
+    echo "  Could not install Frontend Design plugin (install manually: /plugin install frontend-design@claude-plugins-official)"
+else
+  echo "  Claude Code CLI not found — install Frontend Design plugin manually after setup:"
+  echo "    /plugin install frontend-design@claude-plugins-official"
+fi
+
 # --- Record installed version ---
 if [ -f "$PLAYBOOK_DIR/VERSION" ]; then
   cp "$PLAYBOOK_DIR/VERSION" "$CLAUDE_DIR/.playbook-version"

package/package.json

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

package/settings.json

@@ -2,6 +2,9 @@
   "env": {
     "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
   },
+  "enabledPlugins": {
+    "frontend-design@claude-plugins-official": true
+  },
   "permissions": {
     "allow": [
       "Bash(python3:*)",