product-playbook 1.0.10 → 1.2.0

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.0.10",
+      "version": "1.2.0",
       "source": "./."
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,7 +1,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.0.10",
+  "version": "1.2.0",
   "author": {
     "name": "Charles Chen"
   },

package/README.es.md

@@ -182,8 +182,8 @@ product-playbook/
 | Modo | Pasos | Duración | Ideal para |
 |------|-------|----------|-----------|
 | 🚀 **Modo Rápido** | 3 pasos | ~30 min | Validación rápida de ideas, preparación de pitch |
-| 📦 **Modo Completo** | 20 pasos | Varias horas | Planificación de nuevo producto, grandes renovaciones |
-| 🔄 **Modo Revisión** | 12 pasos | 1-2 horas | Iteración sobre productos existentes |
+| 📦 **Modo Completo** | 9–11 pasos (8 Core + 1 Journey Map por defecto ON + 2 Optional por defecto OFF) | 1-2 horas | Planificación de nuevo producto, grandes renovaciones |
+| 🔄 **Modo Revisión** | 6–8 pasos (6 Core + 2 Optional) | <1 hora | Iteración sobre productos existentes |
 | ✏️ **Modo Personalizado** | 4-16 pasos | Variable | Llenar vacíos específicos |
 | ⚡ **Modo Build** | 7 pasos | ~1 hora | El problema es conocido, ir directo a soluciones |
 | 🔧 **Expansión de Funcionalidades** | 4 pasos | ~30 min | Agregar una sola funcionalidad a un producto existente |
@@ -280,6 +280,18 @@ Genera un paquete completo de handoff de desarrollo e inicia desarrollo en Claud
 > Por favor lee CLAUDE.md y TASKS.md, comienza ejecutando la Fase 0
 ```
 
+### 🪝 Hooks de Ciclo de Vida
+
+Tres hooks del plugin convierten las reglas centrales del playbook de "Claude debe recordarlas" a "el harness las aplica de forma determinista". Todos los hooks inyectan recordatorios suaves vía `systemMessage` — **ninguno bloquea al usuario**.
+
+| Evento | Disparador | Acción |
+|--------|-----------|--------|
+| `SessionStart` | Cada sesión nueva o reanudada | Inyecta automáticamente `.product-playbook-progress.md` y `.product-context.md` en el contexto del modelo, para que una sesión de planificación interrumpida se reanude exactamente desde el paso pausado |
+| `UserPromptSubmit` | Cada prompt durante una sesión de planificación activa | Detecta (a) prompts off-topic (debug / error / "arregla este código") y recuerda a Claude aplicar la regla de guardar progreso de SKILL.md; (b) palabras clave de intención de cambio (`改 step 2`, `update persona`, `rehacer JTBD`) y recuerda aplicar las reglas de Change Propagation |
+| `PreToolUse` (Write/Edit/MultiEdit) | Antes de cada escritura de archivo | Si el proyecto sigue en fase de planificación (sin marcador `.product-dev-active`) y el destino es código fuente (`.ts/.tsx/.py/.go/...`), recuerda a Claude que la planificación produce documentos, no código. El marcador se crea automáticamente al ejecutar `/product-dev` |
+
+Los hooks se cargan automáticamente desde `hooks/hooks.json` al instalar el plugin. Operan como no-op fuera de proyectos product-playbook, por lo que instalar el plugin no afecta a otros codebases.
+
 ### 📄 Importación y Exportación de Documentos
 
 **Importa** cualquier documento existente al flujo de planificación — sin copiar y pegar manualmente:
@@ -401,7 +413,7 @@ Comparando la calidad de respuesta entre "con guía del Skill" y "sin guía del
 
 - **Hard Gate de Autoevaluación de Calidad** (+100%): Si la IA critica proactivamente su propio output con estándares estrictos, señala brechas y exige mejoras después de completar un entregable — 0% de tasa de aprobación sin el Skill
 - **Context Bootstrap** (+100%): Si la IA recopila información foundacional del producto antes de comenzar a planificar, en lugar de saltar directamente a implementación técnica — completamente omitido sin el Skill
-- **Modo Expansión de Funcionalidades** (+83%): Si la IA reconoce escenarios de "agregar una funcionalidad a un producto existente" y activa un flujo simplificado de 4 pasos en lugar de los 7-12 pasos completos — sin el Skill, salta directamente a soluciones técnicas
+- **Modo Expansión de Funcionalidades** (+83%): Si la IA reconoce escenarios de "agregar una funcionalidad a un producto existente" y activa un flujo simplificado de 4 pasos en lugar de los 6-11 pasos completos — sin el Skill, salta directamente a soluciones técnicas
 - **Integración de Seguridad** (+75%): Si el handoff de desarrollo incluye arquitectura de seguridad, plantillas .gitignore y medidas de seguridad específicas de plataforma — sin el Skill, la seguridad se reduce a una tabla resumen
 
 > Ver [`evals/`](./evals/) para metodología detallada y datos.
@@ -428,7 +440,7 @@ cp -r product-playbook/commands/* ~/.claude/commands/
 | Comando | Descripción |
 |---------|-------------|
 | `/product-quick <descripción>` | Modo Rápido — recorre JTBD → PR-FAQ → North Star en menos de 30 min |
-| `/product-full <descripción>` | Modo Completo — plan de producto completo de 20 pasos |
+| `/product-full <descripción>` | Modo Completo — plan de producto completo (9–11 pasos; Journey Map por defecto ON) |
 | `/product-revision <descripción>` | Modo Revisión — iterar y optimizar un producto existente |
 | `/product-build <descripción>` | Modo Build — omitir Discovery, ir directo a soluciones |
 | `/product-feature <descripción>` | Modo Extensión — añade una funcionalidad a un producto existente (4 pasos) |

package/README.ja.md

@@ -183,8 +183,8 @@ product-playbook/
 | モード | ステップ | 所要時間 | 最適な用途 |
 |------|-------|----------|----------|
 | 🚀 **クイックモード** | 3ステップ | 約30分 | 迅速なアイデア検証、ピッチ準備 |
-| 📦 **フルモード** | 20ステップ | 数時間 | 新プロダクト企画、大規模リニューアル |
-| 🔄 **リビジョンモード** | 12ステップ | 1-2時間 | 既存プロダクトの改善 |
+| 📦 **フルモード** | 9–11ステップ（8 Core + 1 デフォルト ON Journey Map + 2 デフォルト OFF Optional） | 1-2時間 | 新プロダクト企画、大規模リニューアル |
+| 🔄 **リビジョンモード** | 6–8ステップ（6 Core + 2 Optional） | <1時間 | 既存プロダクトの改善 |
 | ✏️ **カスタムモード** | 4-16ステップ | 場合による | 特定のギャップを埋める |
 | ⚡ **ビルドモード** | 7ステップ | 約1時間 | 問題は既知、ソリューションに直行 |
 | 🔧 **機能拡張** | 4ステップ | 約30分 | 既存プロダクトに単一機能を追加 |
@@ -281,6 +281,18 @@ MVPを修正 → User Stories、DBスキーマ、プロダクトスペックサ
 > CLAUDE.mdとTASKS.mdを読んで、Phase 0の実行を開始してください
 ```
 
