Introduction
ForgeTrail gives your coding agent a development method, seven phases with exit criteria and approval gates, and keeps the project's phase, decisions, and lessons in the repository so the next session picks up where the last one stopped.
Forge the path. Keep the trail.
Most AI coding sessions forget everything when you close the tab. ForgeTrail tells the agent what each phase needs before it moves on, and keeps the phase you are in, the decisions you made, and the gotchas you hit inside the app repo.
It is not a library, a SaaS, or a plugin. It is a methodology encoded into files your agent reads, follows, and updates. Distilled from Catalyst Forge production work.
The persisted outcome
After a first sitting you should see:
.forgetrail/FORGETRAIL_LITE.md(or MCP tools serving the same protocol)appledger/with a profile and a session recorddocs/GENESIS.mdand, once drafted,docs/PHASE_1_BRIEF.md
The installer can place the Lite file and hooks. The agent writes the ledger, the brief, decision records, and the session. Those updates are not automatic. An empty ledger after a busy session is a protocol miss.
A labeled two-session walk-through is on Continuity.
The problem those files solve
- Context evaporates between sessions. Every new chat starts from zero unless the repo holds the trail.
- No structure, no momentum. Features land in random order. Hardening gets skipped.
- You manage the AI instead of building. Re-explaining architecture eats the session.
- Decisions get lost and mistakes repeat. A gotcha from session 3 returns in session 6 if nobody wrote it down.
Three paths, one trail
| Path | Who uses it | Host needs | What runs |
|---|---|---|---|
| Lite | First-time and small-project users | A coding agent that can read files. Node is optional. | You copy or install one protocol file. The agent follows it and writes appledger/. |
CLI (forgetrail) |
People who want files placed by a command | Node.js 20+ | An installer. Lite, or the full template tree. It does not run the agent. |
MCP (forgetrail-mcp) |
People who want methodology tools in the IDE | Node.js 20+, an MCP client, FORGETRAIL_ROOT |
Tools for kickoff, resume, and lessons. The app still owns appledger/. |
Recommended first path: Try. Stay on Lite until you want IDE tools or a vendored template tree.
Do not add forgetrail to an app's dependencies. Do not merge forgetrail and forgetrail-mcp.
Two surfaces
| Surface | What it is |
|---|---|
| forgetrail.dev | Product story: home, Try, About |
| forgetrail.dev/docs | This guide: install, CLI, MCP, phases, continuity |
GitHub remains the source of truth for methodology files.
Next
- Try: Genesis plus Lite, no MCP required
- Continuity: two sessions, one ledger
- Install: npm, pnpm dlx, or a checkout
- MCP: always-current tools in the IDE