playbook-ai 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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.2.0] — 2026-03-11
+
+### New Commands
+- **`/new-project`** — Automates full project setup: clone or create a repo, wire terminal alias, generate comprehensive CLAUDE.md and WORK_LOG.md, connect PM tool, and make the initial commit. One command to go from zero to working project.
+
+### Context Management
+- **Efficient WORK_LOG reads** — `/start` now reads only the header + most recent session from WORK_LOG.md instead of the full file. Prevents context bloat as your projects accumulate session history.
+- **Auto-trim on `/end`** — WORK_LOG.md is automatically trimmed to 25 sessions on closeout. Older entries are removed (git history preserves them). No manual cleanup needed.
+- **Claude Code version check** — `/start` now checks your Claude Code version and nudges you if you're significantly behind. Non-blocking, single-line heads up.
+
+### Improvements
+- **Tech stack template** — `tech_stack.md` is now installed automatically during setup and updates (if you don't already have one). Tracks your tools and integrations across projects.
+- **`/new-project` in update flow** — The update script now includes the new-project command in its file list.
+
+## [1.1.0] — 2026-03-09
+
+### Parallel Work Upgrades
+- **Agent Teams** — added as Level 3 in the parallel work hierarchy. Claude can now propose or you can request multi-agent teams for cross-layer features, large refactors, and parallel implementation. Enabled via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var in settings.json.
+- **Ralph Loop** — added as Level 4 in the parallel work hierarchy. Autonomous iteration on well-defined tasks using the official `ralph-wiggum` plugin. Walk-away capability for migrations, test coverage, batch refactors.
+- **Updated hierarchy** — 5 levels from lightest to heaviest: main thread → subagents → agent teams → ralph loop → /handoff
+
+### Fixes
+- **`/start` flow** — briefing no longer blocks waiting for `/rename` response. Rename prompt and briefing now appear in the same message.
+
 ## [1.0.0] — 2026-03-08
 
 ### Initial Release

package/CLAUDE.md

@@ -15,8 +15,8 @@
 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.
+- On `/start`, **at the top of the response 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)
+- Include the full briefing in the **same message** below the rename prompt. The user can rename at any time — do not wait for it.
 
 ## Project Management Integration
 - Your PM tool (ClickUp, Linear, Notion, Jira, etc.) is the **source of truth for task priorities** when available
@@ -25,6 +25,15 @@
 - 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
 
+## Tech Stack Awareness
+- **`~/.claude/tech_stack.md` is the global tech stack registry** — check it before recommending new tools, frameworks, or services
+- **Start with what's already in use**, but always evaluate whether it's the best fit. If a new tool is genuinely better for the job, propose the switch — explain what it replaces, why it's better, and what the migration cost is.
+- Consolidation is a tiebreaker, not a constraint. When two options are roughly equal, pick the one already in the stack. When one is clearly better, recommend it regardless.
+- When a new tool is adopted in any project, add it to tech_stack.md immediately
+- When a tool is dropped, move it to the Deprecated section with the reason and date
+- When evaluating options during `/plan`, reference tech_stack.md to see what's already available
+- If the file doesn't exist yet, create it on first tool adoption using the template from the Playbook repo
+
 ## Development Rules
 - **Plan before multi-file changes** — use `/plan` to structure the approach, get approval, then execute
 - **Commit frequently** with clear, descriptive messages
@@ -37,12 +46,26 @@
 ### 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.
+3. **Agent Team (automatic or requested)** — for parallel *implementation* across multiple layers (frontend + backend + tests, multi-component features, competing hypotheses). Claude may propose a team, or you can request one. Each teammate is a full Claude instance with its own context. Higher token cost (~7x) — use only when teammates can work independently on distinct scopes. Requires `"agentTeams": true` in settings.json.
+4. **Ralph Loop (explicit, via plugin)** — for autonomous iteration on well-defined tasks with clear success criteria. Claude works in a continuous loop, seeing its own prior work, until a completion promise is met or max iterations reached. Great for "walk away" tasks: migrations, test coverage, batch refactors. Install: `/plugin install ralph-wiggum@claude-plugins-official`. Invoke: `/ralph-loop "prompt" --max-iterations N --completion-promise "DONE"`. Cancel: `/cancel-ralph`.
+5. **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
 