+### 🪝 ライフサイクルフック
+
+3つのプラグインフックで、Playbook の中核ルールを「Claude の記憶頼み」から「ハーネスによる強制実行」へ昇格させます。すべてのフックは `systemMessage` によるソフトリマインダーを注入するのみで、**ユーザーを止めることはありません**。
+
+| イベント | トリガー | 役割 |
+|---------|---------|------|
+| `SessionStart` | 新規 / 再開セッションごと | `.product-playbook-progress.md` と `.product-context.md` を自動でモデルの context に注入し、中断した企画を直前のステップから途切れなく再開 |
+| `UserPromptSubmit` | 企画進行中のプロンプト送信ごと | (a) 脱線メッセージ（debug / エラー / "このコード直して"）を検出して SKILL.md の進捗保存ルールを実行するよう Claude に指示。(b) 変更意図キーワード（`改 step 2`、`update persona`、`JTBD やり直し`）を検出して Change Propagation ルールの適用を促す |
+| `PreToolUse` (Write/Edit/MultiEdit) | ファイル書き込み前 | プロジェクトが企画フェーズ（`.product-dev-active` マーカー無し）で、対象がソースコード拡張子（`.ts/.tsx/.py/.go/...`）の場合、「企画はドキュメントのみ、コードは生成しない」と Claude にリマインド。マーカーは `/product-dev` 実行時に自動生成 |
+
+フックはプラグインインストール時に `hooks/hooks.json` から自動ロードされます。product-playbook プロジェクト外では完全に no-op で動作するため、他のコードベースへの影響はありません。
+
 ### 📄 ドキュメントインポート＆エクスポート
 
 **インポート** — 既存のドキュメントを企画フローに直接取り込み、手動コピペ不要：
@@ -402,7 +414,7 @@ Claude Codeは自動的に：
 
 - **品質セルフチェック ハードゲート**（+100%）：AIが成果物完成後に厳格な基準で自発的に自身の出力を批評し、ギャップを指摘し、改善を求めるかどうか — スキルなしでは合格率0%
 - **Context Bootstrap**（+100%）：AIが企画を始める前に基礎的なプロダクト情報を収集するか、それとも技術的実装にすぐ飛び込むか — スキルなしでは完全にスキップ
-- **機能拡張モード**（+83%）：AIが「既存プロダクトへの機能追加」シナリオを認識し、フルの7-12ステップではなく効率化された4ステップフローを起動するか — スキルなしでは技術ソリューションに直行
+- **機能拡張モード**（+83%）：AIが「既存プロダクトへの機能追加」シナリオを認識し、フルの6-11ステップではなく効率化された4ステップフローを起動するか — スキルなしでは技術ソリューションに直行
 - **セキュリティ統合**（+75%）：開発ハンドオフにセキュリティアーキテクチャ、.gitignoreテンプレート、プラットフォーム固有のセキュリティ対策が含まれるか — スキルなしではセキュリティは単一のサマリー表に縮小
 
 > 詳細な方法論とデータは[`evals/`](./evals/)を参照。
