product-playbook 1.2.4 → 1.2.6

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.4",
+      "version": "1.2.5",
       "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.2.4",
+  "version": "1.2.5",
   "author": {
     "name": "Charles Chen"
   },

package/README.es.md

@@ -451,6 +451,101 @@ El consumo de tokens es prácticamente idéntico en ambos brazos (151K vs 154K)
 
 ---
 
+### Iteración 6: Pase de Optimización de Tokens (v1.2.5)
+
+Una iteración de reducción de tokens. Misma semántica del contenido del skill, menor huella por sesión. Objetivo: ≥25% de reducción de tokens manteniendo la calidad al 100%.
+
+**Cambios entregados:**
+- **SKILL.md adelgazado** — se extrajeron las Sub-Agent Delegation Rules al lazy `rules-subagent-dispatch.md`; se ajustaron las descripciones de Hard Gate; se consolidó la duplicación de Mode Overview. **6,188 → 2,877 tokens (-54%)** para el entry point eager.
+- **División de rules-context.md** — se mantuvo la lógica de decisión como eager (1,594 tokens); se movieron las plantillas YAML verbosas + procedimiento de Bootstrap + scripts de UX de conflicto al lazy `rules-context-template.md` (1,849 tokens, cargado sólo al activarse).
+- **rules-quality-review.md adelgazado** — destilado de 1,040 → 817 tokens con un protocolo compacto de 3 pasos + checklists de 1 línea por framework.
+- **Agentes especialistas adelgazados** — se removió el conocimiento de framework embebido que duplicaba `references/*.md`, reemplazado con punteros on-demand. **discovery-specialist −25%, strategy-critic −18%, pre-mortem-runner −20%** por despacho.
+
+**Ahorros estimados por sesión Full Mode de 9 pasos:**
+
+| Fuente | Antes | Después | Ahorrado |
+|--------|:------:|:-----:|:-----:|
+| Eager (SKILL + context + progress) | ~8,800 | ~5,500 | **−3,300** |
+| Quality review (×9 cargas por paso) | ~9,360 | ~7,353 | **−2,007** |
+| Despachos de sub-agent (3 especialistas) | ~9,005 | ~7,106 | **−1,899** |
+| **Total por sesión** | **~27,200** | **~18,900** | **−8,300 (−30%)** |
+
+**Validación de calidad:** pre-mortem-runner (el especialista más sensible a calidad según Iteración 5) re-ejecutó eval-12 sobre el contenido adelgazado de v1.2.5. Resultado: **9/9 assertions PASS** — 16 escenarios cubriendo las 5 categorías, 5 escenarios fundamentados en arquitectura citando componentes reales del stack, 5 experimentos pre-launch de bajo costo con reglas de decisión binaria, encuadre en tiempo pasado mantenido. Una verificación cruzada estática confirmó que las assertions de eval-10/11 (13 en total) tienen soporte explícito en los prompts adelgazados de los agentes.
+
+**Trade-off de costo de tokens:** la división añade 2 nuevos archivos lazy (`rules-subagent-dispatch.md` 978 tokens, `rules-context-template.md` 1,849 tokens) que sólo cargan al activarse. En las rutas de sesión más comunes, nunca cargan. En rutas de Bootstrap-o-Conflicto, los ahorros eager siguen siendo netos positivos.
+
+**Replicado a 5 locales i18n** (zh-TW, zh-CN, ja, es, ko) preservando las traducciones existentes — el adelgazamiento estructural se aplicó de manera idéntica por idioma.
+
+---
+
+## 🧪 Desarrollo y Evals
+
+El directorio `evals/` incluye dos suites de pruebas complementarias y un scorer determinista.
+
+**Local (gratis, recomendado)**: ejecuta los mismos scripts con el CLI `claude` autenticado con tu suscripción Claude Pro/Max (un solo `claude login`). Sin API key, sin costo marginal. El sistema de eval está diseñado para correr localmente antes de cada release.
+
+**CI (opcional, pago)**: `.github/workflows/eval-gate.yml` ejecuta ambas suites en cada PR y en cada push a `main` que cambie `package.json`, y reporta el puntaje en el Job Summary del workflow. **No bloquea merge ni publish** — el maintainer decide si actuar ante regresiones. CI requiere el secret `ANTHROPIC_API_KEY` (GitHub Actions no puede usar OAuth en un contenedor headless); sin el secret, los jobs de eval **se omiten limpiamente** (gris ⏭️) en lugar de fallar en rojo.
+
+### Ejecución local
+
+```bash
+# Recomendado: un comando ejecuta ambas suites
+npm run eval
+
+# O ejecuta cada una por separado
+npm run eval:trigger      # ~5–15 min — el skill se activa automáticamente?
+npm run eval:behavioral   # ~10–40 min — claude como assistant Y como judge
+npm run eval:zh-TW        # behavioral eval contra el set en zh-TW
+npm run eval:quick        # solo 1 corrida, sin mayoría (iteración rápida)
+npm run eval:test         # tests unitarios del scorer
+
+# Llamá los scripts Python directamente cuando necesites control fino:
+python3 evals/run_behavioral_eval.py --only 11        # debuggear un eval id
+python3 evals/run_behavioral_eval.py --fail-on none   # solo reporta, sin exit 1
+python3 evals/run_trigger_test.py --eval-file evals/trigger-eval-fuzzy.json
+```
+
+Los runs locales usan `--runs 3` por defecto (mayoría absorbe la variabilidad del LLM). El CLI `claude` usa tu sesión OAuth de Claude Pro/Max (`claude login`), sin costo por token. CI usa `--runs 1` y requiere el secret `ANTHROPIC_API_KEY`.
+
+### Severity y scoring
+
+Cada expectation en `evals.json` está etiquetada con una severity:
+
+| Severity | Deducción por fallo | Usado para |
+|---|---|---|
+| `critical` | −15 | Violaciones de Hard Gate, errores de mode-dispatch, separación buyer/user en B2B, defaults de seguridad, integridad de framework (3 capas de JTBD, diagnosis de Rumelt, 15+ escenarios de pre-mortem) |
+| `warning`  | −5  | Profundidad y estructura de calidad (la mayoría de expectations) |
+| `info`     | −1  | Detección de idioma, formato del indicador de progreso |
+
+El score empieza en 100, deduce por fallo, y se clampa a 0–100.
+
+| Banda | Rango | Significado |
+|---|---|---|
+| 🟢 `healthy` | ≥ 90 | Como máximo un fallo crítico |
+| 🟡 `needs-attention` | ≥ 70 | Hasta dos críticos o varios warnings |
+| 🔴 `at-risk` | < 70 | Tres o más críticos; el gate debería fallar |
+
+### Semántica de `--fail-on`
+
+| Valor del flag | El runner sale con código no-cero cuando… |
+|---|---|
+| `critical` | falla cualquier expectation critical (default en CI) |
+| `any` | falla cualquier expectation en cualquier severity |
+| `none` | nunca; modo informativo para exploración local |
+
+Toda la lógica de scoring vive en una sola fuente — `evals/compute_eval_score.py` — para que los dos runners no puedan divergir.
+
+### Checklist de release
+
+Antes de bumpear la versión en `package.json` (un push a `main` con `package.json` modificado dispara `npm publish`):
+
+1. `npm run eval` — obtené los puntajes actuales de trigger + behavioral
+2. Si falla algún **critical**, investigá y arreglá antes de publicar
+3. Si solo retrocedieron warnings o info → es decisión tuya; si aceptás la regresión, anotá el motivo en el commit
+4. Commiteá cualquier fix, bumpeá la versión, después `git push`
+
+---
+
 ## 💬 Comandos Disponibles
 
 ### ⌨️ Comandos Slash del CLI de Claude Code

