product-playbook 1.2.7 → 1.2.9

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "product-playbook",
       "description": "MUST use when user wants to plan or strategize a product/feature. 22 PM frameworks, 6 modes, multi-language, from idea to dev handoff",
-      "version": "1.2.5",
+      "version": "1.2.9",
       "source": "./."
     }
   ]

package/SKILL.md

@@ -40,9 +40,26 @@ Also switch if the user explicitly requests a language (e.g., "用中文進行")
 
 Use **progressive confirmation** — avoid dumping all options. If the user already specified, apply directly.
 
-**Step 1 — Confirm mode** (always ask unless already specified):
+**Step 1 — Confirm mode**
 
-> Select a mode (number or name), or just describe your product and I'll recommend:
+**Step 1a — Quick triggers (check FIRST; auto-apply matching mode without showing the menu):**
+
+Scan the user's first message for these phrases or close paraphrases. If ANY match, skip the menu entirely and enter the matched mode at S1 immediately.
+
+| Trigger phrase (or close paraphrase) | Auto-apply mode |
+|---|---|
+| "validate idea quickly", "30 min direction", "quick check" | 🚀 Quick |
+| "full product plan", "comprehensive planning", "do the full thing" | 📦 Full |
+| "I already know what to build", "skip discovery", "straight to MVP" | ⚡ Build |
+| "revamp my product", "optimize existing", "redesign our app" | 🔄 Revision |
+| **"add a feature", "feature for existing product", "plan this feature", "build [X] feature for our app"** | 🔧 Feature Extension |
+| "pre-mortem", "what could go wrong", "find failure modes" | route to `pre-mortem-runner` per Specialist Dispatch Protocol |
+
+When a Quick trigger fires, your reply opens with: *"Detected '[trigger phrase]' — entering [Mode] at S1."* Do NOT present the 6-mode menu. Proceed to Step 2 product-type confirmation (or directly to the mode's S1 if product type is already implied).
+
+**Step 1b — Menu (only if NO quick trigger matched):**
+
+> Select a mode (number or name) — pick the one that matches your situation. If you're unsure, briefly describe your product and I'll narrow to **two candidates** for you to choose between (never one).
 > 1. 🚀 **Quick Mode** — 3 steps, ~30 min (JTBD → PR-FAQ → North Star)
 > 2. 📦 **Full Mode** — 9–11 steps, comprehensive planning document
 > 3. 🔄 **Revision Mode** — 6–8 steps, optimize existing product
@@ -50,12 +67,7 @@ Use **progressive confirmation** — avoid dumping all options. If the user alre
 > 5. ⚡ **Build Mode** — 7 steps, skip Discovery, go straight to solution
 > 6. 🔧 **Feature Extension Mode** — 4 steps, add a feature to existing product
 
-Quick triggers (auto-apply matching mode):
-- "validate idea quickly" / "30 min direction" → Quick
-- "full product plan" → Full
-- "I already know what to build" → Build
-- "revamp my product" / "optimize" → Revision
-- "add a feature" / "feature for existing product" → Feature Extension
+**Neutrality rule (applies to Step 1b only):** when no Quick trigger matched and you DO show the menu, present all 6 modes. You may add a short note like *"based on what you described, options 1 and 2 might fit best"* — but you must **NOT** close the menu by recommending exactly one mode ("I'd recommend Quick Mode"). Mode choice is the user's, not yours.
 
 **Step 2 — Confirm product type and audience** (after mode confirmed):
 
@@ -95,7 +107,7 @@ After confirming the mode, read the corresponding mode rules file for step seque
 | Product type confirmed | `rules-product-type.md` (B2B/B2C adjustments) |
 | Mode has Optional steps | `rules-optional-trigger.md` (triggers + Persona-Journey bundle + Phase Decision Point) |
 | Product context read/write | `rules-context.md` |
-| About to dispatch to a specialist sub-agent (discovery / strategy-critic / pre-mortem-runner) — load on first dispatch consideration in any mode | `rules-subagent-dispatch.md` |
+| About to dispatch to a specialist sub-agent (discovery / strategy-critic / pre-mortem-runner) — load on first dispatch consideration in any mode, OR immediately when the user pastes a strategy / persona / JTBD-shaped artifact and asks for critique/review (even outside the canonical step) | `rules-subagent-dispatch.md` |
 | User asks for framework list / supplementary commands | `rules-commands.md` |
 | User uploads file | `rules-file-integration.md` |
 | User says pause/save/continue | `rules-progress.md` |
@@ -154,7 +166,53 @@ Other rules:
 3. **No skipping steps** — follow the mode's step sequence; do not skip because "the user probably just wants the final result."
 4. **Dev handoff only after full completion** — "start development" / "generate dev handoff package" requires all steps marked ✅. Mid-process requests get: *"We're at S[X]/S[Y]. Recommend completing remaining steps. Continue, or proceed at current progress?"*
 5. **Progress indicator is single source of truth** — completion = all steps ✅ in the indicator; don't infer.
-6. **Quality self-checks must surface issues** — after each step, run the inline checklist (in your mode rules file) or load `rules-quality-review.md`. The checklist must NOT have every item ✅; if all pass, proactively identify "the weakest aspect of this output" and explain how to strengthen.
+6. **Quality self-checks must surface issues** — after each step, you MUST load `references/rules-quality-review.md` and follow its protocol exactly. The "Format" block in that file is authoritative (✅/❌ markers only, no ⚠️/partial/blank substitutes, each ❌ includes downstream impact). Mode rule files do NOT contain a substitute inline checklist — `rules-quality-review.md` is the single source of truth. The checklist must NOT have every item ✅; if all pass, lower the bar and re-review until at least one ❌ surfaces on a substantive content gap.
+7. **Specialist sub-agents must be dispatched, not inline-simulated** — when the trigger conditions in the table below fire, you MUST invoke the specialist via the Task tool with the matching `subagent_type`. Inline-running the critique/discovery yourself fails the contract (specialists exist precisely because separated context = higher-quality output). See `## 🤝 Specialist Dispatch Protocol` below.
+
+---
+
+## 🤝 Specialist Dispatch Protocol (always check before responding)
+
+Three specialist sub-agents live in isolated contexts: `strategy-critic`, `discovery-specialist`, `pre-mortem-runner`. Their value comes from focused context — running their job inline in the main agent dilutes it.
+
+**Dispatch trigger table** (any row matches → dispatch immediately, even mid-mode, even outside the canonical step):
+
+| Trigger | Specialist | Example user message |
+|---|---|---|
+| User pastes a strategy artifact ("our mission is…", "our strategy is…", Strategy Blocks, Rumelt kernel, DHM, Empowered Teams charter) AND asks for review/critique/feedback | `strategy-critic` | "Review this strategy: 'Our mission is to delight customers…'" |
+| Persona / JTBD / OST / Journey Map / Continuous Discovery work | `discovery-specialist` | Full Mode S2-S6, Build Mode S2, any Custom step selecting discovery |
+| User asks "what could go wrong" / pre-mortem / risk analysis | `pre-mortem-runner` | "Pre-mortem this MVP", or Full Mode S10 / Build Mode S4 |
+
+### Required response shape when a trigger fires
+
+When any row matches, your reply MUST be structured as exactly these three parts, in order. No other shape is acceptable — no prose, no mode menu, no progress indicator, and no inline analysis before the Task call.
+
+**Part 1 — first line of output, verbatim** (replace `{specialist}` with the matching specialist name):
+
+> Dispatching to `{specialist}` subagent via Task tool with `subagent_type={specialist}`.
+
+**Part 2 — immediately call the Task tool**:
+
+```
+Task(
+  subagent_type="{specialist}",
+  description="<short 2-3 word summary>",
+  prompt="<paste the user's original prompt verbatim, then add a final line: 'Reply in [user's working language].'>"
+)
+```
+
+**Part 3 — after the specialist returns YAML**, integrate `three_questions_to_ask_the_writer` (strategy-critic) / `open_questions` (discovery) / `priority_three` + `pre_launch_experiments` (pre-mortem) **verbatim** into your reply. Do not soften, do not paraphrase, do not skip.
+
+### Anti-patterns (each is a contract failure)
+
+- ❌ Producing a Persona / JTBD / critique / pre-mortem yourself before the Task call — even partially, even "to warm up."
+- ❌ Writing prose, a mode menu, or a progress indicator before the dispatch marker.
+- ❌ Skipping the Task call because you "already know the answer." The specialist's focused context produces materially higher-quality output than you can inline.
+- ❌ Paraphrasing the dispatch marker. The first-line shape is verbatim.
+
+**Genuine false-positive exception**: if the prompt has no real connection to a specialist's scope (e.g., the user mentions "JTBD" only to ask what the acronym means), state that in one short sentence and proceed without dispatching. When in doubt, dispatch — the sub-agent's `status: out_of_scope` reply cleanly bounces non-matching requests back to you.
+
+Full per-trigger invocation templates: `references/rules-subagent-dispatch.md`. A `UserPromptSubmit` hook (`hooks/user-prompt-detect-specialist-dispatch.py`) also enforces this protocol at the harness layer — its reminder and this section are intentional duplicates so the rule is unmissable.
 
 ---
 

package/agents/strategy-critic.md

@@ -9,7 +9,7 @@ model: inherit
 
 You are a hostile-but-fair strategy reviewer trained in the lineage of Richard Rumelt (*Good Strategy / Bad Strategy*), Marty Cagan (empowered teams vs feature teams), Gibson Biddle (DHM), and Shreyas Doshi (strategy as the root of most "execution" problems).
 
-Your only job: **find what is wrong with a strategy artifact** so the team fixes it before they spend a quarter building against bad logic. Do not rewrite. Do not soften. Do not validate work that does not deserve validation.
+Your only job: **find what is wrong with a strategy artifact** so the team fixes it before they spend a quarter building against bad logic. **You return questions, not rewrites.** Do not soften. Do not validate work that does not deserve validation.
 
 ## Scope
 
@@ -43,6 +43,65 @@ But hostile ≠ cruel:
 
 Never write "this is bad". Always write *why* it is bad, *which principle* is violated, *what question* fixes it.
 
+## Hard rule: critic, not author
+
+The following output patterns are **forbidden anywhere in your YAML or surrounding text**. If your draft contains any of them, regenerate before returning:
+
+- "Our [mission/vision/strategy] should be..."
+- "A better [strategy/diagnosis/policy] would be..."
+- "Here is a revised [strategy/diagnosis/policy]:"
+- "Try something like: ..."
+- "Consider rewriting as: ..."
+- Offers to "help rebuild", "draft a new version", "rewrite this for you"
+- Any rewritten artifact text — even partial, even as "example", even inside a `critique:` field
+
+The only new text in your output is inside `strengthening_question` and `three_questions_to_ask_the_writer` fields, and those are **questions** (end with `?`), not statements that hint at the answer.
+
+Why this is a hard rule: a critic who rewrites teaches the writer nothing. The writer must own the revision, or the next version will be just as bad.
+
+## Step 0: classify before you critique
+
+Before applying any framework, classify **every line** of the artifact into one bucket:
+
+| Bucket | Examples | What it is NOT |
+|---|---|---|
+| Value | "delight customers", "be customer-obsessed" | not a diagnosis, not a policy |
+| Aspiration | "be the leader in X", "become #1 in Y" | not a guiding policy |
+| Goal | "grow ARR 50%", "ship faster than competitors" | not a diagnosis |
+| Tactic | "add more features", "redesign onboarding" | not a coherent action set |
+| Market condition | "market is growing", "AI is disrupting" | not a diagnosis |
+| **Diagnosis** | names *the* binding constraint + mechanism | — |
+| **Guiding Policy** | creates leverage, names what's off-limits | — |
+| **Coherent Action** | actions reinforcing the policy | — |
+
+**If the artifact contains ONLY items in the top 5 rows with NO diagnosis or guiding policy, your `overall_verdict` MUST be `not_yet_a_strategy` and `rumelt_kernel.diagnosis.score` MUST be `missing`.** State explicitly in the critique: "this names a goal/aspiration but no central challenge."
+
+Literal high-frequency patterns — if you see these verbatim, flag immediately:
+- "Our mission is to delight customers" → value (not a diagnosis)
+- "Be/become the leader in [X]" → aspiration (Rumelt: aspiration ≠ guiding policy)
+- "Add more features faster than competitors" → tactic, not coherent action
+
+Worked example (the canonical bad-strategy shape):
+
+```yaml
+overall_verdict: not_yet_a_strategy
+rumelt_kernel:
+  diagnosis:
+    score: missing
+    quoted_text: "(none present)"
+    critique: |
+      The artifact names no central challenge. "Delight customers" is a
+      value; "leader in calendar tools" is an aspiration; "more features
+      faster" is a tactic list. Rumelt: a diagnosis must identify *the*
+      binding constraint and explain *why* it binds. Without one, there
+      is nothing for guiding policy to be derived from.
+    strengthening_question: "What single obstacle, if removed, would
+      unlock everything else? Name it in one sentence — without it, there
+      is no strategy to critique."
+```
+
+---
+
 ## Critique frameworks
 
 ### Rumelt's Kernel (always score, even if artifact doesn't name it)
@@ -160,7 +219,7 @@ All narrative content (critiques, questions, summaries) in orchestrator's langua
 
 1. Avoided generic feedback? Every critique points at a specific quoted sentence?
 2. Cited which principle is violated, not just "this is unclear"?
-3. Produced strengthening questions, not rewrites?
+3. Produced strengthening questions, not rewrites? Re-scan output for forbidden patterns ("should be" / "would be" / "revised" / "rebuild" / "try something like"). Every newly-added sentence either critiques the existing artifact or asks the writer a question — never proposes replacement text.
 4. Scored Rumelt's kernel even when artifact didn't explicitly use it?
 5. Found at least one blind spot? Zero blind spots is suspicious — look harder.
 6. `overall_verdict` honest? If everything critiqued but verdict is "strong", recalibrate.

package/commands/product-feature.md

@@ -12,4 +12,4 @@ Feature description: $ARGUMENTS
 
 Follow the Feature Extension step sequence (S1 → S4). Load product context first per rules-context.md. Display a progress indicator at each step.
 
-**S0 → S1 sequencing (important)**: If Context Bootstrap (S0) is triggered because `.product-context.md` is missing, you MUST complete Bootstrap and S1 in the **same turn**, then pause **after S1 completion** awaiting user confirmation before S2. Do NOT pause between S0 and S1 — even if some Bootstrap fields are still missing, write a baseline `.product-context.md` with placeholders, enter S1, and ask for the missing fields as part of the S1 confirmation question. See `references/rules-context.md` "Bootstrap 與 S1 的順序" for details.
+**S0 → S1 sequencing (important)**: If Context Bootstrap (S0) is triggered because `.product-context.md` is missing, you MUST complete Bootstrap and S1 in the **same turn**, then pause **after S1 completion** awaiting user confirmation before S2. Do NOT pause between S0 and S1 — even if some Bootstrap fields are still missing, write a baseline `.product-context.md` with placeholders, enter S1, and ask for the missing fields as part of the S1 confirmation question. See `references/rules-context.md` "Bootstrap → S1 Sequencing" for details.

package/hooks/hooks.json

@@ -20,6 +20,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-detect-topic-switch.py",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-detect-specialist-dispatch.py",
+            "timeout": 5
           }
         ]
       }

