workflow-ledger 0.3.5 → 0.3.6

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "workflow-ledger",
       "description": "Lightweight, recoverable workflow ledger for Claude Code projects",
-      "version": "0.3.5",
+      "version": "0.3.6",
       "source": "./",
       "author": {
         "name": "MorseWayne"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "workflow-ledger",
   "description": "Lightweight, recoverable workflow ledger for Claude Code projects",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "author": {
     "name": "MorseWayne"
   },

package/README.md

@@ -94,16 +94,17 @@ npx workflow-ledger setup --tool codex
 npx workflow-ledger setup --tool all
 ```
 
-Then initialize a project ledger from the target project root:
+Then initialize a project ledger from the target project root. Bare `init` asks you to choose a language first; automation can pass `--lang en` or `--lang zh-CN` to skip the prompt:
 
 ```bash
 npx workflow-ledger init
-npx workflow-ledger init --tool claude-code
-npx workflow-ledger init --tool codex
-npx workflow-ledger init --tool all
+npx workflow-ledger init --lang en
+npx workflow-ledger init --tool claude-code --lang en
+npx workflow-ledger init --tool codex --lang en
+npx workflow-ledger init --tool all --lang en
 ```
 
-`setup` installs global tool integrations. `init` creates project-local ledger files and short instruction snippets. `claude-code` uses `.claude/WORKFLOW.md`; `codex` uses `.workflow-ledger/WORKFLOW.md` plus `AGENTS.md`.
+`setup` installs global tool integrations. `init` creates project-local ledger files and short instruction snippets. `claude-code` uses `.claude/WORKFLOW.md`; `codex` uses `.workflow-ledger/WORKFLOW.md` plus `AGENTS.md`. The language choice controls newly created ledger templates and tool instruction snippets; existing files are not overwritten.
 
 The Bash installer remains available for Claude Code project initialization:
 

package/README.zh-CN.md

@@ -92,16 +92,17 @@ npx workflow-ledger setup --tool codex
 npx workflow-ledger setup --tool all
 ```
 
-然后在目标项目根目录初始化 ledger：
+然后在目标项目根目录初始化 ledger。裸 `init` 会先交互式选择语言；自动化脚本可传 `--lang en` 或 `--lang zh-CN` 跳过交互：
 
 ```bash
 npx workflow-ledger init
-npx workflow-ledger init --tool claude-code
-npx workflow-ledger init --tool codex
-npx workflow-ledger init --tool all
+npx workflow-ledger init --lang zh-CN
+npx workflow-ledger init --tool claude-code --lang zh-CN
+npx workflow-ledger init --tool codex --lang zh-CN
+npx workflow-ledger init --tool all --lang zh-CN
 ```
 
-`setup` 安装全局工具接入；`init` 创建项目本地 ledger 和短指令片段。`claude-code` 使用 `.claude/WORKFLOW.md`；`codex` 使用 `.workflow-ledger/WORKFLOW.md` 和 `AGENTS.md`。
+`setup` 安装全局工具接入；`init` 创建项目本地 ledger 和短指令片段。`claude-code` 使用 `.claude/WORKFLOW.md`；`codex` 使用 `.workflow-ledger/WORKFLOW.md` 和 `AGENTS.md`。语言选择会影响新创建的 ledger 模板和工具指令片段；已有文件不会被覆盖。
 
 Bash 安装器仍可用于 Claude Code 项目初始化：
 

package/bin/workflow-ledger

@@ -21,7 +21,7 @@ workflow-ledger — lightweight project-local workflow guardrails
 
 Usage:
   workflow-ledger help
-  workflow-ledger init
+  workflow-ledger init [--lang en|zh-CN]
   workflow-ledger doctor
   workflow-ledger list
   workflow-ledger hooks status
@@ -71,9 +71,14 @@ hook_status_value() {
 }
 
 find_template() {
+  local language="$1"
+  local template_name='WORKFLOW.md'
+  if [ "$language" = 'zh-CN' ]; then
+    template_name='WORKFLOW.zh-CN.md'
+  fi
   local candidates=(
-    "$ROOT/.claude/skills/workflow-ledger/templates/WORKFLOW.md"
-    "$REPO_ROOT/skills/workflow-ledger/templates/WORKFLOW.md"
+    "$ROOT/.claude/skills/workflow-ledger/templates/$template_name"
+    "$REPO_ROOT/skills/workflow-ledger/templates/$template_name"
   )
   local candidate
   for candidate in "${candidates[@]}"; do
@@ -85,7 +90,52 @@ find_template() {
   return 1
 }
 
+normalize_language() {
+  case "$1" in
+    en|english) printf 'en' ;;
+    zh|zh-CN|zh-cn|zh_CN|cn|chinese|中文) printf 'zh-CN' ;;
+    *) return 1 ;;
+  esac
+}
+
+choose_language() {
+  local answer=''
+  if [ -t 0 ] && [ -t 1 ]; then
+    printf 'Choose language / 选择语言 [1] English [2] 简体中文: '
+    IFS= read -r answer || answer=''
+    case "$answer" in
+      2|zh|zh-CN|zh-cn|cn|中文) printf 'zh-CN'; return 0 ;;
+    esac
+  fi
+  printf 'en'
+}
+
 cmd_init() {
+  local language=''
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --lang|--language)
+        language="${2:-}"
+        shift 2
+        ;;
+      --lang=*|--language=*)
+        language="${1#*=}"
+        shift
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
+  if [ -n "$language" ]; then
+    if ! language="$(normalize_language "$language")"; then
+      printf 'error: unknown language. Expected en or zh-CN.\n' >&2
+      return 1
+    fi
+  else
+    language="$(choose_language)"
+  fi
+
   if ! mkdir -p "$ROOT/.claude" 2>/dev/null; then
     printf 'error: cannot create .claude directory\n' >&2
     return 1
