playbook-ai 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+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.0.0] — 2026-03-08
+
+### Initial Release
+- **Quarterback model** — Claude proposes, you decide. Every session follows this pattern.
+- **Session commands** — `/start`, `/end`, `/plan`, `/debug`, `/quick`, `/handoff`
+- **Context management** — Automatic state saving, context health warnings, subagent delegation
+- **Verification rules** — Claude must prove changes work, not just say "it should work"
+- **Permission allowlist** — Pre-configured `settings.json` so common commands don't need manual approval
+- **MCP server recommendations** — Curated list of integrations for project management, databases, communication, and more

package/CLAUDE.md

@@ -0,0 +1,79 @@
+# Playbook — Global Rules (All Projects)
+
+> An operating playbook for non-technical founders working with Claude Code.
+> Claude is the quarterback — you're the boss.
+
+## Quarterback Model
+- Claude Code is the **quarterback** — propose plays, execute the plan, surface risks
+- You are the boss — set priorities, approve direction, override when needed
+- Claude should always address you by your first name, never "User" or "Coach"
+
+## Session Discipline
+1. **Start every session** by reading `WORK_LOG.md` and `CLAUDE.md` in the current project
+2. **Update `WORK_LOG.md` at the end of every turn where changes are made** — current status, what was done, what remains. Most recent entries at top
+3. `README.md` is a **static setup guide** — never modify it for session-specific progress
+4. **One feature/task per session** unless you say otherwise — no sprawl
+
+## Session Naming
+- On `/start`, **before the briefing**, prompt the user to name the session: `Copy/paste to name this session:` followed by `/rename <project>` in a code block (directory basename)
+- **Wait for the user to respond** before presenting the briefing. Do not include both in the same message.
+
+## Project Management Integration
+- Your PM tool (ClickUp, Linear, Notion, Jira, etc.) is the **source of truth for task priorities** when available
+- Each project should have a corresponding PM project/board
+- Check PM tool at session start for open/in-progress tasks
+- Update task status as work progresses (if MCP is connected)
+- When bugs, gaps, or future work items are identified, create tasks immediately — don't wait to be asked
+
+## Development Rules
+- **Plan before multi-file changes** — use `/plan` to structure the approach, get approval, then execute
+- **Commit frequently** with clear, descriptive messages
+- **Never push to main** — work on feature branches, PR to main
+- **Never guess at data structures** — read the source first (schema, API docs, existing code)
+- **Complete code only** — full, working blocks, never patches or fragments
+
+## Parallel Work & Context Management
+
+### Hierarchy (use the lightest option that works)
+1. **Keep working in main thread** — default for most tasks
+2. **Subagent (automatic)** — for parallel research, exploration, independent sub-tasks within the same topic. You don't need to do anything.
+3. **Parallel session via `/handoff` (manual)** — for substantial independent work that needs a fresh context window. You open a new terminal, paste a prompt, and report back. Use only when: the task is too large for a subagent, the main session's context is degraded, or the work needs its own lifecycle. Must have material positive impact — don't over-trigger.
+
+### Subagent rules
+- **Don't use subagents for**: simple file reads, single-file edits, tasks that need back-and-forth with you
+- **Always return results** — subagent output isn't visible to you unless Claude summarizes it
+
+### 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.
+
+## Verification
+- **Never declare a task complete without independent verification.** After making a change:
+  - Re-run the relevant query, workflow, or test
+  - Confirm the output matches expectations
+  - Check for regressions in related functionality
+- "It should work" is not verification. Show the evidence.
+
+## Research Integration
+- If a Perplexity MCP is connected, use it to ground planning and decision-making in current data
+- **Use web research when**: evaluating external tools/services, researching current best practices, market/competitive analysis, or when information may be beyond Claude's training cutoff
+- **Don't use web research when**: working with your own codebase, debugging, querying your databases, or tasks where internal context is sufficient
+- **During `/plan` Phase 1 (brainstorming)**: use research tools to ground options in current data when evaluating external tools or approaches
+- **Transparency**: Always tell the user when using web research — say so before the call, and clearly distinguish what came from live web data vs. existing knowledge in the response
+- **Recency discipline**: Perplexity's base LLM may have stale training data, but its value is **live web search**. If a research response includes caveats about training data cutoff or says "verify current status," that means the search didn't return current results. **Immediately follow up** with targeted searches using recency filters to get actual current data. Never present stale results without first attempting to get fresher data.
+
+## Tool Integration
+- When a manual task is performed repeatedly (copy-pasting between apps, checking status in external tools, triggering actions manually), proactively suggest connecting the tool as an MCP server to eliminate the manual step
+- Frame the suggestion with the time/effort saved vs. setup cost
+
+## Code Quality
+- No fabricated data in production — 100% accuracy
+- Propose parallel work when independent tasks can run simultaneously
+- Never overlap files/tables/workflows between parallel sessions
+
+## 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`)
+- Include: context, options considered, decision made, and reasoning
+- Reference from WORK_LOG.md but don't bury decisions in session logs
+- Only for decisions that future sessions need to understand — don't over-document

