@dosx/agent-memory 0.0.13

package/skills/agent-memory/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: agent-memory
+description: >-
+  Orchestrates the local agent-memory Workspace Memory in `.agents/memory/`. Use
+  ONLY when the user explicitly runs the `/agent-memory` command with a
+  subcommand — `init` (create the memory structure; wire the harness-native
+  instruction file — `init` auto-detects harnesses from project markers, or
+  `init cursor` / `init claude` / `init codex` / `init opencode` / `init
+  copilot` / `init gemini` for one harness; prints manual hook-install
+  instructions), `install hooks` (print how to install or refresh lifecycle
+  hooks for one harness when memory already exists — does not copy scripts),
+  `update` (migrate an existing memory to the latest structure without project
+  memory, refresh the agent-memory block in harness instruction files, and
+  instruct the user to refresh installed harness hooks), `bootstrap` (analyze
+  the project and populate the memory), `sync` (refresh `current.md`, the
+  branch's `active-work/<branch>.md`, `log.md`, and `index.md` from repo state;
+  accepts `--auto` to apply all proposed diffs without the per-file prompt),
+  `lint` (check the memory for broken links, orphan files, and consistency
+  problems; accepts `--fix` to also delete stale per-branch `active-work`
+  files), or `help` (list the commands and how to use them). Never trigger
+  automatically; this skill must be invoked on demand only.
+metadata:
+  invocation: manual
+  version: '0.0.13'
+compatibility: >-
+  Works offline from the skill package vendor skeleton. Hook installation is
+  user-run (shell script or npx CLI), not performed by this skill.
+allowed-tools: >-
+  Read Grep Glob Task Edit(.agents/memory/**) Write(.agents/memory/**)
+  Edit(AGENTS.md) Edit(CLAUDE.md) Edit(GEMINI.md) Write(AGENTS.md)
+  Write(CLAUDE.md) Write(GEMINI.md) Edit(.cursor/rules/agent-memory.mdc)
+  Write(.cursor/rules/agent-memory.mdc)
+  Edit(.github/instructions/agent-memory.instructions.md)
+  Write(.github/instructions/agent-memory.instructions.md)
+  Bash(git branch:*) Bash(git status:*) Bash(git diff:*) Bash(git log:*)
+disable-model-invocation: true
+---
+
+# agent-memory
+
+Manual-only orchestrator for the local **agent-memory** method. The canonical
+memory skeleton and migration log are **vendored with this skill** under
+`vendor/` (`vendor/memory/` and `vendor/UPDATE.md`). This skill installs and
+migrates from there — **no remote clone or fetch**. The installed copy lives at
+the target project root in `.agents/memory/`, with its version recorded in
+`.agents/memory/.version` (taken from the newest entry in `vendor/UPDATE.md`).
+
+**Lifecycle hooks are not installed by this skill.** `init`, `update`, and
+`install hooks` print user-run instructions (shell script or `npx` CLI). See
+`references/install-hooks.md`.
+
+**Do not act unless the user explicitly invoked `/agent-memory <command>`.**
+This skill never runs on its own.
+
+## Enabled tools
+
+Pre-approved via the `allowed-tools` frontmatter — a space-separated,
+host-specific, **experimental** field
+([spec](https://agentskills.io/specification#allowed-tools-field)). Hosts that
+do not support it simply ignore it. Names follow the Agent Skills / Claude Code
+convention; adapt them if your host differs.
+
+| Tool                     | Used for                                                                                                                                                                                                                   |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Read`, `Grep`, `Glob`   | Read-only project analysis (`bootstrap`), lint structural checks, migration diffs (`update`), reading `references/*.md` and `vendor/`.                                                                                     |
+| `Task`                   | Parallel read-only subagents in `bootstrap`. Optional — fall back to sequential analysis.                                                                                                                                  |
+| `Edit`, `Write` (scoped) | `.agents/memory/**`, harness instruction files per `references/init.md` (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/agent-memory.mdc`, `.github/instructions/agent-memory.instructions.md`). **Not** hook paths. |
+| `Bash(git …)`            | Read-only git used by `sync` / `lint`: `branch`, `status`, `diff`, `log`. **Never** `git clone` / `fetch` / `pull` / `push`.                                                                                                |
+
+**Deliberately not pre-approved** (the host should still prompt): file deletion
+(`rm`, used only on confirmed `update`/cleanup) and any other shell. This keeps
+the "confirm sensitive changes" rule intact. The skill never writes harness hook
+scripts or configs — the user runs the installer.
+
+### Write boundary
+
+Create, edit, or delete **only** under `.agents/memory/**`, plus harness
+instruction files listed in `references/init.md` (`AGENTS.md`, `CLAUDE.md`,
+`GEMINI.md`, `.cursor/rules/agent-memory.mdc`,
+`.github/instructions/agent-memory.instructions.md`) — and in those **only the
+agent-memory block** (between `<!-- <agent-memory> -->` …
+`<!-- </agent-memory> -->`, or legacy plain tags — to wire it in `init` and
+refresh it in `update`; for `.mdc`/`.instructions.md`, frontmatter plus
+delimited body). Creating a **subdirectory** inside an existing harness dir
+(e.g. `.cursor/rules/`, `.github/instructions/`) is allowed when wiring native
+instruction files; never create the harness root itself unless the user
+explicitly requests it. **Never** write under `.cursor/hooks/`, `.claude/hooks/`,
+`.codex/hooks/`, `.opencode/hooks/`, `.opencode/plugin/`, `.github/hooks/`,
+`.gemini/hooks/`, or merge `hooks.json` / harness `settings.json` for hooks.
+Never touch content outside those scopes, application code, other configs, or
+other docs. Read the rest of the workspace freely.
+
+### Repository source (vendor)
+
+`init` and `update` read the canonical skeleton and migration log **only** from
+this skill package:
+
+- Skeleton: `vendor/memory/` (next to this `SKILL.md`)
+- Migrations: `vendor/UPDATE.md`
+
+Resolve paths relative to the installed skill directory (the folder that
+contains `SKILL.md`). Do **not** `git clone`, do **not** use
+`raw.githubusercontent.com`, and do **not** use `WebFetch` for the skeleton.
+
+In the upstream git repository, the skeleton SoT is
+`skills/agent-memory/vendor/` (next to this skill).
+
+## Routing
+
+Read the subcommand from the invocation, load **only** the matching reference,
+and follow it exactly:
+
+| Command         | Does                                                                                                              | Reference                     |
+| --------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `init`          | Create `.agents/memory/`; wire harness-native instruction file; print hook-install instructions.                  | `references/init.md`          |
+| `install hooks` | Print how to install or refresh lifecycle hooks for one harness (user-run installer).                             | `references/install-hooks.md` |
+| `update`        | Migrate memory; refresh agent-memory block; instruct user to refresh installed hooks.                             | `references/update.md`        |
+| `bootstrap`     | Analyze the project and populate the memory.                                                                      | `references/bootstrap.md`     |
+| `sync`          | Refresh `current.md` / active-work / `log.md` / `index.md` from repo state.                                       | `references/sync.md`          |
+| `lint`          | Check the memory for structural and consistency problems.                                                         | `references/lint.md`          |
+| `help`          | List the commands and how to use them.                                                                            | _Help_ section below          |
+
+If no subcommand is given, or it is not one of those above, run `help` (below)
+and stop. Do not guess the user's intent.
+
+For `init`, an optional second token selects one harness (`cursor`, `claude`,
+`codex`, `opencode`, `copilot`, `gemini`). Load `references/init.md` and follow
+its harness table.
+
+For `install hooks` (or `install hook`), a `<harness>` token is **required**
+(`cursor`, `claude`, `codex`, `opencode`, `copilot`, `gemini`). Load
+`references/install-hooks.md`.
+
+## Help
+
+For `/agent-memory help` (and for any empty or unknown invocation), output the
+following Markdown exactly — nothing else:
+
+---
+
+**agent-memory** — a local Workspace Memory that keeps AI agents on the same
+page.
+
+**Commands**
+
+| Command                       | Does                                                                                                                                                              |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/agent-memory init`          | Create `.agents/memory/`; auto-detect harnesses and write the native instruction file (`.mdc`, `.instructions.md`, or agent `*.md`), or `init <harness>` for one. |
+| `/agent-memory install hooks` | Print how to install or refresh hooks for one harness — `cursor`, `claude`, `codex`, `opencode`, `copilot`, `gemini` (memory must exist).                         |
+| `/agent-memory bootstrap`     | Analyze the project (up to 3 subagents) and populate the memory.                                                                                                  |
+| `/agent-memory update`        | Migrate memory; refresh agent-memory block in harness instruction files; instruct hook refresh.                                                                   |
+| `/agent-memory sync`          | Refresh `current.md` / active-work / `log.md` / `index.md` from repo state. `--auto` applies all diffs without per-file prompts.                                  |
+| `/agent-memory lint`          | Check for broken links, orphan files, stale branches, and consistency. `--fix` also deletes stale per-branch `active-work` files.                                 |
+| `/agent-memory help`          | Show this guide.                                                                                                                                                  |
+
+**Getting started**
+
+- New project? Run `init` (or `init <harness>` — e.g. `init cursor` if you use
+  Cursor and already have a `.cursor/` directory), then optionally `bootstrap`.
+  Install hooks with the printed `npx` or shell command.
+- Memory exists but hooks missing or stale? Run `install hooks <harness>` for
+  instructions, or re-run the installer from the release tag.
+- Keeping the memory current? Run `sync` at checkpoints (end of task, before
+  commit, before compaction). Use `sync --auto` for low-friction routine
+  flushes.
+- Already set up? Use `lint` to check health (`lint --fix` also removes stale
+  per-branch files), `update` to upgrade memory scaffolding, then refresh hooks
+  with the user-run installer if needed.
+
+Method & conventions: `.agents/memory/instructions.md`
+
+---
+
+## Shared rules (apply to every command)
+
+- **Never modify project memory content** — `current.md`, `active-work/*`,
+  `decisions.md`, `log.md`, `domains/*`, `features/*` — unless a command
+  explicitly says so, and only after the user confirms.
+- Run memory/orchestration steps inside the user's current agent. **Do not
+  download, clone, or execute hook installers** — only print instructions for
+  the user to run.
+- If the host ignores `allowed-tools` granularity: still **never** run
+  `git clone`, `git fetch`, `git pull`, or any network fetch for this skill.
+- All paths are relative to the target project root unless stated otherwise
+  (vendor paths are relative to this skill directory).

package/skills/agent-memory/references/agent-block.md

@@ -0,0 +1,115 @@
+# The agent-memory block
+
+The exact block `init` writes into harness instruction files and `update`
+refreshes in place. **Single source of truth** for the block content — both
+`init` and `update` read it from here; never duplicate the block text in those
+references.
+
+**Write targets** (body identical everywhere; see `references/init.md` for
+carrier resolution and which file receives the block):
+
+| Harness  | File                                                                     |
+| -------- | ------------------------------------------------------------------------ |
+| cursor   | `.cursor/rules/agent-memory.mdc` (with `alwaysApply: true` frontmatter)  |
+| copilot  | `.github/instructions/agent-memory.instructions.md`                      |
+| claude   | `CLAUDE.md` (or `AGENTS.md` when `CLAUDE.md` delegates via `@AGENTS.md`) |
+| codex    | `AGENTS.md`                                                              |
+| opencode | `AGENTS.md`                                                              |
+| gemini   | `GEMINI.md` (or delegated carrier — same rules as claude)                |
+
+## The block
+
+```md
+<!-- <agent-memory> -->
+
+## Agent Memory
+
+This project uses Agent Memory (a local Workspace Memory). **Before starting any
+task**, Read `.agents/memory/instructions.md` (it defines the workflow), then
+read `.agents/memory/index.md`, `.agents/memory/current.md`, and your branch's
+file in `.agents/memory/active-work/`.
+
+This memory is **read AND written** by agents — it is not chat history. While
+you work and when you finish a task, keep it current per `instructions.md`:
+update your branch's `active-work/<branch>.md` (Task, progress, touched files,
+blockers), append bullets to the **current session** heading in `log.md`,
+**record architecture and design decisions in `decisions.md`**, keep `index.md`
+aligned with lazy and domain/feature files, and refresh `current.md` when
+project state changes (list open active-work files in _In progress_; move
+completed work to _Done_). Ask the user before changing `vision.md` when
+uncertain. Delete your `active-work/` file when the branch merges. At
+checkpoints (end of task, before commit, before compaction, end of session), run
+`/agent-memory sync` to flush `current.md`, active-work, `log.md`, and
+`index.md` from repo state.
+
+@.agents/memory/instructions.md
+
+<!-- </agent-memory> -->
+```
+
+## Cursor `.mdc` wrapper
+
+For Cursor, prepend this frontmatter to the block above (body unchanged):
+
+```yaml
+---
+description: Agent Memory workspace memory workflow
+alwaysApply: true
+---
+```
+
+`update` compares only the delimited body; preserve frontmatter when refreshing.
+
+## Copilot `.instructions.md` wrapper
+
+For Copilot, prepend this frontmatter to the block above (body unchanged):
+
+```yaml
+---
+applyTo: '**'
+---
+```
+
+Copilot path-specific files under `.github/instructions/**/*.instructions.md`
+are applied only to files matching an `applyTo` glob. `**` makes the block
+**always-on** (every file, every session) — required so the agent receives the
+agent-memory workflow before any task. Without `applyTo`, the file may not apply
+at all. `update` compares only the delimited body; preserve frontmatter when
+refreshing.
+
+## Why the delimiters
+
+`<!-- <agent-memory> -->` … `<!-- </agent-memory> -->` mark the block so
+`update` can find and replace **only** it, without touching anything else in the
+file. HTML comments are invisible in rendered Markdown (no raw tags in the
+preview) but remain machine-identifiable in the source. Never edit content
+outside the delimiters.
+
+## Why both the read list and `@import`
+
+- The explicit "Read `.agents/memory/instructions.md`" line makes the agent load
+  the method file directly. This is the load path for harnesses that treat agent
+  files as plain Markdown or load context via rules — **Cursor** receives the
+  block through `.cursor/rules/agent-memory.mdc` (`alwaysApply: true`);
+  `@import` in `AGENTS.md` is a no-op there. The "Read …" line is the active
+  path on Cursor. For hooks (checkpoint layer), print user-run install commands
+  from `/agent-memory install hooks <harness>` — the skill never installs hooks;
+  see `instructions.md` → _Plain-Markdown harnesses_ (hooks = checkpoint; `.mdc` =
+  context).
+- The `@.agents/memory/instructions.md` line is honored by harnesses that follow
+  the AGENTS.md `@import` convention (Claude Code, Gemini CLI, Codex),
+  auto-loading `instructions.md`.
+
+Including both is intentional and harmless — a harness that loads `@import`
+simply gets `instructions.md` once.
+
+## How to compare
+
+`update` decides whether to refresh by comparing the block currently in the
+instruction file (text between the delimiters, inclusive) against the block
+above, byte-for-byte. Identical → nothing to do. Different → propose the unified
+diff and confirm before replacing (sensitive). Legacy installs may still use
+plain `<agent-memory>` … `</agent-memory>` tags (0.0.4–0.0.5); `update` treats
+those as the same block and replaces them with the comment-delimited canonical
+form. For `.cursor/rules/agent-memory.mdc`, compare the delimited body only —
+ignore YAML frontmatter.

package/skills/agent-memory/references/bootstrap.md

@@ -0,0 +1,84 @@
+# `/agent-memory bootstrap`
+
+Analyze the project and populate the memory with real content. Uses three
+analyses that run as subagents when the host supports them.
+
+## Steps
+
+1. **Permission gate (always).** Tell the user that bootstrap will spawn up to
+   three subagents to analyze the project, and ask for explicit permission
+   before continuing — **even when running under bypass/auto-approve**. If
+   declined, stop.
+
+2. **Ensure structure.** If `.agents/memory/` does not exist, run the `init`
+   procedure first (`references/init.md`), then continue.
+
+3. **Run the three analyses.** Launch them as **parallel subagents** if the host
+   supports subagents (e.g. Claude Code's Task/Agent tool). If it does not, run
+   the same three analyses **sequentially** in the current agent.
+   - **A — Documentation.** Read `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, then
+     `README.md` and other `.md` docs. Extract: product purpose, scope, goals.
+   - **B — Structure.** Map the repo layout: backend, frontend, database,
+     services, and the major areas/modules.
+   - **C — Technologies.** Identify the main languages, frameworks, and tooling,
+     and determine what kind of project it is.
+
+4. **Vision gate.** Before writing `vision.md`, if purpose or scope is unclear
+   from the analyses, **ask the user** — do not invent product goals.
+
+5. **Synthesize and write (skip empties).** Wait for all three, then fill memory
+   files only where there is real content — respect the lazy principle, do not
+   create shallow placeholders:
+
+   | Source        | Writes to                                            |
+   | ------------- | ---------------------------------------------------- |
+   | A (docs)      | `vision.md` (after vision gate)                      |
+   | B (structure) | `architecture.md`, `domains/*.md` (per major area)   |
+   | C (tech)      | `architecture.md` (stack), `patterns.md`             |
+   | synthesis     | `current.md` (state/version), `log.md` session entry |
+
+   - **Register every created lazy file and every `domains/*.md` /
+     `features/*.md` in `index.md`** (under the matching section, replacing
+     `_None yet._`). Otherwise `lint` will flag orphans.
+   - Append to `log.md` using the per-session format in `instructions.md` (one
+     heading + bullets), e.g. `## [YYYY-MM-DD] [docs] bootstrap initial memory`
+     with a bullet list of files created.
+   - Leave `active-work/` with only its `TEMPLATE.md` (no branch files), and
+     **do not invent** decisions — `decisions.md` stays empty unless a genuine,
+     already-made trade-off is documented in the project.
+
+6. **Report.** List which files were created/filled and which were skipped (and
+   why), so the user can fill the gaps later. If vision was uncertain, note what
+   still needs user input. Tell the user to run `/agent-memory sync` at
+   checkpoints to keep `current.md`, active-work, `log.md`, and `index.md`
+   current.
+
+## Subagent prompts
+
+Pass each analysis to a subagent with `Task` (read-only). Replies must be short
+and high-signal — they feed the memory, where tokens matter. **If subagents are
+unavailable, run the three prompts yourself, in order.**
+
+- **A — Documentation:**
+
+  > Read-only task. Read the project's agent/instruction files (`AGENTS.md`,
+  > `CLAUDE.md`, `GEMINI.md`), then `README.md` and other top-level `*.md` docs.
+  > Do not read source code. Return, in ≤150 words: the product purpose (1–2
+  > sentences), scope/goals (bullets), and any stated conventions or
+  > constraints. Cite the file for each fact. If something is not documented,
+  > say so — never invent.
+
+- **B — Structure:**
+
+  > Read-only task. Map the repository layout. Identify backend, frontend,
+  > database, services, and the major modules/areas. Return a concise list of
+  > top-level areas, each with its role and key entry-point path(s). Flag
+  > anything ambiguous. Classify from paths and manifests; avoid reading file
+  > bodies unless necessary.
+
+- **C — Technologies:**
+  > Read-only task. From manifests (`package.json`, `pyproject.toml`, `go.mod`,
+  > `Cargo.toml`, etc.) and config files, identify the main languages,
+  > frameworks, and build/test tooling, and decide the project type (web app,
+  > library, CLI, service, monorepo…). Return: the stack (bullets), notable
+  > tooling, and a one-line project-type verdict with the evidence (which file).

