setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

/memory-kit:setup — 在现有仓库中采用该工具包

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.

插件提供行为逻辑；仓库拥有状态数据。本技能用于创建该状态—— 首次写入前始终询问用户，且绝不修改仓库中已有的文件。

若运行时无可用用户响应（无头模式或

-p

模式运行），则“询问”意味着跳过并报告：使用文档中已有的默认设置，不安装任何标记为可选的内容，最终列出所有刻意未安装的内容以及仍待解决的问题。绝不替用户预设偏好，也绝不将跳过的步骤伪装成已完成。

Step 0 — look before you write

步骤0 — 先查看再写入

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.

用两行内容报告已存在的文件：

.claude/memory/MEMORY.md

、

context/handoffs/

、

knowledge/

、

projects/

、已有的文档目录（

docs/

、

doc/

、

documentation/

）、

.claude/settings.json

、

.gitignore

，以及该仓库是否已有实际内容——代码或除空白README外的文档（真实项目），还是基本为空（全新内存工作区）。是否为Git仓库无关紧要，关键看内容。此步骤之后的所有内容均为需用户一次性确认的提案，而非一系列提示。

Step 1 — the shared memory layers

步骤1 — 共享内存层

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)

以下四个层在仓库中的所有项目间共享。仅创建缺失的文件，从

${CLAUDE_PLUGIN_ROOT}/templates/

复制：

路径	来源	用途
`.claude/memory/MEMORY.md`	`templates/MEMORY-TEMPLATE.md`	钩子在每次会话中注入的热缓存
`context/handoffs/HANDOFF-TEMPLATE.md`	`templates/HANDOFF-TEMPLATE.md`	会话专用笔记格式
`knowledge/index.md`	`templates/workspace/knowledge-index.md`	深层内存目录
`knowledge/concepts/.gitkeep`	—	已提炼模式的存储位置
`.claude/state/.gitkeep`	—	钩子记录文件（已加入Git忽略）

Step 1b — the project layer (

projects/<name>/

)

步骤1b — 项目层（

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.

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.

上述四个层用于存储MEMORY。工作相关的文档——任务、规格、研究、决策、QA——属于某个PROJECT，该工具包默认支持多项目：每个客户或产品对应一个文件夹，这样决策台账、发现记录和QA协议都能精准对应唯一对象。这同样适用于单一产品代码仓库——只需创建一个以产品命名的项目文件夹即可。（早期版本建议在代码仓库中跳过

projects/

，但这导致规格、待办事项和研究文档无处存放，最终散落在仓库根目录。）

询问项目名称，然后为每个项目创建以下内容，仅此而已：

路径	来源	用途
`projects/<name>/README.md`	`templates/workspace/project/README-TEMPLATE.md`	项目介绍 + 文档存储位置映射表
`projects/<name>/BACKLOG.md`	`templates/workspace/project/BACKLOG-TEMPLATE.md`	任务及其实际状态

项目层的其余部分——

plans/

、

research/

、

decisions-log.md

、

review-findings.md

、

qa/

、

materials/

——仅在首次生成对应产物时由创建者创建，绝不提前搭建空文件夹。空文件夹不能算作一层，只是未兑现的承诺。

若仓库已有文档目录，请勿移动任何内容，也请勿提议迁移。将仓库已使用的路径填入README的映射表中，路径需从仓库根目录开始并以

开头，避免被误解为项目相对路径。该表是“计划文档存放位置”的唯一可信来源（SSOT）——默认设置仅为默认值，并非强制规则，仓库自身的布局优先级更高。

判断“已有文档目录”的标准是已提交的内容，而非空文件夹：

docs/

（或

doc/

、

documentation/

）中至少包含一个Git追踪的、由人工编写的Markdown文件。空目录或仅包含无法归属的脚手架文件的目录不算在内——此时使用默认设置。若情况存疑，请询问用户；这将决定未来所有计划文档的查找位置，一次询问的成本远低于后续拆分仓库文档的成本。

全新的空白工作区，首次使用该工具包？还可提供

templates/workspace/

中的

experiments/

沙箱，并且——仅当只有一个项目时——将

templates/workspace/ONBOARDING-BACKLOG.md

作为其待办事项：包含5个首日引导任务。若首日就有两个或更多真实项目，则跳过此步骤（将教程混入客户待办事项会产生干扰，新增一个虚拟项目存放教程则更糟），改为提供

/memory-kit:tour

。

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

