diff --git a/CHANGELOG.md b/CHANGELOG.md index ee38e8a..3ccdddd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,30 @@ For each entry, **Upgrade impact** classifies the change against the [three-buck ## Unreleased +## 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 +asks anything of an adopted team. Everything since v1.0.6: the plugin's hooks checked in real sessions +([#29](https://github.com/Aplyca/AgenticDevelopmentFramework/pull/29)), evals for adopting on the +packaged install and switching to it, and the `/upgrade` stamp fix they found +([#30](https://github.com/Aplyca/AgenticDevelopmentFramework/pull/30)), the packaged install as the +default ([#31](https://github.com/Aplyca/AgenticDevelopmentFramework/pull/31), decision 0018), and +`/adopt` taking the framework at the release it pins. + +**Upgrading from v1.0.x:** `/aplyca-adf:upgrade` moves the pin to `v1.1.0`; nothing else changes in +the project. For a committed project whose team works in Claude Code only, it recommends the switch to +the packaged install. A baseline older than v1.0.0 takes v1.0.0's order to upgrade in first. + +### `/adopt` takes the framework at the release it pins + +`/aplyca-adf:adopt` copied the skeleton from wherever the framework source was — a clone of the +default branch, or a checkout — while pinning the plugin to the newest release tag, so a project's +committed files could be newer than its pinned plugin. The packaged eval found it; the two were +identical then. It now takes the framework at the newest release tag (a shallow clone of the tag, or +a worktree of a local checkout) and stamps that tag's commit. `docs/SETUP.md`'s manual copy says the +same. +**Upgrade impact:** framework-internal — adoptions only. + ### The packaged install is the default ([0018](docs/decisions/0018-packaged-by-default.md), amending [0016](docs/decisions/0016-packaged-install.md)) diff --git a/README.md b/README.md index 8c0d330..3cb4f55 100644 --- a/README.md +++ b/README.md @@ -139,12 +139,12 @@ hooks, stamp the baseline, and verify. 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.6** (2026-10-04), is a patch for the Claude Directory. **v1.0.0** -(2026-10-02) renamed 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. +[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.1.0** (2026-10-04), makes the packaged install the default for new projects. +**v1.0.0** (2026-10-02) renamed 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 diff --git a/docs/SETUP.md b/docs/SETUP.md index 0eeb70a..3b5104c 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -36,6 +36,10 @@ lands, run `/init-project` to replace the planned entries with verified facts. ## 1. Copy the skeleton (on a branch) +Copy from the newest release, which the project will pin: `git ls-remote --tags +https://github.com/aplyca/AgenticDevelopmentFramework 'v*'` lists them, and +`git clone --depth 1 --branch v https://github.com/aplyca/AgenticDevelopmentFramework` gets one. + ```bash cd your-project git switch -c docs/agentic-adoption diff --git a/evals/dynamic/reports/2026-10-04-packaged-paths.md b/evals/dynamic/reports/2026-10-04-packaged-paths.md index 14960ab..cf00219 100644 --- a/evals/dynamic/reports/2026-10-04-packaged-paths.md +++ b/evals/dynamic/reports/2026-10-04-packaged-paths.md @@ -54,3 +54,14 @@ each end state with `check-packaged.sh`, and each transcript was read against it plugin. Adopting from the release tag would close it. - Both sessions found the framework through the runner's `--add-dir` copy of the checkout, a development setup. A real install finds it through the marketplace or a clone. + +## Run 3 — `/adopt` taking the framework at the release it pins + +The open finding above, fixed for v1.1.0: `/adopt` now finds the newest release tag and takes the +framework at that tag — a shallow clone of the tag, or a worktree of a local checkout — and stamps +that tag's commit. `packaged` again on Sonnet: **8 of 8**, $1.30. The session set the framework up at +`v1.0.6` in a scratch worktree outside the project and stamped `ab56cb6`; with the new default, it +recommended packaged first, and committed for teams on other AI tools or cloud sessions. Its +`git ls-remote` ran in one command with `claude plugin marketplace list`, which the runner's deny rule +for `claude` commands refused as a whole — an artifact of the eval — so it took the newest tag from +the local checkout, the same release. diff --git a/evals/static/check-skills.sh b/evals/static/check-skills.sh index 1324c7b..b668c34 100755 --- a/evals/static/check-skills.sh +++ b/evals/static/check-skills.sh @@ -619,6 +619,7 @@ check_practices() { file_contains "$REPO_ROOT/plugins/aplyca-adf/skills/upgrade/SKILL.md" "don't follow into the worktree" || missing+=("/upgrade: carries uncommitted changes into the hub's worktree") file_contains "$REPO_ROOT/plugins/aplyca-adf/skills/adopt/SKILL.md" 'Ask how to install' || missing+=("/adopt: committed or packaged (0016)") file_contains "$REPO_ROOT/plugins/aplyca-adf/skills/adopt/SKILL.md" 'Packaged\*\* — the default' || missing+=("/adopt: packaged is the default (0018)") + file_contains "$REPO_ROOT/plugins/aplyca-adf/skills/adopt/SKILL.md" 'Adopt from a release' || missing+=("/adopt: takes the framework at the release it pins") file_contains "$REPO_ROOT/plugins/aplyca-adf/skills/upgrade/SKILL.md" "sort=-v:refname" || missing+=("/upgrade: moves a packaged project to the newest release tag") file_contains "$REPO_ROOT/plugins/aplyca-adf/skills/upgrade/SKILL.md" 'aplyca-framework@aplyca' || missing+=("/upgrade: migrates the plugin's old name") file_contains "$REPO_ROOT/plugins/aplyca-adf/skills/upgrade/SKILL.md" 'Record the switch' || missing+=("/upgrade: records an install switch as a PDR") diff --git a/plugins/aplyca-adf/.claude-plugin/plugin.json b/plugins/aplyca-adf/.claude-plugin/plugin.json index c2b8188..0c295b6 100644 --- a/plugins/aplyca-adf/.claude-plugin/plugin.json +++ b/plugins/aplyca-adf/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "aplyca-adf", "description": "The Agentic Development Framework for Claude Code. /adopt bootstraps a repository — skeleton, optional modules, guardrail hooks, verified facts — committed or packaged; /upgrade moves an adopted repository to a newer release; /cost-report shows what agent sessions cost, from local transcripts. In a packaged project it also carries the framework's skills, agents, workflows, and hooks, pinned to a release; in a committed project those step aside for the committed copies.", - "version": "1.0.6", + "version": "1.1.0", "author": { "name": "Aplyca", "email": "dev@aplyca.com" diff --git a/plugins/aplyca-adf/README.md b/plugins/aplyca-adf/README.md index d16ae77..2858dfd 100644 --- a/plugins/aplyca-adf/README.md +++ b/plugins/aplyca-adf/README.md @@ -143,7 +143,7 @@ the plugin by a relative path. A machine where nobody trusts the folder — CI { "extraKnownMarketplaces": { "aplyca": { - "source": { "source": "github", "repo": "aplyca/AgenticDevelopmentFramework", "ref": "v1.0.6" } + "source": { "source": "github", "repo": "aplyca/AgenticDevelopmentFramework", "ref": "v1.1.0" } } }, "enabledPlugins": { "aplyca-adf@aplyca": true } diff --git a/plugins/aplyca-adf/skills/adopt/SKILL.md b/plugins/aplyca-adf/skills/adopt/SKILL.md index e920d62..4f1d441 100644 --- a/plugins/aplyca-adf/skills/adopt/SKILL.md +++ b/plugins/aplyca-adf/skills/adopt/SKILL.md @@ -25,21 +25,25 @@ read the source doc (locations in step 1). - **Client repositories:** confirm before pushing anything. If committing AI config isn't appropriate for the client, offer the local-only fallback (`.git/info/exclude`, and the plugin at `--scope local`). -## Step 1 — Locate the framework source +## Step 1 — Locate the framework source, at the newest release -Resolve the framework root, in order: +Adopt from a release, never from whatever commit a checkout is at: the project pins that release +(Step 5), and its committed files and the plugin's copies have to be the same release (decision 0016). -1. The marketplace checkout: the `installLocation` of the marketplace (usually `aplyca`) in - `claude plugin marketplace list --json` — by default `~/.claude/plugins/marketplaces/aplyca/`, or - the framework repository itself when the marketplace was added from a local checkout. Installed - plugins run from a version cache, never from the repository. Run - `claude plugin marketplace update ` first. -2. Otherwise clone: `git clone --depth 1 https://github.com/aplyca/AgenticDevelopmentFramework`. +1. **The newest release:** `git ls-remote --tags https://github.com/aplyca/AgenticDevelopmentFramework 'v*'` + — the highest `vX.Y.Z`, ignoring the `^{}` lines. +2. **The framework at that tag**, as ``, in a scratch folder outside the target: + - from a local checkout of the framework repository that has the tag — the marketplace's + `installLocation` in `claude plugin marketplace list --json`, when the marketplace was added from + one: `git -C worktree add --detach `; + - otherwise: `git clone --depth 1 --branch https://github.com/aplyca/AgenticDevelopmentFramework `. + + Installed plugins run from a version cache, never from the repository. You need `/skeleton/`, `/modules/`, and `/docs/`. -Record the source release, SHA, and date: `git -C describe --tags --abbrev=0 --match 'v*'` -(the newest release at or before the source; none before v1.0.0) and -`git -C log -1 --format='%h (%ad)' --date=short`. +Record the release (the tag), its commit (`git -C rev-parse --short HEAD`), and the +commit's date (`git -C log -1 --format=%ad --date=short`). With no release tag yet, +use the default branch's head and say so. **Already adopted?** If the target's `CLAUDE.md` has a `Skeleton source:` line, don't re-adopt: offer to install modules (steps 3–4 for the chosen modules only, then update the `modules:` list in the @@ -175,9 +179,9 @@ Present the table before going further. Wrong facts here poison every file downs - Top of `CLAUDE.md`: `` - Without it, `/upgrade` has no baseline to diff against. Packaged: the release is the pinned tag and - the SHA its commit (`git -C rev-parse --short '^{commit}'`), and `· install: packaged` follows the modules — it's what turns the plugin's - skills, agents, and hooks on in this project. + The release, its commit, and the date are the ones Step 1 recorded. Without the stamp, `/upgrade` has + no baseline to diff against. Packaged: `· install: packaged` follows the modules — it's what turns + the plugin's skills, agents, and hooks on in this project. - Write **`docs/process/0001-adopt-ai-assisted-workflow.md`** from the PDR template: why the team is adopting, what it adds (files, gates, modules, and the install — committed or packaged, and why), the costs (docs to keep fresh, more tokens