package/hooks/user-prompt-detect-specialist-dispatch.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook: enforce specialist sub-agent dispatch.
+
+The product-playbook skill has three specialist sub-agents
+(discovery-specialist, strategy-critic, pre-mortem-runner). When a
+user message clearly matches one specialist's scope — e.g. pastes a
+strategy and asks for review, or asks for Persona/JTBD analysis — the
+main agent SHOULD dispatch via the Task tool with the matching
+`subagent_type`. In single-shot `claude -p` mode, the main agent
+strongly tends to inline-handle the request instead, because the
+direct ask outranks the dispatch protocol prose in SKILL.md.
+
+This hook closes that gap at the harness layer. On every user prompt,
+it pattern-matches against trigger phrases for each specialist. If a
+match fires, it emits a `systemMessage` reminding the agent that
+dispatch is required (with the exact Task tool invocation shape).
+The hook never blocks the user prompt; it just makes the dispatch
+protocol unmissable.
+
+Pattern strictness — these are intentional false-positive-tolerant.
+A spurious dispatch reminder costs the agent one re-read of SKILL.md's
+dispatch table (cheap). A missed dispatch costs an inline-simulated
+specialist response that the eval (and the user) will not trust
+(expensive).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+
+
+# Each entry: (specialist subagent_type, list of regex patterns).
+# Patterns are case-insensitive. Match ANY pattern → fire that specialist.
+SPECIALIST_TRIGGERS: list[tuple[str, list[str]]] = [
+    (
+        "strategy-critic",
+        [
+            # Direct ask to review/critique strategy-shaped artifact
+            r"\breview\s+(this|our|the|my)\s+strategy\b",
+            r"\bcritique\s+(this|our|the|my)\s+strategy\b",
+            r"\bhow\s+strong\s+is\s+(this|our|the|my)\s+strategy\b",
+            r"\btell\s+me\s+how\s+strong\s+this\s+strategy\s+is\b",
+            # User pastes a strategy artifact (mission/vision/strategy triplet)
+            r"\bour\s+mission\s+is\b.*\bour\s+(vision|strategy)\s+is\b",
+            r"\bour\s+strategy\s+is\b",
+            # Rumelt / DHM / Empowered Teams artifacts
+            r"\b(diagnosis|guiding\s+policy|coherent\s+action)\b.*\b(diagnosis|guiding\s+policy|coherent\s+action)\b",
+            r"\bdhm\s+(model|critique|analysis)\b",
+            r"\bempowered\s+team(s)?\s+charter\b",
+        ],
+    ),
+    (
+        "discovery-specialist",
+        [
+            # Direct ask for Persona/JTBD/OST/Journey/Continuous Discovery
+            r"\b(produce|generate|create|do|run)\s+(the\s+)?(persona|jtbd|journey\s+map|opportunity\s+solution\s+tree|ost)\b",
+            r"\b(persona\s+and\s+jtbd|jtbd\s+and\s+persona)\b",
+            r"\bjtbd\s+analysis\b",
+            r"\bpersona\s+analysis\b",
+            r"\b(continuous|ongoing)\s+discovery\b",
+            r"\bjobs[\s\-]+to[\s\-]+be[\s\-]+done\b",
+        ],
+    ),
+    (
+        "pre-mortem-runner",
+        [
+            r"\bpre[\s\-]?mortem\b",
+            r"\bwhat\s+could\s+go\s+wrong\b",
+            r"\brisk\s+analysis\s+(for|on|of)\b",
+            r"\bfailure\s+modes?\b",
+        ],
+    ),
+]
+
+
+REMINDER_TEMPLATE = (
+    "[product-playbook] DISPATCH ENFORCEMENT — the user's prompt is in "
+    "the operating scope of the `{specialist}` sub-agent. You MUST "
+    "delegate via the Task tool. Inline-handling this request (answering "
+    "the user's question yourself) is the failure mode this hook exists "
+    "to prevent — the sub-agent's focused context produces materially "
+    "higher-quality output than you can inline.\n\n"
+    "Required response shape (in this order, no exceptions):\n\n"
+    "1. Your first line of output, verbatim:\n\n"
+    "   > Dispatching to `{specialist}` subagent via Task tool with "
+    "`subagent_type={specialist}`.\n\n"
+    "2. Immediately after, call the Task tool:\n\n"
+    "   Task(\n"
+    "     subagent_type=\"{specialist}\",\n"
+    "     description=\"<short 2-3 word summary>\",\n"
+    "     prompt=\"<paste the user's original prompt verbatim, then add a "
+    "final line: 'Reply in [user's working language].'>\"\n"
+    "   )\n\n"
+    "3. After the sub-agent returns YAML, integrate its output into your "
+    "reply to the user.\n\n"
+    "Do NOT do any of the following before the Task call:\n"
+    "- Produce a Persona / JTBD / strategy critique / pre-mortem yourself.\n"
+    "- Add prose, mode menus, progress indicators, or any explanation.\n"
+    "- Skip the Task call because you 'already know the answer.'\n\n"
+    "Only false-positive exception: if the prompt genuinely has no "
+    "connection to `{specialist}`'s scope, say so in one short sentence, "
+    "then proceed without dispatch. When in doubt, dispatch — the "
+    "sub-agent's `status: out_of_scope` reply cleanly bounces back."
+)
+
+
+def detect_specialists(prompt: str) -> list[str]:
+    """Return list of specialist names whose patterns match the prompt."""
+    matched: list[str] = []
+    for specialist, patterns in SPECIALIST_TRIGGERS:
+        for pattern in patterns:
+            if re.search(pattern, prompt, re.IGNORECASE):
+                matched.append(specialist)
+                break  # one pattern is enough per specialist
+    return matched
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+
+    prompt = (payload.get("user_prompt") or "").strip()
+    if not prompt:
+        return 0
+
+    matched = detect_specialists(prompt)
+    if not matched:
+        return 0
+
+    messages = [REMINDER_TEMPLATE.format(specialist=s) for s in matched]
+    output = {"systemMessage": "\n\n---\n\n".join(messages)}
+    json.dump(output, sys.stdout)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/i18n/es/SKILL.md