步骤2 — 自动内存决策（询问用户，勿自行假设）

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
```
. You get dated entries, human-confirmed promotion, handoffs, and one file the user can read.
Native owns capture, kit owns the ritual. Set
```
"autoMemoryDirectory"
```
to this repo's
```
.claude/memory
```
and lower the caps to the native limits (200 lines / 25 KB) — the audit, promotion and handoffs still come from the kit.

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

Claude Code拥有自己的自动内存（

~/.claude/projects/<project>/memory/

，每次会话加载，由Claude自动写入无需询问）。将其与工具包同时运行意味着存在两个写入者和两套数据。用一个问题将选择权交给用户：

工具包管理内存（默认）。在
```
.claude/settings.json
```
中写入
```
"autoMemoryEnabled": false
```
。你将获得带时间戳的条目、人工确认的提炼功能、会话交接功能，以及一个用户可直接读取的文件。
原生功能负责捕获，工具包负责流程规范。将
```
"autoMemoryDirectory"
```
设置为当前仓库的
```
.claude/memory
```
，并将上限降至原生功能的限制（200行 / 25 KB）——审核、提炼和会话交接仍由工具包负责。

无论选择哪种方式，都需明确告知用户现在由哪个系统管理该文件。

Step 3 — permission rails

步骤3 — 权限规则

The plugin cannot ship permissions (Claude Code only honours

agent

and

subagentStatusLine

from a plugin's

settings.json

), so propose this merge into the project's

.claude/settings.json

— and never widen an existing allowlist without saying so:

json

{
  "permissions": {
    "deny": [
      "Bash(git push --force:*)",
      "Bash(git push -f:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./**/*.pem)"
    ],
    "ask": [
      "Bash(git reset --hard:*)",
      "Bash(git clean:*)",
      "Bash(rm -rf:*)"
    ]
  }
}

State the rule out loud while you do it: a permission entry is a speed bump for the agent, never a guard on a script. Anything that must not happen belongs inside the script itself.

Do NOT reproduce the v5 allowlist (

Bash(git *)

Bash(npm *)

Bash(node *)

Bash(python3 *)

). It read as a safety feature while auto-approving force-pushes, hard resets and arbitrary code execution through

node -e

插件无法自带权限设置（Claude Code仅遵循插件

settings.json

中的

agent

和

subagentStatusLine

），因此提议将以下内容合并到项目的

.claude/settings.json

中——且未经说明绝不扩大现有允许列表：

json

{
  "permissions": {
    "deny": [
      "Bash(git push --force:*)",
      "Bash(git push -f:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./**/*.pem)"
    ],
    "ask": [
      "Bash(git reset --hard:*)",
      "Bash(git clean:*)",
      "Bash(rm -rf:*)"
    ]
  }
}

执行此操作时需明确说明规则：权限条目是针对Agent的减速带，而非脚本的防护措施。任何绝对禁止的操作都应在脚本内部处理。

请勿重现v5版本的允许列表（

Bash(git *)

、

Bash(npm *)

、

Bash(node *)

、

Bash(python3 *)

）。该列表看似是安全功能，实则自动批准了强制推送、硬重置以及通过

node -e

执行任意代码的操作。

Step 4 — .gitignore

步骤4 — .gitignore

Append only the lines that are missing, each with its reason in one comment:

gitignore

.claude/state/*
!.claude/state/.gitkeep
.claude/memory/MEMORY.md      # personal hot cache — commit deliberately if the team shares it
context/handoffs/*.md         # session notes; keep the template
!context/handoffs/HANDOFF-TEMPLATE.md

For a team repository — more than one human committing, or a shared remote anyone on the team can push to — ask instead: shared memory (commit both) is often the point. Solo or private: the defaults above.

仅添加缺失的行，每行附带一行注释说明原因：

gitignore

.claude/state/*
!.claude/state/.gitkeep
.claude/memory/MEMORY.md      # 个人热缓存——若团队共享则需手动提交
context/handoffs/*.md         # 会话笔记；保留模板文件
!context/handoffs/HANDOFF-TEMPLATE.md

对于团队仓库——有多个用户提交代码，或存在团队成员均可推送的共享远程仓库——需询问用户：共享内存（提交上述两个文件）通常是团队场景的需求。个人或私有仓库：使用上述默认设置。

Step 5 — the optional layers (offer, install nothing by default)

步骤5 — 可选层（仅提供选项，默认不安装）

The plugin also carries a builder's toolkit. None of it costs context until invoked, so it is already available — the only thing that needs a decision is the always-loaded rule:

Building with subagents? Offer to copy
```
${CLAUDE_PLUGIN_ROOT}/templates/rules/orchestration.md
```
into
```
.claude/rules/
```
. Five invariants, always loaded, ~20 lines — that is the entire cost. The agents (
```
executor
```
,
```
recon
```
,
```
idea-validator
```
) and
```
/memory-kit:session-review
```
+
```
/memory-kit:second-opinion
```
work without it; the rule is what makes the discipline binding.
Shipping a product with a UI?
```
/memory-kit:qa-sweep
```
needs a protocol first: copy
```
${CLAUDE_PLUGIN_ROOT}/reference/qa-PROTOCOL-TEMPLATE.md
```
→
```
projects/<name>/qa/README.md
```
, fill every
```
<placeholder>
```
, and merge
```
reference/qa-mcp.json.example
```
into the project
```
.mcp.json
```
. Do this only when the user asks for QA — never as part of a default setup.
Adding your own skills, hooks or agents to this repo?
```
${CLAUDE_PLUGIN_ROOT}/reference/project-extensions.md
```
is the decision table for which shape a repeated workflow takes and what it costs when idle.
Depth for the rest lives in
```
${CLAUDE_PLUGIN_ROOT}/reference/
```
and is read on demand.

插件还包含一套构建工具集。这些工具在被调用前不会占用上下文，因此已随时可用——唯一需要决策的是是否始终加载规则：

是否使用子Agent构建？ 提议将
```
${CLAUDE_PLUGIN_ROOT}/templates/rules/orchestration.md
```
复制到
```
.claude/rules/
```
中。包含5条不变规则，始终加载，约20行——这就是全部成本。Agent（
```
executor
```
、
```
recon
```
、
```
idea-validator
```
）以及
```
/memory-kit:session-review
```
+
```
/memory-kit:second-opinion
```
无需该规则即可运行；该规则的作用是让流程规范具有约束力。
是否交付带UI的产品？
```
/memory-kit:qa-sweep
```
需要先有协议：将
```
${CLAUDE_PLUGIN_ROOT}/reference/qa-PROTOCOL-TEMPLATE.md
```
复制为
```
projects/<name>/qa/README.md
```
，填充所有
```
<placeholder>
```
，并将
```
reference/qa-mcp.json.example
```
合并到项目的
```
.mcp.json
```
中。仅当用户要求QA时才执行此操作——绝不作为默认设置的一部分。
是否要向此仓库添加自定义技能、钩子或Agent？
```
${CLAUDE_PLUGIN_ROOT}/reference/project-extensions.md
```
是一个决策表，用于确定重复工作流的形式以及闲置时的成本。
其余深层内容位于
```
${CLAUDE_PLUGIN_ROOT}/reference/
```
中，按需读取。

Step 6 — verify, then hand back

步骤6 — 验证，然后交还控制权

The files you just created were NOT in context when this session started, so nothing you can see right now proves the injection works. Prove it the only honest way — run the hook yourself and read what it would inject next time:

bash

HOOK="${CLAUDE_PLUGIN_ROOT}/hooks/session-start.py"

你刚刚创建的文件在本次会话开始时并未在上下文中，因此当前可见的内容无法证明注入功能正常工作。唯一可靠的验证方式是自行运行钩子并查看下次会话将注入的内容：

bash

HOOK="${CLAUDE_PLUGIN_ROOT}/hooks/session-start.py"

the variable expands in this skill's text, not in your shell — fall back to finding the file

该变量在本技能文本中展开，而非在你的Shell中——若无法展开则尝试查找文件

[ -f "$HOOK" ] || HOOK=$(find ~/.claude/plugins -path 'memory-kit' -name session-start.py | head -1) CLAUDE_PLUGIN_ROOT="$(dirname "$(dirname "$HOOK")")" python3 "$HOOK" <<< '{"source":"startup"}'


1. The output must contain the working agreement AND a section holding your new `MEMORY.md`
   body. If it still shows the "not set up in this repository" pointer, the scaffold landed in
   the wrong place — say so; do not claim the kit is live.
2. Then, in an interactive session only, `/context` as a second check — it shows THIS session's
   opening injection, so a missing hot cache there is expected today and confirmed on the next
   start. In a headless run there is no `/context`; the hook output above is the whole proof.
3. Tell the user, in three lines: what was created, who owns memory now, and that
   `/memory-kit:close-session` is what they type at the end of the day. Offer `/memory-kit:tour`.

[ -f "$HOOK" ] || HOOK=$(find ~/.claude/plugins -path 'memory-kit' -name session-start.py | head -1) CLAUDE_PLUGIN_ROOT="$(dirname "$(dirname "$HOOK")")" python3 "$HOOK" <<< '{"source":"startup"}'


1. 输出必须包含工作协议以及新创建的`MEMORY.md`内容部分。若仍显示“未在此仓库中设置”的提示，则说明脚手架文件放置位置错误——请告知用户，切勿声称工具包已启用。
2. 仅在交互式会话中，使用`/context`进行二次检查——它会显示本次会话的初始注入内容，因此热缓存缺失是正常现象，下次启动时会自动加载。无头模式下无`/context`；上述钩子输出即为全部验证依据。
3. 用三行内容告知用户：已创建的内容、当前由哪个系统管理内存，以及每天结束时需输入`/memory-kit:close-session`。同时提供`/memory-kit:tour`选项。

What NOT to do

禁止操作

Don't scaffold silently, and don't create the project subfolders (
```
plans/
```
,
```
research/
```
,
```
qa/
```
, …) upfront — they appear when something is actually written into them.
Don't move a repository's existing
```
docs/
```
into
```
projects/
```
. Map it, never migrate it.
Don't overwrite an existing
```
MEMORY.md
```
,
```
settings.json
```
or
```
.gitignore
```
— merge, and show the diff before writing.
Don't invent layers. Memory is
```
MEMORY.md
```
,
```
context/handoffs/
```
,
```
knowledge/concepts/
```
,
```
.claude/rules/
```
; the work's documents live in
```
projects/<name>/
```
. That is the whole system.
Don't declare success from the file listing alone. The v5 kit spent a year claiming the hot cache was "always loaded" while it was never injected; the only proof is seeing it in context.

请勿静默搭建脚手架，也请勿提前创建项目子文件夹（
```
plans/
```
、
```
research/
```
、
```
qa/
```
等）——这些文件夹仅在实际写入内容时才创建。
请勿将仓库中已有的
```
docs/
```
移动到
```
projects/
```
中。只需映射路径，绝不迁移。
请勿覆盖已有的
```
MEMORY.md
```
、
```
settings.json
```
或
```
.gitignore
```
——仅合并内容，并在写入前显示差异。
请勿新增额外层级。内存层包括
```
MEMORY.md
```
、
```
context/handoffs/
```
、
```
knowledge/concepts/
```
、
```
.claude/rules/
```
；工作文档存储在
```
projects/<name>/
```
中。这就是整个系统的全部组成。
请勿仅通过文件列表就宣称设置成功。v5版本的工具包曾长达一年声称热缓存“始终已加载”，但实际上从未注入；唯一的验证依据是在上下文中看到它。

setup

Original

Translation

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

/memory-kit:setup — 在现有仓库中采用该工具包

Step 0 — look before you write

步骤0 — 先查看再写入

Step 1 — the shared memory layers

步骤1 — 共享内存层

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

步骤1b — 项目层（
`projects/<name>/`
）

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

步骤2 — 自动内存决策（询问用户，勿自行假设）

Step 3 — permission rails

步骤3 — 权限规则

Step 4 — .gitignore

步骤4 — .gitignore

Step 5 — the optional layers (offer, install nothing by default)

步骤5 — 可选层（仅提供选项，默认不安装）

Step 6 — verify, then hand back

步骤6 — 验证，然后交还控制权

the variable expands in this skill's text, not in your shell — fall back to finding the file

该变量在本技能文本中展开，而非在你的Shell中——若无法展开则尝试查找文件

What NOT to do

禁止操作

setup

Original

Translation

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

/memory-kit:setup — 在现有仓库中采用该工具包

Step 0 — look before you write

步骤0 — 先查看再写入

Step 1 — the shared memory layers

步骤1 — 共享内存层

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

步骤1b — 项目层（projects/<name>/）

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

步骤2 — 自动内存决策（询问用户，勿自行假设）

Step 3 — permission rails

步骤3 — 权限规则

Step 4 — .gitignore

步骤4 — .gitignore

Step 5 — the optional layers (offer, install nothing by default)

步骤5 — 可选层（仅提供选项，默认不安装）

Step 6 — verify, then hand back

步骤6 — 验证，然后交还控制权

the variable expands in this skill's text, not in your shell — fall back to finding the file

该变量在本技能文本中展开，而非在你的Shell中——若无法展开则尝试查找文件

What NOT to do

禁止操作

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

步骤1b — 项目层（
`projects/<name>/`
）