From 324f10a7e0f527bdb0898bf6ee9699a8611bb17f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mauricio=20S=C3=A1nchez?= Date: Fri, 2 Oct 2026 18:01:52 -0500 Subject: [PATCH 1/2] fix: the install refreshes a marketplace added before MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A machine that added the aplyca marketplace before the rename keeps its copy, which lists only aplyca-framework, and `marketplace add` leaves it 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 run `claude plugin marketplace update aplyca` before the install. Tested on a copy of the marketplace from 7383422. Co-Authored-By: Claude Opus 5.5 --- ADOPT.md | 4 +++- CHANGELOG.md | 10 ++++++++++ README.md | 8 ++++++-- docs/SETUP.md | 5 +++-- evals/static/check-skills.sh | 1 + plugins/aplyca-adf/README.md | 8 +++++++- 6 files changed, 30 insertions(+), 6 deletions(-) diff --git a/ADOPT.md b/ADOPT.md index 5fa80f7..785e8f4 100644 --- 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 index 3691612..3ad292a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,16 @@ For each entry, **Upgrade impact** classifies the change against the [three-buck ## Unreleased +### 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 index 81a5cbe..29f311d 100644 --- 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`). diff --git a/docs/SETUP.md b/docs/SETUP.md index de233f0..429eb3f 100644 --- 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/evals/static/check-skills.sh b/evals/static/check-skills.sh index 07767fd..e07dcb7 100755 --- 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 index 20d5630..325002a 100644 --- 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** → From 0dcccafd5d83eaaec148443a1a81229a7ef3860d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mauricio=20S=C3=A1nchez?= Date: Fri, 2 Oct 2026 18:03:42 -0500 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20release=20v1.0.0=20=E2=80=94=20one?= =?UTF-8?q?=20plugin,=20a=20packaged=20install,=20and=20semantic=20version?= =?UTF-8?q?ing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Turns Unreleased into v1.0.0, covering #17–#20 and the install fix, and opens it with the order to upgrade in from 7383422: install aplyca-adf with the prompt, run /aplyca-adf:upgrade (renames the setting, pins v1.0.0, restamps), then uninstall aplyca-framework. plugin.json is already 1.0.0, and the static check now matches it to the heading. README's "Update a project" and UPGRADING point at releases: the target is the newest tag, the stamp carries the version, and a project adopted before v1.0.0 has its own scenario. The plugin README's update section no longer tells those projects to update a plugin they never installed. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 27 ++++++++++++++++++++++++ README.md | 41 ++++++++++++++++++------------------ docs/UPGRADING.md | 17 +++++++++++---- plugins/aplyca-adf/README.md | 11 +++------- 4 files changed, 64 insertions(+), 32 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ad292a..92c9aa0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,33 @@ 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 · …`), 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 diff --git a/README.md b/README.md index 29f311d..fed5476 100644 --- a/README.md +++ b/README.md @@ -136,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 (``) 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/UPGRADING.md b/docs/UPGRADING.md index db58727..ea0bb8b 100644 --- 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 - + ``` Commit with a clear message: ``` -chore: upgrade skeleton to +chore: upgrade skeleton to 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/plugins/aplyca-adf/README.md b/plugins/aplyca-adf/README.md index 325002a..fd41e2b 100644 --- a/plugins/aplyca-adf/README.md +++ b/plugins/aplyca-adf/README.md @@ -157,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.