+### Agent Team rules
+- **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)
+
+### Ralph Loop rules
+- **Only use for**: tasks with binary success criteria (tests pass, linter clean, migration complete)
+- **Never use for**: tasks requiring judgment calls, design decisions, or unclear completion criteria
+- Always set `--max-iterations` to prevent runaway token usage
+- Start conservative (10-20 iterations), increase if needed
+
 ### 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.

package/VERSION

@@ -1 +1 @@
-1.0.0
+1.2.0

package/commands/end.md

@@ -12,23 +12,29 @@ 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. **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.
+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:
+   - Keep the Overall State / header section intact
+   - Keep the 25 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.
 
-4. **Cleanup** — remove temporary artifacts:
+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.
+
+5. **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:
+6. **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. **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:**
+8. **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

package/commands/new-project.md

@@ -0,0 +1,80 @@
+Set up a new project for Claude Code — clone or create a repo, wire all local config, and get ready for `/start`.
+
+## Gather Info
+
+Ask the user (skip anything they already provided):
+1. **Project name** — this becomes the folder name and terminal alias (e.g., `wildflower`)
+2. **Repo situation** — one of:
+   - **Existing GitHub repo** — provide the repo (e.g., `bluemax713/wildflower` or a full URL)
+   - **Create new repo** — public or private? Description?
+   - **No repo yet** — just set up the local folder, wire git later
+3. **PM tool** — should a project/list be created in their PM tool (ClickUp, etc.) via MCP? Skip if no PM MCP is connected.
+
+## Execute Setup
+
+Run these steps. Skip any that are already done (e.g., repo already cloned, alias already exists).
+
+### 1. Local repo
+
+- **Existing repo:** `git clone` into `~/Documents/GitHub/<name>/`
+- **Create new:** `gh repo create <name> --private/--public --clone` in `~/Documents/GitHub/`
+- **No repo:** `mkdir -p ~/Documents/GitHub/<name> && cd ~/Documents/GitHub/<name> && git init`
+- If `~/Documents/GitHub/<name>/` already exists, STOP and ask — don't overwrite.
+
+### 2. Terminal alias
+
+- Add `alias <name>='cd ~/Documents/GitHub/<name> && claude'` to `~/.zshrc`
+- Place it in the "Claude Code project aliases" block with the other aliases
+- If an alias with that name already exists, STOP and ask.
+- Run `source ~/.zshrc` so it works immediately in new shells.
+
+### 3. Project scaffolding
+
+Only create files that don't already exist in the repo:
+
+- **CLAUDE.md** — Create a **thorough** project-level CLAUDE.md. This is the most important file — it's what Claude reads every session. Don't leave it as a skeleton.
+  - Read every file in the repo to understand the project before writing it
+  - Include: what the project does, tech stack table, project structure tree, key conventions/business rules, architecture/data flow, and any environment/credential notes
+  - Model it after well-structured examples (tech stack table, project tree with descriptions, business rules table, flow diagrams)
+  - If the repo is empty/new, write what you know from the user's description and mark unknowns with `[TBD]` — but still create the full structure so it's easy to fill in
+  - Never leave CLAUDE.md as a thin placeholder — a future session should be able to understand the project from this file alone
+
+- **WORK_LOG.md** — Create with:
+  ```
+  # <Project Name> Work Log
+
+  ## Last updated: <today's date>
+
+  ## Overall State: Project initialized
+
+  ## Recent Changes (<today's date>)
+
+  1. **Project setup** — repo cloned/created, local config wired, ready for `/start`.
+
+  ## Known Issues / Next Steps
+  - Run `/start` to begin first working session
+  ```
+
+- **.gitignore** — Only create if one doesn't exist. Use a sensible default based on what's in the repo (Node, Python, etc.), or a minimal one if unclear.
+
+### 4. PM integration (optional)
+
+If a PM MCP is connected and the user wants it:
+- Create a project/list in the PM tool
+- Note the project ID in WORK_LOG.md for reference
+
+### 5. Initial commit
+
+If new files were created:
+- Stage the new files (CLAUDE.md, WORK_LOG.md, .gitignore)
+- Commit: `feat: initialize project for Claude Code`
+- Push to remote if a remote exists
+
+### 6. Confirm
+
+Present a summary:
+- **Repo:** cloned/created at `~/Documents/GitHub/<name>/`
+- **Alias:** `<name>` → opens folder + launches Claude
+- **Files created:** list what was scaffolded
+- **PM:** project created (or skipped)
+- **Ready:** type `<name>` in a new terminal to start working, or run `/start` now

