dsh-todo-ledger

dsh plugin --profile web add dsh-todo-ledger

dsh-todo-ledger

  

[English](README.md) | [中文](README_zh.md)

Repository: https://github.com/haruri03/dsh-todo-ledger

A host-level DSH plugin that turns the todo ledger workflow into a resident prompt section,

a set of native tools, and context stored inside the repository's _todo/ directory.

It addresses the failure mode where rules live in a skill or AGENTS.md, the model forgets to

read them, and the task list has to be rewritten every turn:

Before · This plugin

Rules live in AGENTS.md / a skill and stop working when the model does not read them · A host-level systemPrompt.section is present every step of every session, with no load step to forget

The system todo_write list is overwritten each turn and progress is lost · Authoritative state lives in the repository's _todo/ files and survives sessions and compaction

Context exists only in conversation history and disappears after compaction · todo_checkpoint / todo_note write conclusions and next steps into _todo/context/, and a snapshot is injected on every prompt assembly

The model has to assemble shell commands itself · 12 native tools with schema validation and readable errors

The file format is fully compatible with an external todo CLI: the plugin and the original CLI can

both write the same repository and both can run doctor on it.

The ledger scaffold follows the caller's choice: todo_init and todo_add accept an optional

language (en or zh), and the plugin writes the chosen form for the files of that ledger. It

defaults to English, so a caller outside a Chinese-speaking locale always gets an English ledger.

Both written forms are read, so a ledger written in either language — including one created by an

earlier version — keeps working, and content inside the sections is free-form.

Register before implementation

When a ledger exists, the prompt instructs the agent to reuse a matching task or call todo_add for substantive new work requested by the user before editing deliverables, changing configuration, or running state-changing commands. Register the requested outcome, not each implementation step. Brief read-only scope inspection may come first; trivial Q&A and read-only checks need no task. Unclear scope calls for clarification, not an invented task. Historical checkpoints and inferred follow-ups do not authorize new work. Missing ledgers are initialized only when the user asks or confirms.

This is prompt guidance, not a runtime execution block or automatic task-creation mechanism.

Install (manual)

Choose one:

Human: copy this directory to $HOME/.dsh/profiles/<profile>/node_modules/dsh-todo-ledger,

then append this row to the profile's cordis.patch.yml:

- insert:
    - id: todo-ledger
      name: './lib/index.js'

Agent: run plugin_manager install_bundle --target "<path-to-plugin>".

Install from Git

When the repository root is the package (it contains package.json and dsh.bundle), install it

directly from its Git URL:

plugin_manager install_bundle --target "git+https://github.com/haruri03/dsh-todo-ledger.git"

The same operation is available to humans through the Web plugin page ("Add plugin") or the CLI:

dsh plugin --profile <profile> add "git+https://github.com/haruri03/dsh-todo-ledger.git"

Install from npm

The package is published as dsh-todo-ledger, so the npm name alone installs it:

plugin_manager install_bundle --target "dsh-todo-ledger"

dsh plugin --profile <profile> add dsh-todo-ledger

Tarball URLs are accepted too. To update, remove and reinstall, or wait for an upstream release.

After installation, every new session carries a [todo-ledger · cross-session tasks and context]

prompt section, and the tool list gains:

todo_context / todo_list / todo_add / todo_show / todo_status / todo_complete / todo_archive / todo_note / todo_checkpoint / todo_snapshot / todo_doctor / todo_init

No restart is required.

Layout

Inside the repository root (the directory that contains _todo/; a repository that already keeps todo/ keeps working, the plugin accepts either name):

_todo/
├── todo.md              queue: `- [status] slug`
├── tasks.md             index: `- [status] **slug** — title → [details](tasks/slug.md)`
├── tasks/<slug>.md      details: goal / subtasks / acceptance / progress / blockers / files
├── archived/<slug>.md   completed + ## Delivery record (includes the sign-off quote)
├── AGENTS.md            directory notes generated by todo_init
└── context/             added by this plugin
    ├── now.md           current goal / next step / key files (overwritten by todo_checkpoint)
    └── log.md           append-only log (automatic tool trace + todo_note)

States are todo / doing / blocked / review; there is no done. review means work is

finished and waiting for the owner's sign-off. Closing a task requires both evidence and

signoff (the owner's own words); neither may be omitted. This is a hard rule of the todo ledger

workflow.

How it works

flowchart LR
  subgraph host["DSH host"]
    prompt["system prompt assembly"]
    tools["native todo_* tools"]
    cli["todo-context CLI"]
  end
  subgraph plugin["dsh-todo-ledger"]
    section["prompt section + snapshot"]
    store["lib/store.js"]
    reader["lib/context-reader.js"]
    format["lib/format.js<br/>EN/ZH templates + alias table"]
  end
  subgraph repo["repository"]
    fil

…(truncated)