package/README.md

@@ -0,0 +1,127 @@
+# Playbook
+
+An operating playbook for non-technical founders working with Claude Code.
+
+Most Claude Code configs are built for developers. This one is built for operators — people who use Claude as their technical co-founder to build and run products without writing code themselves.
+
+## What's included
+
+| File | What it does |
+|------|-------------|
+| `CLAUDE.md` | Core rules: quarterback model, session discipline, verification, context management |
+| `commands/start.md` | `/start` — session kickoff with project briefing |
+| `commands/end.md` | `/end` — session closeout with handoff documentation |
+| `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/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
+
+### Option 1: npm (recommended)
+
+```bash
+npx playbook-ai install
+```
+
+That's it. Works without installing anything globally.
+
+### Option 2: Plugin
+
+```bash
+/plugin install playbook
+```
+
+Run this inside Claude Code. The plugin gives you the same commands as skills (`/playbook:start`, `/playbook:end`, etc.) and includes a SessionStart hook that kicks off your session automatically.
+
+### Option 3: Manual (git clone)
+
+```bash
+git clone https://github.com/bluemax713/playbook.git
+cd playbook
+chmod +x install.sh
+./install.sh
+```
+
+> **Don't have git?** Download the [latest release](https://github.com/bluemax713/playbook/archive/refs/heads/main.zip), unzip it, and run `./install.sh` from the folder. Updates will still work — they'll use direct downloads instead of git.
+
+## After installing
+
+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
+4. **Run `/start`** in Claude Code to verify everything works
+
+## 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.
+
+**Your customizations are always safe.** Updates will never delete or overwrite anything you've personalized:
+
+- **Commands** update automatically (they're standard across all users)
+- **`CLAUDE.md`** is never touched without your explicit permission — if the new version has changes, you choose: keep yours, use the new Playbook version, or let Claude merge both together while preserving your customizations
+- **`settings.json`** keeps your existing permissions intact — new ones are suggested for your approval, never forced
+
+Everything is transparent. Check `settings.json` to see exactly what's auto-approved. The Playbook source is [open on GitHub](https://github.com/bluemax713/playbook) — every command, every permission, and every update mechanism is visible.
+
+## How it works
+
+### The quarterback model
+Claude proposes plays, you call the shots. Claude will always present options and wait for your approval before making changes. You set priorities, Claude executes.
+
+### Session lifecycle
+Every session follows a consistent pattern:
+- `/start` — Claude reads context, checks your PM tool, presents a briefing
+- Work happens — one feature/task per session to prevent sprawl
+- `/end` — Claude updates documentation, cleans up, commits, and presents a summary
+
+### Commands
+- **`/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.
+- **`/handoff`** — Claude uses this (not you) when a task should run in a separate terminal with fresh context.
+
+### Context management
+Claude proactively manages session quality:
+- Saves state incrementally during long sessions (not just at the end)
+- Warns you when context is getting heavy and suggests strategies
+- Uses subagents for parallel work automatically
+- Generates parallel session prompts when a fresh context would produce better results
+
+## 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:
+
+| Category | MCP Server | What it does |
+|----------|-----------|-------------|
+| **Google Workspace** | [Google Workspace CLI](https://github.com/googleworkspace/cli) | Gmail, Drive, Calendar, Docs, Sheets, Chat, Admin — one MCP for all Google services |
+| **Project Management** | [ClickUp](https://mcp.clickup.com), [Linear](https://github.com/linear/linear-mcp), Notion | Read/update tasks, check priorities, create issues |
+| **Database** | [Supabase](https://mcp.supabase.com), Neon, PlanetScale | Run queries, apply migrations, inspect schema |
+| **Analytics** | [Metabase](https://github.com/easecloudio/mcp-metabase-server), Posthog | Query dashboards, pull metrics |
+| **Automation** | [n8n](https://github.com/leonardsellem/n8n-mcp-server), Make, Zapier | Read/update workflows, check execution logs |
+| **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 |
+
+**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.
+
+**The rule of thumb:** If you find yourself repeatedly switching to another app to copy data, check status, or trigger an action — that's a sign you should connect it as an MCP server. Tell Claude "I keep having to manually check X in Y tool" and it will help you evaluate whether an MCP connection would save time.
+
+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.
+
+## Customizing
+
+This playbook is a starting point. Customize `CLAUDE.md` to fit your workflow:
+- Add tool-specific sections (database, CI/CD, deployment platforms)
+- Add project-specific rules in project-level `CLAUDE.md` files
+- Add new commands in `~/.claude/commands/` for your recurring workflows
+
+**Tip:** You don't need to do any of this manually. Just tell Claude what you want — "set up the Slack MCP server," "add a rule about always running tests," "create a new command for deployments" — and Claude will handle the file edits and configuration for you. Or even just ask Claude, after installing this Playbook, to "/plan review README.md and walk me through everything."
+
+## License
+
+MIT

package/VERSION

@@ -0,0 +1 @@
+1.0.0

package/bin/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util';
+import { install } from '../lib/installer.js';
+
+const USAGE = `
+playbook-ai — Operating playbook for non-technical founders working with Claude Code
+
+Usage:
+  npx playbook-ai install    Install the playbook to ~/.claude/
+  npx playbook-ai --help     Show this help message
+
+Learn more: https://github.com/bluemax713/playbook
+`.trim();
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    help: { type: 'boolean', short: 'h' },
+  },
+});
+
+const command = positionals[0];
+
+if (values.help || !command) {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+if (command === 'install') {
+  await install();
+} else {
+  console.error(`Unknown command: ${command}\n`);
+  console.log(USAGE);
+  process.exit(1);
+}

package/commands/debug.md

@@ -0,0 +1,14 @@
+Follow this systematic debugging process:
+
+1. **Reproduce** — Confirm the bug exists. Get the exact error, query, or behavior. Don't guess.
+2. **Isolate** — Narrow down the root cause:
+   - What changed recently? (Check WORK_LOG.md, recent commits, recent deployments)
+   - Where in the pipeline does it fail?
+   - What does the data actually look like? (Query the source directly)
+3. **Fix** — Apply the minimal fix. Don't refactor surrounding code.
+4. **Verify** — Independently confirm the fix works:
+   - Re-run the failing query/workflow
+   - Check the output matches expectations
+   - Confirm no regressions in related functionality
+
+Report findings at each step. Don't skip to step 3.

package/commands/end.md

@@ -0,0 +1,37 @@
+Session closeout. Do everything needed so the user can walk away without taking notes or remembering anything. The next `/start` must pick up seamlessly.
+
+## Steps
+
+1. **Review what was done this session.** Look at all changes made, files edited, commits created, and conversations had. Don't miss anything.
+
+2. **Update WORK_LOG.md.** This is the critical handoff document.
+   - Update "Last updated" date
+   - Update "Overall State" headline if it changed
+   - Add numbered entries under "Recent Changes (this session)" for everything done — be specific (file names, node counts, what changed and why)
+   - Update "Workflow Status" or equivalent current-state section to reflect reality
+   - 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. **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.
+
+4. **Cleanup** — remove temporary artifacts:
+   - Delete `HANDOFF_RESULT.md` if it exists in the project root
+   - Remove any other temp files created during the session (scratch scripts, debug output, etc.)
+   - Do NOT delete docs/decisions/ files — those are permanent
+
+5. **Pre-commit checklist** — before committing, verify:
+   - All changes tested/verified (not just "should work" — show evidence)
+   - No hardcoded secrets, tokens, or credentials in code
+   - No uncommitted changes left behind accidentally
+   - No temp files being committed
+   - Branch pushed to origin
+
+6. **Commit and push.** Stage all changed files, commit with a clear message summarizing the session's work, and push to remote. Do NOT commit .env or credentials.
+
+7. **Present the closeout summary:**
+   - **Done this session** — bullet list of completed work
+   - **Left in progress** — anything partially done and where it stands
+   - **Next session priorities** — what `/start` will surface as the top items
+   - **Action items** — anything that requires action outside of Claude Code
+
+Keep it concise. The goal is zero information loss between sessions.

package/commands/handoff.md

@@ -0,0 +1,41 @@
+This command is for CLAUDE to invoke, never the user. Generate a parallel session prompt when a task should run in a separate Claude Code terminal with fresh context.
+
+## When to use this
+
+Only when ALL of these are true:
+- The task is substantial enough to benefit from a fresh context window
+- The task is independent from the main session's current work
+- Continuing in the main session would materially degrade output quality
+- A subagent within this session can't handle it (too large, needs its own lifecycle)
+
+Do NOT use when:
+- The session is almost done anyway
+- A subagent would suffice
+- The overhead of context-switching outweighs the benefit
+
+## What to generate
+
+Create a complete, self-contained prompt block to paste into a new Claude Code terminal. The block must include:
+
+1. **Context** — Everything the new session needs to know. No assumptions about shared state. Include specific file paths, IDs, table names, and any decisions already made.
+2. **Task** — Clear, specific instructions for what to do.
+3. **Embedded commands** — If the new session should /plan first, say so explicitly in the prompt.
+4. **Output instructions** — Tell the new session to:
+   - Save all artifacts to files (not just terminal output)
+   - Write a brief summary to `HANDOFF_RESULT.md` in the project root: what was done, what files changed, any decisions made
+   - Do NOT run /end — no WORK_LOG update, no PM tool update, no commit. Just do the work and stop.
+   - The user will close the terminal when done.
+
+## Format for the user
+
+Present the prompt in a single code block that can be copy-pasted. Preface it with:
+- One sentence explaining what the parallel session will do
+- "Open a new Claude Code terminal and paste the block below. When it's done, come back here and tell me 'parallel done.'"
+
+## After return
+
+When the user says the parallel session is done:
+1. Read `HANDOFF_RESULT.md` from the project root
+2. Integrate the results into the main session's work
+3. Delete `HANDOFF_RESULT.md` (cleanup)
+4. Continue with the main session's work

package/commands/plan.md

@@ -0,0 +1,25 @@
+Before making any changes, assess the task and create a structured plan.
+
+## Phase 1: Assess Complexity
+
+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
+  - Flag which approach you'd recommend and why
+  - Wait for approval of a direction before proceeding to Phase 2
+  - Save the decision to `docs/decisions/YYYY-MM-DD-<topic>.md` if it's non-trivial
+
+## Phase 2: Implementation Plan
+
+1. **Scope** — What's in scope, what's NOT. State assumptions.
+2. **Steps** — Ordered steps. For each:
+   - What file(s) to change
+   - What the change does
+   - What could go wrong
+   - 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.
+Keep it concise — bullet points, not essays.

package/commands/quick.md

@@ -0,0 +1,10 @@
+Quick mode — for bug fixes, small changes, and one-off tasks that don't need full session ceremony.
+
+Skip the full /start briefing. Instead:
+1. Read CLAUDE.md (for rules) and the last WORK_LOG.md entry (for context) — don't present a briefing.
+2. Do the task.
+3. Update WORK_LOG.md with a brief entry (2-3 lines under a "Quick fix" sub-header of today's date).
+4. Commit with a clear message.
+5. If the fix reveals a bigger issue, flag it and suggest creating a task — don't scope-creep.
+
+Do NOT skip: task creation if a bug/gap is discovered. Do NOT skip: committing changes.

package/commands/start.md

@@ -0,0 +1,71 @@
+Read CLAUDE.md and WORK_LOG.md to understand the project and where we left off.
+
+Check your project management tool via MCP (if available) for current task priorities. If not connected, skip this step and rely on WORK_LOG.md.
+
+Check your auto-memory files for any relevant context from prior sessions.
+
+## Step 0: Check for Playbook Updates
+
+Before anything else, silently check if a newer version of Playbook is available. This must not slow down the session or require user interaction unless there's actually an update.
+
+### 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`.
+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.
+   - **If both fail:** Skip the update check entirely. Do not mention it to the user. Continue with the normal briefing.
+4. Compare the installed version with the latest version. If they match, skip to the normal briefing.
+
+### If an update is available
+
+1. Fetch the CHANGELOG.md content between the installed version and the latest:
+   - Via git: `git -C ~/.claude/.playbook show origin/main:CHANGELOG.md`
+   - Via curl: `curl -sf https://raw.githubusercontent.com/bluemax713/playbook/main/CHANGELOG.md`
+2. Extract only the entries NEWER than the user's installed version. Do not show the entry for their current version.
+3. Present to the user:
+
+   > **Playbook vX.Y.Z is available** (you have vA.B.C). Here's what's new:
+   >
+   > [Relevant changelog entries]
+   >
+   > Would you like to update?
+
+4. **If the user says yes:**
+   - Run `bash ~/.claude/.playbook/update.sh` (if git is available in the playbook dir) or fetch updated files via curl and run the update.
+   - After update.sh completes, check if CLAUDE.md has changed between versions:
+     - Via git: `git -C ~/.claude/.playbook diff vA.B.C..origin/main -- CLAUDE.md` (or compare the files directly)
+     - Or: compare `~/.claude/CLAUDE.md` with `~/.claude/.playbook/CLAUDE.md`
+   - If CLAUDE.md has NOT changed upstream: done, continue to briefing.
+   - If CLAUDE.md HAS changed upstream, tell the user what changed (summarize the differences in plain language), then offer three choices:
+     1. **Keep mine** — no changes to your CLAUDE.md
+     2. **Use Playbook** — replace your CLAUDE.md with the new Playbook version
+     3. **Merge** — I'll combine your customizations with the new Playbook changes into one file. I'll show you the result before saving.
+   - If the user picks **Merge**: read both files, produce a merged version that preserves user customizations while incorporating new upstream content, show it to the user for approval, and only write it after they confirm.
+
+   After any new settings.json permissions are available in the updated Playbook, check if the user's `~/.claude/settings.json` is missing any permissions from the Playbook version. If so, mention: "The new version includes some additional pre-approved permissions: [list them briefly]. Want me to add these to your settings?" Only add with user approval.
+
+5. **If the user says no (skip the update):** Continue with the normal briefing. Do not mention the update again during this session.
+
+---
+
+## Normal Briefing
+
+Present a concise briefing:
+- **Where we left off** — last session's work (from WORK_LOG.md)
+- **Current status** — what's working, what's not
+- **Known issues** — bugs, blockers, pending items
+- **PM tasks** — open/in-progress tasks if PM tool is available
+- **Suggested next steps** — prioritized list of what to tackle, flagging anything that needs a decision
+
+Keep it short and scannable. Bullet points. No fluff. Wait for direction before making changes.
+
+## Session Naming
+
+**Before the briefing**, prompt the user to name the session. Output only this — nothing else:
+
+> Copy/paste to name this session:
+> `/rename <project>`
+
+Where `<project>` is the current directory's basename (e.g., `playbook`). Then **wait for the user to respond** before presenting the briefing. Do not include the briefing in the same message.

package/install.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# Playbook Installer — Claude Code Operating Playbook
+# Copies config files into ~/.claude/ for Claude Code to use.
+# Also sets up the local Playbook source for automatic updates.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLAUDE_DIR="$HOME/.claude"
+COMMANDS_DIR="$CLAUDE_DIR/commands"
+PLAYBOOK_DIR="$CLAUDE_DIR/.playbook"
+REPO_URL="https://github.com/bluemax713/playbook.git"
+
+echo "Installing Playbook into $CLAUDE_DIR..."
+
+# Create directories if they don't exist
+mkdir -p "$COMMANDS_DIR"
+
+# --- Set up Playbook source for updates ---
+
+# Determine if we're running from a git repo
+IS_GIT_REPO=false
+if [ -d "$SCRIPT_DIR/.git" ] || git -C "$SCRIPT_DIR" rev-parse --git-dir > /dev/null 2>&1; then
+  IS_GIT_REPO=true
+fi
+
+if [ "$IS_GIT_REPO" = true ]; then
+  # Running from a git clone — copy the repo to the standard location
+  if [ "$SCRIPT_DIR" != "$PLAYBOOK_DIR" ]; then
+    if [ -d "$PLAYBOOK_DIR" ]; then
+      echo "  Updating Playbook source at $PLAYBOOK_DIR..."
+      rm -rf "$PLAYBOOK_DIR"
+    fi
+    cp -R "$SCRIPT_DIR" "$PLAYBOOK_DIR"
+    echo "  Playbook source saved to $PLAYBOOK_DIR"
+  else
+    echo "  Already running from $PLAYBOOK_DIR"
+  fi
+else
+  # Not a git repo (downloaded zip, curl, etc.) — try to clone fresh
+  if command -v git &> /dev/null; then
+    echo "  Cloning Playbook repo for update support..."
+    if [ -d "$PLAYBOOK_DIR" ]; then
+      rm -rf "$PLAYBOOK_DIR"
+    fi
+    git clone --quiet "$REPO_URL" "$PLAYBOOK_DIR"
+    echo "  Playbook source cloned to $PLAYBOOK_DIR"
+  else
+    # No git available — copy what we have, updates will use curl
+    if [ -d "$PLAYBOOK_DIR" ]; then
+      rm -rf "$PLAYBOOK_DIR"
+    fi
+    cp -R "$SCRIPT_DIR" "$PLAYBOOK_DIR"
+    echo "  Playbook source saved to $PLAYBOOK_DIR (install git for easier updates)"
+  fi
+fi
+
+# --- Install files ---
+
+# Copy CLAUDE.md (won't overwrite if exists — user might have customized it)
+if [ -f "$CLAUDE_DIR/CLAUDE.md" ]; then
+  echo "  CLAUDE.md already exists — skipping (back up yours first if you want to replace it)"
+else
+  cp "$PLAYBOOK_DIR/CLAUDE.md" "$CLAUDE_DIR/CLAUDE.md"
+  echo "  Installed CLAUDE.md"
+fi
+
+# Copy commands (will overwrite — commands are meant to be standard)
+for cmd in "$PLAYBOOK_DIR/commands/"*.md; do
+  filename=$(basename "$cmd")
+  cp "$cmd" "$COMMANDS_DIR/$filename"
+  echo "  Installed command: /${filename%.md}"
+done
+
+# Copy settings.json (won't overwrite if exists — user might have custom permissions)
+if [ -f "$CLAUDE_DIR/settings.json" ]; then
+  echo "  settings.json already exists — skipping (review playbook/settings.json to merge permissions)"
+else
+  cp "$PLAYBOOK_DIR/settings.json" "$CLAUDE_DIR/settings.json"
+  echo "  Installed settings.json"
+fi
+
+# --- Record installed version ---
+if [ -f "$PLAYBOOK_DIR/VERSION" ]; then
+  cp "$PLAYBOOK_DIR/VERSION" "$CLAUDE_DIR/.playbook-version"
+  echo "  Version $(cat "$CLAUDE_DIR/.playbook-version" | tr -d '\n') installed"
+else
+  echo "1.0.0" > "$CLAUDE_DIR/.playbook-version"
+  echo "  Version 1.0.0 installed"
+fi
+
+echo ""
+echo "Done! Restart Claude Code to pick up the new config."
+echo ""
+echo "Next steps:"
+echo "  1. Edit ~/.claude/CLAUDE.md to add your name (replace 'you/your' with your preferences)"
+echo "  2. Set up your MCP servers in ~/.claude.json (project management, database, etc.)"
+echo "  3. Create a WORK_LOG.md in your project root"
+echo "  4. Run /start in Claude Code to verify everything works"
+echo ""
+echo "Playbook will automatically check for updates when you run /start."

package/lib/installer.js

@@ -0,0 +1,124 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+const COMMANDS_DIR = path.join(CLAUDE_DIR, 'commands');
+const PLAYBOOK_DIR = path.join(CLAUDE_DIR, '.playbook');
+
+// Files to copy into .playbook/ for the update mechanism
+const PLAYBOOK_SOURCE_FILES = [
+  'CLAUDE.md',
+  'settings.json',
+  'install.sh',
+  'update.sh',
+  'VERSION',
+  'CHANGELOG.md',
+];
+
+export async function install() {
+  console.log(`Installing Playbook into ${CLAUDE_DIR}...`);
+
+  // Create directories
+  await fs.mkdir(COMMANDS_DIR, { recursive: true });
+  await fs.mkdir(PLAYBOOK_DIR, { recursive: true });
+
+  const summary = { installed: [], skipped: [] };
+
+  // --- Install CLAUDE.md ---
+  const claudeMdDest = path.join(CLAUDE_DIR, 'CLAUDE.md');
+  if (await fileExists(claudeMdDest)) {
+    summary.skipped.push('CLAUDE.md (already exists)');
+  } else {
+    await fs.copyFile(path.join(PACKAGE_ROOT, 'CLAUDE.md'), claudeMdDest);
+    summary.installed.push('CLAUDE.md');
+  }
+
+  // --- Install commands (always overwrite) ---
+  const commandsSource = path.join(PACKAGE_ROOT, 'commands');
+  const commandFiles = await fs.readdir(commandsSource);
+  for (const file of commandFiles) {
+    if (!file.endsWith('.md')) continue;
+    await fs.copyFile(
+      path.join(commandsSource, file),
+      path.join(COMMANDS_DIR, file)
+    );
+    const commandName = file.replace(/\.md$/, '');
+    summary.installed.push(`command: /${commandName}`);
+  }
+
+  // --- Install settings.json ---
+  const settingsDest = path.join(CLAUDE_DIR, 'settings.json');
+  if (await fileExists(settingsDest)) {
+    summary.skipped.push('settings.json (already exists)');
+  } else {
+    await fs.copyFile(path.join(PACKAGE_ROOT, 'settings.json'), settingsDest);
+    summary.installed.push('settings.json');
+  }
+
+  // --- Set up .playbook/ source for auto-updates ---
+  // Copy individual files
+  for (const file of PLAYBOOK_SOURCE_FILES) {
+    const src = path.join(PACKAGE_ROOT, file);
+    if (await fileExists(src)) {
+      await fs.copyFile(src, path.join(PLAYBOOK_DIR, file));
+    }
+  }
+
+  // Copy commands/ directory into .playbook/commands/
+  const playbookCommandsDir = path.join(PLAYBOOK_DIR, 'commands');
+  await fs.mkdir(playbookCommandsDir, { recursive: true });
+  for (const file of commandFiles) {
+    if (!file.endsWith('.md')) continue;
+    await fs.copyFile(
+      path.join(commandsSource, file),
+      path.join(playbookCommandsDir, file)
+    );
+  }
+
+  // --- Write version ---
+  const versionFile = path.join(PACKAGE_ROOT, 'VERSION');
+  let version = '1.0.0';
+  if (await fileExists(versionFile)) {
+    version = (await fs.readFile(versionFile, 'utf-8')).trim();
+  }
+  await fs.writeFile(path.join(CLAUDE_DIR, '.playbook-version'), version + '\n');
+
+  // --- Print summary ---
+  console.log('');
+  if (summary.installed.length > 0) {
+    console.log('Installed:');
+    for (const item of summary.installed) {
+      console.log(`  + ${item}`);
+    }
+  }
+  if (summary.skipped.length > 0) {
+    console.log('Skipped:');
+    for (const item of summary.skipped) {
+      console.log(`  - ${item}`);
+    }
+  }
+
+  console.log(`\nVersion ${version} installed.`);
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Open ~/.claude/CLAUDE.md and replace "you" with your name');
+  console.log('  2. Create a WORK_LOG.md in your project root');
+  console.log('  3. Run /start in Claude Code');
+  console.log('');
+  console.log('Playbook will automatically check for updates when you run /start.');
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "playbook-ai",
+  "version": "1.0.0",
+  "description": "Operating playbook for non-technical founders working with Claude Code",
+  "bin": {
+    "playbook-ai": "bin/cli.js"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "lib/",
+    "commands/",
+    "CLAUDE.md",
+    "settings.json",
+    "install.sh",
+    "update.sh",
+    "VERSION",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "playbook",
+    "ai",
+    "operations"
+  ],
+  "author": "Max Assoulin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bluemax713/playbook.git"
+  },
+  "homepage": "https://github.com/bluemax713/playbook",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/settings.json

@@ -0,0 +1,70 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3:*)",
+      "Bash(python:*)",
+      "Bash(node:*)",
+      "Bash(npm install*)",
+      "Bash(npm run*)",
+      "Bash(npm test*)",
+      "Bash(npm list*)",
+      "Bash(npm info*)",
+      "Bash(pip install*)",
+      "Bash(pip list*)",
+      "Bash(pip show*)",
+      "Bash(pip freeze*)",
+      "Bash(pytest:*)",
+      "Bash(uv:*)",
+      "Bash(cat:*)",
+      "Bash(ls:*)",
+      "Bash(pwd)",
+      "Bash(which:*)",
+      "Bash(echo:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(wc:*)",
+      "Bash(grep:*)",
+      "Bash(rg:*)",
+      "Bash(find:*)",
+      "Bash(tree:*)",
+      "Bash(diff:*)",
+      "Bash(jq:*)",
+      "Bash(mkdir:*)",
+      "Bash(touch:*)",
+      "Bash(cp:*)",
+      "Bash(mv:*)",
+      "Bash(curl:*)",
+      "Bash(date*)",
+      "Bash(whoami*)",
+      "Bash(hostname*)",
+      "Bash(env*)",
+      "Bash(npx:*)",
+      "Bash(bun:*)",
+      "Bash(bunx:*)",
+      "Bash(git status*)",
+      "Bash(git log*)",
+      "Bash(git diff*)",
+      "Bash(git show*)",
+      "Bash(git branch*)",
+      "Bash(git rev-parse*)",
+      "Bash(git fetch*)",
+      "Bash(git stash*)",
+      "Bash(git add*)",
+      "Bash(git commit*)",
+      "Bash(git checkout*)",
+      "Bash(git switch*)",
+      "Bash(git pull*)",
+      "Bash(git push*)",
+      "Bash(git remote*)",
+      "Bash(git merge*)",
+      "Bash(git rebase*)",
+      "Bash(git clone*)",
+      "Bash(git tag*)",
+      "Bash(git cherry-pick*)",
+      "Bash(git -C ~/.claude/.playbook*)",
+      "Bash(bash ~/.claude/.playbook/update.sh*)",
+      "Bash(chmod +x ~/.claude/.playbook/*)",
+      "Bash(gh:*)"
+    ]
+  }
+}