@@ -429,7 +441,7 @@ cp -r product-playbook/commands/* ~/.claude/commands/
 | コマンド | 説明 |
 |---------|-------------|
 | `/product-quick <説明>` | クイックモード — JTBD → PR-FAQ → North Starを30分以内で実行 |
-| `/product-full <説明>` | フルモード — 20ステップの完全なプロダクト企画 |
+| `/product-full <説明>` | フルモード — 完全なプロダクト企画（9–11ステップ；Journey Map デフォルト ON） |
 | `/product-revision <説明>` | リビジョンモード — 既存プロダクトの改善と最適化 |
 | `/product-build <説明>` | ビルドモード — ディスカバリーをスキップ、ソリューションに直行 |
 | `/product-feature <説明>` | 機能拡張モード — 既存プロダクトに単一機能を追加（4ステップ） |

package/README.ko.md

@@ -182,8 +182,8 @@ product-playbook/
 | 모드 | 단계 | 소요 시간 | 적합한 경우 |
 |------|------|---------|-----------|
 | 🚀 **퀵 모드** | 3단계 | ~30분 | 빠른 아이디어 검증, 피칭 준비 |
-| 📦 **풀 모드** | 20단계 | 수 시간 | 신규 제품 기획, 대규모 개편 |
-| 🔄 **리비전 모드** | 12단계 | 1-2시간 | 기존 제품 반복 개선 |
+| 📦 **풀 모드** | 9–11단계 (8 Core + 1 기본 ON Journey Map + 2 기본 OFF Optional) | 1-2시간 | 신규 제품 기획, 대규모 개편 |
+| 🔄 **리비전 모드** | 6–8단계 (6 Core + 2 Optional) | <1시간 | 기존 제품 반복 개선 |
 | ✏️ **커스텀 모드** | 4-16단계 | 다양 | 특정 부분 보완 |
 | ⚡ **빌드 모드** | 7단계 | ~1시간 | 문제가 명확한 경우, 솔루션으로 바로 |
 | 🔧 **기능 확장** | 4단계 | ~30분 | 기존 제품에 단일 기능 추가 |
@@ -280,6 +280,18 @@ MVP 수정  → User Stories, DB Schema, 제품 스펙 요약 자동 업데이
 > CLAUDE.md와 TASKS.md를 읽고, Phase 0 실행 시작
 ```
 
+### 🪝 라이프사이클 훅
+
+세 개의 플러그인 훅이 Playbook의 핵심 규칙을 "Claude가 알아서 기억"에서 "하네스가 강제 실행"으로 끌어올립니다. 모든 훅은 `systemMessage` 형태의 소프트 리마인더만 주입하며, **사용자를 막지 않습니다**.
+
+| 이벤트 | 트리거 시점 | 역할 |
+|--------|------------|------|
+| `SessionStart` | 새 세션 또는 재개 시마다 | `.product-playbook-progress.md`와 `.product-context.md`를 자동으로 모델 context에 주입하여, 중단된 기획을 직전 단계에서 매끄럽게 이어가도록 함 |
+| `UserPromptSubmit` | 기획 진행 중 프롬프트 제출마다 | (a) 주제 이탈 메시지(debug / 에러 / "이 코드 고쳐주세요")를 감지해 SKILL.md의 진행 상황 저장 규칙을 따르도록 Claude에 지시. (b) 변경 의도 키워드(`改 step 2`, `update persona`, `JTBD 다시 작성`)를 감지해 Change Propagation 규칙 적용을 환기 |
+| `PreToolUse` (Write/Edit/MultiEdit) | 파일 쓰기 전마다 | 프로젝트가 기획 단계(`.product-dev-active` 마커 없음)이고 대상이 소스 코드 확장자(`.ts/.tsx/.py/.go/...`)일 경우, "기획은 문서만 생성, 코드는 생성하지 않는다"는 원칙을 Claude에 리마인드. 마커는 `/product-dev` 실행 시 자동 생성됨 |
+
+훅은 플러그인 설치 시 `hooks/hooks.json`에서 자동 로드됩니다. product-playbook 프로젝트가 아닌 곳에서는 완전히 no-op이므로 다른 codebase에 영향을 주지 않습니다.
+
 ### 📄 문서 가져오기 및 내보내기
 
 **가져오기** — 기존 문서를 기획 플로우에 직접 투입, 수동 복사 붙여넣기 불필요:
@@ -401,7 +413,7 @@ Claude Code가 자동으로:
 
 - **품질 자체 점검 하드 게이트** (+100%): AI가 납품물 완성 후 엄격한 기준으로 자체 산출물을 비판하고, 갭을 지적하며, 개선을 요구하는지 여부 — 스킬 없이는 0% 통과율
 - **Context Bootstrap** (+100%): AI가 기획을 시작하기 전에 기초 제품 정보를 수집하는지, 기술 구현으로 바로 뛰어들지 않는지 — 스킬 없이는 완전히 건너뜀
-- **기능 확장 모드** (+83%): AI가 "기존 제품에 기능 추가" 시나리오를 인식하고 전체 7-12단계 대신 간소화된 4단계 플로우를 활성화하는지 — 스킬 없이는 기술 솔루션으로 바로 점프
+- **기능 확장 모드** (+83%): AI가 "기존 제품에 기능 추가" 시나리오를 인식하고 전체 6-11단계 대신 간소화된 4단계 플로우를 활성화하는지 — 스킬 없이는 기술 솔루션으로 바로 점프
 - **보안 통합** (+75%): 개발 핸드오프에 보안 아키텍처, .gitignore 템플릿, 플랫폼별 보안 조치가 포함되는지 — 스킬 없이는 보안이 단일 요약 테이블로 축소
 
 > 상세한 방법론과 데이터는 [`evals/`](./evals/)를 참조하세요.
@@ -428,7 +440,7 @@ cp -r product-playbook/commands/* ~/.claude/commands/
 | 명령 | 설명 |
 |------|------|
 | `/product-quick <설명>` | 퀵 모드 — JTBD → PR-FAQ → North Star를 30분 이내 실행 |
-| `/product-full <설명>` | 풀 모드 — 완전한 20단계 제품 기획 |
+| `/product-full <설명>` | 풀 모드 — 완전한 제품 기획 (9–11단계; Journey Map 기본 ON) |
 | `/product-revision <설명>` | 리비전 모드 — 기존 제품 반복 최적화 |
 | `/product-build <설명>` | 빌드 모드 — 디스커버리 건너뛰고 솔루션으로 바로 |
 | `/product-feature <설명>` | 기능 확장 모드 — 기존 제품에 단일 기능 추가 (4단계) |

package/README.md

@@ -182,8 +182,8 @@ product-playbook/
 | Mode | Steps | Duration | Best for |
 |------|-------|----------|----------|
 | 🚀 **Quick Mode** | 3 steps | ~30 min | Rapid idea validation, pitch prep |
-| 📦 **Full Mode** | 20 steps | Several hours | New product planning, major revamps |
-| 🔄 **Revision Mode** | 12 steps | 1-2 hours | Iterating on existing products |
+| 📦 **Full Mode** | 9–11 steps (8 Core + 1 Default-ON Journey Map + 2 Default-OFF Optionals) | 1-2 hours | New product planning, major revamps |
+| 🔄 **Revision Mode** | 6–8 steps (6 Core + 2 Optional) | <1 hour | Iterating on existing products |
 | ✏️ **Custom Mode** | 4-16 steps | Varies | Filling specific gaps |
 | ⚡ **Build Mode** | 7 steps | ~1 hour | Problem is known, jump to solutions |
 | 🔧 **Feature Expansion** | 4 steps | ~30 min | Adding a single feature to an existing product |
@@ -280,6 +280,18 @@ Generate a complete dev handoff package and kick off Claude Code development wit
 > Please read CLAUDE.md and TASKS.md, start executing Phase 0
 ```
 
+### 🪝 Lifecycle Hooks
+
+Three plugin hooks turn the playbook's core rules from "Claude needs to remember" into harness-enforced behavior. All hooks emit advisory `systemMessage` reminders — none of them block the user.
+
+| Event | Trigger | What it does |
+|-------|---------|--------------|
+| `SessionStart` | Every new / resumed session | Auto-injects `.product-playbook-progress.md` and `.product-context.md` into the model's context so a planning session resumes from the exact step it was paused at. |
+| `UserPromptSubmit` | Each user prompt during an active planning session | Detects (a) off-topic prompts (debug / error / "fix this code") and reminds Claude to follow the off-topic save-progress rule, and (b) change-intent keywords (`改 step 2`, `update persona`, `重做 JTBD`) and reminds Claude to apply the Change Propagation rules. |
+| `PreToolUse` (Write/Edit/MultiEdit) | Each file-write attempt | If the project is still in planning mode (no `.product-dev-active` marker) and the target is a source-code file (`.ts/.tsx/.py/.go/...`), reminds Claude that planning produces docs, not code. The marker is auto-created when `/product-dev` runs. |
+
+Hooks are auto-loaded from `hooks/hooks.json` when the plugin is installed. They no-op outside playbook projects, so installing the plugin has zero effect on unrelated codebases.
+
 ### 📄 Document Import & Export
 
 **Import** any existing document into the planning flow — no manual copy-paste:
@@ -401,7 +413,7 @@ By comparing response quality between "with Skill guidance" and "without Skill g
 
 - **Quality Self-check Hard Gate** (+100%): Whether the AI proactively critiques its own output with strict standards, flags gaps, and demands improvement after completing a deliverable — 0% pass rate without the Skill
 - **Context Bootstrap** (+100%): Whether the AI collects foundational product information before starting to plan, rather than jumping straight into technical implementation — completely skipped without the Skill
-- **Feature Expansion Mode** (+83%): Whether the AI recognizes "adding a feature to an existing product" scenarios and activates a streamlined 4-step flow instead of the full 7-12 steps — without the Skill, it jumps straight to technical solutions
+- **Feature Expansion Mode** (+83%): Whether the AI recognizes "adding a feature to an existing product" scenarios and activates a streamlined 4-step flow instead of the full 6-11 steps — without the Skill, it jumps straight to technical solutions
 - **Security Integration** (+75%): Whether the dev handoff includes security architecture, .gitignore templates, and platform-specific security measures — without the Skill, security is reduced to a single summary table
 
 > See [`evals/`](./evals/) for detailed methodology and data.
@@ -428,7 +440,7 @@ cp -r product-playbook/commands/* ~/.claude/commands/
 | Command | Description |
 |---------|-------------|
 | `/product-quick <description>` | Quick Mode — run through JTBD → PR-FAQ → North Star in under 30 min |
-| `/product-full <description>` | Full Mode — complete 20-step product plan |
+| `/product-full <description>` | Full Mode — comprehensive plan (9–11 steps; Journey Map default ON) |
 | `/product-revision <description>` | Revision Mode — iterate and optimize an existing product |
 | `/product-build <description>` | Build Mode — skip Discovery, jump straight to solutions |
 | `/product-feature <description>` | Feature Extension — add a single feature to an existing product (4 steps) |

package/README.zh-CN.md

@@ -182,8 +182,8 @@ product-playbook/
 | 模式 | 步骤数 | 耗时 | 适合情境 |
 |------|--------|------|---------|
 | 🚀 **快速模式** | 3 步 | ~30 分钟 | 快速验证想法、准备简报 |
-| 📦 **完整模式** | 20 步 | 数小时 | 新产品规划、重大改版 |
-| 🔄 **改版模式** | 12 步 | 1-2 小时 | 既有产品改版优化 |
+| 📦 **完整模式** | 9–11 步(8 Core + 1 预设启用 Journey Map + 2 预设停用 Optional) | 1-2 小时 | 新产品规划、重大改版 |
+| 🔄 **改版模式** | 6–8 步(6 Core + 2 Optional) | <1 小时 | 既有产品改版优化 |
 | ✏️ **自订模式** | 4-16 步 | 依选择 | 补足特定环节 |
 | ⚡ **直接实作** | 7 步 | ~1 小时 | 问题已知，直接进解法 |
 | 🔧 **功能扩充** | 4 步 | ~30 分钟 | 既有产品加单一功能 |
@@ -280,6 +280,18 @@ product-playbook/
 > 请读取 CLAUDE.md 和 TASKS.md，开始执行 Phase 0
 ```
 
+### 🪝 生命周期 Hooks
+
+三个 plugin hook 将 playbook 的核心规则从「靠 Claude 自己记得」转为「由 harness 强制执行」。所有 hook 只注入 `systemMessage` 软提醒，**不阻挡用户**。
+
+| 事件 | 触发时机 | 作用 |
+|------|---------|------|
+| `SessionStart` | 每次新 session 或 resume | 自动将 `.product-playbook-progress.md` 与 `.product-context.md` 注入模型 context，让中断的规划从原步骤无缝接续 |
+| `UserPromptSubmit` | 规划进行中每次提交 prompt | 检测（a）离题消息（debug / 错误 / "帮我改 code"）→ 提醒 Claude 执行 SKILL.md 的存档规则；（b）变更意图关键字（`改 step 2`、`update persona`、`重做 JTBD`）→ 提醒套用 Change Propagation 规则 |
+| `PreToolUse` (Write/Edit/MultiEdit) | 每次写文件前 | 若项目仍在规划阶段（无 `.product-dev-active` 标记）且目标是源代码后缀（`.ts/.tsx/.py/.go/...`），提醒 Claude「规划只产文档、不产 code」。`/product-dev` 执行时会自动建立该标记 |
+
+Hooks 由 `hooks/hooks.json` 在 plugin 安装时自动加载。在非 product-playbook 项目中完全 no-op，安装 plugin 不会影响其他 codebase。
+
 ### 📄 文档导入与导出
 
 **导入**任何现有文档到规划流程中 — 无需手动复制粘贴：
@@ -401,7 +413,7 @@ Claude Code 会自动：
 
 - **品质自检 Hard Gate**（+100%）：AI 在完成产出后，是否会主动以严格标准批判自己的输出、标记不足并要求改进——无 Skill 时通过率为 0%
 - **Context Bootstrap**（+100%）：首次使用时是否会先收集产品基础资讯再开始规划，而非直接跳入技术实作——无 Skill 时完全跳过此步骤
-- **功能扩充模式**（+83%）：是否能识别「在既有产品上加功能」的场景，启用 4 步精简流程而非完整 7-12 步——无 Skill 时直接输出技术方案
+- **功能扩充模式**(+83%):是否能识别「在既有产品上加功能」的场景,启用 4 步精简流程而非完整 6-11 步——无 Skill 时直接输出技术方案
 - **安全性整合**（+75%）：开发交接包是否包含安全架构、.gitignore 模板、平台特定安全措施——无 Skill 时安全性仅占一个简表
 
 > 详细评测方法与数据见 [`evals/`](./evals/) 目录。
@@ -428,7 +440,7 @@ cp -r product-playbook/commands/* ~/.claude/commands/
 | 指令 | 说明 |
 |------|------|
 | `/product-quick <描述>` | 快速模式 — 30 分钟内跑完 JTBD → PR-FAQ → North Star |
-| `/product-full <描述>` | 完整模式 — 完整 20 步产品企划 |
+| `/product-full <描述>` | 完整模式 — 完整产品企划(9–11 步;Journey Map 预设启用) |
 | `/product-revision <描述>` | 改版模式 — 既有产品改版优化 |
 | `/product-build <描述>` | 直接实作模式 — 跳过 Discovery，直接进解法 |
 | `/product-feature <描述>` | 功能扩展模式 — 在现有产品新增单一功能（4 步） |

package/README.zh-TW.md

@@ -182,8 +182,8 @@ product-playbook/
 | 模式 | 步驟數 | 耗時 | 適合情境 |
 |------|--------|------|---------|
 | 🚀 **快速模式** | 3 步 | ~30 分鐘 | 快速驗證想法、準備簡報 |
-| 📦 **完整模式** | 20 步 | 數小時 | 新產品規劃、重大改版 |
-| 🔄 **改版模式** | 12 步 | 1-2 小時 | 既有產品改版優化 |
+| 📦 **完整模式** | 9–11 步(8 Core + 1 預設啟用 Journey Map + 2 預設停用 Optional) | 1-2 小時 | 新產品規劃、重大改版 |
+| 🔄 **改版模式** | 6–8 步(6 Core + 2 Optional) | <1 小時 | 既有產品改版優化 |
 | ✏️ **自訂模式** | 4-16 步 | 依選擇 | 補足特定環節 |
 | ⚡ **直接實作** | 7 步 | ~1 小時 | 問題已知，直接進解法 |
 | 🔧 **功能擴充** | 4 步 | ~30 分鐘 | 既有產品加單一功能 |
@@ -280,6 +280,18 @@ product-playbook/
 > 請讀取 CLAUDE.md 和 TASKS.md，開始執行 Phase 0
 ```
 
+### 🪝 生命週期 Hooks
+
+三個 plugin hook 將 playbook 的核心規則從「靠 Claude 自己記得」轉為「由 harness 強制執行」。所有 hook 只注入 `systemMessage` 軟提醒，**不阻擋使用者**。
+
+| 事件 | 觸發時機 | 作用 |
+|------|---------|------|
+| `SessionStart` | 每次新 session 或 resume | 自動將 `.product-playbook-progress.md` 與 `.product-context.md` 注入模型 context，讓中斷的規劃從原步驟無縫接續 |
+| `UserPromptSubmit` | 規劃進行中每次送出 prompt | 偵測（a）離題訊息（debug / 錯誤 / "幫我改 code"）→ 提醒 Claude 執行 SKILL.md 的存檔規則；（b）變更意圖關鍵字（`改 step 2`、`update persona`、`重做 JTBD`）→ 提醒套用 Change Propagation 規則 |
+| `PreToolUse` (Write/Edit/MultiEdit) | 每次寫檔前 | 若專案仍在規劃階段（無 `.product-dev-active` 標記）且目標是原始碼副檔名（`.ts/.tsx/.py/.go/...`），提醒 Claude「規劃只產文件、不產 code」。`/product-dev` 執行時會自動建立該標記 |
+
+Hooks 由 `hooks/hooks.json` 在 plugin 安裝時自動載入。在非 product-playbook 專案中完全 no-op，安裝 plugin 不會影響其他 codebase。
+
 ### 📄 文件匯入與匯出
 
 **匯入**任何現有文件到規劃流程中 — 無需手動複製貼上：
@@ -401,7 +413,7 @@ Claude Code 會自動：
 
 - **品質自檢 Hard Gate**（+100%）：AI 在完成產出後，是否會主動以嚴格標準批判自己的輸出、標記不足並要求改進——無 Skill 時通過率為 0%
 - **Context Bootstrap**（+100%）：首次使用時是否會先收集產品基礎資訊再開始規劃，而非直接跳入技術實作——無 Skill 時完全跳過此步驟
-- **功能擴充模式**（+83%）：是否能識別「在既有產品上加功能」的場景，啟用 4 步精簡流程而非完整 7-12 步——無 Skill 時直接輸出技術方案
+- **功能擴充模式**(+83%):是否能識別「在既有產品上加功能」的場景,啟用 4 步精簡流程而非完整 6-11 步——無 Skill 時直接輸出技術方案
 - **安全性整合**（+75%）：開發交接包是否包含安全架構、.gitignore 模板、平台特定安全措施——無 Skill 時安全性僅佔一個簡表
 
 > 詳細評測方法與數據見 [`evals/`](./evals/) 目錄。
@@ -428,7 +440,7 @@ cp -r product-playbook/commands/* ~/.claude/commands/
 | 指令 | 說明 |
 |------|------|
 | `/product-quick <描述>` | 快速模式 — 30 分鐘內跑完 JTBD → PR-FAQ → North Star |
-| `/product-full <描述>` | 完整模式 — 完整 20 步產品企劃 |
+| `/product-full <描述>` | 完整模式 — 完整產品企劃(9–11 步;Journey Map 預設啟用) |
 | `/product-revision <描述>` | 改版模式 — 既有產品改版優化 |
 | `/product-build <描述>` | 直接實作模式 — 跳過 Discovery，直接進解法 |
 | `/product-feature <描述>` | 功能擴充模式 — 在既有產品新增單一功能（4 步） |

package/SKILL.md

@@ -47,8 +47,8 @@ When the user triggers this skill, use a **progressive confirmation** approach
 Select a mode (enter a number or name), or just tell me about your product and I'll recommend the best mode:
 
 1. 🚀 **Quick Mode** — 3 steps, ~30 min (JTBD → PR-FAQ → North Star)
-2. 📦 **Full Mode** — 20 steps, comprehensive planning document
-3. 🔄 **Revision Mode** — 12 steps, optimize existing product
+2. 📦 **Full Mode** — 9–11 steps (8 Core + 1 Default-ON Journey + 2 Default-OFF Optionals; 8 if flow is too simple to map), comprehensive planning document
+3. 🔄 **Revision Mode** — 6–8 steps (6 Core + 2 Optional), optimize existing product
 4. ✏️ **Custom Mode** — Choose your own framework combination
 5. ⚡ **Build Mode** — 7 steps, skip Discovery, go straight to solution
 6. 🔧 **Feature Extension Mode** — 4 steps, add a feature to existing product
@@ -84,17 +84,17 @@ Who is this plan primarily for?
 | Mode | Description | Fixed Outputs | Best For |
 |------|-------------|---------------|----------|
 | 🚀 **Quick Mode** | Actionable direction in 30 min; three fixed steps, no skipping | ① JTBD Statement ② PR-FAQ ③ North Star Metric | Quick alignment, idea validation, preparing a pitch |
-| 📦 **Full Mode** | Run through all frameworks; produce a deliverable plan | All frameworks (see step sequence) | New product planning, major revamps |
-| 🔄 **Revision Mode** | Optimize an existing product with user data and a feature baseline | Current state analysis → Pain point synthesis → Solution → Validation | Feature revamps, UX optimization, product repositioning |
+| 📦 **Full Mode** | 8 Core + 1 Default-ON Journey Map + 2 Default-OFF Optionals; produces a deliverable plan | Strategy → Persona → **Journey Map (default ON)** → JTBD → Pain+HMW+Ranking → PR-FAQ → Solution Evaluation → MVP → North Star (+ optional Positioning, PMF/GTM/Validation) | New product planning, major revamps |
+| 🔄 **Revision Mode** | 6 Core steps + 2 Optional, baseline-aware | Current state + JTBD re-validation → Pain points → Pain+HMW+Ranking (+optional Positioning) → PR-FAQ (+optional Pre-mortem) → MVP → North Star + Validation | Feature revamps, UX optimization, product repositioning |
 | ✏️ **Custom Mode** | Choose your own framework combination or completeness level | User-specified | Filling in specific gaps |
 | ⚡ **Build Mode** | Skip Discovery, go straight to solutions | PR-FAQ + Pre-mortem + GEM/RICE + MVP + North Star | Problem is known; need fast execution |
 | 🔧 **Feature Extension Mode** | Add a single feature to an existing product; streamlined 4-step flow | Problem + Context → Three parallel solutions + AI recommendation → Risk assessment → Execution scope | Adding features to an existing product; clear feature requirements |
 
 ### 📊 Completeness Levels (Custom Mode only)
 
-**🔴 Low (Lean)**: JTBD Statement → One HMW → PR-FAQ → North Star (any step can be swapped)
-**🟡 Medium (Standard)**: Persona + JTBD → Pain Points + HMW + Positioning → Parallel Solutions + MVP → North Star + PMF + Product Spec Summary
-**🟢 High (Comprehensive)**: Medium + Journey Map + OST + Strategy Blocks + RICE + Pre-mortem + Hypothesis Validation
+**🔴 Low (Lean — 4 steps)**: JTBD Statement → One HMW → PR-FAQ → North Star (any step can be swapped)
+**🟡 Medium (Standard — 8 or 9 steps)**: Persona → **(Journey Map auto-inserted unless flow is too simple)** → JTBD → Pain+HMW+Ranking → Positioning → PR-FAQ → Solution Evaluation → MVP → North Star
+**🟢 High (Comprehensive — 11 steps)**: Standard + Strategy Diagnosis + **Journey Map (bundled with Persona, default ON)** + PMF/GTM/BM/Validation
 
 ### 👥 Target Audience
 
@@ -130,6 +130,23 @@ When product context read/write is triggered, read `references/rules-context.md`
 
 When the user asks to list frameworks or uses supplementary commands, read `references/rules-commands.md`.
 
+**For any mode that contains Optional steps (Full / Revision / Comprehensive Custom), read `references/rules-optional-trigger.md` for trigger conditions, the Persona-Journey bundling rule, and the Phase Decision Point output format.**
+
+---
+
+## 🔗 Global Rule: Persona-Journey Bundling
+
+**Whenever a mode includes a Persona step, Journey Map is included by DEFAULT in the very next step.** Persona defines Who; Journey Map describes the journey Who experiences. This applies equally to 0-to-1 and existing products — the relevant variable is whether the user's Job spans multiple stages, not whether the product already exists. (Teresa Torres, Indi Young, and Amazon Working Backwards all treat Journey Map as essential during 0-to-1.)
+
+Skip Journey Map only when one of the following holds:
+1. **Single interaction point** — the Job is solved by a single API call, single button, backend service, or pure config tool
+2. **Flow is only 1–2 steps** — too short for stage transitions; Journey Map degenerates into a list
+3. **User explicitly requests skip** — e.g., "skip Journey Map"
+
+When skipping, surface the decision rather than silently dropping it: *"Persona is complete. Based on context ([single interaction point / flow has only N steps]), Journey Map is being skipped. Reply 'add journey' to add it back."*
+
+Full skip logic, Custom Mode conditional insert behavior, and Phase Decision Point format live in `references/rules-optional-trigger.md`.
+
 ---
 
 ## Startup Flow

package/commands/product-dev.md

@@ -10,12 +10,15 @@ Then read the following reference files in order:
 
 Based on the product planning content completed in the current conversation, generate the full dev handoff package:
 1. Confirm the tech stack (if not specified by the user, recommend one based on product characteristics)
-2. Generate CLAUDE.md (Claude Code project memory)
-3. Generate TASKS.md (feature breakdown + phased releases + acceptance criteria)
-4. Generate TICKETS.md (ticket list)
-5. Generate docs/ARCHITECTURE.md (directory structure + DB Schema + API Endpoints)
-6. Generate docs/PRD.md + docs/PRODUCT-SPEC.md
-7. Generate scripts/setup.sh (one-click initialization)
-8. Display Claude Code transition guide
+2. Create the `.product-dev-active` marker file at the project root (empty file). This signals the plugin's PreToolUse hook that the project has officially entered the dev-handoff phase, so subsequent source-code writes are no longer gated.
+3. Generate CLAUDE.md (Claude Code project memory)
+4. Generate TASKS.md (feature breakdown + phased releases + acceptance criteria)
+5. Generate TICKETS.md (ticket list)
+6. Generate docs/ARCHITECTURE.md (directory structure + DB Schema + API Endpoints)
+7. Generate docs/PRD.md + docs/PRODUCT-SPEC.md
+8. Generate scripts/setup.sh (one-click initialization)
+9. Display Claude Code transition guide
 
 If no product planning content exists in the conversation, prompt the user to run a product planning flow first.
+
+Note: `.product-dev-active` is a session-local marker (gitignored by the plugin). Delete it if the project ever returns to planning-only mode.

package/commands/product-full.md

@@ -1,5 +1,5 @@
 ---
-description: Full Mode Product Planning — Run through all 20 steps across every framework, producing deliverable planning documents
+description: Full Mode Product Planning — Run 8 Core + up to 3 Optional steps (8–11 total) across the most relevant frameworks, producing deliverable planning documents
 argument-hint: <product description>
 ---
 
@@ -10,4 +10,4 @@ When executing each step, load the corresponding reference files as indicated in
 Execution mode: Full Mode
 Product description: $ARGUMENTS
 
-Follow the step sequence in rules-full.md (S1 → S20). First confirm the product type (B2B/B2C) and target audience, then begin the first step. Display a progress indicator at each step.
+Follow the step sequence in rules-full.md (S1 → S11, with Optional steps gated by triggers in rules-optional-trigger.md). First confirm the product type (B2B/B2C) and target audience, then begin the first step. Render a Phase Decision Point block before any phase that contains Optional steps, and display a progress indicator at each step.

package/commands/product-revision.md

@@ -10,4 +10,4 @@ When executing each step, load the corresponding reference files as indicated in
 Execution mode: Revision Mode
 Product description: $ARGUMENTS
 
-Follow the step sequence in rules-revision.md (S1 → S12). S1 will proactively ask about existing product metrics (DAU/MAU, retention rate, key user feedback, etc.). Display a progress indicator at each step.
+Follow the step sequence in rules-revision.md (S1 → S8, with Optional steps gated by triggers in rules-optional-trigger.md). S1 will proactively ask about existing product metrics (DAU/MAU, retention rate, key user feedback, etc.). Render a Phase Decision Point block before any phase that contains Optional steps, and display a progress indicator at each step.

package/hooks/hooks.json

@@ -0,0 +1,40 @@
+{
+  "description": "product-playbook hooks: auto-load planning state, detect off-topic / change-propagation prompts, and gate code-file writes during the planning phase.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session-start-load-progress.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-detect-topic-switch.py",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre-write-planning-gate.py",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/pre-write-planning-gate.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: gate code-file writes during the planning phase.
+
+The product-playbook plugin draws a hard line between PLANNING (produces
+docs) and DEVELOPMENT (produces code). Until the user runs `/product-dev`
+to enter the dev-handoff phase — which creates a `.product-dev-active`
+marker file — Claude should not be writing source code.
+
+This hook fires on Write / Edit / MultiEdit. If:
+  • a planning session is in progress (progress file exists, not complete)
+  • AND the dev-active marker is absent
+  • AND the target path looks like source code
+
+…it injects an advisory `systemMessage` reminding Claude to finish
+planning first. The hook does NOT block the tool call (permissionDecision
+remains unset / allowed) so the user retains an explicit override path.
+
+Doc/text files (.md, .txt, .json, etc.) are always allowed — those are
+expected planning artifacts.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+CODE_EXTENSIONS = {
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+    ".py", ".rb", ".php", ".go", ".rs", ".java", ".kt",
+    ".swift", ".cs", ".cpp", ".cc", ".c", ".h", ".hpp",
+    ".vue", ".svelte", ".scala", ".dart", ".m", ".mm",
+}
+
+WATCHED_TOOLS = {"Write", "Edit", "MultiEdit"}
+
+
+def _planning_in_progress(progress_file: Path) -> bool:
+    if not progress_file.is_file():
+        return False
+    try:
+        body = progress_file.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return False
+    lowered = body.lower()
+    if "status: complete" in lowered or "status：complete" in lowered:
+        return False
+    if re.search(r"status\s*[:：]\s*completed", lowered):
+        return False
+    return True
+
+
+def _target_path(tool_name: str, tool_input: dict) -> str | None:
+    if not isinstance(tool_input, dict):
+        return None
+    return tool_input.get("file_path") or tool_input.get("path")
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+
+    tool_name = payload.get("tool_name")
+    if tool_name not in WATCHED_TOOLS:
+        return 0
+
+    cwd = Path(payload.get("cwd") or os.getcwd())
+
+    # Dev phase active → silent passthrough.
+    if (cwd / ".product-dev-active").is_file():
+        return 0
+
+    if not _planning_in_progress(cwd / ".product-playbook-progress.md"):
+        return 0
+
+    target = _target_path(tool_name, payload.get("tool_input") or {})
+    if not target:
+        return 0
+
+    suffix = Path(target).suffix.lower()
+    if suffix not in CODE_EXTENSIONS:
+        return 0
+
+    message = (
+        f"[product-playbook] Heads-up: '{target}' looks like source code, "
+        "but this project is still in the PLANNING phase (no "
+        "`.product-dev-active` marker). The plugin's contract is "
+        "planning-produces-docs, dev-produces-code. Recommended: finish "
+        "the current mode's remaining steps, then run `/product-dev` to "
+        "enter the dev-handoff phase. If the user has explicitly asked "
+        "for code now, acknowledge the override and proceed."
+    )
+    json.dump({"systemMessage": message}, sys.stdout)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())