playbook-ai 1.4.2 → 1.5.2

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 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.5.2] — 2026-05-28
+
+### Architecture
+- **Subagent model replaces manual handoffs** — `/chess`, `/future`, and `/plan` no longer generate copy-paste prompt blocks for new terminals. All three now spawn Agent subagents directly, with the appropriate model (Opus 4.6 for `/chess` Human Mode and `/future` narratives; Sonnet for `/plan` and `/chess` System Mode). Fresh context window, results return automatically to the main session. No terminal switching, no copy-pasting.
+- **Brief file pattern** — all commands write a structured `.md` brief before spawning. The subagent reads the file (intake data + execution framework); the user reviews a short intake summary in chat (~150-250 words), not the full brief. Output is appended to the same file — brief and results live together as one artifact. Full brief available at `docs/chess/`, `docs/futures/`, or `docs/plans/` for review or editing before running.
+- **`/handoff` rewritten** — now defines the canonical subagent pattern: write brief → show summary → cost warning (Opus only) → spawn Agent → receive results → continue in main session. Used as the reference by `/chess`, `/future`, and `/plan`.
+
+### Commands
+- **`/plan`** — Phase 1 stays inline (conversational direction-setting). Phases 2+3 (hardening + implementation steps) now spawn a Sonnet subagent for complex plans, keeping the main session lean. Simple plans continue inline. Self-contained — no `/start` required.
+- **`/chess`** — Self-contained. Intake summary shown in chat for approval; cost warning before Opus spawn. Chess brief written to `docs/chess/YYYY-MM-DD-[slug].md`; full debrief appended to same file. System Mode: inline Sonnet for simple systems, Sonnet subagent for complex, Opus subagent only when system complexity genuinely warrants it.
+- **`/future`** — `/chess` bridge updated: each swing-state adversarial decision gets a 3-sentence context block (what it is, why it's adversarial, what's at stake) plus an explicit recommendation (run / skip) and a direct *"Run /chess on this?"* confirmation. High threshold for recommending run — both material AND genuinely adversarial. Conservative by default: most runs surface zero chess candidates.
+
+## [1.5.1] — 2026-05-28
+
+### Strategy
+- **`/future` upgraded to handoff model** — now runs the same way as `/chess`: intake and assumption check in the main session (Sonnet), three narratives and synthesis in a fresh Opus 4.6 parallel session. Keeps main session clean; returns the one-screen primary output via return prompt so the user can discuss it immediately. Self-contained — does not require `/start` to have been run first.
+- **Retrospective mode** — on startup, `/future` checks `docs/futures/` for prior runs. If found, offers to run an update that reads what's changed since the prior session and revises the scenarios with actual data. Turns a one-time exercise into a navigation system.
+- **Assumption check** — brief pre-scenario check (borrowed from `/plan`): surfaces the 2–3 assumptions baked into the user's success scenario and asks which feel shaky. Shaky assumptions seed The Unraveling, making it specific rather than generic.
+- **Synthesis verdicts** — quadrant output now uses ✅ / ⚠️ / ❌ format (borrowed from `/chess` System Mode) for scannability.
+- **`/chess` bridge** — swing-state decisions with a real counterparty are flagged `[/chess candidate]` in the output. Creates a natural hand-off between strategic planning and adversarial analysis.
+- **Saves to `docs/futures/`** — full output (all three narratives + synthesis + primary output) persisted as a dated file. Primary output returned verbatim to main session for discussion.
+
+## [1.5.0] — 2026-05-27
+
+### Strategy
+- **New `/future` command** — scenario planning via three futures (The Win, The Unraveling, The Headwind). Reads project context silently, runs a short intake, then writes three past-tense narratives rewound month by month to today. Synthesizes them via quadrant analysis to surface double-confirmed critical actions, swing-state decisions, and failure drivers. Output is one screen: a thesis, 3 load-bearing decisions (ordered by when they must be made), 3 anti-patterns to avoid (with why they're tempting and the early signal you're sliding in), and your move this week. Full narratives available in appendix on request. Ends with an optional 30-day ClickUp or WORK_LOG check-in. The third scenario (The Headwind) is the one most people skip — it surfaces external forces you need to be resilient against, not just what you did right or wrong.
+
 ## [1.4.3] — 2026-05-25
 
 ### Performance

