forgetrail

ForgeTrail

Forge the path. Keep the trail.

ForgeTrail gives your next coding session a place to start. It keeps the phase, decisions, and handoff in your repository so an agent can read them when you resume. Start with Lite for a small project. You do not have to run all seven phases to try the method.

ForgeTrail instructs the agent to read tracking, preserve approved decisions, and pause at approval gates. The agent must write the handoff. Those updates are not automatic. Optional hooks enforce the checks documented for their supported host.

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 appledger/, 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 appledger/.
CLI (forgetrail)	Node.js 20+	Installer. Writes Lite and Cursor hooks, or the full template tree. It does not write a tracking JSON file. Skips files that already exist. Does not run the agent.
MCP (forgetrail-mcp)	Cursor or Claude	Phase guidance, templates, and lessons search. The ledger 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 ledger in appledger/, and templates pre-loaded with first-party production lessons. Each project leaves decisions, lessons, and a session handoff that future work follows. Those lesson notes are not independent adoption evidence. A new install does not create .forgetrail/workflow_tracking.json.

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

See the rest of the Catalyst Forge shelf.