Setup

---
name: setup
description: Use once, right after installing the addit-harness Claude Code plugin, to place the parts a plugin can't carry natively (CLAUDE.md, AGENTS.md, path-scoped rules/, references/, settings.json) into ~/.claude or the current project. Also use to re-sync after a plugin update, or to switch between global and project scope.
user-invocable: true
argument-hint: "[--scope global|project] [--link] [--plugins]"
---

# addit-harness setup

The `addit-harness` plugin ships `agents/` and `skills/` — those are already
live once the plugin is installed, nothing to do. This skill places the rest:
**`CLAUDE.md`, `AGENTS.md`, `rules/` (path-scoped language conventions),
`references/`, and `settings.json`** — none of which Claude Code plugins can
carry natively (no plugin-level memory file, no path-scoped auto-load rules,
no plugin-carried permissions/model).

## Choosing a scope — ask, don't silently default

`--scope` changes where files land in a way that's annoying to undo cleanly
(global touches every Claude Code session on the machine; project touches
just the current repo). Don't guess:

- If the user already passed `--scope` as an argument to this skill, use it
  as given — no need to ask.
- If they didn't, and the conversation doesn't already make the intent
  obvious (e.g. "just try it here" / "in this repo only" → project; "on my
  machine" or no project context at all → global), **ask** which they want
  before running anything. Offer `global` as the default recommendation
  since it is what most users want, but let them choose:
  - `global`: places everything under `~/.claude/` — applies to every Claude
    Code session on the machine.
  - `project`: places `CLAUDE.md`, `AGENTS.md`, `rules/`, `references/` bare
    at the current project root, and `settings.json` at
    `./.claude/settings.json` — matches Claude Code's own memory-file
    convention (project memory at root, project settings nested under
    `.claude/`) and only applies inside this one project.
- Mention while asking that the plugin itself can independently be scoped
  too (`/plugin install addit-harness@addit --scope local` keeps
  agents/skills confined to this repo as well) — see the README's *Install*
  section for both mechanisms together.

## What to run

Once the scope is settled, run the bundled script with the Bash tool:

```bash
bash "${CLAUDE_PLUGIN_ROOT}/skills/setup/scripts/setup.sh" --scope <global|project> [--link] [--plugins]
```

`--link` symlinks instead of copying, so edits to `rules/`/`settings.json`
track the plugin's own git checkout. Default is copy.

`--plugins` (opt-in) additionally runs `claude plugin marketplace add <source>`
for each `extraKnownMarketplaces` entry and `claude plugin install <id>` for
each `enabledPlugins` key set to `true`, read from the placed `settings.json`
(no hardcoded list; plugins you disabled are skipped). It needs the `claude`
CLI on `PATH` and skips with a message if it is missing. Whether Claude Code
installs `enabledPlugins` by itself on first start is unverified, so use this
flag when you want them installed now. If a nested install fails from inside a
session, run the printed `claude plugin ...` commands in a normal shell.

The script backs up anything it would overwrite to
`~/.claude/.install-backups/<stamp>/` (global) or
`.claude/.install-backups/<stamp>/` (project) and prints a summary of what it
placed and where.

`settings.json` is merged, not replaced: your `hooks`, `statusLine`, `env`
and other keys the template lacks survive, and `enabledPlugins` /
`extraKnownMarketplaces` / `env` are deep-merged with your existing values winning (a
plugin you disabled stays disabled; an `env` value you set is never overwritten). Keys the template owns (`model`,
`permissions`) are updated to the template's values, so a backup is taken
first. Re-running is idempotent. With `--link`, `settings.json` is symlinked
rather than merged.

For `--scope global`, it also retires any leftover unprefixed `agents/`
and `skills/` from a pre-plugin install (the pre-plugin copy installer, since removed,
used to copy those straight into `~/.claude/agents` and `~/.claude/skills`
unprefixed — the plugin now exposes the same content as
`addit-harness:<name>`, so the old copies are stale duplicates). A legacy
install predates the plugin, so its content has usually drifted from
whatever the plugin ships today — exact-match wouldn't catch most real
duplicates. Instead it compares line-level similarity: a name match at or
above 50% similar is treated as the same file at a different revision (backed
up, then removed — so even a wrongly-flagged heavy customization is
recoverable from the backup, never destroyed outright); anything less
similar is left in place and reported, since it's more likely a genuinely
unrelated file that happens to share the name.

## When to re-run

- After the plugin auto-updates (new `rules/`/`references/`/`settings.json`
  content), re-run with the same `--scope` to pick up the changes. You don't
  have to remember this yourself: the plugin ships a `SessionStart` hook
  (`hooks/check-setup-version.sh`) that hashes just the files this script
  copies (`CLAUDE.md`, `AGENTS.md`, `rules/`, `references/`,
  `settings.json`) and compares it against a marker this script writes on
  each run (`~/.claude/.addit-harness-setup-version` for global,
  `.claude/.addit-harness-setup-version` for project). It's deliberately
  content-based, not plugin-version-based: most releases only touch
  `agents/`/`skills/`/`hooks/`, which the plugin loader already serves live
  and need no re-sync — a version-only check would nag on every release
  regardless of whether it touched anything this skill actually copies. It
  also stays silent for a scope you've never run setup for — it only nags
  about a sync you've already opted into.
- To switch scope later (e.g. tried `--scope project`, now want it
  everywhere), re-run with `--scope global` — it's additive, doesn't remove
  the project-scoped files.