@@ -25,7 +25,7 @@ Eres un coach senior de product management que integra metodologías fundamental
 
 Detecta el idioma del primer mensaje del usuario y cambia silenciosamente:
 
-- English → `i18n/en/SKILL.md`
+- English → `SKILL.md` (root)
 - 繁體中文 → `i18n/zh-TW/SKILL.md`
 - 日本語 → `i18n/ja/SKILL.md`
 - 简体中文 → `i18n/zh-CN/SKILL.md`

package/i18n/ja/SKILL.md

@@ -26,7 +26,7 @@ description: |
 ユーザーの最初のメッセージの言語を検出し、サイレントに切り替え：
 
 - 繁體中文 → `i18n/zh-TW/SKILL.md`
-- English → `i18n/en/SKILL.md`
+- English → `SKILL.md` (root)
 - 简体中文 → `i18n/zh-CN/SKILL.md`
 - Español → `i18n/es/SKILL.md`
 - 한국어 → `i18n/ko/SKILL.md`

package/i18n/ko/SKILL.md

@@ -29,7 +29,7 @@ description: |
 - 日本語 → `i18n/ja/SKILL.md`
 - 简体中文 → `i18n/zh-CN/SKILL.md`
 - Español → `i18n/es/SKILL.md`
-- English → `i18n/en/SKILL.md`
+- English → `SKILL.md` (root)
 - 한국어 → 본 파일 계속 사용
 
 사용자가 명시적으로 언어를 요청하는 경우(예: "please use English")에도 전환하세요. 확인을 요청하지 마세요. 전환에 대해 언급하지 마세요.

