playbook-ai 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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.1] — 2026-03-15
+
+### Improvements
+- **Network diagnostics** — `/debug` now includes a Step 0 connectivity check when sessions are slow. Runs `speedtest` (if installed) to rule out network issues before diving into code debugging.
+- **Speedtest CLI recommended** — Added to tech stack template under new "Diagnostics" section. Install with `brew install teamookla/speedtest/speedtest`.
+- **Troubleshooting section in README** — Guidance for diagnosing slow sessions with install instructions and thresholds.
+
 ## [1.2.0] — 2026-03-11
 
 ### New Commands

package/CLAUDE.md

@@ -89,6 +89,15 @@
 - 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
 
+## Inbox
+- Every project can have an `inbox/` folder at the repo root — a drop zone for files you want Claude to read
+- `inbox/` must be in `.gitignore` — nothing in it should ever be committed
+- **Large files warning:** If you're dropping in large files (PDFs, CSVs, images, etc.), know that `inbox/` is temporary and local only. If you need to keep those files long-term, save them somewhere permanent (Google Drive, your file system, etc.) before or after the session. Claude will not preserve them.
+- When you say things like "check the files I gave you," "look at what I dropped in," or "read the files" without specifying a path — Claude should check `inbox/` first
+- During the session, Claude reads and uses inbox files freely
+- At `/end`, Claude cleans up: extracts any useful information (saves to memory, docs, or code as needed), then **deletes all files** from `inbox/`. If a file needs to persist, Claude moves it to an appropriate location in the project (e.g., `docs/`, `templates/`) before deleting the original
+- The goal is zero files in `inbox/` after every session — no accumulation, no bloat
+
 ## Code Quality
 - No fabricated data in production — 100% accuracy
 - Propose parallel work when independent tasks can run simultaneously

package/README.md

@@ -113,6 +113,17 @@ 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.
 
+## 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:
+
+```bash
+brew install teamookla/speedtest/speedtest
+speedtest
+```
+
+If you see high latency (>500ms), significant packet loss (>5%), or very low upload speeds (<1 Mbps), your connection is the bottleneck. This is common on in-flight Wi-Fi, tethered connections, or congested networks. Claude's `/debug` command will automatically suggest checking connectivity when sessions are sluggish.
+
 ## Customizing
 
 This playbook is a starting point. Customize `CLAUDE.md` to fit your workflow:

package/VERSION

@@ -1 +1 @@
-1.2.0
+1.2.1

package/commands/debug.md

@@ -1,5 +1,6 @@
 Follow this systematic debugging process:
 
+0. **Check connectivity (only if the session is slow)** — If responses are taking unusually long, run `speedtest` (if installed) to check for high latency, packet loss, or low bandwidth. If the connection is poor (>500ms latency, >5% packet loss, or <1 Mbps upload), flag it and suggest deferring to a better connection before debugging code.
 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)

package/commands/end.md

@@ -24,6 +24,11 @@ Session closeout. Do everything needed so the user can walk away without taking
    - 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
+   - **Inbox cleanup:** If `inbox/` exists and has files:
+     - Review each file — extract any information that should persist (save to memory, docs, code, etc.)
+     - If a file needs to live permanently in the project, move it to the right location (e.g., `docs/`, `templates/`)
+     - Delete everything remaining in `inbox/` — the goal is zero files after every session
+     - Report what was cleaned up: "Cleaned inbox: deleted X files, moved Y to Z"
 
 6. **Pre-commit checklist** — before committing, verify:
    - All changes tested/verified (not just "should work" — show evidence)

package/commands/new-project.md

@@ -55,7 +55,9 @@ Only create files that don't already exist in the repo:
   - 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.
+- **inbox/** — Create the directory with a `.gitkeep` inside so git tracks the empty folder: `mkdir -p inbox && touch inbox/.gitkeep`
+
+- **.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. **Always include `inbox/*` and `!inbox/.gitkeep`** so the folder exists in the repo but its contents are never committed.
 
 ### 4. PM integration (optional)
 

package/commands/start.md

@@ -71,6 +71,17 @@ This check should be fast (one bash command) and never block the session.
 
 ---
 
+## Step 2: Inbox Check
+
+Check if an `inbox/` folder exists at the project root and contains any files.
+
+1. If `inbox/` doesn't exist or is empty — skip, say nothing.
+2. If `inbox/` has files, list them in the briefing under **Inbox files:** with file names and sizes.
+3. Do NOT read or process the files yet — just surface what's there so the user knows Claude is aware of them.
+4. When the user says things like "check the files I gave you," "look at what I dropped in," or "read the files" without specifying a path — check `inbox/` first.
+
+---
+
 ## Normal Briefing
 
 Present a concise briefing:

package/package.json

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

package/templates/tech_stack.md

@@ -33,6 +33,11 @@
 |------|---------|-------|
 | — | — | — |
 
+## Diagnostics
+| Tool | Purpose | Notes |
+|------|---------|-------|
+| [Speedtest CLI](https://www.speedtest.net/apps/cli) | Network diagnostics | `brew install teamookla/speedtest/speedtest` — rule out connectivity before debugging slow sessions |
+
 ## Deprecated
 | Tool | Was Used In | Reason | Date |
 |------|-------------|--------|------|