package/commands/start.md

@@ -1,4 +1,10 @@
-Read CLAUDE.md and WORK_LOG.md to understand the project and where we left off.
+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)
+- Skip all "Previous Sessions" / older dated entries — that history exists for reference but shouldn't be loaded into context on every start
+- If WORK_LOG.md is under 80 lines total, just read the whole thing
 
 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.
 
@@ -38,11 +44,11 @@ Before anything else, silently check if a newer version of Playbook is available
      - 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:
+   - If CLAUDE.md HAS changed upstream, tell the user what changed (summarize the differences in plain language), then offer two 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.
+     2. **Merge** — I'll add the new Playbook changes to your CLAUDE.md while preserving ALL of your customizations. I'll show you the result before saving.
+   - **CRITICAL: Never offer a full replacement option.** Users have personal customizations in their CLAUDE.md (their name, MCP server configs, integrations like ClickUp/Perplexity/n8n, custom rules). A full replacement would destroy all of that. The only safe options are keeping theirs or merging.
+   - If the user picks **Merge**: read both files, produce a merged version that preserves ALL user customizations (name, integrations, MCP configs, custom sections) while incorporating new upstream structural/feature changes. Show the result 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.
 
@@ -50,6 +56,21 @@ Before anything else, silently check if a newer version of Playbook is available
 
 ---
 
+## Step 1: Claude Code Version Check
+
+After the Playbook update check, verify the user's Claude Code version is reasonably current.
+
+1. Run `claude --version` to get the installed version (format: `X.Y.Z (Claude Code)`).
+2. Compare the **minor version** (the Y in X.Y.Z) against a minimum: **2.0.0**.
+3. **Only warn if the user is 2+ minor versions behind the minimum** (e.g., on 1.8.x when minimum is 2.0.0). Patch versions don't matter.
+4. If behind, show a single-line nudge — not a blocker:
+   > **Heads up:** Your Claude Code is vX.Y.Z — the Playbook works best on v2.0+. Run `claude update` to get the latest.
+5. If current or close enough, say nothing. No output = no noise.
+
+This check should be fast (one bash command) and never block the session.
+
+---
+
 ## Normal Briefing
 
 Present a concise briefing:
@@ -63,9 +84,9 @@ Keep it short and scannable. Bullet points. No fluff. Wait for direction before
 
 ## Session Naming
 
-**Before the briefing**, prompt the user to name the session. Output only this — nothing else:
+**At the top of your response**, before the briefing, prompt the user to name the session:
 
 > 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.
+Where `<project>` is the current directory's basename (e.g., `playbook`). Then include the full briefing in the **same message** below the rename prompt. The user can rename at any time — do not wait for it.

package/install.sh

@@ -80,6 +80,16 @@ else
   echo "  Installed settings.json"
 fi
 