package/skills/agent-memory/references/init.md

@@ -0,0 +1,211 @@
+# `/agent-memory init`
+
+Create the agent-memory structure in the target project and wire it into the
+harness-specific instruction file(s). Prints user-run instructions for lifecycle
+hooks (does not install hooks). Idempotent: never duplicate or overwrite
+existing memory or harness instruction files.
+
+## Invocation
+
+```text
+/agent-memory init                  # auto-detect harnesses from the project
+/agent-memory init <harness>        # wire one harness only
+```
+
+Accepted `<harness>` values (aliases in parentheses):
+
+| Harness    | Aliases       | Native instruction file (context)                   | Harness dir for hooks               |
+| ---------- | ------------- | --------------------------------------------------- | ----------------------------------- |
+| `cursor`   | —             | `.cursor/rules/agent-memory.mdc`                    | `.cursor/` — lifecycle hooks        |
+| `claude`   | `claude-code` | `CLAUDE.md`                                         | `.claude/` — lifecycle hooks        |
+| `codex`    | —             | `AGENTS.md`                                         | `.codex/` — lifecycle hooks         |
+| `opencode` | —             | `AGENTS.md`                                         | `.opencode/` — plugin + sync script |
+| `copilot`  | `github`      | `.github/instructions/agent-memory.instructions.md` | `.github/` — lifecycle hooks        |
+| `gemini`   | —             | `GEMINI.md`                                         | `.gemini/` — lifecycle hooks        |
+
+If `<harness>` is missing, **auto-detect** (see step 4). If it is unknown, stop
+and list the accepted values.
+
+Canonical sources live under `skills/agent-memory/` in the agent-memory repo:
+
+- Agent block: [`references/agent-block.md`](./agent-block.md)
+- Harness hooks/plugin: [`references/install-hooks.md`](./install-hooks.md)
+
+## Steps
+
+1. **Guard.** If `.agents/memory/` already exists, stop and tell the user the
+   project is already initialized — suggest `/agent-memory update` or
+   `/agent-memory install hooks <harness>` to refresh hooks. Do not overwrite
+   anything.
+
+2. **Copy the skeleton.** Read this skill's `vendor/memory/` (see `SKILL.md` →
+   Repository source) and copy that directory into the project as
+   `.agents/memory/` (the entire directory, including `active-work/TEMPLATE.md`
+   and `.gitignore` for hook-local state files). Do not clone or fetch remotely.
+
+3. **Write the version anchor.** Create `.agents/memory/.version` containing the
+   latest version — the newest version section in this skill's
+   `vendor/UPDATE.md`, e.g. `0.0.13`.
+
+4. **Parse the harness target.** From the invocation, read optional `<harness>`.
+   Normalize aliases (`claude-code` → `claude`, `github` → `copilot`). If
+   omitted, set mode to `auto` and **detect harnesses** (see **Auto-detection**
+   below).
+
+5. **Resolve carriers and wire instruction files.** Use the **canonical block**
+   from [`references/agent-block.md`](./agent-block.md) — copy it verbatim (the
+   `<!-- <agent-memory> -->` … `<!-- </agent-memory> -->` delimiters and
+   everything between them).
+
+   **Carrier resolution (before writing):** a harness is **served** if any file
+   it auto-loads already contains the block. The block is written only into the
+   **distinct set of effective carriers** — never into a second file the same
+   harness also loads.
+   - **Nominal native** per harness (table above).
+   - **Delegation via `@import`:** if `CLAUDE.md` or `GEMINI.md` contains
+     `@AGENTS.md` or `@./AGENTS.md`, the effective carrier for that harness is
+     `AGENTS.md`, not the nominal file. Do **not** write the block into the file
+     that delegates. Resolve recursively (`@CLAUDE.md`, `@GEMINI.md` in
+     `AGENTS.md` / other agent files); stop on cycles.
+   - **Copilot coexistence:** Copilot auto-loads `AGENTS.md` **and**
+     `.github/instructions/agent-memory.instructions.md`. If `AGENTS.md` is an
+     effective carrier (codex, opencode, or claude via delegation), Copilot is
+     already served — **do not** create
+     `.github/instructions/agent-memory.instructions.md`. If Copilot is the only
+     harness that needs a carrier and `AGENTS.md` is not one, create the
+     `.instructions.md` file and do not touch `AGENTS.md`.
+
+   **Targeted mode** (`init <harness>`): resolve the carrier for that harness
+   only. If the nominal native delegates to a file that already has the block,
+   skip and report. If it delegates to a file **without** the block, write the
+   block into the referenced file (effective carrier), not the nominal native.
+
+   **Auto mode** (`init`): detect harnesses (below), resolve carriers for each,
+   write the block once per distinct carrier. Apply copilot coexistence and
+   delegation rules across the full set.
+
+   **Cursor `.mdc` wrapper:** the block body is the canonical block verbatim.
+   Prepend YAML frontmatter:
+
+   ```yaml
+   ---
+   description: Agent Memory workspace memory workflow
+   alwaysApply: true
+   ---
+   ```
+
+   **Copilot `.instructions.md` wrapper:** the block body is the canonical block
+   verbatim. Prepend YAML frontmatter so the file is **always-on** (Copilot
+   path-specific files apply only to files matching `applyTo`):
+
+   ```yaml
+   ---
+   applyTo: '**'
+   ---
+   ```
+
+   **Prerequisite dirs (create harness roots only on explicit request).** Native
+   instruction files that live inside a harness dir require that dir to already
+   exist. By default the skill does **not** create `.cursor/`, `.claude/`,
+   `.codex/`, `.opencode/`, `.github/`, or `.gemini/`. If the required dir is
+   missing, **stop** for that harness and ask the user: offer to create it (and
+   the needed subdir) on explicit confirmation, or tell them to create/enable it
+   first (e.g. open the harness once so it creates its dir) and re-run. Create
+   the harness root only when the user explicitly requests it. Required dir per
+   harness:
+
+   | Harness  | Required dir (for native + hooks)                                   |
+   | -------- | ------------------------------------------------------------------- |
+   | cursor   | `.cursor/` (native `.cursor/rules/`, hooks `.cursor/hooks/`)        |
+   | copilot  | `.github/` (native `.github/instructions/`, hooks `.github/hooks/`) |
+   | claude   | `.claude/` (hooks only; `CLAUDE.md` lives at root)                  |
+   | codex    | `.codex/` (hooks only; `AGENTS.md` lives at root)                   |
+   | opencode | `.opencode/` (hooks only; `AGENTS.md` lives at root)                |
+   | gemini   | `.gemini/` (hooks only; `GEMINI.md` lives at root)                  |
+
+   Creating a **subdirectory** inside an existing harness dir (e.g.
+   `.cursor/rules/`, `.github/instructions/`) is allowed; never create the
+   harness root itself unless user explicitly requests it.
+
+   **Idempotency:** if a carrier already contains a delimited agent-memory block
+   (`<!-- <agent-memory> -->` … `<!-- </agent-memory> -->`, or legacy plain
+   `<agent-memory>` … `</agent-memory>` from 0.0.4–0.0.5), skip it — do not add
+   a second one. For `.mdc`, compare the body between delimiters (ignore
+   frontmatter when comparing).
+
+   **Orphan block cleanup:** for `cursor` / `copilot`, if `AGENTS.md` contains a
+   block but is **not** an effective carrier (no codex/opencode/claude via
+   delegation), warn and offer to remove it (**sensitive** — show diff, confirm
+   first). Do not remove a block from `AGENTS.md` when it serves codex,
+   opencode, or claude via delegation.
+
+6. **Print hook-install instructions.** Follow
+   [`references/install-hooks.md`](./install-hooks.md) for each harness that
+   applies (targeted: that harness only; auto: every detected harness whose
+   prerequisite dir exists). In `init`, run those steps **without** the memory
+   guard (step 1 of that reference). **Do not** copy hook scripts or merge
+   harness hook configs — only print the user-run `npx` / shell commands. Note:
+   the skill never creates harness roots; the user-run installer **does** create
+   them if missing when the user runs the printed command.
+
+7. **Report.** List: mode (auto or targeted harness), detected harness(es),
+   skeleton created, carrier file(s) wired or skipped (and why — delegation,
+   copilot coexistence, idempotency), orphan-block offers, hook-install
+   commands printed (or skipped for missing harness dirs), and suggest
+   `bootstrap` / `sync` next steps. For Cursor, note that **hooks are the
+   recommended checkpoint integration** (user-installed) and **`.mdc` is the
+   context layer**.
+
+## Auto-detection (`init` without `<harness>`)
+
+Scan the project root for file markers. Do **not** wire every existing agent
+file — detect harness(es), then install each native (with carrier resolution).
+
+| Marker (project root)                       | Harness inferred | Notes                            |
+| ------------------------------------------- | ---------------- | -------------------------------- |
+| `CLAUDE.md` or `.claude/` (dir)             | `claude`         | Claude Code                      |
+| `GEMINI.md` or `.gemini/` (dir)             | `gemini`         | Gemini CLI / Antigravity         |
+| `.cursor/` or `.cursor/rules/` (directory)  | `cursor`         | Cursor rules system              |
+| `.github/copilot-instructions.md`           | `copilot`        | Copilot repo-wide                |
+| `.github/instructions/` (directory)         | `copilot`        | Copilot path-specific            |
+| `~/.copilot/instructions` (home)            | `copilot`        | **detection only** — never write |
+| `AGENTS.md` + `.codex/`                     | `codex`          |                                  |
+| `AGENTS.md` + `.opencode/`                  | `opencode`       | OpenCode uses `AGENTS.md`        |
+| `AGENTS.md` (no `.codex/` nor `.opencode/`) | ambiguous        | ask user: codex or opencode      |
+
+- **Multi-harness:** if several markers match (e.g. `CLAUDE.md` + `.cursor/`),
+  install each harness, applying carrier resolution and copilot coexistence
+  across the set.
+- **`~/.copilot/instructions`:** use only to infer Copilot usage. The install
+  target remains project-level
+  `.github/instructions/agent-memory.instructions.md` — never write under `~/`.
+- **Inconclusive detection** (no markers, or `AGENTS.md` alone without `.codex/`
+  / `.opencode/`): **ask the user** which harness to install (via `AskQuestion`:
+  cursor, claude, codex, opencode, copilot, gemini). Do not guess. Do not create
+  `AGENTS.md` blindly.
+
+### Carrier example (claude + opencode)
+
+Project: `CLAUDE.md` contains `@AGENTS.md`, `AGENTS.md` exists, `.opencode/`
+exists.
+
+- opencode → carrier `AGENTS.md`
+- claude → `CLAUDE.md` delegates → carrier `AGENTS.md`
+- Result: write the block **once** in `AGENTS.md`; skip `CLAUDE.md`. Report:
+  "claude served via `AGENTS.md` (@import in `CLAUDE.md`); `CLAUDE.md` skipped".
+
+When `CLAUDE.md` is standalone (no `@AGENTS.md`), claude and opencode have
+distinct carriers → write the block in each file that is an effective carrier.
+
+## Notes
+
+- Do not populate the memory here — `init` only scaffolds. To fill it from the
+  codebase, the user runs `/agent-memory bootstrap`. If product vision is
+  unclear, ask the user before writing `vision.md` (same rule as `bootstrap` /
+  `sync`).
+- Optional git `pre-commit` hook is **not** wired by `init` — see the
+  [hooks README](https://github.com/diegoos/agent-memory/blob/0.0.13/hooks/README.md).
+- **Context vs checkpoint:** native instruction files (`.mdc`, agent `*.md`,
+  `.instructions.md`) inject the agent-memory workflow into the model context.
+  Lifecycle hooks (see `install-hooks.md`) run deterministic git checkpoints —
+  they do not replace context injection.