workflow-ledger 0.3.5

package/docs/cli.md

@@ -0,0 +1,94 @@
+# CLI
+
+`workflow-ledger` includes a small zero-dependency Bash CLI for project-local guardrails.
+
+The installer copies it to:
+
+```bash
+.claude/bin/workflow-ledger
+```
+
+It does not modify your shell `PATH`.
+
+## Commands
+
+```bash
+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 doctor
+workflow-ledger list
+workflow-ledger hooks status
+workflow-ledger hooks install
+```
+
+## `setup`
+
+Installs global Workflow Ledger integrations for supported AI coding tools.
+
+- `--tool claude-code` installs the global Claude Code skill to `~/.claude/skills/workflow-ledger` and copies the local CLI to `~/.claude/bin/workflow-ledger`.
+- `--tool codex` installs the Codex skill to `~/.agents/skills/workflow-ledger` when `~/.codex` exists.
+- `--tool all` configures all detected adapters.
+
+`setup` is environment-level and may skip tools that are not installed.
+
+## `init`
+
+Creates project-local Workflow Ledger files for selected tools.
+
+- `--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.
+- `--root PATH` targets a project root other than the current directory.
+
+`init` preserves existing ledger files and instruction sections.
+
+## `doctor`
+
+Runs read-only health checks against `.claude/WORKFLOW.md`.
+
+Errors return exit code `1`:
+
+- Missing `.claude/WORKFLOW.md`.
+- Missing core sections: `Active`, `Backlog / Future`, or `Completed`.
+- In Progress task without `Current phase`.
+- In Progress task without `Intent`.
+- In Progress task without `Current todo`.
+- In Progress task without `Resume next`.
+- Blocked task without `Blocked by` or `Resume next`.
+
+Warnings do not fail the command:
+
+- More than one Active task.
+- Level 2/3 task without `Changes` or `Prerequisites`.
+- Ledger older than the latest git commit.
+- Active task with more than 80 lines.
+- Completed task still under `Active` without `Close summary`.
+- Backlog with more than 10 items.
+
+## `list`
+
+Prints a compact summary of active tasks, current focus, resume next action, backlog count, and completed count.
+
+If `.claude/WORKFLOW.md` is missing, `list` prints a message and exits `0`.
+
+## Hooks
+
+Hooks are optional and advisory.
+
+```bash
+.claude/bin/workflow-ledger hooks status
+.claude/bin/workflow-ledger hooks install
+```
+
+`hooks install` writes these project-local hook files:
+
+```text
+.claude/hooks/hooks.json
+.claude/hooks/session-start
+```
+
+It does not overwrite existing hook files and does not modify global Claude Code settings.

package/docs/design.md

@@ -0,0 +1,43 @@
+# Design
+
+`workflow-ledger` is a lightweight OpenSpec-style change ledger for Claude Code projects.
+
+## Problem
+
+Long-running Claude Code tasks can be interrupted, resumed in a new session, or continued by another agent. Plain chat history and current-session todos are not enough for reliable recovery. Heavy spec systems solve this with many files and formal stages, but that is too much for everyday development.
+
+## Approach
+
+Use one single-file change ledger, `.claude/WORKFLOW.md`, plus a reusable Claude Code skill.
+
+The skill teaches Claude how to:
+
+- classify task weight
+- create or update one intent-first task entry
+- keep `Current todo` mutable as implementation reveals new work
+- track prerequisites, blockers, and discovered future work
+- close completed work into a concise history section
+
+## Non-goals
+
+- No per-task file by default.
+- No mandatory proposal/design/tasks documents.
+- No mandatory hook automation.
+- No heavyweight CLI runtime or package manager; the optional CLI stays zero-dependency and project-local.
+
+## File model
+
+- `.claude/WORKFLOW.md`: project-local change ledger.
+- `.claude/skills/workflow-ledger/SKILL.md`: reusable workflow instructions.
+- Optional attachments: only for long Level 3 details.
+
+## Task levels
+
+- Level 0: Q&A/read-only, no ledger.
+- Level 1: lightweight edit, ledger optional.
+- Level 2: standard code work, ledger required.
+- Level 3: complex work, ledger required and optional attachments allowed.
+
+## Recovery model
+
+To resume work, read `.claude/WORKFLOW.md`, find `Active`, follow `Intent`, `Current phase`, `Current todo`, `Prerequisites`, `Blocked by`, and `Resume next`. Verify the current repository state before trusting stale ledger entries.

package/docs/design.zh-CN.md

@@ -0,0 +1,47 @@
+# 设计说明
+
+`workflow-ledger` 是面向 Claude Code 项目的轻量级 OpenSpec-style change ledger。
+
+## 问题
+
+长时间运行的 Claude Code 任务可能会中断、在新会话中恢复，或者交给另一个 agent 继续。单靠聊天历史和当前会话 todo，不足以可靠恢复任务状态。
+
+重型 spec 系统可以通过许多文件和正式阶段解决这个问题，但这对日常开发来说经常太重。
+
+## 方案
+
+使用一个单文件 change ledger `.claude/WORKFLOW.md`，再配合一个可复用 Claude Code skill。
+
+skill 指导 Claude：
+
+- 判断任务重量级别。
+- 创建或更新一个 intent-first 任务条目。
+- 执行中发现新情况时允许调整 `Current todo`。
+- 跟踪前置依赖、阻塞和执行中发现的未来任务。
+- 把完成任务归档为简洁历史。
+
+## 非目标
+
+- 默认不为每个任务创建独立文件。
+- 不强制创建 proposal / design / tasks 文档。
+- 不强制使用 hook 自动化。
+- 不引入重型 CLI 运行时或包管理器；可选 CLI 保持零依赖、项目本地。
+
+## 文件模型
+
+- `.claude/WORKFLOW.md`：项目本地 change ledger。
+- `.claude/skills/workflow-ledger/SKILL.md`：可复用工作流说明。
+- 可选附件：只用于 Level 3 的长细节。
+
+## 任务级别
+
+- Level 0：问答 / 只读解释，不需要 ledger。
+- Level 1：轻量修改，ledger 可选。
+- Level 2：标准代码任务，需要 ledger。
+- Level 3：复杂任务，需要 ledger，可选附件。
+
+## 恢复模型
+
+恢复任务时读取 `.claude/WORKFLOW.md`，找到 `Active`，根据 `Intent`、`Current phase`、`Current todo`、`Prerequisites`、`Blocked by` 和 `Resume next` 继续。
+
+在信任 ledger 前，应先检查当前仓库状态；如果代码现状和 ledger 不一致，以当前代码和 git 状态为准，并更新 ledger。

package/docs/usage.md

@@ -0,0 +1,119 @@
+# Usage
+
+## Install into a project
+
+Recommended global setup:
+
+```bash
+npx workflow-ledger setup
+```
+
+Configure a specific AI coding tool:
+
+```bash
+npx workflow-ledger setup --tool claude-code
+npx workflow-ledger setup --tool codex
+npx workflow-ledger setup --tool all
+```
+
+Then initialize the project ledger from the project root:
+
+```bash
+npx workflow-ledger init
+npx workflow-ledger init --tool claude-code
+npx workflow-ledger init --tool codex
+npx workflow-ledger init --tool all
+```
+
+The `claude-code` project adapter creates `.claude/WORKFLOW.md` and updates `CLAUDE.md`. The `codex` project adapter creates `.workflow-ledger/WORKFLOW.md` and updates `AGENTS.md`.
+
+The Bash installer remains available:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MorseWayne/workflow-ledger/main/install.sh | bash
+```
+
+The init flow is idempotent:
+
+- creates the relevant Workflow Ledger file only if missing
+- preserves existing instruction sections and ledgers
+
+If you already have a local checkout:
+
+```bash
+/path/to/workflow-ledger/install.sh /path/to/your/project
+```
+
+Manual Claude Code install has three required project-local steps: copy the skill, add the `CLAUDE.md` snippet, and create the ledger file.
+
+```bash
+mkdir -p .claude/skills .claude
+cp -R /path/to/workflow-ledger/skills/workflow-ledger .claude/skills/workflow-ledger
+cp /path/to/workflow-ledger/skills/workflow-ledger/templates/WORKFLOW.md .claude/WORKFLOW.md
+```
+
+Add the `CLAUDE.md` snippet so Claude has an always-loaded reminder to use the skill for Level 2/3 work:
+
+```bash
+cat /path/to/workflow-ledger/examples/claude-project/CLAUDE.md.snippet >> CLAUDE.md
+```
+
+## CLI guardrails
+
+After installation, you can run the CLI:
+
+```bash
+workflow-ledger doctor
+workflow-ledger list
+workflow-ledger hooks status
+```
+
+For Claude Code project-local installs, the copied CLI is also available:
+
+```bash
+.claude/bin/workflow-ledger doctor
+```
+
+Install optional advisory hooks only when you want SessionStart reminders:
+
+```bash
+.claude/bin/workflow-ledger hooks install
+```
+
+The CLI is a guardrail and summary tool. Claude still uses the `workflow-ledger` skill for the actual workflow.
+
+## Start tracking work
+
+In Claude Code:
+
+```text
+/workflow-ledger start "add streaming usage accounting"
+```
+
+Claude should:
+
+1. classify the task level
+2. create or update `.claude/WORKFLOW.md`
+3. write the smallest `Intent`
+4. set mutable `Current todo`, `Prerequisites`, and `Resume next`
+5. use TodoWrite for the current session
+
+## Resume work
+
+```text
+/workflow-ledger resume
+```
+
+Claude should read `.claude/WORKFLOW.md`, verify repo state, and continue from `Intent`, `Current phase`, `Current todo`, `Prerequisites`, `Blocked by`, and `Resume next`.
+
+## Close work
+
+```text
+/workflow-ledger close
+```
+
+Claude should move the task from `Active` to `Completed` and record a short `Close summary` with outcome, validation, and gaps.
+
+## Keep it lightweight
+
+Do not create attachments unless a Level 3 task needs long research, design details, or large validation output.