+# 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"
+else
+  if [ -f "$PLAYBOOK_DIR/templates/tech_stack.md" ]; then
+    cp "$PLAYBOOK_DIR/templates/tech_stack.md" "$CLAUDE_DIR/tech_stack.md"
+    echo "  Installed tech_stack.md template"
+  fi
+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.0.0",
+  "version": "1.2.0",
   "description": "Operating playbook for non-technical founders working with Claude Code",
   "bin": {
     "playbook-ai": "bin/cli.js"
@@ -10,6 +10,7 @@
     "bin/",
     "lib/",
     "commands/",
+    "templates/",
     "CLAUDE.md",
     "settings.json",
     "install.sh",

package/settings.json

@@ -1,4 +1,7 @@
 {
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
   "permissions": {
     "allow": [
       "Bash(python3:*)",

package/templates/tech_stack.md

@@ -0,0 +1,48 @@
+# Tech Stack — Global (All Projects)
+
+> Single source of truth for tools, services, and integrations in active use.
+> Check this before recommending new tools — prefer what's already here.
+
+## Languages & Runtimes
+| Tool | Used In | Notes |
+|------|---------|-------|
+| — | — | — |
+
+## Frameworks & Libraries
+| Tool | Used In | Notes |
+|------|---------|-------|
+| — | — | — |
+
+## Platforms & Services
+| Tool | Used In | Notes |
+|------|---------|-------|
+| GitHub | all projects | Source control, repos |
+
+## MCP Servers
+| Server | Purpose | Notes |
+|--------|---------|-------|
+| — | — | — |
+
+## Claude Code Plugins
+| Plugin | Purpose | Notes |
+|--------|---------|-------|
+| — | — | — |
+
+## Infrastructure
+| Tool | Used In | Notes |
+|------|---------|-------|
+| — | — | — |
+
+## Deprecated
+| Tool | Was Used In | Reason | Date |
+|------|-------------|--------|------|
+| — | — | — | — |
+
+---
+
+**Rules:**
+- When evaluating tools for a new project, check this file first
+- Prefer tools already in use unless there's a strong reason not to
+- When adopting a new tool, add it here immediately
+- When dropping a tool, move it to Deprecated with the reason
+- This file is maintained by Claude across all sessions

package/update.sh

@@ -29,9 +29,10 @@ fetch_via_git() {
 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")
+  local cmd_files=("start.md" "end.md" "plan.md" "debug.md" "quick.md" "handoff.md" "new-project.md")
 
   mkdir -p "$PLAYBOOK_DIR/commands"
+  mkdir -p "$PLAYBOOK_DIR/templates"
 
   for f in "${files[@]}"; do
     curl -sf "$RAW_BASE/$f" -o "$PLAYBOOK_DIR/$f" || return 1
@@ -41,6 +42,9 @@ fetch_via_curl() {
     curl -sf "$RAW_BASE/commands/$f" -o "$PLAYBOOK_DIR/commands/$f" || return 1
   done
 
+  # Fetch templates (non-fatal if missing — they're optional)
+  curl -sf "$RAW_BASE/templates/tech_stack.md" -o "$PLAYBOOK_DIR/templates/tech_stack.md" 2>/dev/null
+
   return 0
 }
 
@@ -97,6 +101,13 @@ elif [ -f "$TEMP_DIR/settings.json" ]; then
   echo "  Installed settings.json"
 fi
 
+# --- Install tech_stack.md template if missing ---
+
+if [ ! -f "$CLAUDE_DIR/tech_stack.md" ] && [ -f "$PLAYBOOK_DIR/templates/tech_stack.md" ]; then
+  cp "$PLAYBOOK_DIR/templates/tech_stack.md" "$CLAUDE_DIR/tech_stack.md"
+  echo "  Installed tech_stack.md template"
+fi
+
 # --- Update version (LAST — only on success) ---
 
 if [ -f "$PLAYBOOK_DIR/VERSION" ]; then