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

[mauricios]

What changed and why

Implements 0016, revised after review, and adds 0017. Breaking: the plugin aplyca-framework is renamed aplyca-adf, and the next release is v1.0.0.

One plugin, aplyca-adf (0016)

• The installer moves in: /aplyca-adf:adopt, /aplyca-adf:upgrade, and /aplyca-adf:cost-report, under plugins/aplyca-adf/skills/, moved with git mv.
• Next to them, for the packaged install: the 20 skills, 8 agents, 4 workflows, and hook scripts. They're generated from skeleton/.claude/ by scripts/build-aplyca-adf.sh, which rebuilds only the paths listed in .generated, and they're named under the plugin (/aplyca-adf:triage, @aplyca-adf:code-reviewer).
• The marketplace lists one plugin.
• In a committed project the copies step aside:
  • Hooks: _lib.sh makes a copy that isn't the project's own stand down unless CLAUDE.md's stamp says install: packaged. This is enforced in code, and tested: it acts in a packaged project, stands down in a committed one, and does nothing in a project without the framework.
  • Skills and agents open with "Step 0 — which copy": unless CLAUDE.md says "This project uses the packaged install", follow the committed file. In live tests, the agent skipped that step when both copies matched. So:
  • Every project pins its release: "ref": "vX.Y.Z" on the marketplace, equal to the stamp's release, committed projects included. The plugin's copies and the committed files are always one release, so a skill listed twice never runs a different version.
• Switching installs is a recorded decision: when /aplyca-adf:upgrade switches a project between committed and packaged, the same pull request writes a PDR in the project. It covers why, what changes for the team, how to switch back, and the deciders, adds the index row, and marks PDR-0001 as amended. Switching back to committed keeps aplyca-adf on and pinned.
• The rename: /aplyca-adf:upgrade replaces aplyca-framework@aplyca. The plugin README and the changelog give the uninstall commands.

Semantic versioning (0017)

• The rules: MAJOR when an adopting team has to act, MINOR for additive or opt-in capabilities, PATCH for fixes.
• Where it shows:
  • The changelog heading: ## vX.Y.Z — <date> — <title>.
  • The tag vX.Y.Z on the release PR's merge commit.
  • The plugin's "version", which changes only in a release. A static check holds it equal to the newest release.
  • The stamp, which keeps the commit for the diff: Skeleton source: v1.0.0 · <SHA> (<date>). Older stamps still work.
• Upgrades move from release to release.

Joining an adopted project needs no install

• The project's .claude/settings.json works like a package manifest. In the first session after a developer trusts the folder, Claude Code fetches the marketplace at the pinned release and loads aplyca-adf, because the marketplace lists it by a relative path.
• The project's own docs/getting-started/DEV-SETUP.md says so. It's now merge-required in the upgrade taxonomy; it was unlisted, so upgrades skipped it.
• The install prompt stops when the plugin's already on, instead of sending a joining developer to /aplyca-adf:upgrade. ADOPT.md asks before it treats an adopted project as an upgrade.
• A packaged project's DEV-SETUP.md lists the key commands by their full names, written by /aplyca-adf:adopt and by the install switch.

Where it's documented

• docs/SETUP.md: § Packaged install, and the stamp format.
• docs/UPGRADING.md: the versioning convention, and the packaged scenario.
• CONTRIBUTING.md: cutting a release, the generated paths.
• Both READMEs, ADOPT.md, the skills catalog, SECURITY.md, the repo's CLAUDE.md, and the changelog.

Upgrade impact

• Overwrite: .claude/hooks/_lib.sh.
• Merge: CLAUDE.md's first line, for the stamp format; docs/getting-started/DEV-SETUP.md, for the joining paragraph.
• Migration:
  1. Install aplyca-adf with the install prompt.
  2. Run /aplyca-adf:upgrade, which renames the setting and pins the release.
  3. Uninstall aplyca-framework.

How to verify

1. ./evals/run-evals.sh. New and changed checks:
   • the generated paths match the skeleton (a copy of the plugin is rebuilt and diffed);
   • the marketplace lists only aplyca-adf;
   • the version is semver and matches the newest release;
   • the hooks act only where they should;
   • the rename migration is in /aplyca-adf:upgrade;
   • joining needs no install: DEV-SETUP.md, the install prompt, the packaged names.
2. claude plugin validate plugins/aplyca-adf and claude plugin validate . both pass.

Verified / not verified

• Verified:
  • Static suites: 153, 75, 45, and 11 pass.
  • Live sessions with the generated plugin, about $1.20 in all:
    • Packaged project: the plugin's guard blocks --no-verify.
    • Committed project: only the project's own guard blocks, and the plugin's copy stands down.
    • Joining with no install: a fresh plugin cache, a folder marked trusted in a throwaway config, and only the committed settings pinned to this branch. Claude Code fetched the marketplace and loaded aplyca-adf 1.0.0 with all 27 commands; no install record was written.
    • The handover step: followed when it said to read the file; skipped twice when it relied on the visible note with identical copies. That's why the release pin carries the guarantee.
• Not verified:
  • A real v1.0.0 tag pinned by a project. The tag comes with the release.
  • A real /aplyca-adf:adopt or /aplyca-adf:upgrade in packaged mode, or migrating from aplyca-framework. The pilot is the test.
  • Claude Code's cloud sessions, which don't load the plugin.

Merge danger

Reversible: mostly. Reverting restores aplyca-framework, but projects that already switched would have to switch back.
Blast radius:

• Every adopted project that turns on aplyca-framework@aplyca: its teammates lose /upgrade until the project switches. Today that's the pilot, whose #221 isn't merged and can switch first.
• Committed projects: only the _lib.sh change, which behaves the same and is tested.

🤖 Generated with Claude Code