@@ -95,7 +145,7 @@ cmd_init() {
     printf 'kept existing .claude/WORKFLOW.md\n'
   else
     local template
-    if ! template="$(find_template)"; then
+    if ! template="$(find_template "$language")"; then
       printf 'workflow-ledger skill template not found; run install.sh from the workflow-ledger checkout.\n' >&2
       return 0
     fi

package/bin/workflow-ledger.js

@@ -2,6 +2,8 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const readline = require('readline/promises');
+const { stdin: input, stdout: output } = require('process');
 const { spawnSync } = require('child_process');
 
 const repoRoot = path.resolve(__dirname, '..');
@@ -15,12 +17,23 @@ const toolAliases = new Map([
   ['all', 'all'],
 ]);
 
+const languageAliases = new Map([
+  ['en', 'en'],
+  ['english', 'en'],
+  ['zh', 'zh-CN'],
+  ['zh-cn', 'zh-CN'],
+  ['zh_CN', 'zh-CN'],
+  ['cn', 'zh-CN'],
+  ['chinese', 'zh-CN'],
+  ['中文', 'zh-CN'],
+]);
+
 function printHelp() {
   console.log(`workflow-ledger — lightweight workflow guardrails for AI coding agents
 
 Usage:
   workflow-ledger setup [--tool claude-code|codex|all]
-  workflow-ledger init [--tool claude-code|codex|all] [--root PATH]
+  workflow-ledger init [--tool claude-code|codex|all] [--lang en|zh-CN] [--root PATH]
   workflow-ledger help
   workflow-ledger doctor
   workflow-ledger list
@@ -31,14 +44,26 @@ setup installs global tool integrations. init creates project-local ledger files
 }
 
 function parseArgs(argv) {
-  const args = { command: argv[0] || 'help', tool: 'claude-code', root: targetRoot };
+  const args = { command: argv[0] || 'help', tool: 'claude-code', language: '', root: targetRoot, interactiveLanguage: argv[0] === 'init' };
   for (let i = 1; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--tool') {
       args.tool = argv[i + 1] || '';
+      args.interactiveLanguage = false;
       i += 1;
     } else if (arg.startsWith('--tool=')) {
       args.tool = arg.slice('--tool='.length);
+      args.interactiveLanguage = false;
+    } else if (arg === '--lang' || arg === '--language') {
+      args.language = argv[i + 1] || '';
+      args.interactiveLanguage = false;
+      i += 1;
+    } else if (arg.startsWith('--lang=')) {
+      args.language = arg.slice('--lang='.length);
+      args.interactiveLanguage = false;
+    } else if (arg.startsWith('--language=')) {
+      args.language = arg.slice('--language='.length);
+      args.interactiveLanguage = false;
     } else if (arg === '--root') {
       args.root = path.resolve(argv[i + 1] || '.');
       i += 1;
@@ -47,6 +72,7 @@ function parseArgs(argv) {
     }
   }
   args.tool = toolAliases.get(args.tool) || args.tool;
+  args.language = args.language ? languageAliases.get(args.language) || args.language : 'en';
   return args;
 }
 
@@ -103,6 +129,32 @@ function validateTool(tool) {
   return true;
 }
 
+function validateLanguage(language) {
+  if (!['en', 'zh-CN'].includes(language)) {
+    console.error(`error: unknown language '${language}'. Expected en or zh-CN.`);
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
+async function chooseLanguage() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return 'en';
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question('Choose language / 选择语言 [1] English [2] 简体中文: ');
+    const normalized = answer.trim().toLowerCase();
+    if (['2', 'zh', 'zh-cn', 'cn', '中文'].includes(normalized)) return 'zh-CN';
+    return 'en';
+  } finally {
+    rl.close();
+  }
+}
+
+function localizedPath(...segments) {
+  return path.join(repoRoot, ...segments);
+}
+
 function createResult() {
   return { configured: [], skipped: [], errors: [] };
 }
@@ -169,11 +221,19 @@ function setup(args) {
   console.log('\nNext: run workflow-ledger init in a project.');
 }
 
-function initClaudeCodeProject(root, result) {
+function templateFile(language, englishPath, chinesePath) {
+  return language === 'zh-CN' ? localizedPath(...chinesePath) : localizedPath(...englishPath);
+}
+
+function initClaudeCodeProject(root, language, result) {
   const claudeDir = path.join(root, '.claude');
   ensureDir(claudeDir);
   copyFileIfMissing(
-    path.join(repoRoot, 'skills', 'workflow-ledger', 'templates', 'WORKFLOW.md'),
+    templateFile(
+      language,
+      ['skills', 'workflow-ledger', 'templates', 'WORKFLOW.md'],
+      ['skills', 'workflow-ledger', 'templates', 'WORKFLOW.zh-CN.md']
+    ),
     path.join(claudeDir, 'WORKFLOW.md'),
     'created .claude/WORKFLOW.md',
     'kept existing .claude/WORKFLOW.md',
@@ -181,7 +241,11 @@ function initClaudeCodeProject(root, result) {
   );
   appendSnippet(
     '## Workflow Ledger',
-    path.join(repoRoot, 'examples', 'claude-project', 'CLAUDE.md.snippet'),
+    templateFile(
+      language,
+      ['examples', 'claude-project', 'CLAUDE.md.snippet'],
+      ['examples', 'claude-project', 'CLAUDE.zh-CN.md.snippet']
+    ),
     path.join(root, 'CLAUDE.md'),
     'updated CLAUDE.md',
     'kept existing Workflow Ledger section in CLAUDE.md',
@@ -189,11 +253,15 @@ function initClaudeCodeProject(root, result) {
   );
 }
 
-function initCodexProject(root, result) {
+function initCodexProject(root, language, result) {
   const ledgerDir = path.join(root, '.workflow-ledger');
   ensureDir(ledgerDir);
   copyFileIfMissing(
-    path.join(repoRoot, 'templates', 'WORKFLOW.md'),
+    templateFile(
+      language,
+      ['templates', 'WORKFLOW.md'],
+      ['templates', 'WORKFLOW.zh-CN.md']
+    ),
     path.join(ledgerDir, 'WORKFLOW.md'),
     'created .workflow-ledger/WORKFLOW.md',
     'kept existing .workflow-ledger/WORKFLOW.md',
@@ -201,7 +269,11 @@ function initCodexProject(root, result) {
   );
   appendSnippet(
     '# Workflow Ledger',
-    path.join(repoRoot, 'examples', 'codex-project', 'AGENTS.md.snippet'),
+    templateFile(
+      language,
+      ['examples', 'codex-project', 'AGENTS.md.snippet'],
+      ['examples', 'codex-project', 'AGENTS.zh-CN.md.snippet']
+    ),
     path.join(root, 'AGENTS.md'),
     'updated AGENTS.md',
     'kept existing Workflow Ledger section in AGENTS.md',
@@ -209,12 +281,14 @@ function initCodexProject(root, result) {
   );
 }
 
-function initProject(args) {
+async function initProject(args) {
   if (!validateTool(args.tool)) return;
+  if (!validateLanguage(args.language)) return;
+  const language = args.interactiveLanguage ? await chooseLanguage() : args.language;
   const result = createResult();
   ensureDir(args.root);
-  if (args.tool === 'claude-code' || args.tool === 'all') initClaudeCodeProject(args.root, result);
-  if (args.tool === 'codex' || args.tool === 'all') initCodexProject(args.root, result);
+  if (args.tool === 'claude-code' || args.tool === 'all') initClaudeCodeProject(args.root, language, result);
+  if (args.tool === 'codex' || args.tool === 'all') initCodexProject(args.root, language, result);
   printResult('Workflow Ledger Init', result);
 }
 
@@ -228,12 +302,19 @@ function delegateToBash(argv) {
 }
 
 const args = parseArgs(process.argv.slice(2));
-if (args.command === 'help' || args.command === '-h' || args.command === '--help') {
-  printHelp();
-} else if (args.command === 'setup') {
-  setup(args);
-} else if (args.command === 'init') {
-  initProject(args);
-} else {
-  delegateToBash(process.argv.slice(2));
-}
+async function main() {
+  if (args.command === 'help' || args.command === '-h' || args.command === '--help') {
+    printHelp();
+  } else if (args.command === 'setup') {
+    setup(args);
+  } else if (args.command === 'init') {
+    await initProject(args);
+  } else {
+    delegateToBash(process.argv.slice(2));
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/docs/cli.md

@@ -16,9 +16,12 @@ It does not modify your shell `PATH`.
 workflow-ledger setup --tool claude-code
 workflow-ledger setup --tool codex
 workflow-ledger setup --tool all
-workflow-ledger init --tool claude-code
-workflow-ledger init --tool codex
-workflow-ledger init --tool all
+workflow-ledger init
+workflow-ledger init --lang en
+workflow-ledger init --lang zh-CN
+workflow-ledger init --tool claude-code --lang en
+workflow-ledger init --tool codex --lang en
+workflow-ledger init --tool all --lang en
 workflow-ledger doctor
 workflow-ledger list
 workflow-ledger hooks status
@@ -37,11 +40,13 @@ Installs global Workflow Ledger integrations for supported AI coding tools.
 
 ## `init`
 
-Creates project-local Workflow Ledger files for selected tools.
+Creates project-local Workflow Ledger files for selected tools. Bare `init` asks for a language when run in a terminal; pass `--lang en` or `--lang zh-CN` for non-interactive use.
 
 - `--tool claude-code` creates `.claude/WORKFLOW.md` and updates `CLAUDE.md`.
 - `--tool codex` creates `.workflow-ledger/WORKFLOW.md` and updates `AGENTS.md`.
 - `--tool all` initializes both project adapters.
+- `--lang en` creates English ledger templates and instruction snippets.
+- `--lang zh-CN` creates Simplified Chinese ledger templates and instruction snippets.
 - `--root PATH` targets a project root other than the current directory.
 
 `init` preserves existing ledger files and instruction sections.

package/examples/claude-project/CLAUDE.zh-CN.md.snippet

@@ -0,0 +1,18 @@
+## Workflow Ledger
+
+使用 `workflow-ledger` 跟踪可恢复的开发工作。
+
+- 执行前先分级：Level 0 问答，Level 1 轻量编辑，Level 2 标准代码工作，Level 3 复杂工作。
+- Level 2/3 任务，以及用户希望跨会话跟踪的任务，都维护在 `.claude/WORKFLOW.md` 中。
+- 被跟踪的工作只记录恢复状态：`Intent`、可变的 `Current todo`、`Prerequisites`、可选的 `Blocked by`，以及一个具体的 `Resume next`。
+- 关闭工作前，把任务移到 `Completed`，写简短 `Close summary`：outcome、validation、gaps；验证失败时任务保持 In Progress 或 Blocked。
+- 记录依赖和发现的未来任务；先完成阻塞当前工作的前置条件，把非阻塞发现延后到 Backlog/Future。
+- 当前会话执行用 TodoWrite；里程碑历史和恢复点用 `.claude/WORKFLOW.md`。
+- 不要创建附件或额外 spec 文件，除非 Level 3 工作确实需要，或用户明确要求。
+
+不要找理由跳过 ledger：
+
+- “这个很小”仍然需要分级；Level 2/3 工作必须跟踪。
+- “我之后再更新”不安全；在重要待办/范围变化、阻塞、验证结果和交接点更新。
+- TodoWrite 是会话本地状态；`.claude/WORKFLOW.md` 是持久恢复状态。
+- 保持核心字段稳定，让 `.claude/bin/workflow-ledger doctor` 能检查 ledger。

package/examples/codex-project/AGENTS.zh-CN.md.snippet

@@ -0,0 +1,11 @@
+# Workflow Ledger
+
+把 Workflow Ledger 作为 Codex 会话共享的恢复状态。
+
+- 恢复被跟踪的工作前，先读取 `.workflow-ledger/WORKFLOW.md`。
+- Level 2/3 或跨会话任务记录在 `.workflow-ledger/WORKFLOW.md`。
+- 保持 ledger 简短：当前工作、进展，以及一个具体的 `Resume next` 动作。
+- 默认只有一个 Active 任务；不确定的后续事项放到 Backlog/Future。
+- 使用 `Intent`、可变的 `Current todo`、`Prerequisites`、可选的 `Blocked by`，以及一个具体的 `Resume next`。
+- 关闭工作前记录简短 `Close summary`：outcome、validation、gaps。
+- 不要把完整命令输出、原始工具 JSON、详细 diff 或临时推理粘进 ledger。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow-ledger",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Lightweight, recoverable workflow ledger for AI coding agents.",
   "license": "MIT",
   "repository": {

package/skills/workflow-ledger/templates/WORKFLOW.zh-CN.md

@@ -0,0 +1,50 @@
+# Workflow Ledger
+
+Claude Code 开发工作的轻量级可恢复台账。
+
+## Active
+
+<!-- workflow-ledger:task
+id: WF-YYYY-MM-DD-001
+level: 2
+status: In Progress
+current_phase: 当前焦点
+updated: YYYY-MM-DD
+-->
+
+### WF-YYYY-MM-DD-001 — 任务标题
+Status: In Progress
+Level: 2
+Started: YYYY-MM-DD
+Last updated: YYYY-MM-DD
+Current phase: 当前焦点
+
+Intent:
+- 一个用户可见的目标或变更意图。
+
+Current todo:
+- [ ] 可随发现调整的下一步事项。
+
+Changes:
+- 记录会影响恢复上下文的范围、待办、前置条件或阻塞变化。
+
+Prerequisites:
+- 继续当前工作前必须满足的条件，或 None。
+
+Resume next:
+- 一个具体的下一步动作。
+
+## Backlog / Future
+
+- [ ] 当前任务范围外发现的未来事项 — 因为不阻塞当前意图而延后。
+
+## Completed
+
+### WF-YYYY-MM-DD-000 — 已完成任务标题
+Completed: YYYY-MM-DD
+Level: 1
+
+Close summary:
+- Outcome: 用户可见结果。
+- Validation: 已执行的检查。
+- Gaps: 剩余后续事项或 none。

package/templates/WORKFLOW.zh-CN.md

@@ -0,0 +1,50 @@
+# Workflow Ledger
+
+AI coding agent 共享的可恢复状态台账。
+
+## Active
+
+<!-- workflow-ledger:task
+id: WF-YYYY-MM-DD-001
+level: 2
+status: In Progress
+current_phase: 当前焦点
+updated: YYYY-MM-DD
+-->
+
+### WF-YYYY-MM-DD-001 — 任务标题
+Status: In Progress
+Level: 2
+Started: YYYY-MM-DD
+Last updated: YYYY-MM-DD
+Current phase: 当前焦点
+
+Intent:
+- 一个用户可见的目标或变更意图。
+
+Current todo:
+- [ ] 可随发现调整的下一步事项。
+
+Changes:
+- 记录会影响恢复上下文的范围、待办、前置条件或阻塞变化。
+
+Prerequisites:
+- 继续当前工作前必须满足的条件，或 None。
+
+Resume next:
+- 一个具体的下一步动作。
+
+## Backlog / Future
+
+- [ ] 当前任务范围外发现的未来事项 — 因为不阻塞当前意图而延后。
+
+## Completed
+
+### WF-YYYY-MM-DD-000 — 已完成任务标题
+Completed: YYYY-MM-DD
+Level: 1
+
+Close summary:
+- Outcome: 用户可见结果。
+- Validation: 已执行的检查。
+- Gaps: 剩余后续事项或 none。