Introduction

When developing multi-step tasks in a DSH environment, session interruptions or context compression can easily cause progress to be lost. To solve this problem, a mechanism is needed to persist planning, state, and retrospective records to disk.

Plugin Introduction

trailmap (Trail Map) is a workflow plugin maintained by JohnXu22786. It stores all task information in the workspace’s .trail/ directory. No matter how a session is interrupted, work can be resumed by reading the persisted state.

Core Features

  • State-machine driven: Step states transition between todo, in progress, and done, with support for canceling and resuming. When dependencies are not satisfied, a step is automatically marked as “blocked”.
  • Plan template generator: Generates a milestone skeleton with one click based on task type (research/development/docs/blank), and dependencies are automatically wired.
  • Dependency annotations: Steps can declare dependencies. Dependencies are validated before starting a step, and circular dependencies are automatically detected.
  • Audit event stream: All progress is written to an append-only log and automatically referenced during debrief.
  • Debrief summary: When a task ends, milestones, steps, cancellations, and the timeline are automatically summarized. A manual debrief section is also supported.
  • Deterministic completion gate: The check command verifies that all steps are closed and the structure is valid.
  • Three interfaces: Provides DSH tools (10 trailmap_* tools), a standalone CLI (trail), and a skill (SKILL.md).

Installation and Enablement

Before installation, make sure the environment meets Node >= 20. Use the official installation command:

dsh plugin --profile demo add github:JohnXu22786/file-planning

The plugin injects configuration through cordis.patch.yml and registers tools into ctx.tools, allowing the model to invoke trailmap_* tools.

Typical Usage

Use the CLI to initialize, transition, and debrief:

# 1. 初始化计划（使用 blank 类型以运行完整循环）
node bin/trail.js init "Add regression tests to the toolchain" --kind blank

# 2. 查看状态
node bin/trail.js status

# 3. 启动第一个里程碑
node bin/trail.js start m1-1

# 4. 执行工作...
# 5. 完成步骤
node bin/trail.js finish m1-1

# 6. 完成门检查（步骤关闭且结构正确时通过）
node bin/trail.js check

# 7. 复盘并归档
node bin/trail.js debrief --close

You can also use the trail command directly after running npm link.

Notes

  • Directory permissions: The plugin runs with the permissions of the current DSH process. Make sure it has read and write access to the .trail/ directory.
  • Version control: The .trail/ directory is excluded from version control by default. It is recommended to manually check .gitignore.
  • Dependencies: Depends on @deepseek-ai/cordis and @deepseek-ai/dsh-tools.
  • Code review: Please inspect the source code and license (MIT) before installation.

Conclusion

trailmap is suitable for DSH users who need a structured workflow and persistent state. For more details, refer to the plugin directory or the GitHub repository.