Aplyca · mauricios · Oct 2, 2026 · Oct 2, 2026 · Oct 2, 2026 · Oct 2, 2026
diff --git a/ADOPT.md b/ADOPT.md
@@ -0,0 +1,53 @@
+# Adopt the framework — for AI agents
+
+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.
+
+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
+branch, delivered as a draft pull request — and wait for their go-ahead.
+
+## 1. Check the project
+
+- **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`.
+- **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,
+from the project's root:
+
+```bash
+claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
+claude plugin install aplyca-framework@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.
+
+The install changes `.claude/settings.json`. Show the developer the diff and leave it uncommitted: the
+adoption's pull request carries it.
+
+## 3. Run the adoption
+
+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).
+- **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
+  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
+committed to the default branch (except a new repository's first commit, with the developer's yes),
+and nothing is pushed until the developer approves.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,51 @@ For each entry, **Upgrade impact** classifies the change against the [three-buck
 
 ## Unreleased
 
+### `/upgrade` offers the modules a project doesn't have
+
+`/upgrade` updated only the modules a project already had and never offered the others, so a project
+adopted before modules existed would never be offered the dispatcher hub (`parallel-agents`), the
+ClickUp integration, or the GitHub harness. It now lists the missing modules, recommends the ones
+the repository's facts support (the same rules as `/adopt`), and installs the chosen ones in the same
+upgrade pull request with their customize steps. Choosing `parallel-agents` moves the upgrade into a
+worktree of its own, so the main checkout starts as a clean hub (`aplyca-framework` 0.2.4).
+**Upgrade impact:** framework-internal; update the plugin.
+
+### The plugin installs per project, never for the whole machine
+
+The install docs (README, plugin README, `docs/SETUP.md`) installed the plugin at Claude Code's default
+`user` scope, which turns it on in every project on the machine. They now install it with
+`--scope project` from the project's folder — recorded in the committed `.claude/settings.json`, so
+the team is offered it and every worktree of a hub gets it — or `--scope local` to try it alone.
+Both READMEs open with an install prompt to paste into any Claude Code session — terminal, desktop
+app, or IDE: it runs the two commands, skips a plugin the project already declares, stops in a hub's
+main checkout, and reports a leftover user-scope copy. The plugin README adds the steps for the
+desktop app's Code tab (**+ → Plugins → Add plugin**, scope "this project"). `/adopt` commits
+that setting with the adoption and checks it; `/upgrade` offers to add it when the project doesn't
+have it. `docs/MCP-INTEGRATION.md` pointed MCP servers at `.claude/mcp.json` or a global file; it now
+uses the project's `.mcp.json`.
+**Upgrade impact:** merge `docs/MCP-INTEGRATION.md` (one line, § Wiring it into AI tools).
+**Migration:** if you installed the plugin at user scope, let `/upgrade` add the project setting; once
+every project you use it in has it, run `claude plugin uninstall aplyca-framework@aplyca --scope user`
+and `claude plugin marketplace remove aplyca --scope user`.
+
+### Adopt in one prompt — and in a new project
+
+A Claude Code session told "Adopt the Agentic Development Framework in this project: <repository URL>"
+had nothing to follow, so it could copy the skeleton by hand and skip the fact-checking, the version
+stamp, and the pull request. A new `ADOPT.md` at the repository root, pointed to from the top of the
+README, is the procedure for agents: confirm with the developer, check the project (new, already
+adopted, or a hub's main checkout), install the plugin with `--scope project`, then run `/adopt` — in
+a new session, or in the same one by following the skill's file from the marketplace folder.
+`/adopt` gains a mode for a new project with no code yet: it offers `git init` and the first commit,
+asks for the planned stack instead of reading it, marks those entries
+`<!-- planned: not in the repository yet -->`, records the stack as ADR-0001 (`proposed`), and
+delivers without a remote. `/init-project` is the step that replaces the planned entries once the
+first code lands. `/adopt` and `/upgrade` find the marketplace folder through
+`claude plugin marketplace list --json` instead of assuming its path.
+**Upgrade impact:** overwrite `.claude/skills/init-project/SKILL.md`; the rest is framework-internal —
+update the plugin.
+
 ### Test first in every lane; the hub enforced
 
 ([0014](docs/decisions/0014-test-first-in-every-lane.md); [0008](docs/decisions/0008-dispatcher-and-worker-worktrees.md), addendum)

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -19,6 +19,7 @@ The repo slug is `AgenticDevelopmentFramework` (renamed from `ai-dev-starter-kit
   - `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
+- `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
 - `.claude/` — configuration for working on **this framework repo** (not for target projects)

diff --git a/README.md b/README.md
@@ -1,5 +1,9 @@
 # Agentic Development Framework
 
+> **AI agents:** asked to adopt, use, or install this framework in a project? Follow
+> [ADOPT.md](ADOPT.md) (raw: `https://raw.githubusercontent.com/aplyca/AgenticDevelopmentFramework/main/ADOPT.md`)
+> — don't copy files from this repository by hand.
+
 A production-grade framework for professional **multi-perspective spec-driven, test-driven, docs-first AI-assisted development.** It ships as a portable project skeleton you drop into any codebase, optional modules for your Git host and ways of working, and an installer plugin for Claude Code. It includes an enforced multi-perspective spec model, specialized agents, workflow skills, multi-agent workflows, and guardrail hooks. Engineering standards and a team onboarding path are part of it too.
 
 The framework is built on three reinforcing disciplines:
@@ -34,29 +38,74 @@ Most of what's here was proven in real client projects first — some built on t
 
 ### With Claude Code — the installer plugin (recommended)
 
-1. **Install the plugin** — once per machine:
+**In one prompt.** Open a Claude Code session on the project — in the terminal, the desktop app, or an
+IDE — and say:
+
+```text
+Adopt the Agentic Development Framework in this project: https://github.com/aplyca/AgenticDevelopmentFramework
+```
+
+This README points the session to [ADOPT.md](ADOPT.md), the procedure for agents: check the project,
+install the plugin for this project only, and run the adoption below — in a new project too, before
+any code exists. Step by step:
+
+1. **Install the plugin in the project.** Paste this prompt into a Claude Code session opened on the
+   project — in the terminal, the desktop app, or an IDE:
+
+   <!-- install-prompt: keep identical in README.md and the plugin's README -->
+   ```text
+   Install the aplyca-framework plugin (Agentic Development Framework) for this project only — never
+   at user scope.
+
+   1. Check that this folder is the root of a git repository. If .claude/settings.json already enables
+      aplyca-framework@aplyca, say so and skip to step 6.
+   2. If scripts/agent/worktree-new.sh exists and this is the main checkout (git rev-parse --git-dir
+      equals git rev-parse --git-common-dir), stop: the hub takes no edits. Tell me to run this from a
+      worktree.
+   3. From this folder, run:
+      claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
+      claude plugin install aplyca-framework@aplyca --scope project
+   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
+      that copy. Don't run them.
+   6. Tell me to start a new session here, then run /upgrade if CLAUDE.md has a "Skeleton source:"
+      line, otherwise /adopt.
+   ```
+
+   Or run the two commands yourself, from the project's folder:
 
    ```bash
-   claude plugin marketplace add aplyca/AgenticDevelopmentFramework
-   claude plugin install aplyca-framework@aplyca
+   cd your-project
+   claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
+   claude plugin install aplyca-framework@aplyca --scope project
    ```
 
+   Both commands 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`).
+   In the desktop app's Code tab, add the marketplace the same way, then install from
+   **+ → Plugins → Add plugin** with the scope set to this project
+   ([details](plugins/aplyca-framework/README.md#in-the-desktop-app)).
+
 2. **Run `/adopt`** in the project. It inspects the repository (stack, commands, branching model,
    tracker, Git host) and asks which [optional modules](modules/README.md) you want. Then it copies the
    skeleton, fills the placeholders from verified repository facts only, and configures the guardrail
    hooks (`.claude/hooks/config.sh`). It records the adoption as a process decision (PDR-0001), stamps
    the baseline version at the top of `CLAUDE.md`, verifies the hooks and the `@AGENTS.md` import, and
-   prepares a **draft pull request** on its own branch. It never commits to your default branch.
+   prepares a **draft pull request** on its own branch — the plugin setting the install wrote goes
+   in with it. It never commits to your default branch.
 3. **Finish what only the team knows** in that pull request: the remaining `[PLACEHOLDER]`s, the
    constitution's principles, the sensitive areas (`AGENTS.md` and `CAREFUL_GLOBS`), and the
    stakeholder-update settings in `docs/TRACKER-INTEGRATION.md`
    (live site, previews, CMS entry links, task statuses). With the `clickup` module, each developer
    signs in once through `/mcp`. Then review and merge the pull request like any change.
-4. **Optional — the whole team:** let `/adopt` register the marketplace in the project's
-   `.claude/settings.json`, so every teammate is offered the plugin (and `/upgrade`) when they trust
-   the folder.
-5. **Add a module later:** run `/adopt` again in the adopted repository. It detects the adoption and
-   offers the modules you don't have yet.
+4. **A new project with no code yet?** `/adopt` asks for the planned stack instead of reading it,
+   records it as the first architecture decision, and marks those entries as planned. Run
+   `/init-project` once the first code lands, to replace them with verified facts.
+5. **Add a module later:** `/upgrade` offers the modules you don't have yet, and so does running
+   `/adopt` again in the adopted repository.
 
 The plugin contains **no framework content** — adopted repositories get plain committed files that
 every AI tool can read, with or without the plugin.
@@ -81,7 +130,7 @@ The `3eb7777` release (2026-10-01) fixes defects that affect every adopted repos
 the order to upgrade in from an older baseline; if your settings pin a model ID, switch it to the
 `sonnet` alias.
 
-1. **Update the plugin** — then restart Claude Code:
+1. **Update the plugin** from the project's folder — then restart Claude Code:
 
    ```bash
    claude plugin marketplace update aplyca
@@ -91,11 +140,16 @@ the order to upgrade in from an older baseline; if your settings pin a model ID,
 2. **Run `/upgrade`** in the adopted project. It reads the baseline stamp
    (`<!-- Skeleton source: <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
-   CHANGELOG migration steps, and shows you the plan before changing anything. Then it updates the
-   files — your project-specific content stays — re-stamps, and prepares a draft pull request.
+   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.
 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.
 
+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-framework/README.md#install)).
+
 By hand, or to cherry-pick one improvement: [docs/UPGRADING.md](docs/UPGRADING.md).
 
 ## How it works

diff --git a/docs/SETUP.md b/docs/SETUP.md
@@ -2,16 +2,32 @@
 
 How to adopt the framework in a repository by hand. With Claude Code, the installer plugin does all of
 this for you — `/adopt` inspects the repository, copies the skeleton and the modules you choose, fills
-the placeholders from verified facts, configures the hooks, and opens a draft pull request:
+the placeholders from verified facts, configures the hooks, and opens a draft pull request. Install it
+with [the install prompt](../README.md#with-claude-code--the-installer-plugin-recommended) in any Claude
+Code session, or with these commands:
 
 ```bash
-claude plugin marketplace add aplyca/AgenticDevelopmentFramework
-claude plugin install aplyca-framework@aplyca
+cd your-project
+claude plugin marketplace add aplyca/AgenticDevelopmentFramework --scope project
+claude plugin install aplyca-framework@aplyca --scope project
 # then, in the repository:  /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
+`--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-framework/README.md#in-the-desktop-app).
+
 The manual path below is the same procedure, step by step.
 
+**A new project with no code yet:** create the repository and one first commit holding what's there
+(`git init -b main`, then `git add -A && git commit -m "chore: initial commit"`, with `--allow-empty`
+for an empty folder), and adopt on a branch as below. Where a
+step asks for facts, write the planned ones and mark each `<!-- planned: not in the repository yet -->`;
+record the stack as ADR-0001 (`docs/architecture/decisions/`, status `proposed`). Once the first code
+lands, run `/init-project` to replace the planned entries with verified facts.
+
 ## 1. Copy the skeleton (on a branch)
 
 ```bash
@@ -147,8 +163,9 @@ Open the pull request as a draft; merge after review like any other change.
 
 ## Updating
 
-Update the plugin, restart Claude Code, then run `/upgrade` in the adopted repository — it plans the
-update from the baseline stamp, keeps your customizations, and prepares a draft pull request:
+Update the plugin from the adopted repository's folder, restart Claude Code, then run `/upgrade` there —
+it plans the update from the baseline stamp, keeps your customizations, and prepares a draft pull
+request:
 
 ```bash
 claude plugin marketplace update aplyca

diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md
@@ -233,6 +233,17 @@ Then decide how far to go: the spec-folder workflow (new skills, templates, `spe
 main benefit. Existing single-file specs stay as they are; new work uses folders, and a legacy spec
 moves into a folder the next time it changes.
 
+### "We adopted before the modules existed"
+
+Your stamp has no `modules:` part, so nothing optional was installed. `/upgrade` lists the modules
+you don't have and recommends the ones your repository's facts support — `parallel-agents` when
+several agent sessions may work at once (each task gets its own worktree, branch, pull request, and
+session; the main checkout only dispatches), `clickup` when requirements arrive as ClickUp tasks,
+`github` on GitHub, `git-hooks` for local gates. The ones you choose join the same upgrade pull
+request, with their customize steps. Choosing `parallel-agents` moves the upgrade itself into a
+worktree, so the main checkout starts as a clean hub. By hand: `cp -R modules/<name>/files/.` (no
+overwrite) and follow its `MODULE.md`.
+
 ### "I just want one new skill" (e.g. `/triage`)
 
 You don't need a full upgrade. Cherry-pick the skill directory: