file-planning

The hardest part of a multi-step task is rarely writing the plan. It is losing your place when a session dies, the context gets compressed, or you open a fresh window and have to guess where things left off. file-planning (Trail Map) writes the plan, execution state, field notes, and debrief entirely into a .trail/ directory in your workspace, so resuming just means reading the state and picking up exactly where you stopped.

Under the hood a small state machine governs each step through todo, in progress, and done, with the ability to cancel or re-open anytime. Steps can declare dependencies; unmet ones automatically flag downstream work as blocked, and circular dependencies are detected and refused. A template generator spins up a milestone skeleton for research, development, docs, or blank tasks with dependencies wired in one shot, and everything stays editable after creation. Every transition appends to an immutable event log, and the debrief command automatically summarizes milestones, steps, cancellations, and the timeline while preserving any hand-written retrospective sections you add. A final deterministic check confirms all steps are closed and the structure is sound before you call it done.

Built for DSH plugin-harness users running multi-step agent workflows who are tired of context loss. It ships with zero runtime dependencies, persists everything to plain files, and works standalone via a lightweight CLI or integrated through the dsh tools interface.