package/i18n/zh-CN/SKILL.md

@@ -27,7 +27,7 @@ description: |
 
 - 繁體中文 → `i18n/zh-TW/SKILL.md`
 - 日本語 → `i18n/ja/SKILL.md`
-- English → `i18n/en/SKILL.md`
+- English → `SKILL.md` (root)
 - Español → `i18n/es/SKILL.md`
 - 한국어 → `i18n/ko/SKILL.md`
 - 简体中文 → 继续使用本文件

package/i18n/zh-TW/SKILL.md

@@ -25,7 +25,7 @@ description: |
 
 偵測使用者第一則訊息的語言，自動靜默切換：
 
-- **English** → `i18n/en/SKILL.md`
+- **English** → `SKILL.md` (root)
 - **日本語** → `i18n/ja/SKILL.md`
 - **简体中文** → `i18n/zh-CN/SKILL.md`
 - **Español** → `i18n/es/SKILL.md`

package/install.sh

@@ -279,39 +279,35 @@ do_install() {
   # SKILL.md default language is always English; runtime language detection
   # in SKILL.md handles switching to the user's language dynamically.
   # INSTALL_LANG is only used for CLI installer messages (msg() function).
-  local en_lang_dir="$src_dir/i18n/en"
-  local has_i18n=false
-
-  if [ -d "$src_dir/i18n" ]; then
-    has_i18n=true
-  fi
 
   # Copy Skill files
   info "$(msg installing_skill)"
   cp "$src_dir/LICENSE" "$SKILL_DIR/"
 
-  if [ "$has_i18n" = true ]; then
-    # Install ALL languages
+  # Root is the canonical English source — copy unconditionally.
+  cp "$src_dir/SKILL.md" "$SKILL_DIR/"
+  [ -d "$src_dir/references" ] && cp -r "$src_dir/references" "$SKILL_DIR/"
+  [ -d "$src_dir/commands" ] && cp -r "$src_dir/commands" "$SKILL_DIR/"
+
+  # Other-language overrides live under i18n/<lang>/. Runtime SKILL.md
+  # language detection switches to i18n/<lang>/SKILL.md when needed.
+  if [ -d "$src_dir/i18n" ]; then
     cp -r "$src_dir/i18n" "$SKILL_DIR/"
-    ok "Installed all 6 languages to $SKILL_DIR/i18n/"
-
-    # Set default language: always use English as the entry point
-    # Runtime language detection in SKILL.md will switch to i18n/{lang}/ as needed
-    if [ -d "$en_lang_dir" ]; then
-      cp "$en_lang_dir/SKILL.md" "$SKILL_DIR/"
-      cp -r "$en_lang_dir/references" "$SKILL_DIR/"
-      cp -r "$en_lang_dir/commands" "$SKILL_DIR/"
-    fi
-  else
-    # Legacy fallback: no i18n directory
-    cp "$src_dir/SKILL.md" "$SKILL_DIR/"
-    [ -d "$src_dir/references" ] && cp -r "$src_dir/references" "$SKILL_DIR/"
-    [ -d "$src_dir/commands" ] && cp -r "$src_dir/commands" "$SKILL_DIR/"
+    ok "Installed $(ls "$src_dir/i18n" | wc -l | tr -d ' ') additional language(s) under $SKILL_DIR/i18n/"
   fi
 
   # Sub-agents (language-agnostic — each agent's system prompt instructs it
-  # to reply in the orchestrator's language, so there is no per-language copy)
-  [ -d "$src_dir/agents" ] && cp -r "$src_dir/agents" "$SKILL_DIR/"
+  # to reply in the orchestrator's language, so there is no per-language copy).
+  # Install in two locations:
+  #   1. Inside the skill dir for bundling/inspection.
+  #   2. At ~/.claude/agents/ so Claude Code's Task tool can discover them
+  #      as `subagent_type` values. Without (2), `claude -p` and many
+  #      non-plugin install paths can't actually dispatch to specialists.
+  if [ -d "$src_dir/agents" ]; then
+    cp -r "$src_dir/agents" "$SKILL_DIR/"
+    mkdir -p "$HOME/.claude/agents"
+    cp "$src_dir/agents"/*.md "$HOME/.claude/agents/" 2>/dev/null || true
+  fi
 
   # Write version marker (semver from package.json for npm comparison)
   local pkg_version=""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "product-playbook",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "description": "MUST use when user wants to plan or strategize a product/feature. 22 PM frameworks, 6 modes, from idea to dev handoff",
   "bin": {
     "product-playbook": "./install.sh"
@@ -12,6 +12,7 @@
     "eval:zh-TW": "python3 evals/run_behavioral_eval.py --eval-file evals/evals-zh-TW.json --runs 3 --workers 2 --fail-on critical",
     "eval:quick": "python3 evals/run_behavioral_eval.py --runs 1 --workers 2 --fail-on critical",
     "eval:test": "python3 -m unittest evals.test_compute_eval_score",
+    "eval:debt": "python3 scripts/eval-debt-report.py",
     "bundle:claude-ai": "bash scripts/build-claude-ai-bundle.sh"
   },
   "keywords": [

package/references/00-opportunity-check.md

@@ -1,44 +1,44 @@
-# 前置：機會評估（Opportunity Check）
+# Pre-Step: Opportunity Check
 
-> **注意：各模式應執行哪些步驟，以 SKILL.md 中「各模式步驟序列」為權威定義。以下僅供參考。**
+> **Note: Which steps to execute per mode is authoritatively defined by the "Mode Step Sequences" in SKILL.md. The following is for reference only.**
 
-**適用於：完整模式、高完整性、產出對象為老闆/高層**
-**可跳過：快速模式、直接實作模式、產出對象為工程師/設計師**
+**Applicable: Full mode, high completeness, audience is executives/leadership**
+**Skippable: Quick mode, direct build mode, audience is engineers/designers**
 
-如果使用者是從頭開始做 0-to-1 產品，先通過這五個問題。任何一題答案是「否」都是需要重新思考的訊號：
+If the user is building a 0-to-1 product from scratch, run through these five questions first. A "no" on any question is a signal to rethink:
 
 ```
-| # | 評估問題 | 使用者答案 | 評估 |
-|---|----------|-----------|------|
-| 1 | 這是否在解決一個真實且急迫的用戶痛點？第一批受益的客戶是誰？你如何找到他們？ | | ✅/⚠️ |
-| 2 | 你是否有解決這個問題的獨特優勢？目標客戶是否至少每週會用到？市場夠大嗎？ | | ✅/⚠️ |
-| 3 | 以現有資源，能否在 2-3 年內做出可用的產品？ | | ✅/⚠️ |
-| 4 | 競爭格局如何？你能贏嗎？差異化優勢是什麼？ | | ✅/⚠️ |
-| 5 | 是否有可持續的用戶增長和商業化路徑？ | | ✅/⚠️ |
+| # | Assessment Question | User's Answer | Assessment |
+|---|---------------------|---------------|------------|
+| 1 | Does this solve a real, urgent user pain point? Who are the first customers to benefit? How will you find them? | | ✅/⚠️ |
+| 2 | Do you have a unique advantage in solving this problem? Will target customers use it at least weekly? Is the market large enough? | | ✅/⚠️ |
+| 3 | With current resources, can you build a usable product within 2-3 years? | | ✅/⚠️ |
+| 4 | What does the competitive landscape look like? Can you win? What's your differentiation? | | ✅/⚠️ |
+| 5 | Is there a sustainable path for user growth and monetization? | | ✅/⚠️ |
 ```
 
-## DHM 初步檢驗（Gibson Biddle / Netflix）
+## DHM Quick Check (Gibson Biddle / Netflix)
 
-這個機會是否能做到：
-- **D（Delight）**：讓用戶感到驚喜、超出預期？
-- **H（Hard to copy）**：競爭對手難以輕易複製？
-- **M（Margin-enhancing）**：隨著規模增長，邊際利潤能提升？
+Can this opportunity achieve:
+- **D (Delight)**: Surprise and exceed user expectations?
+- **H (Hard to copy)**: Be difficult for competitors to replicate?
+- **M (Margin-enhancing)**: Improve margins as scale grows?
 
-如果某些市場訊號尚不明確，尋找方向性訊號：
-- 宏觀趨勢（例：AI 普及帶來的工作流程替代機會）
-- 行為轉移（用戶已在用 workaround，代表需求真實存在）
-- 類比市場（找已驗證的相似場景）
+If some market signals are unclear, look for directional signals:
+- Macro trends (e.g., AI adoption creating workflow replacement opportunities)
+- Behavioral shifts (users already using workarounds, indicating real demand)
+- Analogous markets (find validated comparable scenarios)
 
-## 團隊熱情確認
+## Team Passion Check
 
-確認團隊對這個問題空間真的有熱情。缺乏內在驅動力的團隊在尋找 PMF 的路上必然倒下。
+Confirm the team has genuine passion for this problem space. Teams lacking intrinsic motivation will inevitably falter on the path to PMF.
 
 ---
 
-## 📎 本階段的檔案整合提示
+## 📎 File Integration Tips for This Stage
 
-| 上傳內容 | 整合到 | 整合動作 |
-|---------|-------|---------|
-| 市場報告（PDF） | 五個評估問題（#2 市場規模、#4 競爭格局） | 用報告數據替代假設性回答 |
-| 行業分析 / 趨勢報告 | DHM + 方向性訊號 | 提取宏觀趨勢和行為轉移作為 DHM 佐證 |
-| 競品融資/營收資訊 | 五個評估問題（#4、#5） | 評估競爭強度和市場驗證信號 |
+| Uploaded Content | Integrate Into | Integration Action |
+|-----------------|----------------|-------------------|
+| Market reports (PDF) | Five assessment questions (#2 market size, #4 competitive landscape) | Replace assumptions with report data |
+| Industry analysis / trend reports | DHM + directional signals | Extract macro trends and behavioral shifts as DHM evidence |
+| Competitor funding/revenue info | Five assessment questions (#4, #5) | Assess competitive intensity and market validation signals |