forgetrail 0.4.6 → 0.4.7
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.
- package/README.md +21 -13
- package/TRY_FORGETRAIL.md +1 -0
- package/content/examples/two-session-continuity.md +110 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,31 +10,39 @@
|
|
|
10
10
|
|
|
11
11
|
**Forge the path. Keep the trail.**
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Keep project decisions, development state, and lessons in the repository so your next AI-assisted session can continue with context.
|
|
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).
|
|
14
16
|
|
|
15
17
|
**Docs:** [forgetrail.dev/docs](https://forgetrail.dev/docs) · **Site:** [forgetrail.dev](https://forgetrail.dev)
|
|
16
18
|
|
|
17
|
-
##
|
|
19
|
+
## Start with Lite
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
You need a new empty project folder and a coding agent that can read files. Node is optional.
|
|
20
22
|
|
|
21
|
-
|
|
22
|
-
pnpm dlx forgetrail install --lite --with-genesis-stub
|
|
23
|
-
|
|
23
|
+
1. Write `docs/GENESIS.md` (what, not how).
|
|
24
|
+
2. Copy [`content/FORGETRAIL_LITE.md`](content/FORGETRAIL_LITE.md) to `.forgetrail/FORGETRAIL_LITE.md`, or run `pnpm dlx forgetrail install --lite --with-genesis-stub` (Node.js 20+).
|
|
25
|
+
3. Paste the kickoff line from [TRY_FORGETRAIL.md](TRY_FORGETRAIL.md). Approve the Phase 1 brief before any scaffold.
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
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](https://forgetrail.dev/docs/try).
|
|
26
28
|
|
|
27
|
-
##
|
|
29
|
+
## Lite, CLI, and MCP
|
|
28
30
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
31
|
+
| Path | Who uses it | What it is |
|
|
32
|
+
| --- | --- | --- |
|
|
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. |
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pnpm dlx forgetrail install --lite --with-genesis-stub
|
|
39
|
+
```
|
|
32
40
|
|
|
33
|
-
|
|
41
|
+
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.
|
|
34
42
|
|
|
35
43
|
## What you get
|
|
36
44
|
|
|
37
|
-
A 7-phase playbook, a live `.forgetrail/workflow_tracking.json`, and templates pre-loaded with production lessons. Each project leaves a trail of decisions, gotchas, and breadcrumbs that future work follows. 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. Flags, MCP, and the phase table live in the [docs](https://forgetrail.dev/docs).
|
|
38
46
|
|
|
39
47
|
<!-- xfacts-nutrition-label -->
|
|
40
48
|
|
package/TRY_FORGETRAIL.md
CHANGED
|
@@ -75,6 +75,7 @@ Already have a long PRD? Save it as `docs/GENESIS.md` and use the kickoff line a
|
|
|
75
75
|
|------|------|
|
|
76
76
|
| [`content/GENESIS_SPEC_PROMPT.md`](content/GENESIS_SPEC_PROMPT.md) | Prompt to paste into any LLM chat |
|
|
77
77
|
| [`content/examples/GENESIS_SAMPLE_mars-habitat-roster.md`](content/examples/GENESIS_SAMPLE_mars-habitat-roster.md) | Fictional sample Genesis |
|
|
78
|
+
| [`content/examples/two-session-continuity.md`](content/examples/two-session-continuity.md) | Labeled two-session tracking example |
|
|
78
79
|
| [`content/FORGETRAIL_LITE.md`](content/FORGETRAIL_LITE.md) | Portable agent protocol |
|
|
79
80
|
| [`content/GENESIS_STUB.md`](content/GENESIS_STUB.md) | Stub written by `--with-genesis-stub` |
|
|
80
81
|
| [`README.md`](README.md) | Full methodology overview |
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Two-session continuity (illustrative)
|
|
2
|
+
|
|
3
|
+
This is a labeled example. The project is fictional. It shows how ForgeTrail Lite state survives a closed chat, and how the next session is supposed to consume it. File names match ForgeTrail `0.4.6` / Lite `schemaVersion: "lite-1"`.
|
|
4
|
+
|
|
5
|
+
Nothing here is a benchmark, an adoption claim, or a client record.
|
|
6
|
+
|
|
7
|
+
## The job
|
|
8
|
+
|
|
9
|
+
Build a local CLI, **desk-stamp**, that stamps today's date on markdown notes in the current folder. Weekend tool. No hosted database.
|
|
10
|
+
|
|
11
|
+
## Session 1 (human + coding agent)
|
|
12
|
+
|
|
13
|
+
The human created an empty folder, wrote `docs/GENESIS.md`, and added Lite by copying [`content/FORGETRAIL_LITE.md`](../FORGETRAIL_LITE.md) to `.forgetrail/FORGETRAIL_LITE.md`. No Node was required for that copy.
|
|
14
|
+
|
|
15
|
+
The human pasted the kickoff line from [TRY_FORGETRAIL.md](../../TRY_FORGETRAIL.md). The **agent** (not the CLI) then:
|
|
16
|
+
|
|
17
|
+
1. Created `.forgetrail/workflow_tracking.json` from the Lite starter in `FORGETRAIL_LITE.md` §11.
|
|
18
|
+
2. Drafted `docs/PHASE_1_BRIEF.md`.
|
|
19
|
+
3. Logged one decision and one gotcha.
|
|
20
|
+
4. Stopped after the human approved the brief. No application scaffold yet.
|
|
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.
|
|
23
|
+
|
|
24
|
+
### What was left unfinished
|
|
25
|
+
|
|
26
|
+
Phase 1 exit criteria `phase1BriefLocked` and `stackLocked` are true. `heroFlowAgreed` is still false. `currentPhase` is still `1`. The next session still has to agree the first stamp command, then scaffold.
|
|
27
|
+
|
|
28
|
+
### Persisted excerpt
|
|
29
|
+
|
|
30
|
+
Labeled excerpt of `.forgetrail/workflow_tracking.json` at the end of session 1. Shape matches the Lite starter, not the MCP string-phase starter.
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"schemaVersion": "lite-1",
|
|
35
|
+
"project": {
|
|
36
|
+
"name": "desk-stamp",
|
|
37
|
+
"created": "2026-09-08",
|
|
38
|
+
"description": "Local CLI that stamps today's date on markdown notes",
|
|
39
|
+
"sourceControl": "git",
|
|
40
|
+
"archetype": "one-shot",
|
|
41
|
+
"status": "active"
|
|
42
|
+
},
|
|
43
|
+
"currentPhase": 1,
|
|
44
|
+
"phases": {
|
|
45
|
+
"1": {
|
|
46
|
+
"name": "Plan",
|
|
47
|
+
"status": "in_progress",
|
|
48
|
+
"exitCriteria": {
|
|
49
|
+
"phase1BriefLocked": true,
|
|
50
|
+
"stackLocked": true,
|
|
51
|
+
"heroFlowAgreed": false,
|
|
52
|
+
"v1ScopeAgreed": false
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
},
|
|
56
|
+
"decisions": [
|
|
57
|
+
{
|
|
58
|
+
"date": "2026-09-08",
|
|
59
|
+
"phase": 1,
|
|
60
|
+
"decision": "TypeScript CLI, files on disk only, no hosted store",
|
|
61
|
+
"why": "Weekend tool. A database would be a second product.",
|
|
62
|
+
"alternatives": ["Python script", "SQLite index"]
|
|
63
|
+
}
|
|
64
|
+
],
|
|
65
|
+
"gotchas": [
|
|
66
|
+
{
|
|
67
|
+
"date": "2026-09-08",
|
|
68
|
+
"phase": 1,
|
|
69
|
+
"gotcha": "On Windows, npm 12 npx forgetrail failed to spawn the bin",
|
|
70
|
+
"fix": "Use pnpm dlx forgetrail, or copy FORGETRAIL_LITE.md by hand"
|
|
71
|
+
}
|
|
72
|
+
],
|
|
73
|
+
"sessions": [
|
|
74
|
+
{
|
|
75
|
+
"date": "2026-09-08",
|
|
76
|
+
"phase": 1,
|
|
77
|
+
"summary": "Genesis plus Lite in place. Phase 1 brief drafted and approved. Stack locked. Hero flow not agreed.",
|
|
78
|
+
"nextSession": "Agree the first stamp command, then scaffold the CLI. Do not reopen the no-database decision."
|
|
79
|
+
}
|
|
80
|
+
]
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Session 2 (new chat, same repo)
|
|
85
|
+
|
|
86
|
+
The human opened a new agent chat in the same folder and said: follow `.forgetrail/FORGETRAIL_LITE.md` and continue from tracking.
|
|
87
|
+
|
|
88
|
+
The agent read `.forgetrail/workflow_tracking.json` first. Visible consequences:
|
|
89
|
+
|
|
90
|
+
- It did not re-ask whether to add a database. That decision is already in `decisions[]`.
|
|
91
|
+
- It used `pnpm dlx` on Windows instead of `npx forgetrail`, because `gotchas[]` already recorded the spawn failure.
|
|
92
|
+
- It treated `docs/PHASE_1_BRIEF.md` as locked and asked only about the unfinished hero flow, the first stamp command, before writing application code.
|
|
93
|
+
|
|
94
|
+
That is the trail: phase flags, a decision, a gotcha, and a `nextSession` line. The next chat does not have to reconstruct them from memory.
|
|
95
|
+
|
|
96
|
+
## What persists, and who writes it
|
|
97
|
+
|
|
98
|
+
| Artifact | Who writes it | Automatic? |
|
|
99
|
+
| --- | --- | --- |
|
|
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
|
+
| `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. |
|
|
103
|
+
| `docs/PHASE_1_BRIEF.md` | The agent, then the human approves | No. |
|
|
104
|
+
| `decisions[]`, `gotchas[]`, `sessions[]` | The agent | No. The protocol tells the agent to append. The host does not enforce it. |
|
|
105
|
+
|
|
106
|
+
MCP tools can hand the agent the same protocol and a lessons search. They do not replace the files in the app repo.
|
|
107
|
+
|
|
108
|
+
## Catalog excerpt
|
|
109
|
+
|
|
110
|
+
Keep project decisions, development state, and lessons in the repository so the next session can continue. After one sitting you should see `.forgetrail/workflow_tracking.json` with a phase, a decision, and a `nextSession` line. Full walk-through: this file, and the [continuity](https://forgetrail.dev/docs/continuity) page.
|
package/package.json
CHANGED