workflow-ledger 0.3.5

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "workflow-ledger-dev",
+  "description": "Development marketplace for workflow-ledger",
+  "owner": {
+    "name": "MorseWayne"
+  },
+  "plugins": [
+    {
+      "name": "workflow-ledger",
+      "description": "Lightweight, recoverable workflow ledger for Claude Code projects",
+      "version": "0.3.5",
+      "source": "./",
+      "author": {
+        "name": "MorseWayne"
+      }
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "workflow-ledger",
+  "description": "Lightweight, recoverable workflow ledger for Claude Code projects",
+  "version": "0.3.5",
+  "author": {
+    "name": "MorseWayne"
+  },
+  "homepage": "https://github.com/MorseWayne/workflow-ledger",
+  "repository": "https://github.com/MorseWayne/workflow-ledger",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "skills",
+    "workflow",
+    "ledger",
+    "recoverability"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# workflow-ledger
+
+A lightweight OpenSpec-style change ledger for Claude Code.
+
+`workflow-ledger` helps Claude Code projects stay **traceable, resumable, and adaptable** without forcing every change through proposal/design/task/spec files.
+
+It is designed for one common failure mode of AI-assisted development:
+
+> The conversation is interrupted, context is compacted, or a new session starts — and nobody can immediately tell what was done, what was accepted, what is blocked, and what should happen next.
+
+`workflow-ledger` solves this with a single project overview file: `.claude/WORKFLOW.md`.
+
+[中文文档](README.zh-CN.md)
+
+## Why this workflow exists
+
+Many workflow systems solve recoverability by creating a lot of structure:
+
+- proposal files
+- design files
+- task files
+- per-feature folders
+- phase-specific artifacts
+- command-specific state
+
+That is valuable for large feature work, but too heavy for everyday Claude Code development. Most tasks need something smaller:
+
+- one place to see the active change intent
+- a mutable current todo instead of a frozen plan
+- visible prerequisites, blockers, and deferred work
+- a resume point for the next session
+- a short close summary when work finishes
+
+`workflow-ledger` keeps the parts that matter and removes the parts that slow small tasks down.
+
+## What it gives you
+
+- **One change ledger**: `.claude/WORKFLOW.md` is the source of truth.
+- **Task levels**: Level 0-3 classification keeps simple work light and complex work safer.
+- **Intent-first entries**: each active task records one small user-visible intent.
+- **Mutable todo**: `Current todo` can change as requirements, prerequisites, or blockers appear.
+- **Recoverability**: every active task has `Current phase` as current focus and `Resume next`.
+- **Dependency discipline**: blocking prerequisites stay in the active entry; non-blocking discoveries go to Backlog/Future.
+- **Low file count**: no per-task files by default.
+- **Claude Code native**: shipped as a reusable skill, no runtime dependency required.
+
+## How it compares
+
+| Approach | Strength | Tradeoff | workflow-ledger stance |
+|---|---|---|---|
+| Chat history only | Zero setup | Hard to recover after interruption or compaction | Not enough for multi-step work |
+| Todo list only | Great for current session | Not durable across sessions | Use TodoWrite for in-session execution only |
+| Heavy spec workflows | Strong governance and traceability | Many files and stage overhead | Use only when Level 3 work truly needs it |
+| Hooks-first automation | Deterministic enforcement | Can become noisy and rigid | Use hooks as optional guardrails, not the workflow engine |
+| `workflow-ledger` | Durable, lightweight, reviewable | Requires updating one ledger file at milestones | Default for recoverable Claude Code work |
+
+## Compared with specific tools
+
+| Tool / workflow | Best at | Typical shape | Where `workflow-ledger` differs |
+|---|---|---|---|
+| Superpowers-style skills | Teaching Claude repeatable behaviors through reusable skills and checklists | Skill packs with detailed procedures, design/planning loops, and explicit human approval gates | Uses the same skill-native delivery model, but narrows the scope to task memory: one ledger, change intent, mutable todo, prerequisites, and resume points |
+| GSD-style planning workflows | Breaking large work into researched phases with verification, security, UI, or evaluation reviews | Multi-agent planning and execution, phase documents, review reports, and stronger process gates | Keeps the recoverability pattern but removes most ceremony for day-to-day work; heavyweight review artifacts stay outside the default ledger |
+| OpenSpec-style spec workflows | Governing product or API changes with proposals, specs, tasks, and archival history | Formal proposal/design/task files with a spec lifecycle | Borrows intent/change discipline, but avoids making every change start with proposal/design/tasks/spec files |
+| Claude Code hooks | Deterministically enforcing a rule at tool or lifecycle boundaries | Event handlers for commands such as pre-tool, post-tool, stop, or compact | Treats hooks as optional guardrails; the workflow state remains human-readable in `.claude/WORKFLOW.md` |
+| TodoWrite / session todos | Managing what Claude is doing right now | In-session checklist that is easy to update frequently | Uses TodoWrite for live execution only; the ledger stores durable milestones and handoff context |
+
+In short: Superpowers teaches behaviors, GSD coordinates heavier execution, OpenSpec governs formal changes, hooks enforce events, and TodoWrite tracks the current session. `workflow-ledger` is the smaller missing layer between them: a single-file, OpenSpec-lite memory for everyday Claude Code development.
+
+## Inspired by existing workflows
+
+`workflow-ledger` borrows ideas from spec-driven and skill-driven workflows, but intentionally stays smaller.
+
+- From spec-driven systems such as OpenSpec: explicit change intent, dependency awareness, and archive-style close summaries.
+- From Claude Code skills and Superpowers-style workflows: reusable procedural guidance that loads when needed.
+- From hooks: the idea that some actions may need hard guardrails, while keeping those guardrails optional.
+
+The key design decision is simple:
+
+> Mandatory project rules stay short. Detailed workflow guidance lives in a skill. Durable change state lives in one ledger file.
+
+## Install
+
+Recommended global tool setup:
+
+```bash
+npx workflow-ledger setup
+```
+
+Configure specific AI coding tools:
+
+```bash
+npx workflow-ledger setup --tool claude-code
+npx workflow-ledger setup --tool codex
+npx workflow-ledger setup --tool all
+```
+
+Then initialize a project ledger from the target 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
+```
+
+`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 Bash installer remains available for Claude Code project initialization:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MorseWayne/workflow-ledger/main/install.sh | bash
+```
+
+If you already have a local checkout of `workflow-ledger`, you can run the installer directly:
+
+```bash
+/path/to/workflow-ledger/install.sh /path/to/your/project
+```
+
+Manual project-local install for Claude Code:
+
+```bash
+mkdir -p .claude/skills
+cp -R skills/workflow-ledger .claude/skills/workflow-ledger
+```
+
+Personal install only installs the skill; project setup still needs the `CLAUDE.md` snippet and `.claude/WORKFLOW.md`:
+
+```bash
+mkdir -p ~/.claude/skills
+cp -R skills/workflow-ledger ~/.claude/skills/workflow-ledger
+```
+
+The installer also copies a project-local CLI to `.claude/bin/workflow-ledger`:
+
+```bash
+.claude/bin/workflow-ledger doctor
+.claude/bin/workflow-ledger list
+```
+
+See [docs/cli.md](docs/cli.md) for command details. The CLI is an optional guardrail; it does not replace the skill workflow.
+
+Then invoke it in Claude Code:
+
+```text
+/workflow-ledger start "implement auth flow"
+/workflow-ledger resume
+/workflow-ledger close
+```
+
+## Project setup
+
+A project needs two layers:
+
+1. Global tool setup with `workflow-ledger setup` so supported agents can find the workflow instructions.
+2. Project initialization with `workflow-ledger init` so the repository has a ledger file and a short tool-specific reminder.
+
+For Claude Code, `init` adds the snippet from [examples/claude-project/CLAUDE.md.snippet](examples/claude-project/CLAUDE.md.snippet) to your project's `CLAUDE.md` and creates [skills/workflow-ledger/templates/WORKFLOW.md](skills/workflow-ledger/templates/WORKFLOW.md) at `.claude/WORKFLOW.md`.
+
+For Codex, `init --tool codex` adds [examples/codex-project/AGENTS.md.snippet](examples/codex-project/AGENTS.md.snippet) to `AGENTS.md` and creates [templates/WORKFLOW.md](templates/WORKFLOW.md) at `.workflow-ledger/WORKFLOW.md`.
+
+## The ledger shape
+
+A tracked task is organized like this:
+
+```markdown
+### WF-2026-05-16-001 — Add streaming usage accounting
+Status: In Progress
+Level: 2
+Current phase: Implement conversion fix
+
+Intent:
+- Stabilize streaming usage accounting without expanding the ledger into a transcript.
+
+Current todo:
+- [ ] Update converter.
+- [ ] Add regression test.
+
+Changes:
+- 2026-05-16 — Current implementation path narrowed to the provider conversion code.
+
+Prerequisites:
+- Existing streaming usage tests must be checked before editing.
+
+Resume next:
+- Update the converter and add the smallest regression test.
+```
+
+## Workflow levels
+
+| Level | Use for | Ledger? |
+|---|---|---|
+| Level 0 | Q&A, read-only explanation | No |
+| Level 1 | typo, docs tweak, tiny config, no behavior change | Optional |
+| Level 2 | standard code work, tests, single-module behavior changes | Yes |
+| Level 3 | new features, cross-module work, public APIs, unclear or high-risk changes | Yes, attachments optional |
+
+## Design principles
+
+- Keep the overview file useful at a glance.
+- Keep the active intent small and current.
+- Treat `Current todo` as mutable when implementation reveals new work.
+- Record why prerequisites or future tasks were added.
+- Avoid process for process's sake.
+- Prefer one durable ledger over many scattered notes.
+
+## When to use
+
+Use `workflow-ledger` for:
+
+- multi-step implementation work
+- tasks likely to span sessions
+- work where review history matters
+- debugging or refactoring with dependencies
+- any task where you need to know what is done and what is left
+
+Skip it for:
+
+- pure Q&A
+- trivial one-step changes
+- throwaway exploration
+- tasks where the user explicitly says not to track
+
+## Repository status
+
+This version supports both npm setup and the legacy Bash installer. The CLI can install Workflow Ledger for Claude Code, Codex, or both, while keeping the ledger format lightweight and tool-readable.

package/README.zh-CN.md

@@ -0,0 +1,224 @@
+# workflow-ledger
+
+面向 Claude Code 的轻量级 OpenSpec-style change ledger。
+
+`workflow-ledger` 让 Claude Code 项目在开发过程中保持**可跟踪、可恢复、可调整**，但不强迫每个任务都进入 proposal/design/tasks/spec 文件流程。
+
+它要解决的是 AI 辅助开发里非常常见的问题：
+
+> 会话中断、上下文压缩、换新会话继续时，没人能一眼看清已经做了什么、验收了什么、阻塞在哪里、下一步该干什么。
+
+`workflow-ledger` 用一个项目总览文件解决这个问题：`.claude/WORKFLOW.md`。
+
+## 为什么设计这个工作流
+
+很多工作流系统为了可恢复性，会引入很多结构：
+
+- proposal 文件
+- design 文件
+- task 文件
+- 每个功能一个目录
+- 阶段产物
+- 命令状态机
+
+这些对大型功能很有价值，但对日常 Claude Code 开发太重了。大多数任务真正需要的是：
+
+- 一个地方看当前 change intent
+- 可变的 `Current todo`，而不是冻结计划
+- 能看到前置依赖、阻塞和延期任务
+- 中断后能恢复
+- 完成时只写短 `Close summary`
+
+`workflow-ledger` 保留这些关键能力，同时避免制造大量文件。
+
+## 它提供什么
+
+- **单文件 change ledger**：`.claude/WORKFLOW.md` 是任务状态源。
+- **任务分级**：Level 0-3，让简单任务保持轻量，复杂任务更安全。
+- **Intent-first 条目**：每个 Active 任务只记录一个小的用户可见目标。
+- **可变 todo**：`Current todo` 可以随新增需求、前置依赖或阻塞调整。
+- **可恢复点**：每个活跃任务都有表示当前焦点的 `Current phase` 和 `Resume next`。
+- **依赖管理**：阻塞当前目标的前置依赖留在 Active；非阻塞发现进入 Backlog/Future。
+- **低文件数量**：默认不为每个任务创建独立文件。
+- **Claude Code 原生**：以 skill 形式交付，不需要运行时依赖。
+
+## 和其他方式的区别
+
+| 方式 | 优点 | 代价 | workflow-ledger 的选择 |
+|---|---|---|---|
+| 只靠聊天历史 | 零配置 | 中断或压缩后难恢复 | 多步任务不够用 |
+| 只靠 TodoWrite | 当前会话很好用 | 不能跨会话持久恢复 | 用于当前会话执行，不承担历史记录 |
+| 重型 spec 工作流 | 治理强、可追踪 | 文件多、阶段重 | 只在 Level 3 真需要时使用 |
+| hook 自动化 | 确定性强 | 容易变吵、变硬 | 作为可选保险丝，不作为主流程 |
+| `workflow-ledger` | 轻量、可恢复、可验收 | 需要在里程碑节点更新一个文件 | 默认用于需要恢复的 Claude Code 开发任务 |
+
+## 和具体工具的横向对比
+
+| 工具 / 工作流 | 最擅长 | 常见形态 | `workflow-ledger` 的区别 |
+|---|---|---|---|
+| Superpowers 风格 skills | 用可复用 skill 和 checklist 教 Claude 按固定方式工作 | skill 包、详细流程、设计/计划循环、明确的人类批准门 | 采用同样的 skill-native 交付方式，但范围更窄：只解决任务记忆、change intent、可变 todo、前置依赖和恢复点 |
+| GSD 风格规划工作流 | 把大型工作拆成调研、计划、执行、验证、安全/UI/eval review 等阶段 | 多 agent 规划与执行、阶段文档、review 报告、更强流程门禁 | 借鉴可恢复思路，但把日常任务的仪式感降到最低；重型 review 产物不进入默认 ledger |
+| OpenSpec 风格 spec 工作流 | 用 proposal、spec、tasks 和归档历史治理产品/API 变化 | 正式 proposal/design/task 文件和 spec 生命周期 | 借鉴 intent/change 管理意识，但不要求每个改动都从 proposal/design/tasks/spec 文件开始 |
+| Claude Code hooks | 在工具调用或生命周期边界确定性执行规则 | PreToolUse、PostToolUse、Stop、Compact 等事件处理器 | 把 hooks 视为可选保险丝；工作流状态仍放在可读的 `.claude/WORKFLOW.md` 中 |
+| TodoWrite / 会话 todo | 管理 Claude 当前会话正在做什么 | 当前会话内频繁更新的 checklist | TodoWrite 只负责现场执行；ledger 负责持久里程碑和交接上下文 |
+
+一句话概括：Superpowers 教行为，GSD 编排重型执行，OpenSpec 治理正式变更，hooks 强制事件规则，TodoWrite 跟踪当前会话。`workflow-ledger` 补的是中间那一层：日常 Claude Code 开发里的单文件 OpenSpec-lite 任务记忆。
+
+## 借鉴了哪些思路
+
+`workflow-ledger` 借鉴了 spec-driven 和 skill-driven 工作流，但刻意保持更小：
+
+- 借鉴 OpenSpec 这类 spec-driven 系统：明确 intent、依赖意识和归档式关闭摘要。
+- 借鉴 Claude Code skills / Superpowers 风格：把可复用流程写成 skill，按需加载。
+- 借鉴 hooks：关键动作可以有硬性保护，但不默认把 hook 变成工作流引擎。
+
+核心设计原则是：
+
+> 强制规则保持短；详细流程放 skill；长期 change state 放一个 ledger 文件。
+
+## 安装
+
+推荐先做全局工具接入：
+
+```bash
+npx workflow-ledger setup
+```
+
+也可以只配置特定 AI coding 工具：
+
+```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
+```
+
+`setup` 安装全局工具接入；`init` 创建项目本地 ledger 和短指令片段。`claude-code` 使用 `.claude/WORKFLOW.md`；`codex` 使用 `.workflow-ledger/WORKFLOW.md` 和 `AGENTS.md`。
+
+Bash 安装器仍可用于 Claude Code 项目初始化：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MorseWayne/workflow-ledger/main/install.sh | bash
+```
+
+如果你已经有本地 `workflow-ledger` checkout，也可以直接运行安装脚本：
+
+```bash
+/path/to/workflow-ledger/install.sh /path/to/your/project
+```
+
+手动项目级安装 Claude Code：
+
+```bash
+mkdir -p .claude/skills
+cp -R skills/workflow-ledger .claude/skills/workflow-ledger
+```
+
+个人全局安装只安装 skill；项目仍然需要 `CLAUDE.md` 片段和 `.claude/WORKFLOW.md`：
+
+```bash
+mkdir -p ~/.claude/skills
+cp -R skills/workflow-ledger ~/.claude/skills/workflow-ledger
+```
+
+安装器也会把项目本地 CLI 复制到 `.claude/bin/workflow-ledger`：
+
+```bash
+.claude/bin/workflow-ledger doctor
+.claude/bin/workflow-ledger list
+```
+
+详见 [docs/cli.md](docs/cli.md)。CLI 是可选保护栏，不替代 skill 工作流。
+
+然后在 Claude Code 中调用：
+
+```text
+/workflow-ledger start "implement auth flow"
+/workflow-ledger resume
+/workflow-ledger close
+```
+
+## 项目接入
+
+项目接入分两层：
+
+1. 先用 `workflow-ledger setup` 做全局工具接入，让支持的 agent 能找到工作流指令。
+2. 再用 `workflow-ledger init` 初始化项目，让仓库里有 ledger 文件和短工具提醒。
+
+对 Claude Code，`init` 会把 [examples/claude-project/CLAUDE.md.snippet](examples/claude-project/CLAUDE.md.snippet) 加入项目 `CLAUDE.md`，并把 [skills/workflow-ledger/templates/WORKFLOW.md](skills/workflow-ledger/templates/WORKFLOW.md) 创建到 `.claude/WORKFLOW.md`。
+
+对 Codex，`init --tool codex` 会把 [examples/codex-project/AGENTS.md.snippet](examples/codex-project/AGENTS.md.snippet) 加入 `AGENTS.md`，并把 [templates/WORKFLOW.md](templates/WORKFLOW.md) 创建到 `.workflow-ledger/WORKFLOW.md`。
+
+## 台账结构示例
+
+一个被跟踪的任务大致长这样：
+
+```markdown
+### WF-2026-05-16-001 — Add streaming usage accounting
+Status: In Progress
+Level: 2
+Current phase: Implement conversion fix
+
+Intent:
+- Stabilize streaming usage accounting without expanding the ledger into a transcript.
+
+Current todo:
+- [ ] Update converter.
+- [ ] Add regression test.
+
+Changes:
+- 2026-05-16 — Current implementation path narrowed to the provider conversion code.
+
+Prerequisites:
+- Existing streaming usage tests must be checked before editing.
+
+Resume next:
+- Update the converter and add the smallest regression test.
+```
+
+## 任务分级
+
+| Level | 适用场景 | 是否写 ledger |
+|---|---|---|
+| Level 0 | 问答、只读解释 | 不需要 |
+| Level 1 | typo、文档小改、小配置、无行为变化 | 可选 |
+| Level 2 | 标准代码修改、测试、单模块行为变更 | 需要 |
+| Level 3 | 新功能、跨模块、公共 API、不明确或高风险变更 | 需要，可选附件 |
+
+## 设计原则
+
+- 总览文件必须一眼有用。
+- 保持 Active intent 小而明确。
+- 执行中发现新情况时允许调整 `Current todo`。
+- 新增前置依赖或未来任务时记录原因。
+- 不为了流程而流程。
+- 优先一个持久 ledger，而不是散落的过程文件。
+
+## 什么时候使用
+
+适合：
+
+- 多步骤实现
+- 可能跨会话的任务
+- 需要保留 review 历史的任务
+- 有依赖的 debug / refactor
+- 任何需要知道“已完成什么、还剩什么”的任务
+
+不适合：
+
+- 纯问答
+- 一步完成的小修改
+- 临时探索
+- 用户明确说不用跟踪的任务
+
+## 当前状态
+
+当前版本同时支持 npm setup 和旧的 Bash installer。CLI 可以为 Claude Code、Codex 或两者安装 Workflow Ledger，同时保持 ledger 格式轻量、可被多个工具读取。