feat: adopt in one prompt and in new projects; per-project plugin; /upgrade offers modules

[mauricios]

What changed and why

Adopted projects get the framework's workflow in two ways:

• The skeleton: /adopt copies it, and /upgrade keeps it current.
• The optional modules: the dispatcher hub (parallel-agents), ClickUp, the GitHub harness, and local git hooks.

/upgrade updated only the modules a project already had. It never offered the rest, so a project adopted before modules existed would never be offered them. The marketing-site pilot is exactly that case: baseline 4c6d87e, no modules: in its stamp.

/upgrade now:

• Offers the missing modules. It lists the modules a project doesn't have and recommends the ones the repository's facts support, using the same rules as /adopt:
  • parallel-agents whenever several agent sessions may work at once;
  • clickup when requirements arrive as ClickUp tasks;
  • github on GitHub;
  • git-hooks for local gates.
• Installs the chosen ones in the same upgrade PR, as additive files plus each module's customize steps. It runs each module's own check and lists the new modules in the stamp.
• Moves the whole upgrade into a worktree when parallel-agents is chosen, created with plain git since the module's script isn't there yet. Otherwise the protect-hub hook would start stopping edits in the main checkout halfway through. This way the main checkout starts as a clean hub.

Modules are offered, never imposed. Plugin 0.2.4.

Docs: the plugin README, the root README's update steps, and a new docs/UPGRADING.md scenario, "We adopted before the modules existed".

The plugin installs per project, never for the whole machine

Claude Code's claude plugin marketplace add and claude plugin install default to user scope, which turns the plugin on in every project on the machine. The docs used that default. Now:

• Every install instruction passes --scope project from the project's folder (README, plugin README, docs/SETUP.md). The setting lands in the committed .claude/settings.json: the team is offered the plugin, and every worktree of a hub gets it. --scope local stays available to try it alone.

• /adopt commits that setting with the adoption, adds it (when asked) if a user- or local-scope install left it out, and checks it in Step 6.

• /upgrade offers to add the setting when a project doesn't have it — the case for projects adopted with the old instructions — and the PR body gives the commands that remove the user-scope copy.

• A static check (check_install_scope) fails on any install command without --scope project or --scope local.

• skeleton/docs/MCP-INTEGRATION.md pointed MCP servers at .claude/mcp.json or a global ~/.claude/mcp.json; it now uses the project's .mcp.json.

• An install prompt opens both READMEs, to paste into any Claude Code session on the project: terminal, desktop app, or IDE. It:

  • runs the two --scope project commands;
  • skips a plugin the project already declares;
  • stops in a hub's main checkout;
  • shows the .claude/settings.json diff without committing it, since /adopt or /upgrade carries it;
  • reports a leftover user-scope copy without removing it.

  A static check (check_install_prompt) keeps the two copies identical. The commands stay as the manual alternative.

• The desktop app: the plugin README gets a § In the desktop app. Add the marketplace from a terminal, then in the Code tab click + → Plugins → Add plugin and choose "this project". It also notes that plugins don't load in WSL sessions, and that cloud sessions don't install plugins declared in the repository's settings.

• Correction: the hub note said only project scope reaches worktrees. Since Claude Code 2.1.211, worktrees read the main checkout's .claude/settings.local.json on macOS and Linux, though not on Windows. Project scope stays the default because it reaches every platform and every teammate.

Claude Code still keeps the downloaded plugin files in its cache under the home folder; the scope decides where the plugin is turned on.

Adopt in one prompt — and in a new project

A session told "Adopt the Agentic Development Framework in this project: " had nothing to follow. It could copy the skeleton by hand and skip the fact-checking, the version stamp, and the pull request.

• ADOPT.md at the repository root is the procedure for agents. The top of the README points to it, with the raw URL. The procedure:
  1. Confirm the plan with the developer.
  2. Check the project: new, already adopted (then /upgrade), or a hub's main checkout (then stop).
  3. Install the plugin with --scope project.
  4. Run /adopt, either in a new session or in the same one by following the skill's file from the marketplace folder, so no restart is needed.
