简体中文 # trailmap (Trail Map) A disk-persisted execution-planning plugin: it stores the plan, execution state, field notes, and debrief of multi-step tasks entirely in the workspace .trail/ directory. Interrupted sessions, context compression, or restarting in a new session won't lose your bearings — just read the state and continue after resuming. - State-machine driven: steps go todo → in progress → done (cancellable/revivable); steps whose dependencies are unmet are automatically marked "blocked"; milestones and plan status derive from steps, no manual bookkeeping. - Plan template generator: generate a milestone skeleton in one shot by task kind (research/development/docs/blank), with step dependencies wired up automatically; still editable at any time after creation. - Dependency annotation: steps can declare dependencies; start is gated by dependencies; circular dependencies are detected and blocked. - Audit event stream: every advancement is written to an append-only event log; retros reference it automatically and the process stays traceable. - Debrief notes: at wrap-up, milestones/steps/cancellations/timeline are summarized automatically; hand-written retro sections persist across runs. - Deterministic completion gate: check verifies all steps are closed and the structure is sound, preventing "thought it was done". - Three interfaces: dsh tools (10 trailmap_*), a standalone CLI (trail), and a skill (SKILL.md), all sharing one core. ## Quick start (CLI, zero dependencies) sh node bin/trail.js init "Add regression tests to the toolchain" --kind blank node bin/trail.js status node bin/trail.js start m1-1 # …do the work… node bin/trail.js finish m1-1 node bin/trail.js check # completion gate (passes once the step is closed) node bin/trail.js debrief --close # debrief + archive (--kind blank keeps a single step so the whole loop runs end to end; --kind build generates the full milestone skeleton — see the command reference and docs/format.md.) (Or npm link and use the trail command directly; the TRAILMAP_DIR environment variable selects the workspace, defaulting to the current directory.) ## Installing in DSH sh dsh plugin --profile demo add github:JohnXu22786/file-planning ## Integrating with dsh (pluginized harness) sh dsh plugin --profile demo add ./file-planning dsh --profile demo --dump-config # should show the dsh-plugin-trailmap patch layer dsh --profile demo The harness inserts the plugin line via cordis.patch.yml; Cordis injects ctx.tools and registers all tools; the model can then call trailmap_* to create plans, advance, and debrief end to end. The skill lives in skill/trailmap/. See docs/integration.md. ## Workspace files <workspace>/.trail/ ├── map.json # single source of truth (plan + state + audit events) ├── map.md # rendered view: status lines / next steps / checklists ├── fieldnotes.md # field notes ├── journal.md # trip log ├── debrief.md # debrief notes ├── .active # active plan pointer (multi-plan) └── plans/<alias>/ # parallel plans .trail/ is excluded from version control by default. File format and state machine are documented in docs/format.md. ## Command reference | Command | Purpose | |------|------| | trail init <goal> [--kind …] [--name alias] | Create a trail (template skeleton + dependency wiring) | | trail status [--history] [--json] | Status overview | | trail start/finish/drop/reopen <stepId> | Step state machine (drop requires --reason) | | trail amend … | Amend the plan structure mid-flight | | trail note <text> [--section name] | Field notes | | trail journal <text> | Trip log | | trail check [--json] | Completion gate (exit code 1 on failure; --json mode always exits 0, rely on the ok field) | | trail debrief [--close] / trail close | Debrief (+archive) | | trail render | Regenerate the view after hand-editing map.json | | trail plans / switch <alias> / switch root | Multi-plan management | ## Development sh node --test # all unit tests (Node's built-in test runner, zero dependencies) - lib/machine.js: pure state machine (transitions/derivation/validation/cycle detection) - lib/ops.js: operation layer (shared by the CLI and the dsh adapter) - adapter/index.js: dsh tool plugin entry - scripts/adapter-smoke.mjs: smoke test against the real @deepseek-ai/dsh-tools. To run: create a temp directory, npm init -y && npm pkg set type=module, npm i @deepseek-ai/dsh-tools @deepseek-ai/cordis, copy this script to the temp directory root, also copy the lib/ and adapter/ directories over, then run node adapter-smoke.mjs ## Directory structure file-planning/ ├── adapter/ # dsh plugin entry (Cordis plugin) ├── lib/ # core library (zero deps): machine/store/render/templates/ops/cli ├── bin/trail.js # CLI entry ├── skill/trailmap/ # skill (SKILL.md) ├── scripts/ # smoke test scripts ├── test/ # unit tests (node --test) ├── docs/ # integration docs / file format conventions ├── examples/ # example workspaces (fully executed trails) ├── cordis.patch.yml # bundle patch layer └── package.json # bundle manifest (dsh.bundle) ## License MIT, see LICENSE.