package/README.ja.md

@@ -452,6 +452,101 @@ v1.2.0+ で導入された3つの専門 sub-agent（`discovery-specialist`、`st
 
 ---
 
+### イテレーション6：Token 最適化パス（v1.2.5）
+
+token 削減イテレーション。スキル内容のセマンティクスは同じで、セッションあたりのフットプリントを縮小。目標は品質を 100% に維持しながら 25% 以上の token 削減。
+
+**出荷した変更：**
+- **SKILL.md スリム化** — Sub-Agent Delegation Rules を lazy な `rules-subagent-dispatch.md` に抽出、Hard Gate の記述を簡潔化、Mode Overview の重複を統合。eager エントリポイントで **6,188 → 2,877 tokens（-54%）**。
+- **rules-context.md 分割** — 決定ロジックは eager のまま維持（1,594 tokens）、冗長な YAML テンプレート + Bootstrap 手順 + Conflict UX スクリプトを lazy な `rules-context-template.md`（1,849 tokens、トリガー時のみ読込）に移動。
+- **rules-quality-review.md スリム化** — 1,040 → 817 tokens に蒸留、コンパクトな 3 ステップのプロトコル + 各 framework 1 行のチェックリスト。
+- **Specialist agents スリム化** — `references/*.md` と重複していた framework 知識を削除し、on-demand のポインタに置換。dispatch あたり **discovery-specialist −25%、strategy-critic −18%、pre-mortem-runner −20%**。
+
+**9 ステップ Full Mode セッションあたりの推定削減：**
+
+| ソース | Before | After | 削減 |
+|--------|:------:|:-----:|:-----:|
+| Eager（SKILL + context + progress） | ~8,800 | ~5,500 | **−3,300** |
+| Quality review（×9 ステップロード） | ~9,360 | ~7,353 | **−2,007** |
+| Sub-agent dispatches（3 specialists） | ~9,005 | ~7,106 | **−1,899** |
+| **セッション合計** | **~27,200** | **~18,900** | **−8,300（−30%）** |
+
+**品質検証：** pre-mortem-runner（イテレーション 5 で最も品質感受性が高い specialist）が v1.2.5 のスリム化された内容で eval-12 を再実行。結果は **9/9 assertion PASS** — 全 5 カテゴリーにまたがる 16 シナリオ、実際のスタック構成要素を引用するアーキテクチャ根拠付きシナリオ 5 件、二項決定ルールを持つ低コスト pre-launch 実験 5 件、過去形の枠組みを維持。静的クロスチェックにより、スリム化された agent プロンプトにおいて eval-10/11 の assertion（合計 13 件）すべてに明示的な裏付けがあることを確認。
+
+**Token コストのトレードオフ：** 分割により、トリガー時のみ読み込まれる 2 つの新規 lazy ファイル（`rules-subagent-dispatch.md` 978 tokens、`rules-context-template.md` 1,849 tokens）が追加される。最も一般的なセッション経路ではこれらは読み込まれない。Bootstrap または Conflict 経路でも、eager の削減が依然としてネットでプラス。
+
+**5 つの i18n ロケール（zh-TW、zh-CN、ja、es、ko）にミラー** — 既存の翻訳を保持しつつ、構造的なスリム化を言語ごとに同一に適用。
+
+---
+
+## 🧪 開発と評価
+
+`evals/` ディレクトリには 2 つの補完的なテストセットと決定論的なスコアラーが含まれます。
+
+**ローカル（無料、推奨）**：`claude` CLI を Claude Pro/Max サブスクリプションで認証して（一度だけ `claude login`）同じスクリプトを実行できます。API key 不要、追加コストなし。eval システムは各リリース前にローカルで実行する設計です。
+
+**CI（オプション、有料）**：`.github/workflows/eval-gate.yml` はすべての PR と `package.json` を変更する `main` への push で両方を実行し、スコアを workflow の Job Summary に書き込みます。**merge も publish もブロックしません** — リグレッションに対応するかどうかはメンテナが判断します。CI には `ANTHROPIC_API_KEY` secret が必要です（GitHub Actions は headless コンテナで OAuth が使えません）。secret 未設定時は eval job が**クリーンに skip**（グレー ⏭️）され、誤解を招く赤バツは出ません。
+
+### ローカル実行
+
+```bash
+# 推奨：1 コマンドで両方を実行
+npm run eval
+
+# 個別に実行
+npm run eval:trigger      # ~5–15 分 — skill が自動トリガーされるか
+npm run eval:behavioral   # ~10–40 分 — claude を assistant 兼 judge として使用
+npm run eval:zh-TW        # zh-TW 評価セットで behavioral eval
+npm run eval:quick        # 1 回のみ実行、多数決なし（高速イテレーション）
+npm run eval:test         # スコアラーのユニットテスト
+
+# より細かい制御が必要な場合は、Python スクリプトを直接呼び出します：
+python3 evals/run_behavioral_eval.py --only 11        # 単一の eval id を debug
+python3 evals/run_behavioral_eval.py --fail-on none   # レポートのみ、exit 1 なし
+python3 evals/run_trigger_test.py --eval-file evals/trigger-eval-fuzzy.json
+```
+
+ローカルは `--runs 3` がデフォルト（多数決で LLM のばらつきを吸収）。`claude` CLI は Claude Pro/Max の OAuth セッション（`claude login`）を使うため、トークン課金はありません。CI は `--runs 1` で、`ANTHROPIC_API_KEY` secret が必要です。
+
+### Severity とスコアリング
+
+`evals.json` の各 expectation には severity がタグ付けされています：
+
+| Severity | 失敗時の減点 | 適用範囲 |
+|---|---|---|
+| `critical` | −15 | Hard Gate 違反、Mode dispatch エラー、B2B buyer/user 分離、Security default-on、フレームワークの完全性（JTBD 3 層、Rumelt diagnosis、pre-mortem 15+ シナリオ）|
+| `warning`  | −5  | 品質の深さと構造（多くの expectations）|
+| `info`     | −1  | 言語検出、Progress indicator フォーマット |
+
+100 点からスタート、失敗ごとに減点、0–100 にクランプ。
+
+| Band | 範囲 | 意味 |
+|---|---|---|
+| 🟢 `healthy` | ≥ 90 | critical 失敗は最大 1 つ |
+| 🟡 `needs-attention` | ≥ 70 | critical 2 つまで、または数個の warning |
+| 🔴 `at-risk` | < 70 | critical が 3 つ以上；gate 失敗の対象 |
+
+### `--fail-on` のセマンティクス
+
+| Flag 値 | Runner が exit non-zero になる条件 |
+|---|---|
+| `critical` | critical な expectation が 1 つでも失敗（CI デフォルト）|
+| `any` | severity 問わず任意の expectation が失敗 |
+| `none` | 失敗しない；ローカル探索用 informational mode |
+
+すべてのスコアリングロジックは `evals/compute_eval_score.py` という単一のソースに集約され、2 つの runner が独自実装で drift することを防ぎます。
+
+### リリース前チェックリスト
+
+`package.json` のバージョン bump 前（`main` への push で `package.json` が変わると `npm publish` が走ります）：
+
+1. `npm run eval` — 現在の trigger と behavioral スコアを取得
+2. **critical** な expectation が失敗 → 公開前に調査して修正
+3. warning や info のみが退化 → 判断次第。退化を受け入れる場合は commit にその理由を残す
+4. 修正があれば commit、バージョン bump、`git push`
+
+---
+
 ## 💬 利用可能なコマンド
 
 ### ⌨️ Claude Code CLIスラッシュコマンド

package/README.ko.md

@@ -451,6 +451,101 @@ v1.2.0+ 에서 도입된 3개의 전문 sub-agent (`discovery-specialist`, `stra
 
 ---
 
+### 반복 6: 토큰 최적화 패스 (v1.2.5)
+
+토큰 절감 반복. 스킬 콘텐츠의 시맨틱은 동일하게 유지하되, 세션당 footprint 를 축소. 목표: 품질 100% 를 유지하면서 토큰 ≥25% 감소.
+
+**적용된 변경 사항:**
+- **SKILL.md 슬림화** — Sub-Agent Delegation Rules 를 lazy `rules-subagent-dispatch.md` 로 추출, Hard Gate 설명을 축약, Mode Overview 의 중복을 통합. eager 진입점 기준 **6,188 → 2,877 tokens (-54%)**.
+- **rules-context.md 분할** — 의사결정 로직은 eager (1,594 tokens) 로 유지, 장문 YAML 템플릿 + Bootstrap 절차 + Conflict UX 스크립트는 lazy `rules-context-template.md` (1,849 tokens, 트리거 시에만 로드) 로 이동.
+- **rules-quality-review.md 슬림화** — 1,040 → 817 tokens 로 정제, 컴팩트한 3단계 프로토콜과 프레임워크당 1줄 체크리스트로 구성.
+- **전문가 에이전트 슬림화** — `references/*.md` 와 중복되던 임베디드 프레임워크 지식을 제거하고 온디맨드 포인터로 대체. dispatch 당 **discovery-specialist −25%, strategy-critic −18%, pre-mortem-runner −20%**.
+
+**9-step Full Mode 세션당 예상 절감:**
+
+| 출처 | Before | After | 절감 |
+|------|:------:|:-----:|:-----:|
+| Eager (SKILL + context + progress) | ~8,800 | ~5,500 | **−3,300** |
+| Quality review (×9 step loads) | ~9,360 | ~7,353 | **−2,007** |
+| Sub-agent dispatch (3개 전문가) | ~9,005 | ~7,106 | **−1,899** |
+| **세션당 합계** | **~27,200** | **~18,900** | **−8,300 (−30%)** |
+
+**품질 검증:** pre-mortem-runner (반복 5 기준 품질에 가장 민감한 전문가) 가 v1.2.5 슬림화된 콘텐츠로 eval-12 를 재실행. 결과: **9/9 assertions PASS** — 5개 카테고리 전체에 걸친 16개 시나리오, 실제 stack 컴포넌트를 인용하는 5개의 아키텍처 기반 시나리오, 이진 의사결정 규칙을 가진 5개의 저비용 pre-launch 실험, 과거형 프레이밍 유지. 정적 cross-check 로 eval-10/11 의 assertion (총 13개) 이 슬림화된 에이전트 프롬프트 안에서 모두 명시적으로 뒷받침됨을 확인.
+
+**토큰 비용 트레이드오프:** 분할로 인해 2개의 새 lazy 파일 (`rules-subagent-dispatch.md` 978 tokens, `rules-context-template.md` 1,849 tokens) 이 추가되며, 트리거 시에만 로드됨. 가장 흔한 세션 경로에서는 전혀 로드되지 않음. Bootstrap-or-Conflict 경로에서도 eager 절감분이 여전히 net positive.
+
+**5개 i18n 로케일 (zh-TW, zh-CN, ja, es, ko) 에 미러링** — 기존 번역을 보존하며, 구조적 슬림화는 언어별로 동일하게 적용.
+
+---
+
+## 🧪 개발 및 평가
+
+`evals/` 디렉터리는 두 가지 보완적 테스트 세트와 결정론적 스코어러를 포함합니다.
+
+**로컬 (무료, 권장)**: `claude` CLI를 Claude Pro/Max 구독으로 인증해서 (한 번만 `claude login`) 같은 스크립트를 실행합니다. API key 불필요, 추가 비용 없음. eval 시스템은 각 릴리스 전에 로컬에서 실행하도록 설계되었습니다.
+
+**CI (선택, 유료)**: `.github/workflows/eval-gate.yml`은 모든 PR과 `package.json`을 변경하는 `main`으로의 push에서 두 가지 모두 실행하고, 점수를 workflow Job Summary에 기록합니다. **merge도 publish도 차단하지 않습니다** — 회귀에 대응할지는 유지보수자가 판단합니다. CI는 `ANTHROPIC_API_KEY` secret이 필요합니다 (GitHub Actions는 headless 컨테이너에서 OAuth를 사용할 수 없습니다). secret 미설정 시 eval job은 **깨끗하게 skip**(회색 ⏭️)되며 오해를 일으키는 빨간색 X는 표시되지 않습니다.
+
+### 로컬 실행
+
+```bash
+# 권장: 한 명령으로 두 가지 모두 실행
+npm run eval
+
+# 개별 실행
+npm run eval:trigger      # ~5–15분 — skill이 자동 트리거되는가
+npm run eval:behavioral   # ~10–40분 — claude를 assistant 겸 judge로 사용
+npm run eval:zh-TW        # zh-TW 평가 세트로 behavioral eval
+npm run eval:quick        # 1회만 실행, 다수결 없음 (빠른 이터레이션)
+npm run eval:test         # 스코어러 단위 테스트
+
+# 더 세밀한 제어가 필요할 때 Python 스크립트를 직접 호출:
+python3 evals/run_behavioral_eval.py --only 11        # 단일 eval id 디버그
+python3 evals/run_behavioral_eval.py --fail-on none   # 보고만, exit 1 없음
+python3 evals/run_trigger_test.py --eval-file evals/trigger-eval-fuzzy.json
+```
+
+로컬은 `--runs 3`이 기본값(다수결로 LLM 변동성 흡수). `claude` CLI는 Claude Pro/Max OAuth 세션(`claude login`)을 사용하므로 토큰당 비용이 없습니다. CI는 `--runs 1`을 사용하며 `ANTHROPIC_API_KEY` secret이 필요합니다.
+
+### Severity 및 스코어링
+
+`evals.json`의 각 expectation에는 severity가 태그됩니다:
+
+| Severity | 실패 시 감점 | 적용 범위 |
+|---|---|---|
+| `critical` | −15 | Hard Gate 위반, Mode dispatch 오류, B2B buyer/user 분리, Security default-on, 프레임워크 완전성(JTBD 3계층, Rumelt diagnosis, pre-mortem 15+ 시나리오) |
+| `warning`  | −5  | 품질 깊이와 구조(대부분의 expectations) |
+| `info`     | −1  | 언어 감지, Progress indicator 형식 |
+
+100점에서 시작하여 실패당 차감, 0–100으로 클램프.
+
+| Band | 범위 | 의미 |
+|---|---|---|
+| 🟢 `healthy` | ≥ 90 | critical 실패 최대 1개 |
+| 🟡 `needs-attention` | ≥ 70 | critical 2개 이하 또는 다수의 warning |
+| 🔴 `at-risk` | < 70 | critical 3개 이상; gate 실패 대상 |
+
+### `--fail-on` 의미론
+
+| Flag 값 | Runner가 exit non-zero가 되는 조건 |
+|---|---|
+| `critical` | critical expectation이 하나라도 실패 (CI 기본값) |
+| `any` | severity와 관계없이 임의 expectation 실패 |
+| `none` | 절대 실패하지 않음; 로컬 탐색용 informational mode |
+
+모든 스코어링 로직은 `evals/compute_eval_score.py`라는 단일 소스에 집중되어 있어 두 runner가 독립적으로 구현하여 drift하는 것을 방지합니다.
+
+### 릴리스 체크리스트
+
+`package.json` 버전 bump 전 (`main`으로의 push가 `package.json` 변경 시 `npm publish`를 트리거):
+
+1. `npm run eval` — 현재 trigger와 behavioral 점수 확인
+2. **critical** expectation이 하나라도 실패하면 → 게시 전 조사 후 수정
+3. warning이나 info만 회귀 → 판단 사항. 회귀를 수용하면 commit에 이유 기록
+4. 수정 commit, 버전 bump, `git push`
+
+---
+
 ## 💬 사용 가능한 명령
 
 ### ⌨️ Claude Code CLI 슬래시 명령

package/README.md

@@ -449,6 +449,99 @@ Token cost is essentially identical across arms (151K vs 154K) — keeping a spe
 
 > Raw artifacts and per-assertion divergence in [`~/product-playbook-workspace/iteration-3/benchmark.md`](./evals/).
 
+### Iteration 6: Token Optimization Pass (v1.2.5)
+
+A token-reduction iteration. Same skill content semantics, smaller footprint per session. Goal: ≥25% token reduction while holding quality at 100%.
+
+**Changes shipped:**
+- **SKILL.md slim** — extracted Sub-Agent Delegation Rules to lazy `rules-subagent-dispatch.md`; tightened Hard Gate descriptions; consolidated Mode Overview duplication. **6,188 → 2,877 tokens (-54%)** for the eager entry point.
+- **rules-context.md split** — kept decision logic eager (1,594 tokens); moved verbose YAML templates + Bootstrap procedure + Conflict UX scripts to lazy `rules-context-template.md` (1,849 tokens, loaded only on trigger).
+- **rules-quality-review.md slim** — distilled from 1,040 → 817 tokens with compact 3-step protocol + 1-line per-framework checklists.
+- **Specialist agents slim** — removed embedded framework knowledge that duplicated `references/*.md`, replaced with on-demand pointers. **discovery-specialist −25%, strategy-critic −18%, pre-mortem-runner −20%** per dispatch.
+
+**Estimated savings per 9-step Full Mode session:**
+
+| Source | Before | After | Saved |
+|--------|:------:|:-----:|:-----:|
+| Eager (SKILL + context + progress) | ~8,800 | ~5,500 | **−3,300** |
+| Quality review (×9 step loads) | ~9,360 | ~7,353 | **−2,007** |
+| Sub-agent dispatches (3 specialists) | ~9,005 | ~7,106 | **−1,899** |
+| **Total per session** | **~27,200** | **~18,900** | **−8,300 (−30%)** |
+
+**Quality validation:** pre-mortem-runner (the most quality-sensitive specialist per Iteration 5) re-ran eval-12 on v1.2.5 slimmed content. Result: **9/9 assertions PASS** — 16 scenarios across all 5 categories, 5 architecture-grounded scenarios citing real stack components, 5 cheap pre-launch experiments with binary decision rules, past-tense framing maintained. Static cross-check confirmed eval-10/11 assertions (13 total) all have explicit support in the slim agent prompts.
+
+**Token cost trade-off:** the split adds 2 new lazy files (`rules-subagent-dispatch.md` 978 tokens, `rules-context-template.md` 1,849 tokens) that load only when triggered. In the most common session paths, they never load. In Bootstrap-or-Conflict paths, the eager savings still net positive.
+
+**Mirrored to 5 i18n locales** (zh-TW, zh-CN, ja, es, ko) preserving existing translations — structural slim applied identically per language.
+
+---
+
+## 🧪 Development & Evals
+
+The `evals/` directory ships two complementary test suites and a deterministic scorer.
+
+**Local (free, recommended):** run the same scripts with the `claude` CLI authenticated via your Claude Pro/Max subscription (`claude login` once). No API key, no marginal cost. The eval system is designed to be run locally before each release.
+
+**CI (optional, paid):** `.github/workflows/eval-gate.yml` will run both suites on every PR and on every push to `main` that changes `package.json`, then report the score to the workflow Job Summary. It **never blocks merge or publish** — the maintainer decides whether to act on regressions. CI requires an `ANTHROPIC_API_KEY` secret because GitHub Actions cannot use OAuth in a headless container; without the secret, eval jobs **skip cleanly** (gray ⏭️) instead of failing red.
+
+### Running locally
+
+```bash
+# Recommended: one command runs both suites
+npm run eval
+
+# Or run pieces individually
+npm run eval:trigger      # ~5–15 min — checks if the skill auto-triggers
+npm run eval:behavioral   # ~10–40 min — uses claude as assistant AND judge
+npm run eval:zh-TW        # behavioral eval against the zh-TW eval set
+npm run eval:quick        # 1 run only, no majority vote (fast iteration)
+npm run eval:test         # unit tests for the scoring module
+
+# Drop into the underlying Python scripts when you need finer control:
+python3 evals/run_behavioral_eval.py --only 11        # debug a single eval id
+python3 evals/run_behavioral_eval.py --fail-on none   # report without exit 1
+python3 evals/run_trigger_test.py --eval-file evals/trigger-eval-fuzzy.json
+```
+
+Local runs default to `--runs 3` (majority vote handles LLM variance); the `claude` CLI uses your Claude Pro/Max OAuth session (`claude login`), so there's no per-token cost. CI uses `--runs 1` and requires the `ANTHROPIC_API_KEY` secret.
+
+### Severity & scoring
+
+Every expectation in `evals.json` is tagged with one of three severities:
+
+| Severity | Deduction per failure | Used for |
+|---|---|---|
+| `critical` | −15 | Hard Gate violations, mode-dispatch errors, B2B buyer/user separation, security defaults, framework-level integrity (JTBD three layers, Rumelt diagnosis, pre-mortem 15+ scenarios) |
+| `warning`  | −5  | Quality depth and structure (most expectations) |
+| `info`     | −1  | Language detection, progress-indicator formatting |
+
+Score starts at 100, deducts per failure, clamps to 0–100.
+
+| Band | Range | Meaning |
+|---|---|---|
+| 🟢 `healthy` | ≥ 90 | At most one critical failure |
+| 🟡 `needs-attention` | ≥ 70 | Up to two criticals or several warnings |
+| 🔴 `at-risk` | < 70 | Three or more criticals; gate should fail |
+
+### `--fail-on` semantics
+
+| Flag value | Runner exits non-zero when… |
+|---|---|
+| `critical` | any critical expectation failed (CI default) |
+| `any` | any expectation failed at any severity |
+| `none` | never; informational mode for local exploration |
+
+A single source of truth — `evals/compute_eval_score.py` — implements all scoring so the two runners cannot drift apart.
+
+### Release checklist
+
+Before bumping the version in `package.json` (a push to `main` with a changed `package.json` triggers `npm publish`):
+
+1. `npm run eval` — get current trigger + behavioral scores
+2. If any **critical** expectation fails, investigate and fix before publishing
+3. If only warnings or info regressed, it's a judgment call — note your reasoning in the commit if you accept the regression
+4. Commit any fixes, bump the version, then `git push`
+
 ---
 
 ## 💬 Available Commands

package/README.zh-CN.md

@@ -451,6 +451,101 @@ Claude Code 会自动：
 
 ---
 
+### Iteration 6: Token 优化（v1.2.5）
+
+一次 token 减量迭代。Skill 内容语意不变，但每次 session 的足迹更小。目标：≥25% token 减量，同时品质维持 100%。
+
+**已上线的变更：**
+- **SKILL.md 瘦身** —— 将 Sub-Agent Delegation Rules 抽离到 lazy `rules-subagent-dispatch.md`；收紧 Hard Gate 描述；合并 Mode Overview 的重复段落。eager 入口 **6,188 → 2,877 tokens（-54%）**。
+- **rules-context.md 拆分** —— 保留决策逻辑为 eager（1,594 tokens）；将冗长的 YAML 模板 + Bootstrap 流程 + Conflict UX 脚本迁移到 lazy `rules-context-template.md`（1,849 tokens，仅在触发时才载入）。
+- **rules-quality-review.md 瘦身** —— 由 1,040 → 817 tokens,改写成精简 3 步骤协议 + 每个框架 1 行的 checklist。
+- **专家 sub-agent 瘦身** —— 移除与 `references/*.md` 重复的内嵌框架知识,改为按需指针。每次 dispatch **discovery-specialist −25%、strategy-critic −18%、pre-mortem-runner −20%**。
+
+**9 步 Full Mode session 的预估节省:**
+
+| 来源 | 优化前 | 优化后 | 节省 |
+|--------|:------:|:------:|:------:|
+| Eager（SKILL + context + progress） | ~8,800 | ~5,500 | **−3,300** |
+| Quality review（×9 步载入） | ~9,360 | ~7,353 | **−2,007** |
+| Sub-agent dispatch（3 位专家） | ~9,005 | ~7,106 | **−1,899** |
+| **每次 session 合计** | **~27,200** | **~18,900** | **−8,300（−30%）** |
+
+**品质验证：** 依 Iteration 5 结论,pre-mortem-runner 是品质最敏感的专家,因此在 v1.2.5 瘦身后的内容上重跑 eval-12。结果:**9/9 assertions PASS** —— 涵盖 5 大类别共 16 个情境、5 个引用真实技术栈组件的架构落地情境、5 个具二元决策规则的低成本上线前实验、过去式叙事框架皆维持。eval-10/11 则以静态交叉比对确认(共 13 项 assertion)在瘦身后的 agent prompt 中皆有明确支撑。
+
+**Token 成本权衡：** 拆分新增 2 个 lazy 档案（`rules-subagent-dispatch.md` 978 tokens、`rules-context-template.md` 1,849 tokens），仅在触发时载入。在最常见的 session 路径中,这两个档案永远不会载入;即使是 Bootstrap 或 Conflict 路径,eager 端的节省仍为正。
+
+**已同步至 5 个 i18n 语系**（zh-TW、zh-CN、ja、es、ko），保留既有译文 —— 结构性瘦身按语系一致套用。
+
+---
+
+## 🧪 开发与评测
+
+`evals/` 目录包含两套互补的测试集和一个确定性计分模块。
+
+**本地（免费，推荐）**：用 `claude` CLI 搭配你的 Claude Pro/Max 订阅（先 `claude login` 一次）跑这些 script。不需要 API key、没有额外成本。整套 eval 系统就是设计来在每次发版前本地跑一遍。
+
+**CI（可选，付费）**：`.github/workflows/eval-gate.yml` 会在每个 PR 与每次 push 到 `main`（含 `package.json` 变动）时跑这两套，把分数写进 workflow 的 Job Summary。**不挡 merge、不挡 publish** — 看到结果后由维护者决定要不要调整。CI 需要 `ANTHROPIC_API_KEY` secret（GitHub Actions 在 headless 容器无法走 OAuth）；没设 secret 时 eval job **会干净地 skip**（灰色 ⏭️），不会出现误导的红叉。
+
+### 本地执行
+
+```bash
+# 推荐：一个命令跑完两套
+npm run eval
+
+# 或分开跑
+npm run eval:trigger      # ~5–15 分钟 — skill 是否自动触发
+npm run eval:behavioral   # ~10–40 分钟 — claude 同时当 assistant 和 judge
+npm run eval:zh-TW        # 用 zh-TW 评测集跑 behavioral eval
+npm run eval:quick        # 只跑 1 次，不取多数决（快速 iterate 用）
+npm run eval:test         # 计分模块单元测试
+
+# 需要更细的 flag 控制时，直接调用底层 Python 脚本：
+python3 evals/run_behavioral_eval.py --only 11        # debug 单一 eval id
+python3 evals/run_behavioral_eval.py --fail-on none   # 只报告，不 exit 1
+python3 evals/run_trigger_test.py --eval-file evals/trigger-eval-fuzzy.json
+```
+
+本地默认 `--runs 3`（多数决可吸收 LLM 变异性）；`claude` CLI 走你的 Claude Pro/Max OAuth session（`claude login`），没有按 token 计费的成本。CI 用 `--runs 1` 并需要 `ANTHROPIC_API_KEY` secret。
+
+### Severity 与计分
+
+`evals.json` 里每个 expectation 都标一个 severity：
+
+| Severity | 失败扣分 | 适用情境 |
+|---|---|---|
+| `critical` | −15 | Hard Gate 违反、Mode dispatch 错误、B2B buyer/user 分开、Security default-on、框架完整性（JTBD 三层、Rumelt diagnosis、pre-mortem 15+ scenarios）|
+| `warning`  | −5  | 品质深度与结构（多数 expectations）|
+| `info`     | −1  | 语言侦测、Progress indicator 格式 |
+
+起点 100 分，按失败 deduct，clamp 在 0–100。
+
+| Band | 范围 | 含义 |
+|---|---|---|
+| 🟢 `healthy` | ≥ 90 | 最多一个 critical 失败 |
+| 🟡 `needs-attention` | ≥ 70 | 两个 critical 以下或数个 warning |
+| 🔴 `at-risk` | < 70 | 三个以上 critical；gate 应失败 |
+
+### `--fail-on` 语意
+
+| Flag 值 | Runner 在以下情况 exit non-zero |
+|---|---|
+| `critical` | 任一 critical expectation 失败（CI 默认）|
+| `any` | 任一 expectation 失败（不分 severity）|
+| `none` | 永不失败；本地探索 informational mode |
+
+所有计分逻辑集中在 `evals/compute_eval_score.py` 这个单一来源，避免两个 runner 各自实作造成 drift。
+
+### 发版 checklist
+
+bump `package.json` version 之前（push 到 `main` 且 `package.json` 变动会触发 `npm publish`）：
+
+1. `npm run eval` — 取得当前 trigger + behavioral 分数
+2. 任一 **critical** expectation 失败 → 发版前先查清楚并修掉
+3. 只是 warning 或 info 退步 → 自行判断；若接受退步，在 commit message 写清楚理由
+4. 修完 commit，bump version，然后 `git push`
+
+---
+
 ## 💬 可用指令一览
 
 ### ⌨️ Claude Code CLI Slash Commands

package/README.zh-TW.md

@@ -449,6 +449,100 @@ Claude Code 會自動：
 
 > 原始 artifacts 與每項 assertion 分歧詳見 [`~/product-playbook-workspace/iteration-3/benchmark.md`](./evals/)。
 
+### Iteration 6：Token 優化（v1.2.5）
+
+一輪 token 縮減迭代。Skill 語意內容不變,但每個 session 的 footprint 更小。目標:在維持 100% 品質的前提下,token 用量減少 ≥25%。
+
+**本輪變更**
+
+- **SKILL.md 瘦身**——將 Sub-Agent Delegation Rules 抽出為 lazy 載入的 `rules-subagent-dispatch.md`;精簡 Hard Gate 描述;整併 Mode Overview 重複內容。eager 進入點 **6,188 → 2,877 tokens(-54%)**。
+- **rules-context.md 拆分**——決策邏輯保持 eager(1,594 tokens);冗長的 YAML 模板、Bootstrap 流程與 Conflict UX 腳本移到 lazy `rules-context-template.md`(1,849 tokens,僅在觸發時載入)。
+- **rules-quality-review.md 瘦身**——從 1,040 → 817 tokens,改用緊湊的 3 步驟協定與每個框架 1 行的檢查表。
+- **專家 agents 瘦身**——移除與 `references/*.md` 重複的內嵌框架知識,改為依需要指向參考檔。每次 dispatch:**discovery-specialist −25%、strategy-critic −18%、pre-mortem-runner −20%**。
+
+**單一 9 步 Full Mode session 的預估節省:**
+
+| 來源 | 之前 | 之後 | 節省 |
+|--------|:------:|:-----:|:-----:|
+| Eager(SKILL + context + progress) | ~8,800 | ~5,500 | **−3,300** |
+| Quality review(×9 step loads) | ~9,360 | ~7,353 | **−2,007** |
+| Sub-agent dispatches(3 個專家) | ~9,005 | ~7,106 | **−1,899** |
+| **每次 session 合計** | **~27,200** | **~18,900** | **−8,300(−30%)** |
+
+**品質驗證**:依 Iteration 5 結果中品質最敏感的 pre-mortem-runner,在 v1.2.5 瘦身內容上重跑 eval-12。結果為 **9/9 assertions PASS**——涵蓋全部 5 個類別共 16 個 scenario、5 個引用真實 stack 元件的架構落地 scenario、5 個帶有二元判準的低成本上線前實驗,並維持過去式敘事框架。靜態交叉檢查確認 eval-10/11 的 assertions(共 13 項)在瘦身後的 agent prompt 中皆有明確支撐。
+
+**Token 成本取捨**:拆分新增 2 個 lazy 檔案(`rules-subagent-dispatch.md` 978 tokens、`rules-context-template.md` 1,849 tokens),僅在觸發時載入。在最常見的 session 路徑中,這兩個檔案根本不會載入;即使在 Bootstrap 或 Conflict 路徑下,eager 端的節省仍淨為正。
+
+**5 個 i18n 語系同步**(zh-TW、zh-CN、ja、es、ko),保留既有翻譯——結構性瘦身在各語系等比例套用。
+
+---
+
+## 🧪 開發與評測
+
+`evals/` 目錄包含兩套互補的測試集和一個確定性計分模組。
+
+**本地（免費，推薦）**：用 `claude` CLI 搭配你的 Claude Pro/Max 訂閱（先 `claude login` 一次）跑這些 script。不需要 API key、沒有額外成本。整套 eval 系統就是設計來在每次發版前本地跑一遍。
+
+**CI（選用，付費）**：`.github/workflows/eval-gate.yml` 會在每個 PR 與每次 push 到 `main`（含 `package.json` 變動）時跑這兩套，把分數寫進 workflow 的 Job Summary。**不擋 merge、不擋 publish** — 看到結果後由維護者決定要不要調整。CI 需要 `ANTHROPIC_API_KEY` secret（GitHub Actions 在 headless 容器無法走 OAuth）；沒設 secret 時 eval job **會乾淨地 skip**（灰色 ⏭️），不會出現誤導的紅叉。
+
+### 本地執行
+
+```bash
+# 推薦：一個命令跑完兩套
+npm run eval
+
+# 或分開跑
+npm run eval:trigger      # ~5–15 分鐘 — skill 是否自動觸發
+npm run eval:behavioral   # ~10–40 分鐘 — claude 同時當 assistant 和 judge
+npm run eval:zh-TW        # 用 zh-TW 評測集跑 behavioral eval
+npm run eval:quick        # 只跑 1 次，不取多數決（快速 iterate 用）
+npm run eval:test         # 計分模組單元測試
+
+# 需要更細的 flag 控制時，直接呼叫底層 Python 腳本：
+python3 evals/run_behavioral_eval.py --only 11        # debug 單一 eval id
+python3 evals/run_behavioral_eval.py --fail-on none   # 只報告，不 exit 1
+python3 evals/run_trigger_test.py --eval-file evals/trigger-eval-fuzzy.json
+```
+
+本地預設 `--runs 3`（多數決可吸收 LLM 變異性）；`claude` CLI 走你的 Claude Pro/Max OAuth session（`claude login`），沒有按 token 計費的成本。CI 用 `--runs 1` 並需要 `ANTHROPIC_API_KEY` secret。
+
+### Severity 與計分
+
+`evals.json` 裡每個 expectation 都標一個 severity：
+
+| Severity | 失敗扣分 | 適用情境 |
+|---|---|---|
+| `critical` | −15 | Hard Gate 違反、Mode dispatch 錯誤、B2B buyer/user 分開、Security default-on、框架完整性（JTBD 三層、Rumelt diagnosis、pre-mortem 15+ scenarios）|
+| `warning`  | −5  | 品質深度與結構（多數 expectations）|
+| `info`     | −1  | 語言偵測、Progress indicator 格式 |
+
+起點 100 分，按失敗 deduct，clamp 在 0–100。
+
+| Band | 範圍 | 含意 |
+|---|---|---|
+| 🟢 `healthy` | ≥ 90 | 最多一個 critical 失敗 |
+| 🟡 `needs-attention` | ≥ 70 | 兩個 critical 以下或數個 warning |
+| 🔴 `at-risk` | < 70 | 三個以上 critical；gate 應失敗 |
+
+### `--fail-on` 語意
+
+| Flag 值 | Runner 在以下情況 exit non-zero |
+|---|---|
+| `critical` | 任一 critical expectation 失敗（CI 預設）|
+| `any` | 任一 expectation 失敗（不分 severity）|
+| `none` | 永不失敗；本地探索 informational mode |
+
+所有計分邏輯集中在 `evals/compute_eval_score.py` 這個單一來源，避免兩個 runner 各自實作造成 drift。
+
+### 發版 checklist
+
+bump `package.json` version 之前（push 到 `main` 且 `package.json` 變動會觸發 `npm publish`）：
+
+1. `npm run eval` — 取得當前 trigger + behavioral 分數
+2. 任一 **critical** expectation 失敗 → 發版前先查清楚並修掉
+3. 只是 warning 或 info 退步 → 自行判斷；若接受退步，在 commit message 寫清楚理由
+4. 修完 commit，bump version，然後 `git push`
+
 ---
 
 ## 💬 可用指令一覽