package/VERSION

@@ -1 +1 @@
-1.4.3
+1.5.2

package/commands/chess.md

@@ -1,4 +1,6 @@
-Adversarial strategy analysis and technical stress-testing. Two modes: Human Mode (opponent-modeled, branch-traced) for situations with a real adversary; System Mode (assumption-attack, failure-traced) for technical plans with no human counterparty. Intake runs in the primary session (Sonnet). Human Mode generates a parallel Opus 4.6 handoff; System Mode runs inline.
+Adversarial strategy analysis and technical stress-testing. Two modes: Human Mode (opponent-modeled, branch-traced) for situations with a real adversary; System Mode (assumption-attack, failure-traced) for technical plans with no human counterparty.
+
+**Self-contained.** Does not require `/start`. Reads its own context.
 
 ---
 
@@ -14,15 +16,13 @@ Three routes. Assess before doing anything else.
 
 **Borderline:** Name what makes it ambiguous. Ask the user to confirm before proceeding.
 
-The pre-flight runs on Sonnet. Do not begin intake until the route is confirmed.
-
 ---
 
 ## Human Mode
 
-### Intake: Build the chess brief
+### Intake
 
-Run in the primary session on Sonnet. Ask these questions conversationally — not as a numbered list. Group related questions naturally. Use follow-ups where the answer is thin. The goal is a complete picture before the chess engine runs.
+Run in the main session on Sonnet. Ask conversationally — not as a numbered list. Group related questions naturally. Use follow-ups where the answer is thin.
 
 **The situation**
 - What is the decision, negotiation, or situation you're navigating?
@@ -49,55 +49,61 @@ Run in the primary session on Sonnet. Ask these questions conversationally — n
 - What moves are you currently considering?
 - What counts as a win? An acceptable outcome? A loss?
 
-Once intake is complete, read the summary back to the user and confirm it's accurate before generating the handoff prompt.
-
 ---
 
-### Generate the handoff prompt
-
-Compile everything from intake into a self-contained chess brief. Fill in all [BRACKETS] with real values — current date, actual repo path (use the current working directory), and a short topic slug derived from the situation (e.g., `hilldun-negotiation`, `board-vote`, `vendor-renewal`).
+### Generate the brief and spawn subagent
 
-Create the `docs/chess/` directory in the current project if it doesn't already exist.
+Once intake is complete, compile everything into a chess brief file and spawn an Opus 4.6 subagent. Follow the `/handoff` pattern.
 
-Present the completed handoff prompt to the user in a clearly labeled block:
+**1. Write the brief**
 
-> **Open a new terminal window and paste this entire block:**
+Create `docs/chess/` if it doesn't exist. Write `docs/chess/YYYY-MM-DD-[slug].md` using the template below. Fill in all [BRACKETS] with real values.
 
 ---
 