package/docs/usage.zh-CN.md

@@ -0,0 +1,117 @@
+# 使用指南
+
+本文介绍如何在 Claude Code 项目中使用 `workflow-ledger`。
+
+## 安装到项目
+
+先做全局工具接入：
+
+```bash
+npx workflow-ledger setup
+```
+
+配置特定工具：
+
+```bash
+npx workflow-ledger setup --tool claude-code
+npx workflow-ledger setup --tool codex
+npx workflow-ledger setup --tool all
+```
+
+然后在项目根目录初始化 ledger：
+
+```bash
+npx workflow-ledger init
+npx workflow-ledger init --tool claude-code
+npx workflow-ledger init --tool codex
+npx workflow-ledger init --tool all
+```
+
+`claude-code` 项目 adapter 会创建 `.claude/WORKFLOW.md` 并更新 `CLAUDE.md`。`codex` 项目 adapter 会创建 `.workflow-ledger/WORKFLOW.md` 并更新 `AGENTS.md`。
+
+Bash 安装脚本仍然可用：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MorseWayne/workflow-ledger/main/install.sh | bash
+```
+
+初始化流程是幂等的：
+
+- 只在缺失时创建对应的 Workflow Ledger 文件
+- 保留已有工具指令片段和 ledger
+
+如果你已经有本地 checkout：
+
+```bash
+/path/to/workflow-ledger/install.sh /path/to/your/project
+```
+
+手动安装仍然有三个项目本地必需步骤：复制 skill、追加 `CLAUDE.md` 规则片段、创建 ledger 文件。
+
+```bash
+mkdir -p .claude/skills .claude
+cp -R /path/to/workflow-ledger/skills/workflow-ledger .claude/skills/workflow-ledger
+cp /path/to/workflow-ledger/skills/workflow-ledger/templates/WORKFLOW.md .claude/WORKFLOW.md
+```
+
+把项目规则片段追加到 `CLAUDE.md`，让 Claude 始终能看到 Level 2/3 任务需要使用 skill 和 ledger 的简短提醒：
+
+```bash
+cat /path/to/workflow-ledger/examples/claude-project/CLAUDE.md.snippet >> CLAUDE.md
+```
+
+## 开始跟踪任务
+
+在 Claude Code 中输入：
+
+```text
+/workflow-ledger start "add streaming usage accounting"
+```
+
+Claude 应该：
+
+1. 判断任务级别。
+2. 创建或更新 `.claude/WORKFLOW.md`。
+3. 写最小 `Intent`。
+4. 设置可变的 `Current todo`、`Prerequisites` 和 `Resume next`。
+5. 使用 TodoWrite 跟踪当前会话执行。
+
+## 恢复任务
+
+```text
+/workflow-ledger resume
+```
+
+Claude 应该读取 `.claude/WORKFLOW.md`，检查当前仓库状态，然后根据 `Intent`、`Current phase`、`Current todo`、`Prerequisites`、`Blocked by` 和 `Resume next` 继续执行。
+
+## 更新任务
+
+在执行过程中，只在里程碑节点更新 ledger：
+
+- 任务开始
+- todo/scope 出现实质变化
+- 新增前置依赖
+- 工作被阻塞
+- 验证结果
+- 中断交接
+- 提交或关闭任务
+
+不要每次小编辑都更新。
+
+## 关闭任务
+
+```text
+/workflow-ledger close
+```
+
+Claude 应该：
+
+1. 确认必要工作已完成，或明确延期。
+2. 把任务从 `Active` 移到 `Completed`。
+3. 用 `Close summary:` 替换 active-only 字段。
+4. 只记录 outcome、validation 和 gaps。
+5. 把未来工作保留在 `Backlog / Future`。
+
+## 保持轻量
+
+不要默认创建附件。只有 Level 3 任务需要长调研、详细设计或大量验证输出时，才创建附件并从 `.claude/WORKFLOW.md` 链接过去。

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

@@ -0,0 +1,18 @@
+## Workflow Ledger
+
+Use `workflow-ledger` for recoverable development work.
+
+- Classify tasks before executing: Level 0 Q&A, Level 1 lightweight edit, Level 2 standard code work, Level 3 complex work.
+- Maintain `.claude/WORKFLOW.md` for Level 2/3 tasks and for any task the user wants tracked across sessions.
+- Organize tracked work as resume state: `Intent`, mutable `Current todo`, `Prerequisites`, optional `Blocked by`, and one concrete `Resume next`.
+- Before closing work, move it to `Completed` with a short `Close summary`: outcome, validation, and gaps; failed validation means the task stays In Progress or Blocked.
+- Record dependencies and discovered future tasks; complete prerequisites before blocked work, and defer non-blocking discoveries to Backlog/Future.
+- Use TodoWrite for current-session execution; use `.claude/WORKFLOW.md` for milestone history and resume points.
+- Do not create attachments or extra spec files unless Level 3 work genuinely needs them or the user asks.
+
+Do not rationalize skipping the ledger:
+
+- “This is small” still requires Level classification; Level 2/3 work is tracked.
+- “I will update it later” is unsafe; update at material todo/scope changes, blockers, validation results, and handoff points.
+- TodoWrite is session-local; `.claude/WORKFLOW.md` is the durable recovery state.
+- Keep core fields stable so `.claude/bin/workflow-ledger doctor` can check the ledger.

package/examples/claude-project/WORKFLOW.md

@@ -0,0 +1,36 @@
+# Example Workflow Ledger
+
+## Active
+
+### WF-2026-05-16-001 — Add reusable workflow tracking
+Status: In Progress
+Level: 2
+Started: 2026-05-16
+Last updated: 2026-05-16
+Current phase: Validate installation path
+
+Intent:
+- Add a reusable Claude Code workflow ledger skill without turning the ledger into a transcript or heavyweight spec.
+
+Current todo:
+- [x] Create skill directory.
+- [x] Write SKILL.md.
+- [ ] Validate README install flow.
+- [ ] Close the task if install validation passes.
+
+Changes:
+- 2026-05-16 — Use one .claude/WORKFLOW.md overview instead of one file per task.
+- 2026-05-16 — Keep optional attachments only for Level 3 detail that would make the ledger too long.
+
+Prerequisites:
+- README install instructions must match the actual setup command.
+
+Resume next:
+- Validate the README install flow and close the task if it works.
+
+## Backlog / Future
+
+- [ ] Add an optional hook recipe — deferred because install validation does not require it.
+- [ ] Add a CLI wrapper — deferred unless the skill-only workflow becomes insufficient.
+
+## Completed

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

@@ -0,0 +1,11 @@
+# Workflow Ledger
+
+Use Workflow Ledger as shared resume state for Codex sessions.
+
+- Read `.workflow-ledger/WORKFLOW.md` before resuming tracked work.
+- Track Level 2/3 or cross-session tasks in `.workflow-ledger/WORKFLOW.md`.
+- Keep the ledger short: current work, progress, and one concrete `Resume next` action.
+- Default to one Active task; move uncertain follow-ups to Backlog/Future.
+- Use `Intent`, mutable `Current todo`, `Prerequisites`, optional `Blocked by`, and one concrete `Resume next`.
+- Record a short `Close summary` before closing work: outcome, validation, and gaps.
+- Do not paste full command output, raw tool JSON, detailed diffs, or temporary reasoning into the ledger.

package/hooks/hooks.json

@@ -0,0 +1,10 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "command": ".claude/hooks/session-start"
+      }
+    ]
+  }
+}

package/hooks/session-start

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -u
+
+ledger=".claude/WORKFLOW.md"
+cli=".claude/bin/workflow-ledger"
+
+if [ ! -f "$ledger" ]; then
+  exit 0
+fi
+
+if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+  cat <<'PLUGIN_JSON'
+{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"Workflow Ledger detected.\n- Read .claude/WORKFLOW.md before resuming tracked work.\n- Check Active tasks, Current phase/current focus, Current todo, and Resume next.\n- Run workflow-ledger doctor if state may be stale."}}
+PLUGIN_JSON
+  exit 0
+fi
+
+printf 'Workflow Ledger detected.\n'
+printf -- '- Read .claude/WORKFLOW.md before resuming tracked work.\n'
+printf -- '- Check Active tasks, Current phase/current focus, Current todo, and Resume next.\n'
+
+if [ -x "$cli" ]; then
+  printf -- '- Run .claude/bin/workflow-ledger doctor if state may be stale.\n'
+else
+  printf -- '- Run workflow-ledger doctor if the project CLI is available.\n'
+fi
+
+exit 0

package/install.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_URL="https://github.com/MorseWayne/workflow-ledger"
+ARCHIVE_URL="https://github.com/MorseWayne/workflow-ledger/archive/refs/heads/main.tar.gz"
+MARKER="## Workflow Ledger"
+TARGET_DIR="${1:-$PWD}"
+
+TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
+SCRIPT_PATH="${BASH_SOURCE[0]-}"
+SCRIPT_DIR=""
+if [ -n "$SCRIPT_PATH" ] && [ "$SCRIPT_PATH" != "bash" ] && [ "$SCRIPT_PATH" != "-" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)"
+fi
+
+cleanup_dir=""
+cleanup() {
+  if [ -n "$cleanup_dir" ] && [ -d "$cleanup_dir" ]; then
+    rm -rf "$cleanup_dir"
+  fi
+}
+trap cleanup EXIT
+
+SOURCE_DIR="$SCRIPT_DIR"
+if [ ! -d "$SOURCE_DIR/skills/workflow-ledger" ] || [ ! -f "$SOURCE_DIR/examples/claude-project/CLAUDE.md.snippet" ] || [ ! -f "$SOURCE_DIR/bin/workflow-ledger" ]; then
+  if ! command -v curl >/dev/null 2>&1; then
+    echo "error: curl is required when install.sh is run outside a workflow-ledger checkout" >&2
+    exit 1
+  fi
+  if ! command -v tar >/dev/null 2>&1; then
+    echo "error: tar is required when install.sh is run outside a workflow-ledger checkout" >&2
+    exit 1
+  fi
+
+  cleanup_dir="$(mktemp -d)"
+  curl -fsSL "$ARCHIVE_URL" | tar -xz -C "$cleanup_dir"
+  SOURCE_DIR="$cleanup_dir/workflow-ledger-main"
+fi
+
+if command -v node >/dev/null 2>&1 && [ -f "$SOURCE_DIR/bin/workflow-ledger.js" ]; then
+  node "$SOURCE_DIR/bin/workflow-ledger.js" init --tool claude-code --root "$TARGET_DIR"
+else
+  mkdir -p "$TARGET_DIR/.claude/skills" "$TARGET_DIR/.claude" "$TARGET_DIR/.claude/bin"
+  rm -rf "$TARGET_DIR/.claude/skills/workflow-ledger"
+  cp -R "$SOURCE_DIR/skills/workflow-ledger" "$TARGET_DIR/.claude/skills/workflow-ledger"
+  cp "$SOURCE_DIR/bin/workflow-ledger" "$TARGET_DIR/.claude/bin/workflow-ledger"
+  chmod +x "$TARGET_DIR/.claude/bin/workflow-ledger"
+
+  if [ ! -f "$TARGET_DIR/.claude/WORKFLOW.md" ]; then
+    cp "$SOURCE_DIR/skills/workflow-ledger/templates/WORKFLOW.md" "$TARGET_DIR/.claude/WORKFLOW.md"
+    echo "created .claude/WORKFLOW.md"
+  else
+    echo "kept existing .claude/WORKFLOW.md"
+  fi
+
+  if [ ! -f "$TARGET_DIR/CLAUDE.md" ]; then
+    touch "$TARGET_DIR/CLAUDE.md"
+  fi
+
+  if grep -Fq "$MARKER" "$TARGET_DIR/CLAUDE.md"; then
+    echo "kept existing Workflow Ledger section in CLAUDE.md"
+  else
+    if [ -s "$TARGET_DIR/CLAUDE.md" ]; then
+      printf '\n\n' >> "$TARGET_DIR/CLAUDE.md"
+    fi
+    cat "$SOURCE_DIR/examples/claude-project/CLAUDE.md.snippet" >> "$TARGET_DIR/CLAUDE.md"
+    echo "updated CLAUDE.md"
+  fi
+
+  echo "installed workflow-ledger for Claude Code"
+fi
+
+echo "installed workflow-ledger into $TARGET_DIR"
+echo "next: run /workflow-ledger start \"your task\" in Claude Code"
+echo "optional: run .claude/bin/workflow-ledger doctor"

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "workflow-ledger",
+  "version": "0.3.5",
+  "description": "Lightweight, recoverable workflow ledger for AI coding agents.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MorseWayne/workflow-ledger.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MorseWayne/workflow-ledger/issues"
+  },
+  "homepage": "https://github.com/MorseWayne/workflow-ledger#readme",
+  "keywords": [
+    "claude-code",
+    "workflow",
+    "ledger",
+    "ai-coding",
+    "skills"
+  ],
+  "bin": {
+    "workflow-ledger": "bin/workflow-ledger.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "examples/",
+    "templates/",
+    "docs/*.md",
+    "hooks/",
+    ".claude-plugin/",
+    "install.sh",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "tests/run-cli-tests.sh && node tests/run-node-cli-tests.cjs && bash tests/claude-code/run-skill-behavior-test.sh"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}