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

CHANGELOG.md

@@ -11,6 +11,47 @@ For each entry, **Upgrade impact** classifies the change against the [three-buck
 
 ## Unreleased
 
+### A packaged project reads the framework's reference docs from the plugin
+
+([0019](docs/decisions/0019-reference-docs-in-the-plugin.md), amending [0016](docs/decisions/0016-packaged-install.md))
+
+The four reference docs (`COST-MODEL.md`, `MCP-INTEGRATION.md`, `MEMORY-STRATEGY.md`, `SPEC-MODEL.md`)
+are generic, never edited by a project, and already overwritten verbatim by every upgrade. The
+`aplyca-adf` plugin now carries them in `docs/`, and a packaged project commits none of them, about 950
+fewer lines.
+
+- **Skills and agents** name the plugin's copy, `${CLAUDE_PLUGIN_ROOT}/docs/<doc>.md`, and say it's
+  outside the project. Without that line, an agent on Haiku read `docs/SPEC-MODEL.md` in the project
+  instead.
+- **`deep-spec-analysis`** carries the spec model's text in its plugin copy, because Claude Code
+  doesn't fill in `${CLAUDE_PLUGIN_ROOT}` in a workflow script.
+- **The read rule.** Claude Code asks before reading any file outside the project, the plugin's own
+  folder included. So a packaged project commits
+  `Read(~/.claude/plugins/cache/aplyca/aplyca-adf/**)` in `permissions.allow`.
+- **The session context.** The plugin's SessionStart hook tells a packaged session where the docs
+  are.
+- **Links on GitHub.** The project's files link the docs at the pinned release on GitHub. The new
+  `scripts/link-reference-docs.py` rewrites the links: `/aplyca-adf:adopt` runs it, and
+  `/aplyca-adf:upgrade` runs it to move them with each pin, and back on a switch to the committed
+  install.
+
+A new session-eval suite, `plugin-docs`, checks the reads in real sessions. The committed install is
+unchanged. `TRACKER-INTEGRATION.md` and `PARALLEL-AGENTS.md` stay in the project, because they hold
+its settings.
+
+**Upgrade impact:**
+
+- **Committed projects:** overwrite `.claude/hooks/session-context.sh` and
+  `.claude/workflows/deep-spec-analysis.js`. Both behave as before in a committed project: the
+  workflow's prompts name `docs/SPEC-MODEL.md` through one constant.
+- **Packaged projects:** `/aplyca-adf:upgrade` does these steps after moving the pin.
+  1. **Delete the four docs** from `docs/` where each is unchanged since your baseline. One your team
+     edited stays under a name of its own, or the team switches to the committed install.
+  2. **Rewrite the links:**
+     `python3 <framework>/scripts/link-reference-docs.py . --packaged v<X.Y.Z>`.
+  3. **Add the read rule** to `permissions.allow` in `.claude/settings.json`.
+  4. **Add the names note's last sentence** to `CLAUDE.md`, from `docs/SETUP.md` § Packaged install.
+
 ## v1.1.0 — 2026-10-04 — The packaged install by default, checked in real sessions
 
 A minor release: a new default for new projects, and evals for the packaged install's paths. Nothing

README.md

@@ -116,9 +116,9 @@ any code exists. Step by step:
 5. **Add a module later:** `/upgrade` offers the modules you don't have yet, and so does running
    `/adopt` again in the adopted repository.
 
-By default, adopted repositories use the **packaged** install: the skills, agents, workflows, and hook
-scripts come from the `aplyca-adf` plugin, pinned to a release, and the repository commits only its
-own layer — about 40 fewer files. A team that also uses other AI tools, or Claude Code's cloud
+By default, adopted repositories use the **packaged** install: the skills, agents, workflows, hook
+scripts, and the framework's reference docs come from the `aplyca-adf` plugin, pinned to a release,
+and the repository commits only its own layer — about 50 fewer files. A team that also uses other AI tools, or Claude Code's cloud
 sessions, chooses the **committed** install: plain files every AI tool can read, with or without the
 plugin, which then only installs and maintains them. `/aplyca-adf:adopt` asks which one.
 ([Packaged install](docs/SETUP.md#packaged-install-claude-code-only) · [why](docs/decisions/0016-packaged-install.md) · [the default](docs/decisions/0018-packaged-by-default.md))
@@ -397,7 +397,8 @@ skeleton/                 Portable project skeleton — what an adopting reposit
 
 modules/                  Optional additions: github/, git-hooks/, clickup/, parallel-agents/
 plugins/aplyca-adf/       The Claude Code plugin: /aplyca-adf:adopt, :upgrade, :cost-report — and, for
-                          packaged projects, the skills, agents, workflows, and hooks (generated)
+                          packaged projects, the skills, agents, workflows, hooks, and reference
+                          docs (generated)
 docs/                     Framework docs: SETUP, UPGRADING, ONBOARDING, references, examples,
                           scenarios, decisions
 evals/                    Static checks; hook, module, and plugin tests; triage routing evals and

docs/ONBOARDING.md

@@ -145,7 +145,9 @@ One person, once:
 
 ### Day 1: Orientation and guardrails (2 hours)
 
-Read, in your project:
+Read, in your project — on the packaged install, the skills and the reference docs (`SPEC-MODEL.md`,
+`COST-MODEL.md`, `MEMORY-STRATEGY.md`) come from the plugin: `AGENTS.md` links the docs at the pinned
+release, and the originals are linked below:
 
 1. `AGENTS.md` — the contract every AI tool reads: ground rules, how work flows, delivery rules,
    boundaries. ([original](../skeleton/AGENTS.md); 10 min)
@@ -160,7 +162,8 @@ Read, in your project:
    [`implement`](../skeleton/.claude/skills/implement/SKILL.md) skills — above all their
    *Rationalizations* tables, the excuses agents (and people) make for skipping a step. (20 min)
 6. `docs/COST-MODEL.md` and `docs/MEMORY-STRATEGY.md` — when to escalate a model, where a fact
-   belongs. `docs/TRACKER-INTEGRATION.md` if requirements arrive through a tracker. (15 min)
+   belongs (originals: [cost model](../skeleton/docs/COST-MODEL.md),
+   [memory strategy](../skeleton/docs/MEMORY-STRATEGY.md)). `docs/TRACKER-INTEGRATION.md` if requirements arrive through a tracker. (15 min)
 7. The worked example: [examples/newsletter-signup/](examples/newsletter-signup/). (20 min)
 
 | Tool | Reads | Skills and agents | Rules | Hooks, permissions |

docs/SETUP.md

@@ -21,8 +21,9 @@ claude plugin install aplyca-adf@aplyca --scope project
 [the plugin's README § In the desktop app](../plugins/aplyca-adf/README.md#in-the-desktop-app).
 
 `/aplyca-adf:adopt` recommends the **packaged** install by default
-([decision 0018](decisions/0018-packaged-by-default.md)): the skills, agents, workflows, and hook
-scripts come from the pinned plugin, and the repository commits only its own layer —
+([decision 0018](decisions/0018-packaged-by-default.md)): the skills, agents, workflows, hook
+scripts, and the framework's reference docs come from the pinned plugin, and the repository commits
+only its own layer —
 [§ Packaged install](#packaged-install-claude-code-only) lists what changes. The manual path below is
 the same procedure, step by step, for the **committed** install, which a team that also uses other AI
 tools, or Claude Code's cloud sessions, chooses instead.
@@ -147,7 +148,8 @@ Each customizable doc starts with `<!-- owner · last_updated · scope -->` —
 
 `docs/SPEC-MODEL.md` and `specs/_templates/spec.md` ship with defaults for web projects. To change role
 names, mandatory sections, or conditional rules, update the template, `docs/SPEC-MODEL.md`, and the
-enforcement step in `.claude/skills/write-spec/SKILL.md` together.
+enforcement step in `.claude/skills/write-spec/SKILL.md` together. That takes the committed install:
+in a packaged project, the spec model and `/aplyca-adf:write-spec` come from the plugin.
 
 ## 8. Stamp, commit, and open a draft pull request
 
@@ -172,7 +174,8 @@ Open the pull request as a draft; merge after review like any other change.
 ## Packaged install (Claude Code only)
 
 [Decision 0016](decisions/0016-packaged-install.md). The framework's machinery doesn't enter the
-repository: 20 skills, 8 agents, 4 workflows, and the hook scripts come from the `aplyca-adf` plugin,
+repository: 20 skills, 8 agents, 4 workflows, the hook scripts, and the framework's reference docs
+([decision 0019](decisions/0019-reference-docs-in-the-plugin.md)) come from the `aplyca-adf` plugin,
 pinned to a release tag. The repository commits its own layer as above, and every module's files.
 Choose it when the team works in Claude Code only. Cursor, Copilot, and Gemini users would get
 `AGENTS.md` and the rules but no skills, and Claude Code's cloud sessions don't load the plugin.
@@ -184,10 +187,15 @@ v1.0.0 or later; its entry in [`CHANGELOG.md`](../CHANGELOG.md) says what it bri
 **What changes from the steps above:**
 
 1. **Copy less** (step 1). Leave out `.claude/skills/`, `.claude/agents/`, `.claude/workflows/`, the
-   scripts and helpers in `.claude/hooks/` (keep `config.sh`), `.claude/hooks/README.md`, `GEMINI.md`, `.agents/`,
-   and `.cursor/`. Modules copy as usual: `/dispatch` is the one skill a packaged repository commits.
+   scripts and helpers in `.claude/hooks/` (keep `config.sh`), `.claude/hooks/README.md`, `GEMINI.md`,
+   `.agents/`, `.cursor/`, and the four reference docs: `docs/COST-MODEL.md`,
+   `docs/MCP-INTEGRATION.md`, `docs/MEMORY-STRATEGY.md`, and `docs/SPEC-MODEL.md`. Modules copy as usual: `/dispatch` is the one
+   skill a packaged repository commits. Then point the files that name the reference docs at the
+   release you pin, from the framework copy you took the skeleton from:
+   `python3 <framework>/scripts/link-reference-docs.py . --packaged v<X.Y.Z>`.
 2. **Wire the plugin, not the hooks** (step 5). Drop the `hooks` block from `.claude/settings.json`,
-   since the plugin wires the same hooks, and pin the marketplace to the release:
+   since the plugin wires the same hooks, pin the marketplace to the release, and add the read rule to
+   `permissions.allow`:
 
    ```json
    {
@@ -196,18 +204,23 @@ v1.0.0 or later; its entry in [`CHANGELOG.md`](../CHANGELOG.md) says what it bri
          "source": { "source": "github", "repo": "aplyca/AgenticDevelopmentFramework", "ref": "v<X.Y.Z>" }
        }
      },
-     "enabledPlugins": { "aplyca-adf@aplyca": true }
+     "enabledPlugins": { "aplyca-adf@aplyca": true },
+     "permissions": { "allow": ["Read(~/.claude/plugins/cache/aplyca/aplyca-adf/**)"] }
    }
    ```
 
    The hooks read `.claude/hooks/config.sh` from the project, so step 5's settings apply unchanged.
+   The read rule lets the plugin's skills and agents open its reference docs: Claude Code asks before
+   reading any file outside the project, the plugin's own folder included, unless a rule allows it.
 3. **Tell people the names** (step 3). Everything a plugin carries goes by the plugin's name. Add this
    to the start of `CLAUDE.md` § Skills, agents, and workflows:
 
    > **This project uses the packaged install.** Skills, agents, and workflows come from the
    > `aplyca-adf` plugin, pinned in `.claude/settings.json`. Where these files name a skill or
    > workflow — `/triage`, `/deep-review` — type `/aplyca-adf:triage`, `/aplyca-adf:deep-review`.
-   > Where they name an agent — `@code-reviewer` — its name is `aplyca-adf:code-reviewer`.
+   > Where they name an agent — `@code-reviewer` — its name is `aplyca-adf:code-reviewer`. The
+   > framework's reference docs — the spec model, the cost model, the memory strategy, MCP
+   > integration — come from the plugin too; these files link them at the pinned release.
 
    People read the key commands in `docs/getting-started/DEV-SETUP.md` § AI-assisted development,
    so write them there by their full names: `/aplyca-adf:triage`, `@aplyca-adf:code-reviewer`.
@@ -220,12 +233,14 @@ project and the plugin named: `CLAUDE_PROJECT_DIR="$PWD" CLAUDE_PLUGIN_ROOT=<mar
 where the marketplace folder is the `installLocation` of `aplyca` in
 `claude plugin marketplace list --json`. And in a new session, `/aplyca-adf:triage` is offered.
 
-Each teammate gets the plugin once they trust the folder. A machine nobody opens a session on — CI —
-installs it first, from the repository's folder:
+Each teammate gets the plugin, and the read rule, once they trust the folder. A machine nobody opens a
+session on — CI — installs it first, from the repository's folder; a headless run (`claude -p`) never
+trusts the folder, so pass the read rule with `--allowedTools` if it uses the plugin's skills:
 
 ```bash
 claude plugin marketplace add aplyca/AgenticDevelopmentFramework#v<X.Y.Z> --scope project
 claude plugin install aplyca-adf@aplyca --scope project
+claude -p "<the task>" --allowedTools "Read(~/.claude/plugins/cache/aplyca/aplyca-adf/**)"
 ```
 
 ## Verify

docs/UPGRADING.md

@@ -2,7 +2,7 @@
 
 How to pull newer framework changes into a target project that adopted an earlier version of the skeleton — without losing your team's customizations.
 
-In the packaged install — the default for new projects ([decision 0018](decisions/0018-packaged-by-default.md)) — the skills, agents, workflows, and hook scripts come from the pinned plugin; in the committed install, everything is committed into the project, with no runtime dependency. Either way, a project moves from one release to the next on purpose: the committed files file by file, informed by the three-bucket taxonomy below, and the plugin by moving its pin.
+In the packaged install — the default for new projects ([decision 0018](decisions/0018-packaged-by-default.md)) — the skills, agents, workflows, hook scripts, and the framework's reference docs come from the pinned plugin; in the committed install, everything is committed into the project, with no runtime dependency. Either way, a project moves from one release to the next on purpose: the committed files file by file, informed by the three-bucket taxonomy below, and the plugin by moving its pin.
 
 ## When to upgrade
 
@@ -63,10 +63,10 @@ Every file the skeleton introduces falls into one of three buckets. Your upgrade
 | `.claude/rules/testing.md` | Universal — testing discipline |
 | `.claude/rules/security.md` | Universal — OWASP-style baseline |
 | `.claude/rules/git-workflow.md` | Universal — commit prefixes, branch discipline |
-| `docs/SPEC-MODEL.md` | Framework reference doc |
-| `docs/COST-MODEL.md` | Framework reference doc |
-| `docs/MEMORY-STRATEGY.md` | Framework reference doc |
-| `docs/MCP-INTEGRATION.md` | Framework reference doc |
+| `docs/SPEC-MODEL.md` | Framework reference doc — a packaged project has none: the plugin carries it |
+| `docs/COST-MODEL.md` | Framework reference doc — a packaged project has none: the plugin carries it |
+| `docs/MEMORY-STRATEGY.md` | Framework reference doc — a packaged project has none: the plugin carries it |
+| `docs/MCP-INTEGRATION.md` | Framework reference doc — a packaged project has none: the plugin carries it |
 | `docs/process/0000-pdr-template.md` | The PDR template |
 | `.cursor/rules/*.mdc` | Cursor mirrors of the rules |
 | `specs/_templates/*` | The spec-folder templates (`spec.md`, `plan.md`, `tasks.md`) — merge instead if your team customized them. Your filled-in specs are project-owned |
@@ -145,7 +145,7 @@ cp -R $FW/.claude/agents/* .claude/agents/
 mkdir -p .claude/workflows && cp $FW/.claude/workflows/*.js .claude/workflows/
 cp $FW/.claude/hooks/*.sh $FW/.claude/hooks/*.jq $FW/.claude/hooks/*.py $FW/.claude/hooks/README.md .claude/hooks/   # not config.sh — that one merges
 cp $FW/.claude/rules/{code-quality,testing,security,git-workflow}.md .claude/rules/
-cp $FW/docs/{SPEC-MODEL,COST-MODEL,MEMORY-STRATEGY,MCP-INTEGRATION}.md docs/
+cp $FW/docs/{SPEC-MODEL,COST-MODEL,MEMORY-STRATEGY,MCP-INTEGRATION}.md docs/   # committed install only
 ```
 
 Inspect the diff for surprise (removed files, renamed files). Adjust if the framework has restructured anything.
@@ -260,11 +260,14 @@ old plugin from each machine that installed it:
 ### "We use the packaged install" — or want to
 
 A packaged project ([decision 0016](decisions/0016-packaged-install.md)) doesn't commit the skills,
-agents, workflows, or hook scripts: they come from the `aplyca-adf` plugin, pinned to a release tag
-in `.claude/settings.json`. Upgrading it means two things:
+agents, workflows, hook scripts, or the framework's reference docs
+([decision 0019](decisions/0019-reference-docs-in-the-plugin.md)): they come from the `aplyca-adf`
+plugin, pinned to a release tag in `.claude/settings.json`. Upgrading it means two things:
 
 - **Bump the pin:** the marketplace's `"ref"` moves to the new release tag, `vX.Y.Z`. That one line upgrades
-  every skill, agent, workflow, and hook. Every project moves from release to release, committed ones
+  every skill, agent, workflow, hook, and reference doc. The project's links to the reference docs
+  name the release too: `python3 <framework>/scripts/link-reference-docs.py . --packaged vX.Y.Z`,
+  from the new release, moves them. Every project moves from release to release, committed ones
   too: their pin keeps the plugin's copies at the same release as their committed files.
 - **Merge the committed layer** as in the procedure above — `AGENTS.md`, `CLAUDE.md`, the settings
   (never adding a `hooks` block), `config.sh`, the rules, the docs, and the modules — and skip every

docs/decisions/0016-packaged-install.md

@@ -1,6 +1,6 @@
 # 0016: A packaged install — the framework's machinery from its pinned plugin, `aplyca-adf` (opt-in, Claude Code only)
 
-- **Status:** accepted; amended by [0018](0018-packaged-by-default.md) (the packaged install is the default)
+- **Status:** accepted; amended by [0018](0018-packaged-by-default.md) (the packaged install is the default) and [0019](0019-reference-docs-in-the-plugin.md) (the reference docs come from the plugin)
 - **Date:** 2026-10-02
 - **Amends:** [0009](0009-optional-modules.md) — what ships as committed files