-#### Handoff prompt (embed verbatim — this is what runs in the parallel session)
-
----
-
-You are running a chess-style adversarial analysis. Intake is complete — all context is below. Your job is to think several moves ahead, model each adversary's rational behavior, and produce a debrief the user can act on. Do not ask questions. Do not invoke any slash commands. Run straight through.
-
-Run on Opus 4.6 (`claude-opus-4-6`). Do not switch models.
+```
+# Chess Brief — [YYYY-MM-DD] — [slug]
+*Human Mode*
 
----
+## Run instructions
+Run on Opus 4.6 (claude-opus-4-6). Do not switch models. Do not ask questions. Do not invoke slash commands. Surface reasoning in chat as you go. Append all output under ## Output in this file.
 
-**SITUATION**
-[Paste situation summary]
+## Situation
+[Situation summary]
 
-**OBJECTIVE**
+## Objective
 [What the user is trying to achieve]
 
-**TIME HORIZON**
+## Time horizon
 [One-time / ongoing / deadline: YYYY-MM-DD]
 
-**YOUR POSITION**
-[Standing (stronger/equal/weaker), BATNA, non-negotiables, information held back, what adversary likely assumes]
-
-**ADVERSARIES**
-[For each: name/role, primary goal, secondary interests, motivations, aggression level, BATNA, constraints, what they know about the user]
-
-**THE BOARD**
-[Current state, moves already made or said, moves under consideration, definition of win / acceptable / loss]
-
----
-
-**CHESS REASONING FRAMEWORK**
-
-Surface your reasoning in chat as you go — the user is watching in real time.
+## Your position
+Standing: [stronger / equal / weaker]
+BATNA: [best alternative if this doesn't go their way]
+Non-negotiables: [what they won't concede]
+Information held back: [what they're not disclosing]
+What adversary likely assumes: [their read of the user's position]
+
+## Adversaries
+[For each adversary:]
+**[Name / Role]**
+- Primary goal: [what they want most]
+- Secondary interests: [other things they care about]
+- Motivations: [financial / ego / power / relationship / legal / other]
+- Aggression level: [passive / moderate / aggressive]
+- BATNA: [their best alternative]
+- Constraints: [budget limits, authority limits, approvals needed, external pressures]
+- What they know: [their read of the user's position]
+
+## The board
+Current state: [what's happening right now]
+Moves already made: [what's been said or done that constrains the situation]
+Moves under consideration: [what the user is thinking about doing]
+Win: [definition]
+Acceptable: [definition]
+Loss: [definition]
+
+## Chess reasoning framework
 
 **Step 1 — Inhabit each adversary**
 
@@ -110,7 +116,6 @@ Stay strictly within rational human motivation. Model what a reasonable person i
 For each move the user is considering, trace the likely sequence of responses 3–4 moves deep, or until the path reaches a clearly labeled terminal state. Prune branches that are implausible given the adversary's model — don't trace everything, trace what matters.
 
 Format each branch as:
-
 ```
 Your move → Adversary response → Your counter → Their counter → Terminal: [favorable / acceptable / problematic]
                                → Risk branch: if [X] instead  → Terminal: [recovery cost]
@@ -126,56 +131,53 @@ Where in the move tree can you shift a terminal state? What moves create future
 
 **Step 5 — Recommended line**
 
-State the recommended opening move clearly. Explain why it scores better than the alternatives across the terminal states. Include the top 2 contingency responses for the most likely adversary deviation from the expected path.
+State the recommended opening move clearly. Explain why it scores better than the alternatives across the terminal states. Include the top 2 contingency responses for the most likely adversary deviation.
 
 Be specific: *"Open with X. If they respond with Y, do Z. If they respond with W instead, do V."*
 
----
-
-**OUTPUT**
-
-When the analysis is complete:
+## Output format
+Structure the output as:
+1. Adversary models — internal model for each adversary
+2. Move tree — branches traced per Step 2
+3. Recommended line — the opening move and top 2 contingencies
+4. Assumption flags — where the analysis is most fragile
 
-1. Write the full debrief to: `[REPO_PATH]/docs/chess/[YYYY-MM-DD]-[topic-slug].md`
-   - Create the directory if it doesn't exist
-   - Structure: Situation → Adversary models → Move tree → Recommended line → Contingencies → Assumption flags
+---
 
-2. Display the full debrief in chat so the user can read through it.
+## Output
 
