forgetrail 0.4.15 → 0.4.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +7 -5
  2. package/TRY_FORGETRAIL.md +4 -3
  3. package/content/examples/two-session-continuity.md +2 -2
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -10,9 +10,9 @@
10
10
 
11
11
  **Forge the path. Keep the trail.**
12
12
 
13
- Keep project decisions, development state, and lessons in the repository so your next AI-assisted session can continue with context.
13
+ 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.
14
14
 
15
- After one sitting you should have `.forgetrail/workflow_tracking.json` with the phase you are in, a decision, and a `nextSession` line. A labeled two-session walk-through is in [`content/examples/two-session-continuity.md`](content/examples/two-session-continuity.md).
15
+ 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`](content/examples/two-session-continuity.md).
16
16
 
17
17
  **Docs:** [forgetrail.dev/docs](https://forgetrail.dev/docs) · **Site:** [forgetrail.dev](https://forgetrail.dev)
18
18
 
@@ -31,8 +31,8 @@ The shortest supported first task is: create tracking, draft `docs/PHASE_1_BRIEF
31
31
  | Path | Who uses it | What it is |
32
32
  | --- | --- | --- |
33
33
  | **Lite** | First path | One protocol file. The agent writes tracking. |
34
- | **CLI** (`forgetrail`) | Node.js 20+ | Installer. Writes Lite or the full template tree. Does not run the agent. |
35
- | **MCP** (`forgetrail-mcp`) | Cursor or Claude | Methodology tools. Tracking still lives in the app repo. |
34
+ | **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. |
35
+ | **MCP** (`forgetrail-mcp`) | Cursor or Claude | Phase guidance, templates, and lessons search. Tracking still lives in the app repo. |
36
36
 
37
37
  ```bash
38
38
  pnpm dlx forgetrail install --lite --with-genesis-stub
@@ -42,7 +42,9 @@ MCP: `npx -y forgetrail-mcp` with `FORGETRAIL_ROOT` set. Prefer `pnpm dlx` on Wi
42
42
 
43
43
  ## What you get
44
44
 
45
- 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. Flags, MCP, and the phase table live in the [docs](https://forgetrail.dev/docs).
45
+ 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.
46
+
47
+ Optional hooks in [`content/hooks/`](content/hooks/README.md) 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](https://forgetrail.dev/docs).
46
48
 
47
49
  <!-- xfacts-label -->
48
50
 
package/TRY_FORGETRAIL.md CHANGED
@@ -26,9 +26,10 @@ Prove ForgeTrail in one sitting: write a **what, not how** spec in any AI chat,
26
26
  4. **Add ForgeTrail Lite**
27
27
  - **Copy:** save [`content/FORGETRAIL_LITE.md`](content/FORGETRAIL_LITE.md) as `.forgetrail/FORGETRAIL_LITE.md` in your project, **or**
28
28
  - **CLI** (Node 20+):
29
- `npx forgetrail install --lite`
29
+ `pnpm dlx forgetrail install --lite`
30
30
  Stub for Genesis too:
31
- `npx forgetrail install --lite --with-genesis-stub`
31
+ `pnpm dlx forgetrail install --lite --with-genesis-stub`
32
+ The CLI also writes a starter tracking file and Cursor hooks, and skips files that already exist.
32
33
 
33
34
  5. **Save your spec as `docs/GENESIS.md`**
34
35
  Create `docs/` if needed. That path is the canonical handoff for ForgeTrail (not the repo root).
@@ -66,7 +67,7 @@ Already have a long PRD? Save it as `docs/GENESIS.md` and use the kickoff line a
66
67
  Once you have verified the protocol on a first project, connecting the **ForgeTrail MCP server** is the natural upgrade:
67
68
 
68
69
  1. **Token efficiency:** Instead of pasting or re-reading the 28k-token Lite file, the agent pulls phase playbooks, templates, checklists, and anti-patterns on demand via MCP tools. Your prompt stays clean and focused on your app code.
69
- 2. **Dynamic lessons:** The agent queries `searchLessons` and `getAntiPatterns` before large tasks, avoiding known traps across hundreds of prior sessions.
70
+ 2. **Dynamic lessons:** The agent queries `searchLessons` and `getAntiPatterns` before large tasks, avoiding traps recorded in first-party Catalyst Forge projects.
70
71
  3. **Structured validation:** `validateTracking` catches schema errors immediately.
71
72
 
72
73
  ### How to connect (Cursor)
package/content/examples/two-session-continuity.md CHANGED
@@ -19,7 +19,7 @@ The human pasted the kickoff line from [TRY_FORGETRAIL.md](../../TRY_FORGETRAIL.
19
19
  3. Logged one decision and one gotcha.
20
20
  4. Stopped after the human approved the brief. No application scaffold yet.
21
21
 
22
- The CLI, if used instead of a hand copy, only writes the Lite file and an optional Genesis stub. It does not update tracking, decisions, or sessions. Those writes depend on the agent following the protocol.
22
+ The CLI, if used instead of a hand copy, writes the Lite file, a starter tracking file, hook scripts, and an optional Genesis stub. It does not fill in phases, decisions, or sessions. Those writes depend on the agent following the protocol.
23
23
 
24
24
  ### What was left unfinished
25
25
 
@@ -99,7 +99,7 @@ That is the trail: phase flags, a decision, a gotcha, and a `nextSession` line.
99
99
  | --- | --- | --- |
100
100
  | `.forgetrail/FORGETRAIL_LITE.md` | Human copy, or `forgetrail install --lite` | The file copy is automatic once you run install. Following it is not. |
101
101
  | `docs/GENESIS.md` | Human, or `--with-genesis-stub` plus later edits | Stub only if you asked the CLI for it. |
102
- | `.forgetrail/workflow_tracking.json` | The agent, on first kickoff and after substantive work | No. Empty tracking after a busy session is a protocol miss. |
102
+ | `.forgetrail/workflow_tracking.json` | The agent, on first kickoff and after substantive work. `forgetrail install --lite` places an empty starter. | No. Empty tracking after a busy session is a protocol miss. |
103
103
  | `docs/PHASE_1_BRIEF.md` | The agent, then the human approves | No. |
104
104
  | `decisions[]`, `gotchas[]`, `sessions[]` | The agent | No. The protocol tells the agent to append. The host does not enforce it. |
105
105
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forgetrail",
3
- "version": "0.4.15",
3
+ "version": "0.4.17",
4
4
  "private": false,
5
5
  "description": "ForgeTrail: a persistent development system for building software with AI agents. CLI, Lite protocol, and methodology templates.",
6
6
  "license": "Apache-2.0",