package/update.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# Playbook Updater — Fetches latest version and updates commands + settings.
+# Called by /start when an update is available and the user approves.
+# CLAUDE.md is NOT touched by this script — Claude handles that interactively.
+
+set -e
+
+CLAUDE_DIR="$HOME/.claude"
+COMMANDS_DIR="$CLAUDE_DIR/commands"
+PLAYBOOK_DIR="$CLAUDE_DIR/.playbook"
+REPO_URL="https://github.com/bluemax713/playbook.git"
+RAW_BASE="https://raw.githubusercontent.com/bluemax713/playbook/main"
+TEMP_DIR="$CLAUDE_DIR/.playbook-update-tmp"
+
+# --- Fetch latest source ---
+
+fetch_via_git() {
+  if [ -d "$PLAYBOOK_DIR/.git" ]; then
+    git -C "$PLAYBOOK_DIR" pull --quiet origin main 2>/dev/null
+    return $?
+  elif command -v git &> /dev/null; then
+    rm -rf "$PLAYBOOK_DIR"
+    git clone --quiet "$REPO_URL" "$PLAYBOOK_DIR" 2>/dev/null
+    return $?
+  fi
+  return 1
+}
+
+fetch_via_curl() {
+  # Download key files individually via GitHub raw content
+  local files=("VERSION" "CHANGELOG.md" "CLAUDE.md" "settings.json" "install.sh" "update.sh")
+  local cmd_files=("start.md" "end.md" "plan.md" "debug.md" "quick.md" "handoff.md")
+
+  mkdir -p "$PLAYBOOK_DIR/commands"
+
+  for f in "${files[@]}"; do
+    curl -sf "$RAW_BASE/$f" -o "$PLAYBOOK_DIR/$f" || return 1
+  done
+
+  for f in "${cmd_files[@]}"; do
+    curl -sf "$RAW_BASE/commands/$f" -o "$PLAYBOOK_DIR/commands/$f" || return 1
+  done
+
+  return 0
+}
+
+echo "Updating Playbook..."
+
+# Try git first, fall back to curl
+if ! fetch_via_git; then
+  if ! fetch_via_curl; then
+    echo "ERROR: Could not fetch updates. Check your internet connection."
+    exit 1
+  fi
+fi
+
+# --- Stage updates in temp directory (atomic) ---
+
+rm -rf "$TEMP_DIR"
+mkdir -p "$TEMP_DIR/commands"
+
+# Copy commands to temp
+for cmd in "$PLAYBOOK_DIR/commands/"*.md; do
+  [ -f "$cmd" ] && cp "$cmd" "$TEMP_DIR/commands/"
+done
+
+# Copy settings.json to temp (will be merged, not overwritten)
+if [ -f "$PLAYBOOK_DIR/settings.json" ]; then
+  cp "$PLAYBOOK_DIR/settings.json" "$TEMP_DIR/settings.json"
+fi
+
+# --- Validate staged files ---
+
+# Check that key files exist in temp
+if [ ! -f "$TEMP_DIR/commands/start.md" ]; then
+  echo "ERROR: Update validation failed — missing start.md. Update aborted."
+  rm -rf "$TEMP_DIR"
+  exit 1
+fi
+
+# --- Apply updates ---
+
+# Commands: overwrite (they're standard)
+for cmd in "$TEMP_DIR/commands/"*.md; do
+  filename=$(basename "$cmd")
+  cp "$cmd" "$COMMANDS_DIR/$filename"
+  echo "  Updated command: /${filename%.md}"
+done
+
+# Settings.json: additive merge
+if [ -f "$TEMP_DIR/settings.json" ] && [ -f "$CLAUDE_DIR/settings.json" ]; then
+  # Use a simple merge strategy: if the user has settings.json, we don't overwrite.
+  # Claude will handle intelligent merging of new permissions in /start if needed.
+  echo "  settings.json: existing file preserved (new permissions will be suggested in /start)"
+elif [ -f "$TEMP_DIR/settings.json" ]; then
+  cp "$TEMP_DIR/settings.json" "$CLAUDE_DIR/settings.json"
+  echo "  Installed settings.json"
+fi
+
+# --- Update version (LAST — only on success) ---
+
+if [ -f "$PLAYBOOK_DIR/VERSION" ]; then
+  cp "$PLAYBOOK_DIR/VERSION" "$CLAUDE_DIR/.playbook-version"
+  echo "  Updated to version $(cat "$CLAUDE_DIR/.playbook-version" | tr -d '\n')"
+fi
+
+# --- Cleanup ---
+
+rm -rf "$TEMP_DIR"
+echo "Update complete."