-3. Display this block at the end — formatted exactly as shown:
+*(appended by subagent)*
+```
 
 ---
-**Return prompt — paste this into your original session:**
 
-> Chess debrief complete. Read the analysis at `[REPO_PATH]/docs/chess/[YYYY-MM-DD]-[topic-slug].md` and pull the recommended line and top contingencies into our working context so we can decide next steps.
----
+**2. Show intake summary and get approval**
 
-4. Close with a clearly formatted terminal closer — display exactly this as the final output:
+Display a short summary in chat: situation in one sentence, objective, adversaries named, key position details (standing, BATNA, non-negotiables). Do NOT show the full framework. Say: *"Here's what I captured — [summary]. Does this look right?"*
 
-```
-Chess session complete. You can close this window.
-(Do not run /end — the primary session handles closeout.)
-```
+If the user wants to review or edit before running: *"The full brief is at [path] if you want to adjust anything first."*
 
----
+**3. Cost warning**
 
-End of handoff prompt.
+*"This runs on Opus 4.6 — noticeably more expensive than a standard session. Proceed?"*
 
----
+**4. Spawn the subagent**
+
+Spawn an Agent (`model: 'opus'`): *"Read [absolute path to brief file] in full, then execute exactly as instructed. Do not ask questions. Do not invoke slash commands. Append all output under ## Output in that file."*
 
-After presenting the handoff prompt to the user, say:
+**5. Surface results**
 
-> *"Open a new terminal, paste the block above, and watch the chess engine work. When it's done, use the return prompt to bring the debrief back into this session."*
+When the subagent returns, present the recommended line and top contingencies in the main session. The full debrief is in the brief file at `docs/chess/[filename]`.
 
 ---
 
 ## System Mode
 
-### Intake: Build the stress-test brief
+### Intake
 
 If the system, plan, and constraints are already established in the conversation, skip directly to the stress-test. Only ask for information that's genuinely missing.
 
-If context is thin, ask conversationally — not as a numbered list. Use follow-ups where the answer is thin. The goal is a complete picture before the stress-test runs.
+If context is thin, ask conversationally:
 
 **The system**
 - What are you trying to build, fix, or change?
@@ -187,13 +189,15 @@ If context is thin, ask conversationally — not as a numbered list. Use follow-
 - What outcome are you trying to guarantee?
 - What's an acceptable failure mode vs. an unacceptable one?
 
-Once you have sufficient context, proceed directly — no need to read it back unless something is ambiguous.
-
 ---
 
-### System stress-test framework
+### System stress-test
+
+**Simple systems** (single service, clear dependencies, limited blast radius): run inline on Sonnet. No subagent needed.
+
+**Complex systems** (multiple interacting services, deep dependency chains, complex state machines): follow the `/handoff` pattern. Write a brief to `docs/chess/YYYY-MM-DD-[slug]-system.md` with the system description, plan, and the framework below. Spawn a Sonnet subagent (`model: 'sonnet'`). Escalate the subagent to Opus 4.6 (`model: 'opus'`) only when the system complexity genuinely warrants it.
 
-Default: run inline on Sonnet. Escalate to Opus 4.6 inline (no parallel session) when the system is complex enough that a shallow pass would miss real risks — multiple interacting services, deep dependency chains, complex state machines. Surface your reasoning in chat as you go.
+Surface reasoning in chat as you go.
 
 **Step 1 — Map the assumptions**
 

package/commands/future.md

@@ -0,0 +1,255 @@
+Scenario planning via three futures. Rewinds each path month by month to today, synthesizes the decisions that mattered most, and delivers a one-screen action guide with a clear first move.
+
+**Self-contained.** Does not require `/start`. Reads its own context.
+
+---
+
+## Pre-flight (Sonnet, inline)
+
+Silently read the following before doing anything else:
+- `WORK_LOG.md` in the current project
+- `CLAUDE.md` in the current project
+- Recent git log (last 20 commits) if available
+- Any open/in-progress PM tasks if a PM MCP is connected
+
+Do not summarize this to the user. Use it to ground the scenarios in the actual project.
+
+**Check for prior runs.** Look for files in `docs/futures/`.
+
+- If prior run(s) exist: note the most recent file and say: *"I see a /future from [date] — start fresh, or run an update? An update reads what's changed and revises the scenarios with actual data."*
+- If no prior runs: proceed to intake.
+
+---
+
+## Intake (Sonnet, inline)
+
+Ask conversationally — not as a numbered list. One question at a time. Follow up where answers are thin.
+
+**The north star**
+What does massive success look like in concrete terms? Not "we grew a lot" — what's the specific outcome you'd be genuinely proud of? Name it as if it already happened.
+
+**The fear**
+What's the specific failure that keeps you up at night? The one you'd be embarrassed to explain to someone who believed in you.
+
+**The constraints**
+What are the hard limits right now? Runway, team size, a deadline that can't move, a dependency you're waiting on.
+
+**Timeframe**
+Based on project context and what the user described, propose a timeframe:
+- 3–6 months: specific launch, campaign, or sprint with a hard end date
+- 12 months: default for most products and ventures
+- 18–24 months: platforms, infrastructure, or early-stage ventures
+
+Say: *"Based on what you've described, I'd suggest a [N]-month horizon — does that feel right?"* Confirm before proceeding.
+
+---
+
+## Assumption check (Sonnet, inline)
+
+Brief — not a full /plan. Restate the user's success scenario in one sentence, then surface 2-3 assumptions it rests on. Ask which feel solid and which feel shaky.
+
+*"Your success scenario — [restate it] — rests on a few things being true: [A], [B], [C]. Which of these feel solid, and which feel like open questions? Anything shaky will shape what The Unraveling looks like."*
+
+Note the shaky ones. They go into the brief.
+
+---
+
+## Retrospective step (Sonnet subagent — only if prior run exists)
+
+If the user chose the update path: before writing the main brief, spawn a lightweight Sonnet subagent to do the comparison work.
+
+Subagent receives:
+- The prior /future output (read from `docs/futures/[most-recent-file].md` — the ## Output section only)
+- The user's answer to: *"What's the most significant thing that's changed since then — in the project, market, or your constraints?"*
+
+Subagent produces: a 200-300 word comparison note — what the prior thesis got right, where reality diverged, what that changes going into the updated scenarios. This note gets included in the main brief so the Opus subagent doesn't need to re-read the full prior file.
+
+---
+
+## Generate the brief and spawn subagent
+
+Compile everything into a futures brief file and spawn an Opus 4.6 subagent. Follow the `/handoff` pattern.
+
+**1. Write the brief**
+
+Create `docs/futures/` if it doesn't exist. Write `docs/futures/YYYY-MM-DD-[slug].md` using the template below. Fill in all [BRACKETS] with real values.
+
+---
+
+```
+# Future Brief — [YYYY-MM-DD] — [slug]
+[Fresh run / Retrospective update from [prior date]]
+
+## Run instructions
+Run on Opus 4.6 (claude-opus-4-6). Do not switch models. Do not ask questions. Do not invoke slash commands. Surface reasoning in chat as you go. Append all output under ## Output in this file.
+
+## Project context
+[3-5 bullet points from WORK_LOG + CLAUDE.md: current state, recent decisions, known constraints. Enough to ground the scenarios — not a wall of text.]
+
+## Intake
+- North star: [specific success outcome, past tense]
+- Fear: [specific failure]
+- Constraints: [runway, team, deadlines, dependencies]
+- Timeframe: [N months]
+- Shaky assumptions: [the ones the user flagged as uncertain]
+
+[If retrospective:]
+## What's changed since [prior date]
+[The 200-300 word comparison note from the Sonnet retrospective step]
+
+## Futures framework
+
+**Three narratives**
+
+Write all three in past tense. Voice: explaining what happened to someone who loves you and won't let you bullshit them. Start each at the end of the timeframe and rewind month by month to today. Name decisions, not themes. Name the fork points.
+
+**The Win**
+Massive success. What decisions and actions were instrumental? What did you do in month 2 that set up month 8? What did you resist that would have derailed you?
+
+Cover:
+- The decisions that compounded early and paid off late
+- The things you didn't do that turned out to matter
+- The moment it could have gone either way — and what made it go right
+- External factors that helped, and what you did to be positioned for them
+
+**The Unraveling**
+Massive failure. Anchor this in the shaky assumptions from intake — show how they played out.
+
+Cover:
+- What was tempting but harmful (looked like a good idea at the time)
+- What was delayed past the point of recovery
+- The earliest warning sign — before it became obvious
+- What you'd tell yourself in month 2 if you could
+
+**The Headwind**
+You did almost everything right. The universe didn't cooperate. This scenario teaches what you need to be resilient against, not just what to do differently.
+
+Cover:
+- What external forces hit that you couldn't have fully predicted
+- What exposure you had that you didn't need
+- What resilience you had — and what you wish you'd built
+- The real ceiling on what was achievable, even with strong execution
+
+[If retrospective:] For each narrative, note where the prior projections diverged from what actually happened. What did the prior /future get right? What did it miss?
+
+---
+
+**Synthesis**
+
+Do this reasoning internally. Only the output appears in the final results.
+
+**Quadrant analysis** — classify every significant decision/action across the three scenarios:
+- ✅ Double-confirmed critical — appears in The Win AND its absence drives The Unraveling. Highest-confidence levers.
+- ⚠️ Swing-state — present in both Win and Unraveling but executed differently. Hard calls, not obvious moves. Flag each — don't flatten them.
+- ❌ Failure driver — appears in The Unraveling, absent from The Win. Anti-patterns.
+- Resilience gap — surfaces from The Headwind. Within your control but requires deliberate preparation.
+
+**Leading indicators** — for each ❌ and ⚠️ item: what was the earliest signal it was going wrong? Not month 8 — month 2. Extract from the narratives, not asked of the user.
+
+**Irreversibility** — tag each ✅ and ⚠️ item:
+- *(irreversible)* — hiring, pricing model, core tech choices, pivots, strategic commitments
+- *(iterable)* — can be course-corrected without major cost
+
+**Order by when** — sort output items by when the decision needs to be made. Timing drives action.
+
+**Chess candidates** — for each ⚠️ swing-state decision: does it involve a real counterparty with genuinely competing interests? If yes, note it internally. These get surfaced in the /chess bridge section of the output.
+
+---
+
+**Primary output**
+
+Write the one-screen summary. Tight — everything that matters, nothing that doesn't.
+
+**The thesis**
+One paragraph. The single most important variable separating The Win from The Unraveling. Name the one fork in the road.
+
+[If retrospective:] One sentence first: whether the prior thesis still holds or has shifted.
+
+**3 load-bearing decisions** (✅ double-confirmed, ordered by when)
+
+For each:
+- **The decision** — stated plainly
+- **When** — specific window, not "eventually"
+- **Early warning sign** — earliest signal it's going wrong
+- Mark *(irreversible)* where it applies
+
+Three max.
+
+**3 things not to do** (❌ failure drivers)
+
+For each:
+- **The anti-pattern** — what it is
+- **Why it's tempting** — if it weren't, you wouldn't need the warning
+- **The signal you're sliding into it** — earliest sign
+
+Three max.
+
+**Your move this week**
+One or two specific actions, this week. Entry point into the critical path.
+
+---
+
+*Full narratives, complete quadrant, and everything else surfaced are in the appendix. Ask to see it.*
+
+---
+
+## Output
+
+*(appended by subagent)*
+```
+
+---
+
+**2. Show intake summary and get approval**
+
+Display a short summary in chat: north star in one sentence, fear, constraints, timeframe, shaky assumptions. Do NOT show the full framework. Say: *"Here's what I captured — [summary]. Does this look right?"*
+
+If the user wants to review or edit: *"The full brief is at [path] if you want to adjust anything first."*
+
+**3. Cost warning**
+
+*"This runs on Opus 4.6 — noticeably more expensive than a standard session. Proceed?"*
+
+**4. Spawn the subagent**
+
+Spawn an Agent (`model: 'opus'`): *"Read [absolute path to brief file] in full, then execute exactly as instructed. Do not ask questions. Do not invoke slash commands. Append all output under ## Output in that file."*
+
+**5. Surface results**
+
+When the subagent returns, present the one-screen primary output (thesis → 3 decisions → 3 anti-patterns → your move this week) in the main session for discussion.
+
+---
+
+## /chess bridge (after results return)
+
+After presenting the primary output, evaluate the chess candidates the subagent identified. For each ⚠️ swing-state decision that involves a real counterparty:
+
+Apply a strict filter before surfacing. BOTH must be true:
+1. **Real adversarial tension** — a counterparty whose interests genuinely compete with yours, not just a vendor you're selecting or a partner whose goals are aligned
+2. **Material and hard to reverse** — significant money, a strategic dependency, or a relationship where getting it wrong costs you something you can't easily get back
+
+If both aren't true, don't mention /chess. Most /future runs surface zero chess candidates. One is meaningful.
+
+**When a candidate clears the filter**, present it as:
+
+> **[Decision name]**
+> [One sentence: what the decision is and who the counterparty is.]
+> [One sentence: what their competing interest is and why that creates genuine tension.]
+> [One sentence: what's at stake — the material downside or opportunity cost if this goes wrong.]
+> **Recommendation: [Run /chess / Skip /chess]** — [one-line rationale]
+>
+> *Run /chess on this?*
+
+The recommendation to run should be conservative. If the stakes are meaningful and the outcome is genuinely uncertain, recommend run. If the adversarial component is minor, the counterparty's interests are broadly aligned, or the decision is iterable — recommend skip.
+
+If no candidates clear the filter, say nothing about /chess.
+
+---
+
+## Follow-up
+
+After the /chess bridge (or if no chess candidates), offer once:
+- If ClickUp MCP is connected: *"Want me to create a ClickUp task to review the load-bearing decisions 30 days from now?"*
+- Otherwise: *"Want me to add a 30-day review reminder to WORK_LOG.md?"*
+
+One line. Don't push it.

package/commands/handoff.md

@@ -1,41 +1,82 @@
-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.
+This command is for Claude to invoke — not the user. It defines the canonical subagent pattern used by /chess, /future, /plan, and any task that benefits from a fresh context window. Replaces the old copy-paste terminal approach entirely.
 
-## 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)
+## The pattern
 
-Do NOT use when:
-- The session is almost done anyway
-- A subagent would suffice
-- The overhead of context-switching outweighs the benefit
+**Step 1 — Intake in main session (Sonnet)**
+Run intake conversationally. Collect everything the subagent needs to execute without asking questions.
 
-## What to generate
+**Step 2 — Write the brief**
+Compile intake data + execution framework into a structured .md file. Use the relevant subdirectory:
+- `/chess` → `docs/chess/YYYY-MM-DD-[slug].md`
+- `/future` → `docs/futures/YYYY-MM-DD-[slug].md`
+- `/plan` → `docs/plans/YYYY-MM-DD-[slug].md`
+- Generic → `docs/handoffs/YYYY-MM-DD-[slug].md`
 
-Create a complete, self-contained prompt block to paste into a new Claude Code terminal. The block must include:
+Create the directory if it doesn't exist.
 
-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.
+**Brief file structure:**
+```
+# [Command] Brief — [YYYY-MM-DD] — [slug]
 
