feat: a packaged project reads the reference docs from the plugin (decision 0019)

[mauricios]

The four reference docs — COST-MODEL.md, MCP-INTEGRATION.md, MEMORY-STRATEGY.md, SPEC-MODEL.md, about 950 lines — are generic, never edited by a project, and /upgrade already overwrites them verbatim. A packaged project no longer commits them: the aplyca-adf plugin carries them in docs/, generated from skeleton/docs/ (decision 0019, amending 0016).

TRACKER-INTEGRATION.md and PARALLEL-AGENTS.md stay in the project, because they hold its settings. The committed install is unchanged.

What sessions decided

Headless sessions on Claude Code 2.1.286 shaped the design (report):

Finding	So
${CLAUDE_PLUGIN_ROOT} is filled in for skills and agents	They name the plugin's copy, ${CLAUDE_PLUGIN_ROOT}/docs/<doc>.md
…but not for workflow scripts (an agent got the literal text, and a template literal threw)	deep-spec-analysis's plugin copy carries the spec model's text, through one SPEC_MODEL constant the build fills in
Reading any file outside the project asks first: the plugin's docs/, a skill's own folder, the installed copy in ~/.claude/plugins/cache/	A packaged project commits Read(~/.claude/plugins/cache/aplyca/aplyca-adf/**) in permissions.allow. Checked: with it, the session and a plugin agent read the cache without asking
An agent on Haiku read docs/SPEC-MODEL.md in the project although its instructions gave the plugin's full path	Plugin skills and agents that name a reference doc open with one line: those are the plugin's copies, outside the project

The plugin's SessionStart hook also tells a packaged session where the docs are, so Claude reads them locally instead of fetching the GitHub links.

The project's files

• Links: the project's files link the docs at the pinned release on GitHub. The new scripts/link-reference-docs.py rewrites them:
  • /adopt runs it;
  • /upgrade runs it to move the links with each pin, and back on a switch to committed.
  • It only touches the skeleton's own files, and lists any other file that names a doc.
• Older releases: /adopt and /upgrade leave the docs out only when the release carries them in plugins/aplyca-adf/docs/, so adopting from an older tag still works.
• Spec model: customizing it now takes the committed install. Customizing it already meant editing /write-spec, which a packaged project can't do.

Upgrade impact

• Committed projects: overwrite session-context.sh and deep-spec-analysis.js. Both behave as before.
• Packaged projects: /aplyca-adf:upgrade does four steps after moving the pin:
  1. delete the unchanged docs;
  2. run the link script;
  3. add the read rule;
  4. add the names note's new sentence.

Evals

• Static, all passing: check-skills 158, test-hooks 82, test-modules 45, test-plugin 18. New in this PR:
  • the link script's round trip on the whole skeleton (packaged and back gives identical files), pin moves, idempotence, and tag validation;
  • the session-context line in a packaged project, and its absence when the project keeps its own copies;
  • the plugin's generated workflows parsed with node --check.
• check-packaged.sh: gains the reference-doc checks. On a correct packaged layout all 10 pass; with a doc put back and the rule removed, those two fail.
• New session suite, plugin-docs (Haiku, default permission mode, no extra directories). Run 1 found the path-shortening issue above. Runs 2 and 3 passed after the fix (run 3: 7 of 7, $0.58).
  • agent-spec-model: a plugin agent reads the plugin's spec model.
  • session-docs: the session finds a doc through the session context.
  • without-rule: the control, where the same read is denied.
  • Each check was also run against a session where it should fail, and failed there.

🤖 Generated with Claude Code