Aplyca · mauricios · Oct 2, 2026 · Oct 2, 2026 · Oct 2, 2026
diff --git a/ADOPT.md b/ADOPT.md
@@ -29,10 +29,12 @@ from the project's root:
 
 ```bash
 claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
+claude plugin marketplace update aplyca
 claude plugin install aplyca-adf@aplyca --scope project
 ```
 
-Always with `--scope project`: without it, Claude Code installs at user scope, which turns the plugin
+The update refreshes a copy of the marketplace this machine added before; without it, the install
+can't find `aplyca-adf`. Always with `--scope project`: without it, Claude Code installs at user scope, which turns the plugin
 on in every project on the machine. If `claude plugin list` also shows the plugin at user scope, tell
 the developer, with the commands that remove that copy (the plugin's
 [README § Install](plugins/aplyca-adf/README.md#install)); don't run them.

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,43 @@ For each entry, **Upgrade impact** classifies the change against the [three-buck
 
 ## Unreleased
 
+## v1.0.0 — 2026-10-02 — One plugin, a packaged install, and semantic versioning
+
+Everything since `7383422`: `/upgrade` carries the plugin setting into the hub's worktree
+([#17](https://github.com/Aplyca/AgenticDevelopmentFramework/pull/17)), Claude Code's own worktrees
+are workers ([#18](https://github.com/Aplyca/AgenticDevelopmentFramework/pull/18)), `/cost-report`'s
+Sonnet estimate ([#19](https://github.com/Aplyca/AgenticDevelopmentFramework/pull/19)), and one
+plugin with a packaged install, joining a project with no install, and semantic versioning
+([#20](https://github.com/Aplyca/AgenticDevelopmentFramework/pull/20)). It's the first numbered
+release, and a major one: the installer plugin is renamed `aplyca-adf`.
+
+**Upgrading a repository whose baseline is `7383422`.** In this order:
+
+1. **Install `aplyca-adf` in the project.** Paste the install prompt from the
+   [README](README.md#with-claude-code--the-installer-plugin-recommended) into a session on the
+   project — from a worktree if the project uses the dispatcher hub. It refreshes the marketplace,
+   installs with `--scope project`, and reports a user-scope copy to remove. Then start a new
+   session.
+2. **Run `/aplyca-adf:upgrade`.** It replaces `aplyca-framework@aplyca` in the committed settings,
+   pins the marketplace to `v1.0.0`, applies each part's Upgrade impact below, restamps `CLAUDE.md`
+   (`Skeleton source: v1.0.0 · <SHA> …`), and offers the packaged install. Stay committed unless the
+   team works in Claude Code only. By hand: each part's Upgrade impact, newest first.
+3. **Remove the old plugin** once the pull request merges, on each machine that installed it:
+   `claude plugin uninstall aplyca-framework@aplyca --scope project`. Teammates need nothing else:
+   their next session loads `aplyca-adf` at the pinned release.
+
+A baseline older than `7383422` takes that release's order first, then this one.
+
+### The install refreshes a marketplace added before
+
+A machine that added the `aplyca` marketplace before the rename keeps its copy of it, which lists only
+`aplyca-framework`. Running `claude plugin marketplace add` again leaves that copy alone, so the
+install prompt failed with `Plugin "aplyca-adf" not found` in every project adopted before it. The
+prompt, `ADOPT.md`, and the documented commands now run `claude plugin marketplace update aplyca`
+between adding the marketplace and installing the plugin. Tested on a copy of the marketplace from
+`7383422`.
+**Upgrade impact:** framework-internal.
+
 ### One plugin, `aplyca-adf`, and semantic versioning — breaking
 
 ([0016](docs/decisions/0016-packaged-install.md), [0017](docs/decisions/0017-semantic-versioning.md))

diff --git a/README.md b/README.md
@@ -69,7 +69,10 @@ any code exists. Step by step:
       worktree.
    3. From this folder, run:
       claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
+      claude plugin marketplace update aplyca
       claude plugin install aplyca-adf@aplyca --scope project
+      The update refreshes a copy of the marketplace added before; without it the install can't
+      find aplyca-adf.
    4. Show me the diff of .claude/settings.json: it should add only the aplyca marketplace and the
       plugin. Don't commit it — /adopt or /upgrade puts it in its pull request.
    5. If claude plugin list also shows the plugin at user scope, tell me, with the commands that remove
@@ -78,15 +81,16 @@ any code exists. Step by step:
       "Skeleton source:" line, otherwise /aplyca-adf:adopt.
    ```
 
-   Or run the two commands yourself, from the project's folder:
+   Or run the commands yourself, from the project's folder:
 
    ```bash
    cd your-project
    claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
+   claude plugin marketplace update aplyca
    claude plugin install aplyca-adf@aplyca --scope project
    ```
 
-   Both commands write to the project's `.claude/settings.json` and nowhere else: the plugin is on in
+   They write to the project's `.claude/settings.json` and nowhere else: the plugin is on in
    this project only, and teammates get it once they trust the folder. Without `--scope`,
    Claude Code installs at `user` scope — on in every project on your machine — so always pass it. To
    try the plugin alone first, use `--scope local` (the git-ignored `.claude/settings.local.json`).
@@ -132,32 +136,33 @@ hooks, stamp the baseline, and verify.
 
 ## Update a project
 
-The framework is copied in, not installed as a dependency, so updates are deliberate and keep your
-customizations. Read the **Upgrade impact** of each release in [CHANGELOG.md](CHANGELOG.md) first.
-The latest release, `7383422` (2026-10-01), opens with the order to upgrade in; `/upgrade` now
-offers the modules you don't have, and the plugin installs per project. A baseline older than
-`3eb7777` takes that release's three fixes first — they affect every adopted repository — and if your
-settings pin a model ID, switch it to the `sonnet` alias.
-
-1. **Update the plugin** from the project's folder — then restart Claude Code:
-
-   ```bash
-   claude plugin marketplace update aplyca
-   claude plugin update aplyca-adf@aplyca
-   ```
-
+Updates are deliberate: `/aplyca-adf:upgrade` moves a project from one release to the next in a draft
+pull request and keeps its customizations. Read the **Upgrade impact** of each release in
+[CHANGELOG.md](CHANGELOG.md) first. From v1.0.0, releases follow semantic versioning
+([decision 0017](docs/decisions/0017-semantic-versioning.md)), so a major release asks something of
+your team. The latest, **v1.0.0** (2026-10-02), renames the plugin `aplyca-adf` and opens with the
+order to upgrade in. A baseline older than `7383422` takes that release's order first, and one older
+than `3eb7777` takes its three fixes before that — they affect every adopted repository.
+
+1. **Get the plugin into the project.** Adopted before v1.0.0 — a stamp with no `v` version? Paste
+   the [install prompt](#with-claude-code--the-installer-plugin-recommended) into a session on the
+   project; it installs `aplyca-adf`. Then start a new session. A project already pinned to a release
+   needs nothing here: the pinned plugin runs the upgrade.
 2. **Run `/aplyca-adf:upgrade`** in the adopted project. It reads the baseline stamp
    (`<!-- Skeleton source: <version> · <SHA> (<date>) · modules: … -->`) and diffs the framework from that
-   version to the latest. It sorts every changed file into overwrite, merge, or additive, applies the
+   release to the newest. It sorts every changed file into overwrite, merge, or additive, applies the
    CHANGELOG migration steps, and offers the optional modules the project doesn't have yet — the
-   dispatcher hub (`parallel-agents`) among them. It shows you the plan before changing anything.
-   Then it updates the files — your project-specific content stays — installs the modules you chose,
-   re-stamps, and prepares a draft pull request.
+   dispatcher hub (`parallel-agents`) among them — and the other install, committed or packaged. It
+   shows you the plan before changing anything. Then it updates the files — your project-specific
+   content stays — installs the modules you chose, moves the release pin, re-stamps, and prepares a
+   draft pull request.
 3. **Review the pull request** and run the verification in [docs/UPGRADING.md](docs/UPGRADING.md):
    valid settings, hooks that fire, both instruction files loading, a smoke test of a changed skill.
+   Once it merges, everyone's next session loads the new release.
 
-Installed the plugin at user scope earlier? `/upgrade` adds the project setting in its pull request;
-then remove the user-scope copy ([how](plugins/aplyca-adf/README.md#install)).
+Installed the plugin at user scope, or under its old name `aplyca-framework`? `/aplyca-adf:upgrade`
+fixes the project setting in its pull request; then remove the old copy
+([how](plugins/aplyca-adf/README.md#install)).
 
 By hand, or to cherry-pick one improvement: [docs/UPGRADING.md](docs/UPGRADING.md).
 

diff --git a/docs/SETUP.md b/docs/SETUP.md
@@ -9,12 +9,13 @@ Code session, or with these commands:
 ```bash
 cd your-project
 claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
+claude plugin marketplace update aplyca
 claude plugin install aplyca-adf@aplyca --scope project
-# then, in the repository:  /adopt
+# then, in the repository:  /aplyca-adf:adopt
 ```
 
 `--scope project` turns the plugin on in this project only, through its committed
-`.claude/settings.json` — the team is offered it, and every worktree of a hub project gets it. Without
+`.claude/settings.json` — teammates get it once they trust the folder, and every worktree of a hub project gets it. Without
 `--scope`, Claude Code installs it for every project on your machine. To try it alone first, use
 `--scope local`. From the desktop app's Code tab:
 [the plugin's README § In the desktop app](../plugins/aplyca-adf/README.md#in-the-desktop-app).

diff --git a/docs/UPGRADING.md b/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.
 
-The framework ships as a copy-in skeleton, not a runtime dependency. There is no `npm update` equivalent. Upgrades are deliberate, file-by-file, and informed by the three-bucket taxonomy below.
+By default the framework is committed into the project, not a runtime dependency; in the packaged install, the skills, agents, workflows, and hook scripts come from the pinned plugin instead. 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
 
@@ -113,7 +113,7 @@ Concrete steps. Do this on a branch in the target project.
 
 Read the skeleton-source line at the top of your project's `CLAUDE.md`. If absent, infer it: read the framework's `git log --oneline` and pick the latest SHA whose features you can identify in your project. Record this as `OLD_SHA`.
 
-The new target is the framework's current `main` SHA — call it `NEW_SHA`.
+The target is the newest release, `vX.Y.Z` (`git -C /path/to/AgenticDevelopmentFramework tag --list 'v*' --sort=-v:refname | head -1`). The commit its tag points to is `NEW_SHA`.
 
 ### 2. Read the changelog
 
@@ -175,13 +175,13 @@ Resolve conflicts manually. The principle: keep your customizations (project ide
 Edit the top of `CLAUDE.md`:
 
 ```markdown
-<!-- Skeleton source: <NEW_SHA> (<today's date>) · modules: <list or none> -->
+<!-- Skeleton source: <vX.Y.Z> · <NEW_SHA> (<today's date>) · modules: <list or none> -->
 ```
 
 Commit with a clear message:
 
 ```
-chore: upgrade skeleton to <NEW_SHA>
+chore: upgrade skeleton to <vX.Y.Z>
 
 What changed:
 - Added /spec-drift skill
@@ -248,6 +248,15 @@ does it and reports a user-scope copy to remove), then run `/upgrade` in a new s
 the release's parts newest first and offers the modules you don't have. If the project uses the
 dispatcher hub, run it from a worktree: from this release on, the hub's main checkout takes no edits.
 
+### "We adopted before v1.0.0 (2026-10-02)"
+
+The installer plugin is now `aplyca-adf`; the project's settings still turn on `aplyca-framework`.
+Install `aplyca-adf` with the README's install prompt, which refreshes the marketplace first, then run
+`/aplyca-adf:upgrade` in a new session. It replaces the old name in the committed settings, pins the
+marketplace to the release, and restamps with the version. Once its pull request merges, remove the
+old plugin from each machine that installed it:
+`claude plugin uninstall aplyca-framework@aplyca --scope project`.
+
 ### "We use the packaged install" — or want to
 
 A packaged project ([decision 0016](decisions/0016-packaged-install.md)) doesn't commit the skills,

diff --git a/evals/static/check-skills.sh b/evals/static/check-skills.sh
@@ -625,6 +625,7 @@ check_practices() {
     file_contains_literal "$REPO_ROOT/ADOPT.md" '--scope project' || missing+=("ADOPT.md: the agent entry point installs per project")
     file_contains_literal "$REPO_ROOT/README.md" '(ADOPT.md)' || missing+=("README.md: points agents to ADOPT.md")
     file_contains "$SKELETON/docs/getting-started/DEV-SETUP.md" 'needs no install step' || missing+=("DEV-SETUP.md: joining a project needs no install")
+    file_contains "$REPO_ROOT/README.md" 'claude plugin marketplace update aplyca' || missing+=("install prompt: refreshes a marketplace added before")
     file_contains "$REPO_ROOT/README.md" 'there is nothing to install' || missing+=("install prompt: stops when the project already turns the plugin on")
     file_contains "$REPO_ROOT/docs/SETUP.md" 'by their full names' || missing+=("SETUP.md: a packaged DEV-SETUP.md names the commands in full")
     if [ ${#missing[@]} -eq 0 ]; then

diff --git a/plugins/aplyca-adf/README.md b/plugins/aplyca-adf/README.md
@@ -39,7 +39,10 @@ at user scope.
    worktree.
 3. From this folder, run:
    claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
+   claude plugin marketplace update aplyca
    claude plugin install aplyca-adf@aplyca --scope project
+   The update refreshes a copy of the marketplace added before; without it the install can't
+   find aplyca-adf.
 4. Show me the diff of .claude/settings.json: it should add only the aplyca marketplace and the
    plugin. Don't commit it — /adopt or /upgrade puts it in its pull request.
 5. If claude plugin list also shows the plugin at user scope, tell me, with the commands that remove
@@ -48,11 +51,13 @@ at user scope.
    "Skeleton source:" line, otherwise /aplyca-adf:adopt.
 ```
 
-Or run the two commands yourself, from the project's folder:
+Or run the commands yourself, from the project's folder. The update refreshes a copy of the
+marketplace added before, which doesn't list `aplyca-adf` yet:
 
 ```bash
 cd your-project
 claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
+claude plugin marketplace update aplyca
 claude plugin install aplyca-adf@aplyca --scope project
 ```
 
@@ -82,6 +87,7 @@ made with the commands above works there too. To install from the app instead:
 
    ```bash
    claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
+   claude plugin marketplace update aplyca
    ```
 
 2. In a local or SSH session on the project, click **+** next to the prompt box, then **Plugins** →
@@ -151,11 +157,6 @@ files, so a skill listed twice never runs a different version.
 
 Every project pins a release, so updating the plugin changes nothing until the pin moves.
 `/aplyca-adf:upgrade` moves it to the newest release and brings the committed files along, in one pull
-request; restart Claude Code after it merges. A project that isn't pinned yet — adopted before
-v1.0.0 — takes the newest release from the project's folder, then runs `/aplyca-adf:upgrade`, which
-pins it:
-
-```bash
-claude plugin marketplace update aplyca
-claude plugin update aplyca-adf@aplyca --scope project
-```
+request; restart Claude Code after it merges. A project adopted before v1.0.0 isn't pinned and turns
+on `aplyca-framework`: install `aplyca-adf` with the [install prompt](#install), then run
+`/aplyca-adf:upgrade`, which renames the setting and pins the release.