feat!: one plugin, aplyca-adf, with a packaged install, and semantic versioning (decisions 0016, 0017)

.claude-plugin/marketplace.json

@@ -1,21 +1,21 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "aplyca",
-  "description": "Aplyca's AI-agentic development tooling — installer and upgrader for the Agentic Development Framework skeleton",
+  "description": "Aplyca's agentic development tooling — the Agentic Development Framework's plugin, aplyca-adf",
   "owner": {
     "name": "Aplyca",
     "email": "dev@aplyca.com"
   },
   "plugins": [
     {
-      "name": "aplyca-framework",
-      "description": "Adopt and upgrade the Aplyca Agentic Development Framework in any repository. /adopt bootstraps a repo (copies the skeleton and chosen modules, fills placeholders from verified repo facts, configures guardrail hooks, stamps the baseline SHA); /upgrade syncs an adopted repo to a newer skeleton version using the three-bucket taxonomy; /cost-report measures what agent sessions cost.",
+      "name": "aplyca-adf",
+      "description": "The Agentic Development Framework for Claude Code: /adopt and /upgrade install and maintain it in a repository, committed or packaged; /cost-report measures what agent sessions cost. A packaged project also takes the framework's skills, agents, workflows, and guardrail hooks from this plugin, pinned to a release.",
       "author": {
         "name": "Aplyca",
         "email": "dev@aplyca.com"
       },
       "category": "productivity",
-      "source": "./plugins/aplyca-framework"
+      "source": "./plugins/aplyca-adf"
     }
   ]
 }

ADOPT.md

@@ -3,7 +3,7 @@
 You were asked to adopt, use, install, or set up the Agentic Development Framework in a project. This
 page is the procedure. Don't copy files from this repository by hand: the adoption fills the skeleton
 from verified facts about the project, stamps the version it came from, and lands as a draft pull
-request — the installer plugin's `/adopt` does all of that.
+request — the `aplyca-adf` plugin's `/aplyca-adf:adopt` does all of that.
 
 The project is the one the developer named, usually your session's folder. Before step 1, tell the
 developer what you'll do — install the plugin for this project only, then adopt the framework on a
@@ -13,26 +13,29 @@ branch, delivered as a draft pull request — and wait for their go-ahead.
 
 - **Not a git repository?** Offer `git init -b <default branch>` (ask for the name; suggest `main`).
   A new project with no code yet is fine: `/adopt` has a mode for it.
-- **Already adopted?** If `CLAUDE.md` has a `Skeleton source:` line, the task is an upgrade: follow
-  steps 2 and 3 with `/upgrade` in place of `/adopt`.
+- **Already adopted?** If `CLAUDE.md` has a `Skeleton source:` line, the framework is already here.
+  When `.claude/settings.json` enables `aplyca-adf@aplyca`, a developer joining the project has
+  nothing to install: they start a new session and accept the prompt to trust the folder. Ask
+  whether they want an upgrade instead; if so, follow steps 2 and 3 with `/upgrade` in place of
+  `/adopt`.
 - **The main checkout of a hub?** If `scripts/agent/worktree-new.sh` exists and
   `git rev-parse --git-dir` equals `git rev-parse --git-common-dir`, stop: the hub takes no edits. Ask
   the developer to start a session in a worktree and run this there.
 
 ## 2. Install the plugin for this project only
 
-Skip this step when `.claude/settings.json` already enables `aplyca-framework@aplyca`. Otherwise run,
+Skip this step when `.claude/settings.json` already enables `aplyca-adf@aplyca`. Otherwise run,
 from the project's root:
 
 ```bash
 claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
-claude plugin install aplyca-framework@aplyca --scope project
+claude plugin install aplyca-adf@aplyca --scope project
 ```
 
 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-framework/README.md#install)); don't run them.
