forgetrail

ForgeTrail

Forge the path. Keep the trail.

ForgeTrail gives your coding agent a method: seven phases, each with exit criteria, and a pause for your approval before the agent moves on. As it works, the agent records the phase, decisions, and gotchas in your repository, so a new chat days later starts from that record instead of from zero.

In session one, the agent drafts a Phase 1 brief, you approve it, and the agent logs the stack decision and a note for next time. In session two, a fresh chat reads that record, skips the settled questions, finishes the open Phase 1 item, and asks to move into Phase 2 with that phase's guidance. The record is .forgetrail/workflow_tracking.json. Labeled walk-through: content/examples/two-session-continuity.md.

Docs: forgetrail.dev/docs · Site: forgetrail.dev

Start with Lite

You need a new empty project folder and a coding agent that can read files. Node is optional.

• Write docs/GENESIS.md (what, not how).
• Copy content/FORGETRAIL_LITE.md to .forgetrail/FORGETRAIL_LITE.md, or run pnpm dlx forgetrail install --lite --with-genesis-stub (Node.js 20+).
• Paste the kickoff line from TRY_FORGETRAIL.md. Approve the Phase 1 brief before any scaffold.

The shortest supported first task is: create tracking, draft docs/PHASE_1_BRIEF.md, and wait for approval. You do not have to run all seven phases. Full recipe: Try.

Lite, CLI, and MCP

Path	Who uses it	What it is
Lite	First path	One protocol file. The agent writes tracking.
CLI (forgetrail)	Node.js 20+	Installer. Writes Lite with a starter tracking file and Cursor hooks, or the full template tree. Skips files that already exist. Does not run the agent.
MCP (forgetrail-mcp)	Cursor or Claude	Phase guidance, templates, and lessons search. Tracking still lives in the app repo.

pnpm dlx forgetrail install --lite --with-genesis-stub

MCP: npx -y forgetrail-mcp with FORGETRAIL_ROOT set. Prefer pnpm dlx on Windows. Do not add forgetrail to an app's dependencies. Do not merge the two packages.

What you get

A 7-phase playbook, a live .forgetrail/workflow_tracking.json, and templates pre-loaded with first-party production lessons. Each project leaves a trail of decisions, gotchas, and breadcrumbs that future work follows. Those lesson notes are not independent adoption evidence.

Optional hooks in content/hooks/ load the current phase at session start in Cursor or Claude Code, validate tracking edits, and check for a session note at session stop. The agent still does the writing. Flags, MCP, and the phase table live in the docs.

xFacts label

• AppFacts: viewer · raw
• ToolFacts: viewer · raw
• SkillFacts: viewer · raw

Development

pnpm --dir mcp-server install
pnpm run mcp:build
pnpm site:dev

Site (FilePress + docs mount): pnpm ship.

Apache-2.0 · Catalyst Forge LLC