setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# /memory-kit:setup — adopt the kit in an existing repository

The plugin ships behaviour; the repository owns the state. This skill creates that state —
**always asking before the first write**, and never touching files the repo already has.

Running without a user who can answer (a headless or `-p` run)? Then "offer" means **skip and
report**: take the documented default where one exists, install nothing that the skill marks as
opt-in, and finish with a list of what was deliberately not installed and what question is still
open. Never invent a preference on the user's behalf and never present a skipped step as done.

## Step 0 — look before you write

Report in two lines what already exists: `.claude/memory/MEMORY.md`, `context/handoffs/`,
`knowledge/`, `projects/`, an existing documentation home (`docs/`, `doc/`, `documentation/`),
`.claude/settings.json`, `.gitignore`, and whether this repo already holds work of its own —
code, or documents other than a bare README (a real project) — or is effectively empty (a fresh
memory workspace). Being a git repo decides nothing; content does. Everything after this is a proposal the user
confirms once, not a sequence of prompts.

## Step 1 — the shared memory layers

These four are shared across every project in the repo. Create only what is missing, copying
from `${CLAUDE_PLUGIN_ROOT}/templates/`:

| Path | From | Purpose |
|---|---|---|
| `.claude/memory/MEMORY.md` | `templates/MEMORY-TEMPLATE.md` | the hot cache the hook injects every session |
| `context/handoffs/HANDOFF-TEMPLATE.md` | `templates/HANDOFF-TEMPLATE.md` | the per-session note format |
| `knowledge/index.md` | `templates/workspace/knowledge-index.md` | the catalog of deep memory |
| `knowledge/concepts/.gitkeep` | — | where promoted patterns land |
| `.claude/state/.gitkeep` | — | hook bookkeeping (gitignored) |

## Step 1b — the project layer (`projects/<name>/`)

The four layers above hold MEMORY. The work's own documents — tasks, specs, research, decisions,
QA — belong to a PROJECT, and the kit is multi-project by design: one folder per client or
product, so that a decision ledger, a findings registry and a QA protocol each count and describe
exactly ONE thing. **This applies to a single-product code repository too** — it simply has one
project folder, named after the product. (Earlier versions told you to skip `projects/` in a code
repo. That left specs, backlogs and research with no home, and they scattered into the repo root.)

Ask for the name(s), then create per project — nothing more:

| Path | From | Purpose |
|---|---|---|
| `projects/<name>/README.md` | `templates/workspace/project/README-TEMPLATE.md` | what it is + **the map of where its documents live** |
| `projects/<name>/BACKLOG.md` | `templates/workspace/project/BACKLOG-TEMPLATE.md` | tasks and their real status |

The rest of the project layer — `plans/`, `research/`, `decisions-log.md`, `review-findings.md`,
`qa/`, `materials/` — is **created on first use by whoever produces the artifact**, never
scaffolded upfront. An empty folder is not a layer; it is a promise nobody kept. `plans/` appears
with the first spec, written from `templates/workspace/project/SPEC-TEMPLATE.md`; an `executor`
told to build past a missing decision may add one `plans/<date>-<slug>-assumed.md` from
`ASSUMED-SPEC-TEMPLATE.md`, and nothing else in that folder is an agent's to create.

**If the repository already has a documentation home**, do NOT move anything and do NOT propose a
migration. Fill the README's map table with the paths it already uses, written from the repo root
with a leading `/` so they can't be misread as project-relative. That table is the SSOT for "where
does a plan go" — the defaults are a default, not a law, and a repo's own layout outranks them.

The test for "already has one" is **committed content, not a folder**: a `docs/` (or `doc/`,
`documentation/`) holding at least one markdown file that git tracks and that a human wrote. An
empty directory, or one holding only scaffolding you cannot attribute to anyone, does not count —
use the defaults. When the call is genuinely close, ASK; it decides where every future plan gets
looked for, and it is cheap to ask once and expensive to split a repo's documents across two homes.

Brand-new empty workspace, first time with the kit? Also offer the `experiments/` sandbox from
`templates/workspace/`, and — **only when there is exactly one project** —
`templates/workspace/ONBOARDING-BACKLOG.md` as its backlog: five guided tasks for day one. With
two or more real projects on day one, skip it (a tutorial mixed into a client's backlog is noise,
and a third fake project to hold it is worse) and offer `/memory-kit:tour` instead.

## Step 2 — the auto-memory decision (ask, do not assume)

Claude Code has its own auto memory (`~/.claude/projects/<project>/memory/`, loaded every
session, written by Claude without asking). Running it alongside the kit means two writers and
two truths. Put the choice to the user in one question:

- **Kit owns memory (default).** Write `"autoMemoryEnabled": false` into `.claude/settings.json`
  (for CI or a headless run, `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` does the same). You get dated
  entries, human-confirmed promotion, handoffs, and one file the user can read.
- **Both, side by side.** Leave auto memory on. It keeps writing its own index under
  `~/.claude/projects/<project>/memory/` (machine-local, outside the repo); the kit keeps the
  repo files and the ritual. Two writers, two truths — say so, and make the kit's `MEMORY.md`
  the one that counts for handoffs and promotion.

Do NOT point `autoMemoryDirectory` at the kit's `.claude/memory`: the setting only accepts an
absolute path or one starting with `~/` (so it cannot be committed portably), and Claude Code
would rewrite the kit's `MEMORY.md` in its own index format, overwriting the dated cache.

Whichever is chosen, say plainly which system now owns the file.

## Step 3 — permission rails (v2)

**`/memory-kit:setup rails`** (the argument `rails`, e.g. from the SessionStart «Rails:» line) runs
THIS step alone on an already adopted repo: skip Steps 0–2 and 4–6, build the proposal below, show
the diff of `.claude/settings.json`, merge on a yes and write `.claude/state/rails-v2`; on a no,
write `.claude/state/rails-declined`. Either file silences the nudge. A full setup writes the same
marker after this step. Headless: write nothing, report the proposal.

The plugin cannot ship permissions (Claude Code only honours `agent` and `subagentStatusLine`
from a plugin's `settings.json`) — the destructive git operations are already guarded by the
kit's git-guard hook (force push, `reset --hard`, `clean -f`, `branch -D`, `checkout .`,
`restore .`, `push --mirror`; opt-out `CMK_GIT_GUARD=off`). The rails cover the rest. Build the
proposal from what is actually in this repo:

1. **Env files that exist.** List the repo root: `.env`, `.env.local`, `.env.*.local`,
   `.env.development`, `.env.production`, `.env.test`, `*.pem`. For each one PRESENT, a
   `Read(./<name>)` and an `Edit(./<name>)` deny. Never `.env.example` / `.env.sample` — those
   are meant to be read.
2. **Ask before acting outside the repo:**

```json
{
  "permissions": {
    "deny": ["Read(./.env)", "Edit(./.env)"],
    "ask": [
      "Bash(gh pr create *)", "Bash(gh pr merge *)", "Bash(gh pr comment *)",
      "Bash(gh pr edit *)", "Bash(gh pr close *)", "Bash(gh pr review *)",

From awrshift/agent-memory-kit, MIT.

More from awrshift/agent-memory-kit