-## Format for the user
+## Run instructions
+Run on [model]. Do not ask questions. Do not invoke slash commands.
+Append all output under ## Output in this file.
 
-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.'"
+## [Intake data — context, goals, constraints, situation]
 
-## After return
+## Framework
+[Full execution instructions for the subagent]
 
-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
+---
+
+## Output
+
+*(appended by subagent)*
+```
+
+**Step 3 — Show intake summary in chat**
+Display 150-250 words covering what was captured. This is what the user reviews and approves — not the full brief or the framework. Say: *"Here's what I captured — [summary]. Does this look right?"*
+
+If the user wants to inspect or edit before running: *"The full brief is at [path] if you want to adjust anything first."*
+
+**Step 4 — Cost warning for Opus**
+If the subagent will run on Opus 4.6, say before spawning: *"This runs on Opus 4.6 — noticeably more expensive than a standard session. Proceed?"*
+
+**Step 5 — Spawn the subagent**
+After the user confirms, spawn an Agent with the appropriate model:
+- Opus 4.6 (`model: 'opus'`): /chess Human Mode, /future narratives + synthesis. **Never Opus 4.7.**
+- Sonnet (`model: 'sonnet'`): /plan Phases 2+3, /chess System Mode, generic handoffs
+
+Subagent prompt: *"Read [absolute path to brief file] in full, then execute exactly as instructed in that file. Do not ask questions. Do not invoke slash commands. Append all output under the ## Output section of that same file."*
+
+**Step 6 — Receive and surface results**
+The subagent appends output to the brief file and returns a summary to the main session. Present the key findings to the user for discussion.
+
+**Step 7 — Continue in main session**
+Discussion, follow-up decisions, and next steps happen here. Do not start a new session for the debrief.
+
+---
+
+## When to use subagents vs. inline
+
+Use a subagent when:
+- The task will generate substantial output (3,000+ tokens) that would bloat main session
+- A fresh context window produces meaningfully better output (adversarial analysis, scenario narratives)
+- The task is independent enough to run without back-and-forth
+
+Stay inline when:
+- The task is conversational or needs real-time course-correction
+- The output is short and immediately actionable
+- The overhead of a subagent isn't worth it
+
+---
+
+## Generic handoff (no specific command)
+
+When handing off work not covered by /chess, /future, or /plan:
+1. Summarize task + context into a brief
+2. Save to `docs/handoffs/YYYY-MM-DD-[slug].md`
+3. Follow steps 3-7 above
+4. After return: read the Output section, integrate results into the main session's work

package/commands/plan.md

@@ -1,18 +1,30 @@
 Before making any changes, assess the task and create a structured plan.
 
-## Phase 1: Assess Complexity
+**Self-contained.** Does not require `/start` to have been run.
+
+---
+
+## Phase 1: Assess Complexity (Sonnet, inline)
 
 Read all relevant files first. Then determine:
-- **Is this straightforward?** (One obvious approach, clear requirements) → Skip to Phase 2.
+- **Is this straightforward?** (One obvious approach, clear requirements) → proceed directly to Phase 2 inline.
 - **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
   - Save the decision to `docs/decisions/YYYY-MM-DD-<topic>.md` if it's non-trivial
 
+Once the direction is approved, assess whether the plan warrants a subagent:
+- **Simple plan** (single file, clear scope, low risk surface) → continue inline for Phases 2+3
+- **Complex plan** (multi-file, architectural choices, meaningful risk surface, current session context is already heavy) → spawn a Sonnet subagent for Phases 2+3
+
+---
+
 ## Phase 2: Harden the Direction
 
-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.
+**Simple plans — inline (Sonnet):**
+
+Before writing implementation steps, stress-test the chosen direction.
 
 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:
@@ -23,6 +35,21 @@ Before writing implementation steps, stress-test the chosen direction. Scale dep
 
 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.
 
+**Complex plans — Sonnet subagent (follow `/handoff` pattern):**
+
+Write a brief to `docs/plans/YYYY-MM-DD-[slug].md` containing:
+- The approved direction and all relevant context (file paths, schemas, APIs, constraints)
+- The Phase 2+3 framework below
+- Instruction to return the complete hardened plan in its response
+
+Show the user a short summary of the direction and context captured. Confirm before spawning.
+
+Spawn a Sonnet subagent (`model: 'sonnet'`): *"Read [absolute path] in full, then execute exactly as instructed. Do not ask questions. Do not invoke slash commands. Append all output under ## Output in that file."*
+
+When the subagent returns, present the hardened plan to the user and wait for approval before making any changes.
+
+---
+
 ## Phase 3: Implementation Steps
 
 Direction is hardened. Write the execution plan once, correctly.

package/package.json

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