初版

AGENTS.md

@@ -1,15 +1,31 @@
-# jsc-template — 共用 Skills（跨 AI 助理）
+# jsc-persona — AI 人格化記憶聊天（跨 AI 助理）
 
-本 repo 是一組以 **Agent Skills（`SKILL.md`）** 標準撰寫的共用 skills，可同時被 Claude Code、Codex、Antigravity、OpenCode 使用。
+本 repo 是一個以 **Agent Skills（`SKILL.md`）** 標準撰寫的 plugin，讓 AI 以「人格」的方式
+持有身分、情緒與記憶。可同時被 Claude Code、Codex、Antigravity、OpenCode 使用。
 
 ## 給 AI 助理的指引
 
-- 所有可用的 skills 位於本 repo 的 `skills/<name>/SKILL.md`。
-- 在處理任務前，先比對使用者需求與各 skill `SKILL.md` frontmatter 的 `description`，若相符請載入並依其步驟執行。
-- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc-template:<name>` 呼叫；Codex 以 `$<name>`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc-template:` 前綴，不需強制加。
-- 完整清單與每個 skill 的用途，請見 `README.md` 的「Skills 目錄」。
+- 所有 skills 位於 `skills/<name>/SKILL.md`；處理任務前先比對使用者需求與各 `description`。
+- **呼叫慣例**：Claude Code 與 Antigravity 以 `/jsc-persona:<name>` 呼叫；Codex 用 `$<name>`；
+  OpenCode 由模型依描述自動觸發。
+- 完整清單見 `README.md` 的「Skills 目錄」。
+
+## 這個 plugin 的運作前提（動手前一定要知道）
+
+1. **所有狀態變更都經過 `scripts/persona.py`**，不要手動編輯 `state/lock.json`、`.runtime/`、
+   `memory/INDEX.md`、`relations/graph.mmd`（這些由 CLI 產生）。
+2. **每個 CLI 呼叫都要帶 `--session <PERSONA_SESSION>`**，值來自 `SessionStart` hook 注入的
+   `<persona-runtime>` 區塊。帶錯或冒用其他 session 會被 `PreToolUse` hook 拒絕。
+3. **一個程序只能載入一個人格**；同一 session 的 sub agent 沿用同一把鎖。
+   要讓兩個人格對話，用 `/jsc-persona:persona-invite`（`persona-guest` sub agent + 聊天室），
+   **不要**去讀對方的人格目錄——會被 hook deny，而且那是設計上的紅線。
+4. **人格資料不在本 repo**，預設在 `~/.claude/personas/`（可用 `PERSONA_HOME` 覆寫）。
 
 ## 慣例
 
-- 新增 skill 一律放在 `skills/<name>/`，且 `<name>` 使用小寫與連字號。
+- 新增 skill 一律放在 `skills/<name>/`，`<name>` 使用小寫與連字號。
 - `description` 要寫清楚觸發條件（何時用、何時不用），這是跨助理自動載入的唯一依據。
+- Python 只用標準庫（hook 必須在任何環境都能跑，不能依賴 pip 套件）。
+- 所有面向使用者的輸出使用**繁體中文（台灣用語）**、UTF-8 無 BOM、不得出現亂碼。
+- 改動鎖或隔離邏輯（`scripts/persona_lib.py` 的 `guard_decide`／`acquire_lock`）後，
+  **必須**跑 `python3 scripts/selftest.py` 且全綠，並為新規則補一條測試。