+[README § Install](plugins/aplyca-adf/README.md#install)); don't run them.
 
 The install changes `.claude/settings.json`. Show the developer the diff and leave it uncommitted: the
 adoption's pull request carries it.
@@ -41,11 +44,11 @@ adoption's pull request carries it.
 
 The plugin's skills load when a session starts, so this session doesn't have `/adopt` yet. Either:
 
-- **Hand over:** tell the developer to start a new session in the project and run `/adopt`
-  (`/upgrade` for an adopted project).
+- **Hand over:** tell the developer to start a new session in the project and run
+  `/aplyca-adf:adopt` (`/aplyca-adf:upgrade` for an adopted project).
 - **Continue here:** find the marketplace's folder — the `installLocation` of `aplyca` in
   `claude plugin marketplace list --json` — then read
-  `plugins/aplyca-framework/skills/adopt/SKILL.md` (or `upgrade/SKILL.md`) inside it and follow it step
+  `plugins/aplyca-adf/skills/adopt/SKILL.md` (or `upgrade/SKILL.md`) inside it and follow it step
   by step. It is the same procedure `/adopt` runs.
 
 Its ground rules hold either way: every filled placeholder traces to a file you read, nothing is

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-All notable changes to the Agentic Development Framework. Versions are referenced by **commit SHA + date** — the framework does not use semver.
+All notable changes to the Agentic Development Framework. From v1.0.0, releases follow semantic versioning and are tagged `vX.Y.Z` ([decision 0017](docs/decisions/0017-semantic-versioning.md)); earlier releases are referenced by **commit SHA + date**.
 
 Adopting projects: see [`docs/UPGRADING.md`](docs/UPGRADING.md) for the procedure to pull these changes into a project that already adopted an earlier skeleton version.
 
@@ -11,6 +11,96 @@ For each entry, **Upgrade impact** classifies the change against the [three-buck
 
 ## Unreleased
 
+### One plugin, `aplyca-adf`, and semantic versioning — breaking
+
+([0016](docs/decisions/0016-packaged-install.md), [0017](docs/decisions/0017-semantic-versioning.md))
+
+The installer plugin `aplyca-framework` is renamed **`aplyca-adf`**. From the next release,
+releases follow semantic versioning and are tagged `vX.Y.Z`, starting at **v1.0.0**: the rename is
+the major change.
+
+#### Changed
+- **The plugin's name and its skills' names.** Its skills are `/aplyca-adf:adopt`,
+  `/aplyca-adf:upgrade`, and `/aplyca-adf:cost-report`, and the marketplace lists only `aplyca-adf`.
+  A project that turns on `aplyca-framework@aplyca` loses `/upgrade` until it switches.
+- **Versions.**
+  - A release is `vMAJOR.MINOR.PATCH`: MAJOR when an adopting team has to act, MINOR for additive or
+    opt-in capabilities, PATCH for fixes.
+  - It gets a `vX.Y.Z` tag, and the plugin's `"version"` matches. That version changes only in a
+    release pull request, and a static check holds the two equal.
+  - The `CLAUDE.md` stamp keeps the commit: `Skeleton source: v1.0.0 · <SHA> (<date>) · …`. Older
+    stamps still work.
+
+#### Upgrade impact
+- **Merge:** `CLAUDE.md`'s first line takes the new stamp format; `/aplyca-adf:upgrade` restamps it.
+- **Migration**, in each adopted project:
+  1. Install `aplyca-adf` with the install prompt.
+  2. Run `/aplyca-adf:upgrade`. It replaces `aplyca-framework@aplyca` with `aplyca-adf@aplyca` in the
+     committed settings.
+  3. Remove the old plugin: `claude plugin uninstall aplyca-framework@aplyca --scope project`.
+
+### A packaged install: the machinery from the pinned plugin
+
+([0016](docs/decisions/0016-packaged-install.md), amending [0009](docs/decisions/0009-optional-modules.md))
+
+A pilot's upgrade touched 82 files, mostly generic machinery that no project edits, and its team asked
+to use the framework like a package. A team that works in Claude Code only can now choose a
+**packaged** install. The committed install stays the default.
+
+#### Added
+- **The machinery in `aplyca-adf`:** the 20 core skills, the 8 agents, the 4 workflows, and the hook
+  scripts, wired through the plugin's own `hooks.json`.
+  - They're named under the plugin and refer to each other that way: `/aplyca-adf:triage`,
+    `@aplyca-adf:code-reviewer`.
+  - They're generated from `skeleton/.claude/` by `scripts/build-aplyca-adf.sh`, and a static check
+    fails when the two drift apart.
+- **They act only in a packaged project**, whose stamp says `install: packaged`. Committed projects
+  turn the plugin on too, for `/aplyca-adf:upgrade`. There the plugin's hooks stand down, so nothing
+  runs twice. Its skills and agents open with a step that hands over to the committed files, and the
+  pin keeps both copies at one release.
+- **Every project pins its release**, `"ref": "vX.Y.Z"` on the `aplyca` marketplace in its
+  `.claude/settings.json`, equal to the release in its stamp. `/aplyca-adf:upgrade` moves the pin and
+  the committed files together, from release to release. In a committed project the pin keeps the
+  plugin's copies at the same release as the committed files.
+- **The packaged install:**
+  - It commits only its own layer and its modules, about 40 fewer files.
+  - `CLAUDE.md` gets a note mapping the short names the docs use to the plugin's, and
+    `docs/getting-started/DEV-SETUP.md` lists the key commands by their full names.
+  - `docs/SETUP.md` § Packaged install covers the steps, and `docs/UPGRADING.md` covers upgrades.
+- **`/aplyca-adf:adopt` asks committed or packaged.** `/aplyca-adf:upgrade` moves a packaged project
+  from release to release by bumping the pin, skips the paths the plugin carries, and offers to switch
+  between the two installs. The switch is recorded as a PDR in the project, amending PDR-0001.
+
+#### Changed
+- **`.claude/hooks/_lib.sh`** reads `config.sh` from next to the scripts, as before, or else from the
+  project's `.claude/hooks/config.sh` (`CLAUDE_PROJECT_DIR`). A copy of the hooks that isn't the
+  project's own stands down unless the project is packaged. A committed install behaves the same.
+
+#### Upgrade impact
+- **Overwrite:** `.claude/hooks/_lib.sh`.
+- **To switch to packaged:** `/aplyca-adf:upgrade` offers it from v1.0.0 (`docs/UPGRADING.md`, "We use
+  the packaged install — or want to").
+
+### Joining an adopted project: open it and trust the folder
+
+A developer joining a project that uses the framework has nothing to install. The project's committed
+`.claude/settings.json` works like a package manifest: in the first session after they trust the
+folder, Claude Code fetches the marketplace at the pinned release and loads `aplyca-adf`. That was
+tested on a machine that had never installed the plugin. The project's own docs didn't say so.
+
+#### Changed
+- **`docs/getting-started/DEV-SETUP.md`**, the project's setup guide, says it: open a session, trust
+  the folder, and `/plugin` lists the plugin. Never install it at user scope.
+- **The install prompt** stops when the project already turns the plugin on, instead of sending a
+  joining developer to `/aplyca-adf:upgrade`. `ADOPT.md` asks before it treats "use the framework" in
+  an adopted project as an upgrade.
+- **`DEV-SETUP.md` is merge-required** in the upgrade taxonomy. It was unlisted, so upgrades left it
+  alone.
+
+#### Upgrade impact
+- **Merge:** `docs/getting-started/DEV-SETUP.md` — add the paragraph to § AI-assisted development;
+  `/aplyca-adf:upgrade` does it.
+
 ### `/cost-report` shows what Opus sessions would have cost on Sonnet
 
 A pilot's report showed every session on Opus, though the project's `"model"` setting said `sonnet`:

CLAUDE.md

@@ -18,7 +18,7 @@ The repo slug is `AgenticDevelopmentFramework` (renamed from `ai-dev-starter-kit
   - `skeleton/specs/` — `README.md` (the process) and `_templates/{spec,plan,tasks}.md`
   - `skeleton/docs/` — constitution, spec model, process (PDRs), reference, tracker integration, and documentation templates
 - `modules/` — optional additions (`github/`, `git-hooks/`, `clickup/`, `parallel-agents/`); each has a `MODULE.md` and a `files/` tree mirroring the target repo
-- `plugins/aplyca-framework/` — the Claude Code installer plugin (`/adopt`, `/upgrade`); contains no framework content
+- `plugins/aplyca-adf/` — the Claude Code plugin: the installer (`/aplyca-adf:adopt`, `:upgrade`, `:cost-report`, written by hand) and, for the packaged install (decisions 0016, 0017), the skeleton's skills, agents, workflows, and hook scripts — **generated** by `scripts/build-aplyca-adf.sh` into the paths its `.generated` file lists; never edit those by hand
 - `ADOPT.md` — the adoption procedure for AI agents, which the top of `README.md` points to; keep it in step with `/adopt`
 - `docs/` — framework guides (setup, upgrading, onboarding, catalogs, examples, scenarios) and `docs/decisions/` (why the framework works the way it does)
 - `evals/` — static checks, hook and module functional tests, dynamic fixtures
@@ -32,5 +32,6 @@ The repo slug is `AgenticDevelopmentFramework` (renamed from `ai-dev-starter-kit
 - Skill and agent frontmatter use only documented keys, hyphenated (`argument-hint`, `disable-model-invocation`, `user-invocable`) — unknown keys are silently ignored. Hooks use the nested `hooks` array and read the event from stdin
 - Relative links inside `skeleton/` must resolve inside an adopting repo — never link to framework-only docs from the skeleton
 - Every change to `skeleton/` or `modules/` carries a `CHANGELOG.md` entry with its **Upgrade impact** (overwrite / merge / additive, plus migration steps when needed); significant design changes get a record in `docs/decisions/`
+- After any change under `skeleton/.claude/`, run `scripts/build-aplyca-adf.sh` and commit `plugins/aplyca-adf/` with it — the static checks fail on drift. The plugin's `"version"` changes only in a release (decision 0017)
 - Run `./evals/run-evals.sh` before committing — structural checks plus functional tests of the hooks and module scripts; CI runs the same on every pull request
 - The repo is public — never include client, customer, or internal project names anywhere (files, examples, commit messages, PR descriptions); use the fictional newsletter feature from `docs/examples/` instead

CONTRIBUTING.md

@@ -1,14 +1,14 @@
 # Contributing to the Agentic Development Framework
 
-Thanks for helping improve the framework. This repository is not an application — it is a portable skeleton, optional modules, documentation, and the `aplyca-framework` Claude Code plugin. Its "code" is mostly prompts, rules, and templates that end up inside other teams' repositories, so a one-line change here changes how many AI agents behave. The guidelines below exist to keep those changes safe to adopt.
+Thanks for helping improve the framework. This repository is not an application — it is a portable skeleton, optional modules, documentation, and the `aplyca-adf` Claude Code plugin. Its "code" is mostly prompts, rules, and templates that end up inside other teams' repositories, so a one-line change here changes how many AI agents behave. The guidelines below exist to keep those changes safe to adopt.
 
 ## Ways to contribute
 
 - **Report a problem** — open an issue describing what you expected, what the AI or the template did instead, and which tool you used (Claude Code, Cursor, Copilot, Antigravity, …).
 - **Improve the skeleton** — clearer rules, better skill instructions, missing spec sections, hooks, tool-compatibility fixes.
 - **Improve a module** — or propose a new one in `modules/` for harness that depends on a Git host or a way of working.
 - **Add worked material** — new playbooks in `docs/scenarios/` or end-to-end examples in `docs/examples/`.
-- **Fix the plugin** — the `/adopt` and `/upgrade` skills in `plugins/aplyca-framework/`.
+- **Fix the plugin** — the `/adopt` and `/upgrade` skills in `plugins/aplyca-adf/`.
 
 For anything larger than a focused fix, open an issue first so we can agree on the direction before you invest the time.
 
@@ -28,14 +28,22 @@ For anything larger than a focused fix, open an issue first so we can agree on t
 1. Fork the repository and create a branch from `main` (`feat/…`, `fix/…`, `docs/…`, `chore/…`).
 2. Make one logical change per pull request.
 3. **Add a `CHANGELOG.md` entry** under `Unreleased`. Adopting teams upgrade by reading it, so classify every skeleton file you touched against the three-bucket taxonomy in [`docs/UPGRADING.md`](docs/UPGRADING.md): *Overwrite*, *Merge*, or *Additive*. Mark changes that don't land in adopted repos as framework-internal.
-4. **Bump the plugin version** in `plugins/aplyca-framework/.claude-plugin/plugin.json` if you changed anything under `plugins/`.
+4. **Bump the plugin version** in `plugins/aplyca-adf/.claude-plugin/plugin.json` if you changed anything under `plugins/`.
 5. Run the checks below.
 6. Open a pull request that explains what changed and *why*, and lists the checks you ran.
 
-**Cutting a release** (maintainers): when `Unreleased` holds changes adopting teams should take, rename
-it to `## <SHA> — <date> — <title>` with the SHA of the last commit it covers. Open it with the
-order to upgrade in when it spans several parts, and add an empty `Unreleased` above it. Adopting
-repositories stamp the commit they upgraded to, so the heading's SHA tells them which entries apply.
+**Cutting a release** (maintainers): when `Unreleased` holds changes adopting teams should take, pick
+the version by [decision 0017](docs/decisions/0017-semantic-versioning.md): MAJOR when a team has to
+act, MINOR for additive or opt-in capabilities, PATCH for fixes. In one pull request, rename
+`Unreleased` to `## vX.Y.Z — <date> — <title>`, open it with the order to upgrade in when it spans
+several parts, add an empty `Unreleased` above it, and set `"version"` in
+`plugins/aplyca-adf/.claude-plugin/plugin.json` to `X.Y.Z` (a static check holds the two equal). Once
+it merges, tag the merge commit `vX.Y.Z` and push the tag: packaged projects pin it, and without it
+they can't take the release.
+
+**The machinery in `plugins/aplyca-adf/` is generated** from `skeleton/.claude/` by
+`scripts/build-aplyca-adf.sh` — every path its `.generated` file lists. Never edit those; after any change under `skeleton/.claude/`, run the script and commit its output with
+the change. The static checks fail when the two drift apart.
 
 ## Checks
 
@@ -54,7 +62,7 @@ claude plugin validate .
 ```
 
 ```bash
-claude plugin validate plugins/aplyca-framework
+claude plugin validate plugins/aplyca-adf
 ```
 
 If you changed how a skill behaves (not just its structure), consider running the relevant dynamic fixture in [`evals/dynamic/`](evals/dynamic/README.md) and noting the result in your PR. Add a new eval only when a real regression surfaces — see [`evals/STRATEGY.md`](evals/STRATEGY.md).