• The README opens the install section with that one-line prompt, then the step-by-step path.
• /adopt has a new-project mode for a repository with no code yet:
  • it offers git init and a first commit, the one exception to "never commit to the default branch";
  • it asks for the planned stack in one round and marks those entries <!-- planned: not in the repository yet -->;
  • it records the stack as ADR-0001 with status proposed;
  • globs point at planned paths or stay empty, and commands that can't run yet are a GAP, not a failure;
  • it delivers without a remote: commit on the branch and show the PR body;
  • /init-project replaces the planned entries once the first code lands; its description and body now say so.
• Finding the marketplace folder: /adopt and /upgrade now use claude plugin marketplace list --json (installLocation) instead of assuming ~/.claude/plugins/marketplaces/<name>/.
• docs/SETUP.md has a short new-project paragraph. The repo's CLAUDE.md lists ADOPT.md.
• Checks: the practices check covers the new-project mode, ADOPT.md's project scope, and the README pointer. check_install_scope now also scans ADOPT.md.

Session evals for adoption

There's a new adopt suite for run-session-evals.sh, built on a new repository with no commits. Report: evals/dynamic/reports/2026-10-01-adopt.md, about $2.10 over two runs.

• one-line-prompt: only the framework's address, with no plugin and no claude commands allowed. Every session that opened the README followed its pointer to ADOPT.md, laid out the --scope project plan, noticed the project is new, and asked before changing anything. That held for Sonnet in both runs and Opus in run 1. In run 2, Opus, given a local folder, opened the adopt skill directly and skipped ADOPT.md's install step, though it stayed safe. The URL path, where the README is the only way in, can only run once this merges.
• new-project: /adopt loaded from this checkout with --plugin-dir, with its questions answered in a follow-up turn.
  • Run 2 met every end-state invariant: one commit on main; the adoption stamped on its own branch; planned entries marked; quick-reference commands left as TODO(team); ADR-0001 proposed, with the agent's alternatives labeled as its own; verification reporting "no code yet" as a GAP.
  • It took 26 turns and cost $1.07.
• Fixed from the runs:
  • /adopt made two commits on main. The wording now says exactly one, after a git status check for secrets.
  • With no remote, /adopt offered to draft the PR body. It now shows the body, with the steps that follow.
  • Headless sessions refuse bulk copies, so adopt sessions run in bypassPermissions mode on throwaway copies of the project and of the framework. Deny rules, which hold in every mode, cover claude commands, git push, and edits under the home folder.
• Runner additions: a suite's own project.sh, inspect.sh for the end state, ## Follow-up turns, and --source.

Upgrade impact

• /upgrade and /adopt: framework-internal; update the plugin.
• docs/MCP-INTEGRATION.md: merge (one line).
• .claude/skills/init-project/SKILL.md: overwrite.
• Migration for a user-scope install: let /upgrade add the project setting; once every project that uses the plugin has it, run claude plugin uninstall aplyca-framework@aplyca --scope user and claude plugin marketplace remove aplyca --scope user.

How to verify

1. Run ./evals/run-evals.sh. The practices check covers the module offer; check_install_scope covers the install commands (it flags both lines of the previous README); check_install_prompt fails when the two prompt copies differ.
2. Read plugins/aplyca-framework/skills/upgrade/SKILL.md Steps 2–6, /adopt § A new project and Step 5, and ADOPT.md.

Verified / not verified

• Verified: static suites 131, 61, 43, and 9 pass; the practices check fails without ADOPT.md. check_install_scope fails on the previous README's install commands; check_install_prompt fails when one copy is edited.
• Checked against the Claude Code docs (desktop, plugin install and loading, settings, worktrees): desktop scope choice, settings shared with the CLI, project-scope plugins in worktrees (2.1.200+), local settings at the main checkout (2.1.211+, not Windows).
• Not verified:
  • A real /upgrade run. The marketing-site pilot is that test.
  • The one-line prompt from the GitHub address: the session evals used a checkout, since ADOPT.md isn't on main yet. Re-run --suite adopt --cases one-line-prompt after the merge.
  • A project-scope install, from the prompt, the terminal, or the desktop app. The --scope options come from the CLI's help and the docs; I didn't run one, because it would change this machine's plugin configuration. The pilot is the first real install.

🤖 Generated with Claude Code