@haposoft/cafekit 0.11.10 → 0.12.0

package/bin/install.js

@@ -37,6 +37,7 @@ const { checkVersions } = require('./lib/version-check');
 const { ensureGitignore } = require('./phases/root-config');
 const { runPostInstall } = require('./phases/post-install');
 const { setupSkillDeps } = require('./phases/skills-setup');
+const { setupRtk } = require('./phases/setup-rtk');
 const { printSummary } = require('./phases/summary');
 
 /** Install a single platform: payload + runtime + metadata, under one spinner. */
@@ -91,6 +92,8 @@ Options:
   -u, --upgrade, -f, --force   Alias of --force-overwrite
   --with-skills-deps   Install skill dependencies (Python venv + pip, npm,
                        Chromium/Playwright). Otherwise prompted interactively.
+  --with-rtk           Install the rtk token-saver (binary + Claude Code hook).
+                       Otherwise prompted interactively.
   -y, --yes            Non-interactive: skip prompts, use defaults (CI)
   -h, --help           Show this help
   -v, --version        Print version
@@ -166,6 +169,7 @@ async function main() {
     ensureGitignore(ctx);
     await runPostInstall(ctx);
     await setupSkillDeps(ctx);
+    await setupRtk(ctx);
     printSummary(ctx);
 
     if (!ctx.dryRun) backup.prune(3);

package/bin/lib/context.js

@@ -185,7 +185,8 @@ function parseInstallerArgs(argv) {
     forceOverwrite: false,
     dryRun: false,
     yes: false,
-    withSkillsDeps: false
+    withSkillsDeps: false,
+    withRtk: false
   };
 
   for (let i = 2; i < argv.length; i++) {
@@ -199,6 +200,8 @@ function parseInstallerArgs(argv) {
       args.yes = true;
     } else if (arg === '--with-skills-deps') {
       args.withSkillsDeps = true;
+    } else if (arg === '--with-rtk') {
+      args.withRtk = true;
     } else if (arg === '--lang') {
       args.lang = argv[++i];
     } else if (arg.startsWith('--lang=')) {

package/bin/lib/i18n.js

@@ -59,6 +59,17 @@ const MESSAGES = {
     // Skills / deps setup
     skillDepsConfirm:      'Install skill dependencies? (Python venv, pip, npm, Chromium — takes a few minutes)',
     skillsSkipped:         'Skill dependencies skipped.\n  Run later: npx @haposoft/cafekit --with-skills-deps',
+
+    // rtk token-saver setup
+    rtkConfirm:            'Install the rtk token-saver? (compacts git/grep/ls/build/test output for Claude Code Bash commands)',
+    rtkInstalling:         'Installing rtk via {method}',
+    rtkInstalled:          'rtk installed',
+    rtkInstallFailed:      'Could not install rtk — skipping (non-fatal). Install manually later: https://github.com/rtk-ai/rtk',
+    rtkInitFailed:         'rtk init -g failed: {reason} — hook not registered (non-fatal)',
+    rtkNeedsJq:            'rtk hook needs jq to run. Install jq, then the hook activates automatically.',
+    rtkFailed:             'rtk setup error: {reason} — skipped (non-fatal)',
+    rtkSkipped:            'rtk token-saver skipped.\n  Run later: npx @haposoft/cafekit --with-rtk',
+    rtkSummary:            'rtk token-saver: hook registered for Claude Code Bash commands',
     venvCreating:          'Setting up Python environment',
     venvReady:             'Python environment ready',
     venvFailed:            'Could not create Python environment — check your Python 3 installation.',
@@ -165,6 +176,17 @@ const MESSAGES = {
 
     skillDepsConfirm:      'スキルの依存関係をインストールしますか？（Python venv、pip、npm、Chromium — 数分かかります）',
     skillsSkipped:         'スキルの依存関係をスキップしました。\n  後で実行: npx @haposoft/cafekit --with-skills-deps',
+
+    // rtk token-saver setup
+    rtkConfirm:            'rtk トークンセーバーをインストールしますか？（Claude Code の Bash コマンドの git/grep/ls/build/test 出力を圧縮します）',
+    rtkInstalling:         '{method} で rtk をインストール中',
+    rtkInstalled:          'rtk をインストールしました',
+    rtkInstallFailed:      'rtk をインストールできませんでした — スキップします（致命的ではありません）。後で手動でインストール: https://github.com/rtk-ai/rtk',
+    rtkInitFailed:         'rtk init -g が失敗しました: {reason} — フックは未登録です（致命的ではありません）',
+    rtkNeedsJq:            'rtk フックの実行には jq が必要です。jq をインストールするとフックが自動的に有効になります。',
+    rtkFailed:             'rtk セットアップエラー: {reason} — スキップしました（致命的ではありません）',
+    rtkSkipped:            'rtk トークンセーバーをスキップしました。\n  後で実行: npx @haposoft/cafekit --with-rtk',
+    rtkSummary:            'rtk トークンセーバー: Claude Code の Bash コマンド用にフックを登録しました',
     venvCreating:          'Python 環境を準備しています',
     venvReady:             'Python 環境の準備ができました',
     venvFailed:            'Python 環境を作成できませんでした — Python 3 のインストールを確認してください。',
@@ -268,6 +290,17 @@ const MESSAGES = {
 
     skillDepsConfirm:      'Cài dependencies cho skill ngay? (Python venv, pip, npm, Chromium — mất vài phút)',
     skillsSkipped:         'Đã bỏ qua dependencies skill.\n  Cài sau bằng lệnh: npx @haposoft/cafekit --with-skills-deps',
+
+    // rtk token-saver setup
+    rtkConfirm:            'Cài rtk token-saver? (rút gọn output git/grep/ls/build/test cho các lệnh Bash của Claude Code)',
+    rtkInstalling:         'Đang cài rtk qua {method}',
+    rtkInstalled:          'Đã cài rtk',
+    rtkInstallFailed:      'Không thể cài rtk — bỏ qua (không nghiêm trọng). Cài thủ công sau: https://github.com/rtk-ai/rtk',
+    rtkInitFailed:         'rtk init -g thất bại: {reason} — hook chưa được đăng ký (không nghiêm trọng)',
+    rtkNeedsJq:            'Hook của rtk cần jq để chạy. Cài jq thì hook sẽ tự kích hoạt.',
+    rtkFailed:             'Lỗi cài rtk: {reason} — đã bỏ qua (không nghiêm trọng)',
+    rtkSkipped:            'Đã bỏ qua rtk token-saver.\n  Cài sau bằng lệnh: npx @haposoft/cafekit --with-rtk',
+    rtkSummary:            'rtk token-saver: đã đăng ký hook cho các lệnh Bash của Claude Code',
     venvCreating:          'Đang thiết lập môi trường Python',
     venvReady:             'Môi trường Python đã sẵn sàng',
     venvFailed:            'Không thể tạo môi trường Python — hãy kiểm tra cài đặt Python 3.',

package/bin/lib/rtk-run.js

@@ -0,0 +1,28 @@
+/**
+ * Local captured-spawnSync helper for the rtk install phase.
+ *
+ * Why local: `lib/skill-deps.js` does not export a `run(cmd, args)` helper
+ * (it uses `runAsync` internally and never re-exports it). The rtk phase
+ * needs a synchronous, captured spawnSync (R2.2, R4.2) that returns
+ * `{ ok, status, stdout, stderr }` — same shape as `skill-deps.runAsync` but
+ * blocking. KISS: one 20-line module, no dependency on `lib/skill-deps.js`
+ * (which is skill-domain and not a generic command runner).
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {object} [opts] — passed through to spawnSync (e.g. { timeout })
+ * @returns {{ ok: boolean, status: number|null, stdout: string, stderr: string }}
+ */
+const { spawnSync } = require('child_process');
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+  return {
+    ok: !r.error && r.status === 0,
+    status: r.status,
+    stdout: r.stdout || '',
+    stderr: r.stderr || ''
+  };
+}
+
+module.exports = { run };

package/bin/phases/setup-rtk.js

@@ -0,0 +1,159 @@
+/**
+ * setup-rtk — opt-in install of the rtk token-saver and its Claude Code hook.
+ *
+ * Phase order (per specs/rtk-installer-integration/design.md):
+ *   shouldRunRtk → ensureRtkBinary → `rtk init -g` → jq precheck → manifest
+ *
+ * R1-01 wired the consent gate (`shouldRunRtk`) and a thin `setupRtk` wrapper.
+ * R2-01 adds the orchestrator: `ensureRtkBinary` (detect/install), the
+ * `rtk init -g` hook registration, the `jq` precheck, and the manifest write.
+ *
+ * Non-fatal invariant (R2.7, R4.1): the entire `setupRtk` body is wrapped in
+ * try/catch. Any throw / non-zero exit / timeout is logged as a warning via
+ * `ctx.t('rtkFailed')` (with `{reason}` interpolation) and the cafekit
+ * install continues with its existing exit code. Mirrors the non-fatal
+ * contract of `phases/skills-setup.js`.
+ *
+ * Idempotency (R2.1, R2.6): re-runs see `hasCmd('rtk')` short-circuit the
+ * binary install path and re-invoke `rtk init -g` (rtk's own command handles
+ * its hook idempotency). The in-memory `ctx.rtkSetupRan` flag records that
+ * setup executed, so downstream consumers (R3-01 summary line) can read it.
+ *
+ * Cross-OS install (validated 2026-06-15): best-effort order
+ *   (1) official prebuilt install script (pinned source)
+ *   (2) `cargo install rtk` when `hasCmd('cargo')`
+ *   (3) skip + warn
+ * covers macOS/Linux dev machines (cargo fall-through) and CI (skip+warn).
+ *
+ * No timeout for `cargo install rtk` (validated 2026-06-15): user accepted
+ * default `spawnSync` timeout; non-fatal guarantee holds via try/catch.
+ */
+
+const dep = require('../lib/skill-deps');
+const rtkRun = require('../lib/rtk-run');
+const { hasCmd } = dep;
+const { run } = rtkRun;
+
+const RTK_INIT_TIMEOUT_MS = 30_000;       // `rtk init -g` is a fast global-hook write
+const RTK_PREBUILT_TIMEOUT_MS = 120_000;  // prebuilt install: curl download + sh pipe; slow networks need headroom
+const RTK_PREBUILT_INSTALL_URL =
+  'https://raw.githubusercontent.com/rtk-ai/rtk/main/install.sh';
+
+/**
+ * Detect rtk binary, installing it if absent. Pure function over `ctx`.
+ *
+ * @param {object} ctx
+ * @returns {'present'|'installed'|'absent'}
+ */
+function ensureRtkBinary(ctx) {
+  if (hasCmd('rtk')) return 'present';
+  return installRtkBinary(ctx) ? 'installed' : 'absent';
+}
+
+/**
+ * Best-effort rtk install. Tries the official prebuilt install script first
+ * (R5.2: surface source), then falls back to `cargo install rtk` if cargo is
+ * available, otherwise returns false (R2.3 non-fatal skip).
+ *
+ * @param {object} ctx
+ * @returns {boolean} true on success, false on failure or no method available
+ */
+function installRtkBinary(ctx) {
+  // Method 1: official prebuilt install script (pinned URL).
+  ctx.ui.info(ctx.t('rtkInstalling', { method: `prebuilt script (${RTK_PREBUILT_INSTALL_URL})` }));
+  const prebuilt = run('sh', ['-c', `curl -fsSL ${RTK_PREBUILT_INSTALL_URL} | sh`], {
+    timeout: RTK_PREBUILT_TIMEOUT_MS
+  });
+  if (prebuilt.ok) return true;
+
+  // Method 2: `cargo install rtk` if cargo is on PATH.
+  if (hasCmd('cargo')) {
+    ctx.ui.info(ctx.t('rtkInstalling', { method: 'cargo install rtk' }));
+    const cargo = run('cargo', ['install', 'rtk']);
+    if (cargo.ok) return true;
+  }
+
+  // No method succeeded.
+  return false;
+}
+
+/**
+ * Phase entrypoint. R2-01 wires the full install + hook + manifest pipeline.
+ * The consent gate is delegated to `shouldRunRtk(ctx)` (R1-01).
+ *
+ * @param {object} ctx
+ * @returns {Promise<object>} the same ctx
+ */
+async function setupRtk(ctx) {
+  if (!(await shouldRunRtk(ctx))) {
+    // Dry-run: enumerate the action set that would have run (validated 2026-06-15).
+    if (ctx.dryRun) {
+      ctx.ui.info(
+        '[dry-run] rtk setup skipped (would: detect rtk binary, install if missing via prebuilt/cargo, run rtk init -g, check jq)'
+      );
+    } else {
+      ctx.ui.info(ctx.t('rtkSkipped'));
+    }
+    return ctx;
+  }
+
+  try {
+    // Step 1: ensure the binary is on PATH (R2.1, R2.2, R2.3).
+    const state = ensureRtkBinary(ctx);
+    if (state === 'absent') {
+      ctx.ui.warn(ctx.t('rtkInstallFailed'));
+      return ctx;
+    }
+    if (state === 'installed') {
+      ctx.ui.info(ctx.t('rtkInstalled'));
+    }
+
+    // Step 2: register rtk's official Claude Code hook via `rtk init -g` (R2.4).
+    const init = run('rtk', ['init', '-g'], { timeout: RTK_INIT_TIMEOUT_MS });
+    if (!init.ok) {
+      ctx.ui.warn(ctx.t('rtkInitFailed', { reason: init.stderr || `exit ${init.status}` }));
+      return ctx;
+    }
+
+    // Step 3: `jq` precheck (R2.5). Warn if missing; do not fail.
+    if (!hasCmd('jq')) {
+      ctx.ui.warn(ctx.t('rtkNeedsJq'));
+    }
+
+    // Step 4: record the action (R2.6, idempotency). In-memory flag — re-runs
+    // observe `hasCmd('rtk')` short-circuit and re-invoke `rtk init -g`,
+    // which is itself idempotent. R3-01 reads this flag for the summary line.
+    ctx.rtkSetupRan = true;
+    return ctx;
+  } catch (err) {
+    // Non-fatal boundary: any unexpected throw becomes a warning, the
+    // installer continues (R2.7, R4.1).
+    ctx.ui.warn(ctx.t('rtkFailed', { reason: (err && err.message) || String(err) }));
+    return ctx;
+  }
+}
+
+/**
+ * Decision matrix for whether the rtk setup phase should run. R1-01.
+ *
+ *   1. --dry-run                          → false (R1.4)
+ *   2. ctx.options.withRtk === true       → true  (R1.1)
+ *   3. !ctx.interactive                   → false (R1.3)
+ *   4. interactive confirm resolves true  → true  (R1.2)
+ *   5. interactive confirm resolves false → false (R1.2)
+ *
+ * @param {object} ctx
+ * @returns {Promise<boolean>}
+ */
+async function shouldRunRtk(ctx) {
+  if (ctx.dryRun) return false;
+  if (ctx.options.withRtk) return true;
+  if (!ctx.interactive) return false;
+  const yes = await ctx.ui.confirm(
+    { message: ctx.t('rtkConfirm'), initialValue: false },
+    false
+  );
+  return yes === true;
+}
+
+module.exports = { shouldRunRtk, setupRtk, ensureRtkBinary, installRtkBinary };

package/bin/phases/summary.js

@@ -55,6 +55,10 @@ function printSummary(ctx) {
   for (const key of platforms) {
     lines.push(key === 'claude' ? t('nsClaude') : t('nsOpencode'));
   }
+  // rtk token-saver result (set by phases/setup-rtk.js when setup completed).
+  if (ctx.rtkSetupRan) {
+    lines.push(t('rtkSummary'));
+  }
   const keySkills = skillsNeedingKeys(platforms);
   if (keySkills.length > 0) {
     lines.push(t('nsKeys', { skills: keySkills.join(', ') }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.11.10",
+  "version": "0.12.0",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/CLAUDE.md

@@ -116,7 +116,7 @@ Consult these when the task touches the relevant area:
 
 ## Language Consistency
 
-When generating specs or structured project output, use the user's preferred language consistently across the whole spec workspace. Technical terms, code samples, and file paths may remain English.
+Spec artifacts (`spec.json`, `requirements.md`, `research.md`, `design.md`, `tasks/*.md`) are **canonical in English** regardless of the session's response language. When the configured language is not English, `hapo:specs` may additionally generate a reference-only translation mirror under `specs/<feature>/i18n/<lang>/`. Chat replies and other non-spec output still follow the user's preferred language. Technical terms, code samples, and file paths stay English.
 
 ## Communication
 

package/src/claude/skills/develop/SKILL.md

@@ -71,7 +71,7 @@ Enabled by default for all develop modes. Disable only with `--no-notes`.
 
 <HARD-GATE>
 DO NOT write implementation code until an approved spec exists.
-- If the directory `specs/<feature-name>` DOES NOT EXIST or `spec.json` is not ready, automatically trigger `/hapo:specs <feature-name>` first to create the specification. Do not improvise.
+- If the directory `specs/<feature-name>` DOES NOT EXIST or `spec.json` is not ready, automatically trigger `/hapo:specs <feature-name> --auto` first to create the specification end-to-end (non-interactive). Do not improvise.
 </HARD-GATE>
 
 <DEFINITION-OF-DONE>

package/src/claude/skills/specs/SKILL.md

@@ -5,7 +5,7 @@ user-invocable: true
 when_to_use: "Invoke to turn a vague idea into an actionable, gated specification."
 category: utilities
 keywords: [specs, requirements, design, tasks]
-argument-hint: "<feature-description> | status | resume | --validate | archive"
+argument-hint: "[<feature-description>] [--auto] | --status | --validate <feature> | --archive"
 metadata:
   author: haposoft
   version: "2.0.0"
@@ -22,6 +22,8 @@ This skill provides a 10-step workflow to transform ideas into evidence-backed s
 Analyze → Dependency Scan → Complexity Assessment → Init → Evidence Gate + Requirements → Design → Tasks → Hydration → Review → Completion
 ```
 
+An entry/dispatch layer sits in front of the pipeline: four flags (`--auto`, `--validate`, `--status`, `--archive`) plus **Interactive State Discovery** (the no-flag path) decide *which part of the pipeline to run and where to stop* — see **Default Behavior**. The pipeline itself is unchanged regardless of how it is invoked.
+
 **CRITICAL:** Before starting, the system MUST:
 1. Scan `specs/` directory for incomplete specs
 2. If any spec is `in_progress` (accept legacy `in-progress` when reading) → ask user whether to continue or create new
@@ -39,7 +41,7 @@ Analyze → Dependency Scan → Complexity Assessment → Init → Evidence Gate
 - Each phase (Init → Requirements → Design → Tasks) must complete before the next begins
 - No skipping — don't write design without requirements
 - Exception: simple tasks may merge requirements + design into one step
-- A normal `/hapo:specs <feature-description>` run is an end-to-end spec creation workflow. Do not stop after Init unless the user explicitly asks for init-only behavior.
+- A `/hapo:specs <feature-description>` run defaults to **Interactive State Discovery**: it asks the Creation Mode (Auto / Stop after Design / Step by step) before running. `--auto` runs the full pipeline end-to-end without asking. Either way, phases never skip — each completes before the next begins, and Init is never a stop point.
 
 ### Scope Rules
 - Respect `scope_lock` absolutely once user has confirmed
@@ -54,6 +56,10 @@ Analyze → Dependency Scan → Complexity Assessment → Init → Evidence Gate
 - `ready_for_implementation` is a hard gate, not a convenience flag. Never set it before the finalization audit passes.
 - Non-trivial specs MUST have an evidence trail in `research.md` before requirements, design, or tasks are finalized. Evidence can be codebase scout findings, external/current research, or an explicit skip rationale.
 
+### Language & Canonical Rules
+- **English is the canonical language for every spec artifact** (`spec.json`, `requirements.md`, `research.md`, `design.md`, `tasks/*.md`) — write them in English regardless of the session's response language.
+- If the configured language (`.claude/settings.json` → `language`) is not English, you MAY additionally generate a **reference-only translation mirror** under `i18n/<lang>/`. See `references/translation-mirror.md`. The mirror never replaces canonical and is never a source of truth.
+
 ### Output Criteria
 - Never implement code — only create spec documents
 - Return file paths and a brief summary
@@ -96,37 +102,62 @@ Forbidden generated artifacts:
 
 ## Default Behavior
 
-### When called WITHOUT arguments
-
-Display selection menu via `AskUserQuestion`:
-
-```json
-{
-  "questions": [{
-    "question": "What would you like to do?",
-    "header": "Specs",
-    "options": [
-      { "label": "Create new spec", "description": "Initialize spec from a feature description" },
-      { "label": "status", "description": "View status of all specs in specs/" },
-      { "label": "resume", "description": "Continue an active spec" },
-      { "label": "--validate", "description": "Review spec (auto-decides: red team or validation)" },
-      { "label": "archive", "description": "Archive completed specs + write journal" }
-    ],
-    "multiSelect": false
-  }]
-}
-```
+> **This section is the entry/dispatch layer ONLY.** It decides *which part of the pipeline to run and where to stop*. It does NOT change any pipeline step, the validator, templates, or rules. The detailed Steps 1–10 below are unchanged.
+
+`hapo:specs` exposes exactly **four flags**: `--auto`, `--validate`, `--status`, `--archive`. Everything else (which spec, new vs continue, how far to run) is resolved by **Interactive State Discovery**, never by extra flags.
+
+**Back-compat aliases** (accepted silently, not advertised): bare `status` / `archive` / `resume`, and `--validate` as today. Treat them as their `--flag` equivalents.
+
+### Dispatch order
+
+1. `--status` (or bare `status`) → run the status report (see **Subcommands**), then stop.
+2. `--validate <feature>` → jump to **Step 9** (the `--validate` rules below are unchanged).
+3. `--archive` (or bare `archive`) → run the archive workflow, then stop.
+4. `--auto` → **non-interactive run**. If the argument matches an unfinished spec → resume it from `current_phase` and finish to Tasks. Otherwise create new and run the full pipeline (Step 1→10) end-to-end. Either way: auto-approve and skip the Creation Mode question; if a new description is missing, ask only for it; the hard safety gates still apply.
+5. Otherwise (`/hapo:specs` or `/hapo:specs "<description>"`) → **Interactive State Discovery**.
+
+### Interactive State Discovery (no-flag path)
+
+Goal: ask the user enough to determine **state** and **intent**, then run the existing pipeline. This only chooses *what to run and where to stop* — it does not alter any step's logic.
+
+1. **Detect state.** Scan `specs/` for unfinished specs (`status=in_progress` / `ready_for_implementation=false`) and git-branch match.
+   - Found → `AskUserQuestion`: `Continue <spec A> · Continue <spec B> · Create new spec`.
+   - None → default to create-new.
+2. **Create-new + no description yet** → ask for the description, then analyze it (logic unchanged):
+   - If description is too short (< 20 words) or missing one concrete detail → stop and ask 1-2 clarifying questions
+   - If the idea has unresolved architecture choices, unclear acceptance criteria, unclear scope boundaries, or multiple plausible approaches → stop and route to `/hapo:brainstorm <idea>` before creating spec artifacts
+   - If task is simple (small bugfix, config change) → suggest "A spec may not be needed for this. Continue anyway?"
+   - If task is complex (multi-module, security/migration related) → auto-activate deep research, ask user 3 scope questions
+   - For non-trivial specs, execute the Step 5 Evidence Gate before writing final requirements. Do not design from memory when codebase or current external evidence can answer the question.
+3. **Creation Mode Gate** (how far to run) — see the dedicated section below. Options: `Auto (→ Tasks)` · `Stop after Design` · `Step by step`. If `.claude/settings.json` → `language` is not English, also offer the **Translation Mirror** (see below).
+4. **Continue an unfinished spec** → read `spec.json.current_phase`, then `AskUserQuestion` offering the **remaining** stop points (e.g. `→ Design`, `→ Tasks`, `Step by step`) and resume the existing pipeline from that phase. If a message accompanied the call, treat it as added context for the next phase (scope expansion → ask, per `references/ask-user-question-gates.md`).
+5. **Run the chosen scope.** On an early stop, emit the Paused Block (Step 10). Sync `spec.json` per `state-sync.md`.
+
+> The pipeline, validator, templates, and rules are unchanged. "Stop after Design" simply halts before Step 7; it runs Steps 1–6 exactly as specified.
+
+### Creation Mode Gate
+
+Shown once (via `AskUserQuestion`) on the no-flag create path, after the description passes the safety gates. It selects the **stop point only** — every phase that runs uses the unchanged Step logic.
+
+| Option | Runs | Stops after | Approvals |
+|---|---|---|---|
+| **Auto (→ Tasks)** | Step 1→10 end-to-end | full (ready gate) | each phase `generated=true` + `approved=true` |
+| **Stop after Design** | Step 1→6 | `design` (before Step 7) | requirements + design `approved=true`; `ready_for_implementation=false` |
+| **Step by step** | one phase at a time | after each phase | per phase `generated=true`, `approved=false` until user approves |
 
-### When called WITH a feature description
+Rules:
+- `--auto` equals choosing **Auto (→ Tasks)** without showing this gate.
+- **Stop after Design** / **Step by step** leave `ready_for_implementation=false` and emit the Paused Block (Step 10).
+- Continuing later: run `/hapo:specs` again → Interactive State Discovery detects the unfinished spec and offers the remaining stop points. No flag or keyword required.
 
-System auto-analyzes the description:
-- If description is too short (< 20 words) or missing one concrete detail → stop and ask 1-2 clarifying questions
-- If the idea has unresolved architecture choices, unclear acceptance criteria, unclear scope boundaries, or multiple plausible approaches → stop and route to `/hapo:brainstorm <idea>` before creating spec artifacts
-- If task is simple (small bugfix, config change) → suggest "A spec may not be needed for this. Continue anyway?"
-- If task is complex (multi-module, security/migration related) → auto-activate deep research, ask user 3 scope questions
-- For non-trivial specs, execute the Step 5 Evidence Gate before writing final requirements. Do not design from memory when codebase or current external evidence can answer the question.
-- After user confirms scope, continue through Init → Evidence/Requirements → Design → Tasks → Finalization in the same workflow unless the user explicitly asks for "init only" or "pause after init".
-- If the workflow must pause for manual approval, the continuation command is `/hapo:specs resume <feature>` or `/hapo:specs <feature>`.
+### Translation Mirror (optional reference copy)
+
+Load `references/translation-mirror.md`. This is the only language feature in the entry layer; canonical artifacts are always English.
+
+- Read `.claude/settings.json` → `language`. If it is **not** English and the run is **interactive** (no `--auto`), ask once via `AskUserQuestion`: "Generate a `<language>` reference copy of this spec? (kept in sync, read-only)".
+- On `Yes` → set `spec.json.translation` (`enabled`, `language`, `language_code`, `dir: i18n/<code>`, `sync: always`) and, after each canonical doc is written in Steps 5–7, regenerate the matching file under `i18n/<code>/` with the reference-only marker.
+- `--auto` does not prompt for a mirror, so an `--auto` create makes none. But if the spec already has `translation.enabled = true` (set in an earlier interactive run), always-sync still applies: an `--auto` resume keeps regenerating the mirror after each canonical write.
+- The mirror is reference-only: never validated, never a source of truth, ignored by `hapo:develop`.
 
 ### When called WITH `--validate` argument
 
@@ -148,9 +179,16 @@ The system MUST NOT execute Steps 1-8. Instead, load `references/review.md` and
 
 ```mermaid
 flowchart TD
-    A["Call /hapo:specs"] --> B{Has description?}
-    B -->|No| C["Menu: init / status / resume / --validate / archive"]
-    B -->|Yes| D["Step 1: Analyze description"]
+    A["Call /hapo:specs"] --> B{Flag?}
+    B -->|"--status"| ST["Status report → stop"]
+    B -->|"--archive"| AR["Archive workflow → stop"]
+    B -->|"--validate"| W
+    B -->|"--auto"| D["Step 1: Analyze description"]
+    B -->|none| DISC["Interactive State Discovery"]
+    DISC --> DISC1{Unfinished spec?}
+    DISC1 -->|Continue| RES["Read current_phase → resume remaining phases"]
+    DISC1 -->|New| D
+    RES --> CM
     D --> DB{"Needs pre-spec brainstorm?"}
     DB -->|Yes| DB2["Stop: run /hapo:brainstorm with same idea"]
     DB -->|No| E{Clear enough?}
@@ -174,7 +212,9 @@ flowchart TD
     N -->|Yes| P["Step 5B: Requirements — write EARS"]
     P --> Q["Step 6: Design — pick discovery mode"]
     Q --> R["Write design.md"]
-    R --> S["Step 7: Tasks — split into individual files"]
+    R --> CM{"Creation Mode?"}
+    CM -->|"Stop after Design"| STOP["Paused at design → emit Paused Block"]
+    CM -->|"Auto / Step by step"| S["Step 7: Tasks — split into individual files"]
     S --> T["Create tasks/task-R*.md + task_registry"]
     T --> U["Step 8: Hydrate Claude Tasks if >= 3 task files"]
     U --> V{Review?}
@@ -233,7 +273,7 @@ Load: `references/scope-inquiry.md`
   - `in_scope`: confirmed scope items
   - `out_of_scope`: excluded items
   - `expansion_policy`: `requires-user-approval`
-- Step 4 itself only initializes files. In a normal `/hapo:specs <feature-description>` run, immediately continue to Step 5 after Init. Stop here only when the user explicitly requested init-only behavior.
+- Step 4 itself only initializes files. The Creation Mode Gate (or `--auto`) decides how far the run proceeds; in every mode Step 4 continues into Step 5 — Init is never a stop point.
 
 ### Step 5: Evidence Gate, Requirements & Research
 - Read `spec.json` — stop if init hasn't completed
@@ -392,6 +432,7 @@ Load: `references/review.md` + `rules/design-review.md`
   Tasks and requirements must reuse the same policy verbatim; mixed policies are invalid.
 - FAIL if `validation.status = "completed"` but `timestamps.validation_done` / `timestamps.review_done`, `updated_at`, and report metadata are not synchronized with the final reviewed state.
 - If `validation_recommended = true` and `validation.status` is not `completed` (or an explicit accepted-risk state recorded by the user), `ready_for_implementation` MUST remain `false`
+- If `translation.enabled = true`, ensure `i18n/<language_code>/` exists and was re-synced after the final canonical write; the mirror itself is excluded from validation and never blocks `ready_for_implementation`.
 - Only after this audit passes may the system mark `progress.tasks = "done"` and `ready_for_implementation = true`
 
 ### Step 10: Completion — Context Reminder (MANDATORY)
@@ -407,15 +448,27 @@ After completing the spec, output a short summary of what was generated, then yo
 💡 Tip: Run /clear or start a new chat session before implementing to reduce planning context carryover.
 ```
 
+### Step 10b: Paused Block (early stop)
+
+When the run stops before Tasks (Creation Mode = **Stop after Design** or **Step by step**), do NOT print the completion block above and do NOT run the deterministic validator (no tasks exist yet). Instead print:
+
+```
+⏸ Spec paused at <phase>: specs/<feature>/
+📌 Continue — run /hapo:specs and choose "Continue <feature>"
+   (or /hapo:specs <feature> --auto to finish straight to Tasks)
+```
+
+`ready_for_implementation` stays `false`. The next `/hapo:specs` run re-detects this spec via Interactive State Discovery and offers the remaining phases.
+
 ## Active Spec State
 
 When user calls `hapo:specs`, system checks `specs/`:
 
 | Situation | Action |
 |---|---|
-| A spec is `in_progress` | Ask: "You have spec `<name>` at phase `<phase>`. Continue? [Y/n]" |
-| A spec matches current git branch | Ask: "Branch `feature/X` has spec `X`. Activate or create new?" |
-| Nothing found | Create new spec or show menu |
+| A spec is `in_progress` | Interactive State Discovery offers `Continue <name>` (resume from `<phase>`) vs `Create new spec` |
+| A spec matches current git branch | Offer `Continue <X>` vs `Create new` |
+| Nothing found | Create new spec → Creation Mode Gate |
 
 **Next step suggestions based on `spec.json`:**
 
@@ -437,8 +490,9 @@ When user calls `hapo:specs`, system checks `specs/`:
 **Timestamps:** Each `timestamps.*_done` field MUST use the **actual current time** (ISO 8601 with timezone) when that specific phase completes. This includes `review_done` and `validation_done` after review/validate workflows. Do NOT reuse the `init` timestamp for later phases. If running the full pipeline end-to-end, capture a fresh timestamp at each phase transition.
 
 **Approvals (auto-approval behavior):**
-- When running the **full pipeline end-to-end** (init → tasks in one session): set `approvals.{phase}.generated = true` AND `approvals.{phase}.approved = true` for each completed phase before proceeding to the next.
-- When running a **single phase**: set `generated = true` but leave `approved = false` — user must explicitly approve before continuing.
+- When running the **full pipeline end-to-end** (`--auto` or Creation Mode "Auto", init → tasks in one session): set `approvals.{phase}.generated = true` AND `approvals.{phase}.approved = true` for each completed phase before proceeding to the next.
+- When running to an **early stop point** (Creation Mode "Stop after Design"): for each phase that ran to reach the stop point, set `generated = true` AND `approved = true`; do not generate later phases; keep `ready_for_implementation = false`.
+- When running a **single phase** (Creation Mode "Step by step"): set `generated = true` but leave `approved = false` — user must explicitly approve before continuing.
 
 **Task inventory:** `task_files` MUST be present and MUST list every real task file exactly once using relative paths like `tasks/task-R1-01-example.md`.
 Task paths that omit the `task-` prefix or use non-padded sequence numbers (for example `tasks/R1-1-example.md`) are invalid for new CafeKit specs.
@@ -447,6 +501,8 @@ Task paths that omit the `task-` prefix or use non-padded sequence numbers (for
 
 **Validation recommendation:** `design_context.validation_recommended` MUST be `true` for auth, privacy, delete-data, migration, schema-change, browser-extension-permission, external-provider, or 5+ task file specs.
 
+**Translation mirror:** `translation` records the optional reference copy (`enabled`, `language`, `language_code`, `dir`, `sync: always`, `last_synced_at`). Canonical artifacts stay English; when `enabled = true`, regenerate `i18n/<language_code>/` after each canonical doc write and stamp `last_synced_at`. The mirror never affects `ready_for_implementation`. See `references/translation-mirror.md`.
+
 **`ready_for_implementation`:** This field MUST only be set to `true` when ALL of the following conditions are met:
 1. `approvals.requirements.approved = true`
 2. `approvals.design.approved = true`
@@ -480,14 +536,28 @@ specs/
         └── red-team-report.md
 ```
 
+When `translation.enabled` is true, a reference-only mirror is added alongside (English stays canonical):
+
+```
+specs/<feature-name>/
+└── i18n/<lang-code>/         # reference only — generated from canonical, never validated
+    ├── requirements.md
+    ├── design.md
+    ├── research.md
+    └── tasks/task-R*.md
+```
+
 ## Subcommands
 
+The canonical surface is four flags. Bare-verb forms are kept only as silent back-compat aliases.
+
 | Command | Purpose | Reference |
 |---|---|---|
-| `/hapo:specs status` | View status of all specs | — |
-| `/hapo:specs resume <feature>` | Continue an active spec | — |
+| `/hapo:specs --status` | View status of all specs (alias: `status`) | — |
 | `/hapo:specs --validate <feature>` | Validate spec (auto: red team + validate based on complexity) | `references/review.md` |
-| `/hapo:specs archive` | Archive completed specs + write journal | `references/archive-workflow.md` |
+| `/hapo:specs --archive` | Archive completed specs + write journal (alias: `archive`) | `references/archive-workflow.md` |
+| `/hapo:specs --auto [<desc>]` | Non-interactive: create (or resume) and run end-to-end to Tasks | — |
+| `/hapo:specs [<desc>]` | Interactive State Discovery (continue unfinished, or create + Creation Mode Gate). Alias `resume` accepted. | — |
 
 ## Quality Standards
 
@@ -578,3 +648,4 @@ Before finalizing any specification, assert all the following:
 - `task-hydration.md` — Task files → Claude Tasks conversion
 - `review.md` — Spec review (auto-decides: red team 8 steps + validate 6 steps)
 - `archive-workflow.md` — Archive workflow (5 steps)
+- `translation-mirror.md` — Optional reference-only translation mirror (detection, layout, sync, fields)

package/src/claude/skills/specs/references/translation-mirror.md

@@ -0,0 +1,83 @@
+# Translation Mirror
+
+Optional, reference-only duplicate of a spec in the user's configured language. The English spec is always the canonical source of truth; the mirror exists only for human cross-reading.
+
+## When To Offer
+
+1. Read the configured language from `.claude/settings.json` → `language` (a freeform label written at install time, e.g. `Tiếng Việt`, `日本語`, `Korean`, `English`).
+2. If the label resolves to English (`English` / `en`) → **do not** offer a mirror; there is nothing to duplicate.
+3. If it is any other language AND the run is interactive (no `--auto`) → ask once via `AskUserQuestion`:
+   - "Generate a `<language>` reference copy of this spec? (kept in sync, read-only)" → `Yes` / `No`.
+4. `--auto` runs are non-interactive → **skip** the offer (an `--auto` create makes no mirror). If `translation.enabled` is already `true` from an earlier run, always-sync still applies during an `--auto` resume.
+5. Persist the choice in `spec.json.translation` (see Fields).
+
+## Language Code
+
+Map the freeform label to a short folder code:
+
+| Label | Code |
+|---|---|
+| Tiếng Việt | `vi` |
+| 日本語 / Japanese | `ja` |
+| 한국어 / Korean | `ko` |
+| 中文 / Chinese | `zh` |
+| Français / French | `fr` |
+| (anything else) | kebab-case slug of the label |
+
+## Layout
+
+The mirror lives under the spec, never replacing canonical files:
+
+```
+specs/<feature>/
+├── spec.json              # canonical state — NOT mirrored
+├── requirements.md        # English canonical
+├── design.md
+├── research.md
+├── tasks/task-R*.md
+└── i18n/<code>/           # mirror (reference only)
+    ├── requirements.md
+    ├── design.md
+    ├── research.md
+    └── tasks/task-R*.md
+```
+
+- Mirror **only** the human-readable docs: `requirements.md`, `design.md`, `research.md`, and every `tasks/task-*.md`.
+- Do **not** mirror `spec.json` (machine state is language-agnostic and lives only at the root).
+- Keep file names and the `tasks/` substructure identical to canonical so they line up 1:1.
+
+## Mirror File Marker
+
+Every generated mirror file MUST begin with this HTML comment so no one mistakes it for a source:
+
+```
+<!-- TRANSLATION MIRROR — generated from English canonical. Reference only. Do not edit; regenerated on sync. -->
+```
+
+EARS trigger keywords and fixed phrases stay in English even inside the mirror (`When`, `If`, `While`, `Where`, `The system shall`); only the variable parts are translated — same rule as `rules/ears-format.md`.
+
+## Always-Sync
+
+`spec.json.translation.sync` is `always`:
+
+- Whenever a canonical doc is written or updated (Step 5 requirements/research, Step 6 design, Step 7 tasks, or any later edit), regenerate the matching mirror file from the new canonical content.
+- After regenerating, set `spec.json.translation.last_synced_at` to the current time.
+- If a canonical task file is added/removed, add/remove the matching mirror file so the two trees stay 1:1.
+
+## Not A Source Of Truth
+
+- The deterministic validator (`validate-spec-output.cjs`) runs on **canonical only**. The `i18n/` tree is never validated and never blocks `ready_for_implementation`.
+- `task_files` and `task_registry` reference canonical paths only.
+- `hapo:develop` implements from canonical English; it must ignore `i18n/`.
+- If the mirror and canonical ever disagree, canonical wins; re-sync the mirror.
+
+## Fields (`spec.json.translation`)
+
+| Field | Meaning |
+|---|---|
+| `enabled` | `true` once the user opts in |
+| `language` | freeform label from settings (e.g. `Tiếng Việt`) |
+| `language_code` | folder code (e.g. `vi`) |
+| `dir` | relative mirror dir (e.g. `i18n/vi`) |
+| `sync` | `always` |
+| `last_synced_at` | ISO 8601 timestamp of the last regeneration |

package/src/claude/skills/specs/rules/ears-format.md

@@ -4,8 +4,8 @@
 EARS (Easy Approach to Requirements Syntax) is the standard format for acceptance criteria in spec-driven development.
 
 EARS patterns describe the logical structure of a requirement (condition + subject + response) and are not tied to any particular natural language.  
-All acceptance criteria should be written in the target language configured for the specification (for example, `spec.json.language` / `en`).  
-Keep EARS trigger keywords and fixed phrases in English (`When`, `If`, `While`, `Where`, `The system shall`, `The [system] shall`) and localize only the variable parts (`[event]`, `[precondition]`, `[trigger]`, `[feature is included]`, `[response/action]`) into the target language. Do not interleave target-language text inside the trigger or fixed English phrases themselves.
+Canonical acceptance criteria are written in **English** (`spec.json.language` is `en`). A non-English rendering only appears in the optional translation mirror (`i18n/<lang>/`, see `references/translation-mirror.md`), never in the canonical files.  
+Keep EARS trigger keywords and fixed phrases in English (`When`, `If`, `While`, `Where`, `The system shall`, `The [system] shall`). In the mirror, localize only the variable parts (`[event]`, `[precondition]`, `[trigger]`, `[feature is included]`, `[response/action]`); do not interleave translated text inside the trigger or fixed English phrases themselves.
 
 ## Primary EARS Patterns
 

package/src/claude/skills/specs/templates/spec-state.json

@@ -2,7 +2,7 @@
   "feature_name": "{{FEATURE_NAME}}",
   "created_at": "{{TIMESTAMP}}",
   "updated_at": "{{TIMESTAMP}}",
-  "language": "vi",
+  "language": "en",
   "status": "in_progress",
   "phase": "initialized",
   "current_phase": "init",
@@ -68,5 +68,13 @@
     "questions_asked": 0,
     "last_validated_at": null
   },
+  "translation": {
+    "enabled": false,
+    "language": null,
+    "language_code": null,
+    "dir": null,
+    "sync": "always",
+    "last_synced_at": null
+  },
   "ready_for_implementation": false
 }