We made a plan document and its clickable prototype point at each other, and added an automatic check that notices when the two have quietly fallen out of sync.
Before this, a prototype knew which plan it came from, but the plan had no idea a prototype existed — and neither file wrote down the data model they supposedly shared, so nothing could tell you they had diverged.
The work was verified end to end (full test suite, a hand-built fixture pair, and a real browser click) before the plan was marked complete. One genuine bug surfaced during the manual walk that the automated tests had missed; it was fixed and regression-tested.
A plan whose source carries a prototype: line now shows a View prototype link in its header, beside the effort and status badges. Clicking it opens the prototype.
To use: add prototype: docs/prototypes/<slug>.html to a plan’s Markdown source and re-render.
Each card in the plans gallery gains a small prototype chip. It is a text label, not a second link — the whole card is already one big link, and nesting a link inside a link is invalid HTML that browsers silently pull apart.
The prototype generator worked out a data model — the thing being tracked, its fields and their types, the main action, and the signal that proves it works — then threw it away once the page was built. That model is now written into both files as a single line of machine-readable data. This is the groundwork that makes the drift check possible at all.
Whenever a prototype is written, a check compares the recorded model against the prototype’s own visible columns and form fields, and against the plan’s copy. When they disagree it prints a warning naming both files, the field that differs, and what to re-run.
To use: nothing — it runs on its own after every prototype write.
Running /plan-agent:prototype against a plan now writes the link and the model into that plan before writing the prototype. When the plan has no Markdown source — most older plans are HTML-only — it skips the write-back, still builds the prototype, and prints one line explaining how to create a source file.
{{SOURCE_PLAN}} was undefined free text that only ever fed a display string. It is now pinned: the repo-relative path of the plan’s Markdown source on the plan path, and empty for idea, image, and Figma inputs. The drift check resolves the owning plan from it, so without a format contract the whole comparison would be unimplementable.
flowchart LR
subgraph BEFORE["Before"]
direction LR
A1["Plan"]
B1["Prototype"]
B1 -->|"proto-source"| A1
end
subgraph AFTER["After"]
direction LR
A2["Plan"]
B2["Prototype"]
M2[["shared data model"]]
A2 -->|"prototype:"| B2
B2 -->|"proto-source"| A2
A2 -.->|"proto-model"| M2
B2 -.->|"proto-model"| M2
end
flowchart TD
W["A prototype file is written"] --> D{"Path gate"}
D -->|"unrelated path"| X["Exit, nothing spawned"]
D -->|"under docs/prototypes/"| G["Rebuild the prototypes gallery"]
G --> C["Run the drift check"]
C --> A{"Model vs. the prototype's
own columns and fields"}
C --> B{"Model vs. the plan's copy"}
A -->|"differs"| W1["Warn, naming both files
and the field"]
B -->|"differs"| W2["Warn, naming both files
and the field"]
A -->|"matches"| S["Silent"]
B -->|"matches"| S
W1 --> Z["Always exit 0"]
W2 --> Z
S --> Z
flowchart TD
S["The prototype generator runs"] --> Q{"Input type?"}
Q -->|"idea, image, Figma"| N["No write-back"]
Q -->|"plan path"| M{"Does the plan have
a Markdown source?"}
M -->|"yes"| W["Write the link and the model
into the plan"]
M -->|"no, most older plans"| K["Skip the write-back,
print how to create one"]
W --> G["Write the prototype"]
K --> G
N --> G
| Situation | Before | After |
|---|---|---|
| Finding a plan’s prototype | No way to know one existed | A link in the plan header, and a chip on the gallery card |
| The shared data model | Worked out, then discarded | Recorded in both files as one line |
| A hand-edited prototype | Nobody notices | Warning naming both files and the diverging field |
| Where the link points | — | Worked out relative to the plan’s own folder, so a custom or nested plans folder still resolves |
| A plan with no prototype | — | Renders character-for-character identically to before |
| Running against an HTML-only plan | — | Prototype still built, no file created, one-line notice printed |
| When the check hits bad input | — | Exits cleanly every time, including missing files and malformed data |
| Check | Result |
|---|---|
End-to-end test test-prototype-plan-link.mjs | 5 passed |
Drift check test test-prototype-drift.sh | 14 passed |
Renderer test test-build-plan-html.mjs | 35 passed |
| Prototypes gallery test | passed |
| Full plugin suite, 37 files | 0 failing |
| Publish and demo suites | 0 failing |
| Version guard | 4.4.0, clean |
| File-copy parity | all identical |
| Pages smoke test | fails, pre-existing |
Also walked by hand: built a matching plan and prototype pair, rendered it, opened the plan in a browser and clicked the link (it reaches a working prototype, and the new data block does not break the prototype’s own behaviour), then ran a three-stage drift walk — a matching pair stays silent, one renamed field produces two warnings naming both files, and removing the plan’s copy silences the plan comparison.
Plan to prototype is regeneration — re-run the generator. Prototype to plan is detection — compare and report.
It uses the existing link colour and the header row’s spacing.
The card is already wrapped in a link, and a nested link is invalid HTML that browsers silently unnest.
A fixed ../prototypes/ would resolve to the wrong folder for any plan stored outside the default location, and nested folders break the same way.
Every other check in this plugin does, and the dispatcher would treat a failure exit as something the user must fix before continuing.
The plan’s header reader is a simple line scanner. An embedded line break or stray separator would silently truncate the block and corrupt the plan’s status and creation date for every tool that reads it.
The drift check read field names straight out of the prototype’s HTML. The page template contains an authoring comment that includes a literal example attribute — data-field="key" — and that comment ships into every generated prototype. So the check reported a field called key that did not exist, on a file that had not drifted at all.
The automated test missed it entirely, because its fixture was a hand-written minimal page rather than the real template. The manual verification walk caught it on the first run.
Two fixes, both kept: strip comments before scanning, and point the test fixture at the real template so this class of bug cannot hide again.
tests/pages/test-pages-smoke.sh.
scripts/build-plan-html.mjs and its bundled twin — read the prototype: key, work out the relative linkscripts/lib/plan-shell.mjs and its bundled twin — emit the marker tag and the header linkscripts/build-plans-index.sh, kit/plugins/plan-agent/hooks/build-index.sh, docs/plans/build-index.sh — the prototype chipkit/plugins/plan-agent/templates/plans-gallery.html — chip stylingkit/plugins/plan-agent/hooks/check-prototype-drift.py — new; the whole comparisonkit/plugins/plan-agent/hooks/dispatch.py — run it after the gallery rebuildskills/prototype/SKILL.md — pinned the source-plan contract, added the model output and the write-back stepskills/prototype/reference/PROTOTYPE-SKELETON.html — the model blocktests/plugins/test-prototype-plan-link.mjs — new; the end-to-end checktests/plugins/test-prototype-drift.sh — new; 10 check branches plus dispatcher fan-outtests/plugins/test-build-plan-html.mjs — the “renders identically without a prototype” check, which renders through the previous version of the renderer and comparesREADME.md, CHANGELOG.md, .claude-plugin/marketplace.json — documentation and the 4.3.1 to 4.4.0 bumpdocs/plans/add-prototype-plan-linking.md and its rendered page — plan marked completekey: value lines at the top of a Markdown file, between two --- markers.