多 AI 協作的角色協議框架 — 把「PM」「Engineer」「Reviewer」這些職能抽象出來，讓任何 AI（Claude / Gemini / Cursor / 你下個用的 LLM）都可以在任意專案上各司其職並互相抽驗。
框架的價值來自於服務、不是規範本身。
charter 的存在感應該被淡化、採用方應該感受到「事情變順了」而非「我又要記住一條紀律」。
| 無痛類型 | 含義 |
|---|---|
| 回鍋開發者無痛（lifecycle） | 不管採用方遇到什麼狀態 — 全新接入 / 升版 / 棄用 / 停用一段時間後重新採用 — charter 都隨時支援、無摩擦銜接 |
| 小白無痛（onboarding） | 由淺入深、越用越愛；最基本的紀律 charter 守住、但啟用方式要極度簡易；採用方不該記 prompt — charter 主動引導、user 最少做 1 個動作 |
- 解決重複溝通：跨 AI 接班 / 跨 session 重啟 / 跨角色交付 / 採用方對 AI 反覆糾正 — 這些重複溝通的成本，charter 透過條款 + 模板 + 紀律統一處理
- 由 charter 引導採用方：不是 user 找 prompt 模板貼給 AI、而是 user 把入口檔給 AI、AI 主動引導 user
- 培養魚塭、不討魚：拒絕為了眼前舒服（quick fix）犧牲未來舒適（系統性無痛）；每個 release 都對齊「是不是讓未來採用方更舒適」而非「現在這個採用方夠用就好」
每次條款 / spec / templates 修訂時，maintainer 必對照三題：
- 這個修訂讓回鍋開發者體驗加分還是減分？
- 這個修訂讓小白接入門檻降低還是升高？
- 這個修訂解決新的重複溝通、還是新增了採用方要記的東西？
任一答「減分 / 升高 / 新增負擔」 → 修訂須降級 / 改寫 / 重新設計。
採用方應該知道「哪些紀律由結構強制守、哪些由多 actor 互檢守、哪些靠單 actor 自律守」 — 對抗「LLM 不可矯正」前提下的循環依賴設計、又能主動加固弱保證項。
charter 既有條款體系隱含雙軸正交分類（dogfood-driven hardening 第十四循環 multi-perspective 評估的結構師金礦顯化）：
| 層 | 強度 | 設計意涵 |
|---|---|---|
| 結構強制 | 強 | 不依賴 LLM「記得」、檔案 / 編譯器層級攔截 — 違反實質難（即使違反、會被退稿留審計痕跡） |
| 多 actor 互檢 | 中 | 至少有第二個 actor（另一 AI / 第二 context / user）參與檢查 — 違反會被攔截 |
| 單 actor 自律 | 弱 | 依賴 LLM 紀律、AI 在當下選擇不違反 — 違反不會被自動攔截、僅留 violation-reflection 集體記憶 |
→ 對齊 core/violation-reflection.md §2「LLM 個體不重要、集體記憶才重要」設計方向 — 不以「物理強制 LLM」為解、以「sandbox + log + 集體演化」為解。
init（接入流程）/ runtime（日常工作）/ post-upgrade（升版後）/ handoff（交接）
每條 charter 條款帶 (物理依據, 檢測時點) 雙標籤 — 詳見各條款檔開頭 blockquote 段（v0.8.2 加）。
「單 actor 自律」格的條款 — 紀律保證等級最弱、需要採用方注意：
| 條款.段 | 弱保證點 | 加固路徑（推薦） |
|---|---|---|
core/role-separation §3.5 繞路禁令 |
AI 透過 sub-agent / 代理 等手段間接違反角色約束 | 升級到「多 actor 互檢」：auditor / Phase 5b validator 抽驗 |
core/multi-role-tracking §3.4 身份穩定承諾 |
AI 未經 user 授權切角色 | 同上 — 升級到 multi-actor |
core/init-template §3.3.2 step 7 七步驟自驅 |
self-instantiation 由 AI 自跑自驗 | step 5 強制 doctor schema 驗證 + Phase 5b 多 actor 互檢（v0.7.0 ship） |
core/violation-reflection 補交反省 |
AI 違規後 AI 自驅補交 | 不升級 — 此條款的價值就在「集體記憶」、不為「矯正」（charter 設計方向） |
core/handoff-chain 接班方七步驟自驅 |
接班 AI 無外部攔截 | 升級：cross-ai-handoff 強化抽驗繼承 + working-stack-discipline DRAFT 必為檔案 |
core/evidence-first 隱性 bug 嚴禁盲猜 |
AI 自律不去猜 | 強化抽驗時要求顯化推斷依據（升級到多 actor） |
→ 設計方向：弱保證項應持續升級到「多 actor 互檢」或「結構強制」 — charter 11 個 dogfood-driven hardening 循環就是此演化路徑的物理載體（如 v0.7.0 Phase 5b 把 init 階段「自抽自驗」從單 actor 升維到多 actor、v0.8.0 axiom 紀律從「自律」升「結構強制」三層雙重防禦）。
charter 自 v0.5.7 起的演化軌跡 — 把弱保證項持續升維到結構強制 / 多 actor 互檢：
| 弱保證項 | 升維 ship | 升維到 | 對應 dogfood signal |
|---|---|---|---|
| F6 surface vs structural（紀律執行） | v0.7.0 → init Phase 5b CHECK 7 | 多 actor 互檢（init 端 fail-fast） | #4（YC + 公司接入） |
| Self-instantiation 結尾自驗 | v0.5.10 → init-template §3.3.2 step 5 強制 doctor schema 驗證 | 多 actor 互檢（doctor 端） | #4 |
| Axiom status 二態紀律 | v0.8.0 → init Phase 5b CHECK 7 ext + doctor §3.9 + verify §3.4 三層雙重防禦 | 多 actor 互檢（三層） | #23 |
| Vendor schema（toml 扁平 / md 純 markdown） | v0.7.4 spec → v0.8.0 實作 → doctor §3.8 E801/W802 | 多 actor 互檢 | #16 |
| 採用方文檔變更歷史 sync | v0.7.2 文檔層 checklist → v0.8.1 doctor §3.10 W901 | 多 actor 互檢 | #6 / #24 |
| _role.md PROVISIONAL/ACTIVE 二態 | v0.10.0 → commit-hook H1（reject、user 授權字樣 binary 攔截） | 結構強制（git pre-commit binary） | #35 |
| F-mode 雙寫（reflection 個體層 + failure_mode_log 集體層） | v0.10.0 → commit-hook H2 + H5（reject） | 結構強制 | #33 / #42 |
| Reflection 檔名 regex / sprint 編號邊界 | v0.10.0 → commit-hook H3 reject + H4 warn | 結構強制 + 軟 advisory | #43 / #44 |
| Cross-AI handoff directive header | v0.10.0 → commit-hook H6 warn + cross-ai-handoff §3.3 | 結構強制（warn）+ 多 actor | #45 |
| F6 強制必啟集合（profile.yaml.enable_modes） | v0.10.2 → commit-hook H7（schema-driven、tools/profiles/_required.yaml source of truth） |
結構強制（binary 不可繞） | #46 / #31 / #52 |
| Charter version 主動通知（init step 0.5） | v0.10.1 → init-template §3.3.2 step 0.5 三分支 | 多 actor 互檢（init 端 advisory） | #47 |
| Spec-as-data 四欄結構 + 真實 stdout 證據要求 | v0.10.3 → 全 spec sweep（doctor §3 + verify §3.1-§3.5 + diagnose-remediate-protocol §2.4） | 多 actor 互檢（spec 提供反例段、降 simulated 率） | #46 / #31 |
| 弱保證項 | 候選升維路徑 | Ship 議程 |
|---|---|---|
| 採用方文檔層 sync 全自動化（變更歷史 / charter_version 對齊全自動） | 升 H8 commit-hook（schema-driven + 採用方 fork 文檔內容完整性） | v0.11.x（user 確認 #6/#24/#30 累積至 ≥ 4 次後） |
| Spec / condition 結構合規 lint | 寫 maintainer-only tools/charter-spec-lint.sh（L1 tool spec 四欄結構 + L2 core/*.md 雙軸 blockquote） |
v0.10.3 ship（本 release 議程 4） |
| Spec / condition 結構合規 schema 自動派生 | lint binary 自動掃 frontmatter 派生「依賴 LLM 紀律的條款清單」（取代本表手寫） | v0.11.x（雙軸 framing 第四段） |
| 個體學習迴圈雙寫雙讀紀律 | 升 commit-hook 多重檢項（H2/H5 已部分 cover） | 觀察累積 |
| Charter dogfooding 啟動（charter repo 自身過 H1-H7 + maintainer-specific H8/H9） | dogfood 完整 LIVE | v1.x 議程 |
→ 設計學意義：本表是 charter「結構強制升維 trajectory」的單一視覺化載體 — 每次新 ship 對應 row 加一條、長期可看到 charter 從「純 spec 規範 + LLM 自律」漸進到「spec + 結構強制兜底」的演化曲線。對齊 dogfood signal #27「spec-driven 與 LLM 自律 循環依賴」結構性解。
對於「值類規範」（如「profile.yaml 某欄位必含某值」）：v0.10.2 H7 立 prior art —
傳統做法 schema-driven 做法（H7 起手）
─────── ──────
F7 加 → 改 doctor spec F7 加 → 改 _required.yaml 一處
→ 改 verify spec → 改 hook 補 5 行 inline check
→ 改 init spec → 採用方 git pull 即傳播
→ 改 hook 加 H8
→ 改 walkthrough （三層 spec 自動失效時 binary 兜底）
→ 採用方手動同步
→ 未來其他「值類規範」（如 enabled_conditions 對齊 / mapping.yaml 必填欄位 / vendor schema 等）都可走同 pattern propagate、不需要每加一個就改五處 spec / 加新 H 號 binary。對應 user 2026-05-06 LIVE 提問「以後如果有 F7 這方式一樣可以解決嗎」結構性解。
每次條款 / spec 修訂時、雙軸矩陣提供額外對齊軸：
- 新加的條款 / spec 落在哪格？（強制 vs 互檢 vs 自律 × init/runtime/post-upgrade/handoff）
- 是否能把既有「弱保證」格升級到「中保證」/「強保證」格？
- 若新加在「弱保證」格、是否累積觀察、找加固路徑？
對應 dogfood signal #22 候選紀律「v0.x 結構修正 >> 規範補丁」 — 結構修正 = 升維到多 actor / 結構強制；規範補丁 = 加更多單 actor 自律紀律。
charter 既有設計「不讓 user 記」紀律完整 — 但對 AI 角度的對稱補完缺：不讓 AI 自己也記不住自己的錯。v0.9.0 補完此對稱。
charter v0.7.3 北極星「charter 引導採用方、不讓 user 記」對採用方角度落地完整（walkthrough + verify 工具 + spec-as-data）— 但對 AI 角度漏：
| 北極星紀律 | 對採用方角度（既有 ✅） | 對 AI 角度（v0.9.0 補完） |
|---|---|---|
| 不讓 user 記 | walkthrough + verify 工具 + spec-as-data | 個體學習迴圈（individual-learning-loop） |
| 回鍋無痛 | 跨多版本升版 walkthrough + 跨版本到最新 | AI 跨 session 學習迴圈（同上） |
| 解決重複溝通 | charter 引導採用方 | 個體 / 集體記憶雙寫紀律（同上） |
| 培養魚塭 | 跨 vendor 純規範 framework | 不變（vendor-agnostic 維持） |
對齊 core/violation-reflection.md §2「LLM 個體不重要、集體記憶才重要」設計方向 — v0.9.0 把此精神完整化：「設計成集體記憶才重要、但個體記憶仍要寫 + 強制讀」雙寫紀律。
| 軸 | 對應條款 | 補完狀態 |
|---|---|---|
| 軸 1：跨 session 同身份接班 | core/working-stack-discipline §5 |
✅ v0.5.7 |
| 軸 2：session 末交接鏈 | core/handoff-chain |
✅ v0.5.x |
| 軸 3：跨 AI 廠商接班 | core/cross-ai-handoff |
✅ v0.5.x |
| 軸 4：個體 AI 跨任務 / 跨 session 學習迴圈 | core/individual-learning-loop |
✅ v0.9.0 補完 |
→ 接班場景四軸從 v0.5.7 開啟（軸 1）到 v0.9.0 第 4 軸補完、完整閉環、第 13 個架構級概念誕生。
| 層 | 物理位置 | 何時寫 | 何時讀 |
|---|---|---|---|
| 集體層 | state/failure_mode_log.md + institutional-memory/*.md |
命中 F-mode 時、由抽驗方退稿並寫 | 跨 session 接班 / 設計新條款時參考歷史 |
| 個體層（v0.9.0 加） | roles/<role>/reflections/<YYYY-MM-DD>_<f-mode>_*.md |
命中 F-mode 時、AI 必雙寫個體層 reflection | 每次 self-instantiation step 0 強制讀（init-template §3.3.2 八步驟） |
→ 雙寫紀律強制（不可只寫集體 / 不可只寫個體）、雙讀紀律強制（init step 0 必讀個體層 + 集體層 + IM 層）。
對應 dogfood signal #34（user 2026-04-30 LIVE 公司專案接入抓到「個體學習迴圈框架必備」、user 直接條款化、不走累積門檻）。
當你的工作流不只一個 AI（例如 Gemini 當 PM、Claude 當 Engineer），你會撞到三個問題：
- 角色綁死特定 AI：「我們的 PM 規則」其實只有 Gemini 跑得對
- 協議綁死特定專案：搬到新專案要重新發明所有紀律
- AI 能力差異無顯式描述：Claude 有 hook、Gemini 沒 hook，協議在後者上會失效
AgentCharter 把這三軸正交化：
Charter (this repo) ← 跨 AI、跨專案、跨角色的最大公約數
│
├── core/ ← 通用條款（職責、抽驗、失敗模式、交付契約…）
├── roles/<role>/ ← 各角色職能定義 + 各 AI 的實作版
├── examples/<project>/ ← 真實專案的對照表（IRON ↔ Charter）
└── templates/ ← 生成 /<role>-init 等的模板
| 公理 | 含義 |
|---|---|
| A1. 角色 ⊥ AI | 「PM」是抽象職能，可由任何 AI 扮演；切換扮演者不該改變協議 |
| A2. AI ⊥ 角色 | 同一個 AI 可在不同專案扮演不同角色；身份無黏著 |
| A3. 專案 ⊥ 框架 | 框架不知道「金融 / 醫療 / SaaS」差異；領域特定條款（如 IRON 風控）放專案內，框架只提供「領域安全公理槽位」（Domain Safety Axiom Slots） |
| 約定 | 含義 |
|---|---|
| 共同記憶根目錄 | 多 AI 共享資產必須位於單一根之下，預設叫 agent-commons/。看到此目錄 ＝ 此專案採用 AgentCharter。詳見 core/common-memory-root.md |
| 檔案 | 一句話描述 |
|---|---|
role-separation.md |
角色互鎖原則 — 寫程式碼權與結案宣告權對稱分離 |
audit-rights.md |
抽驗權 — 結案宣告默認待抽驗，工程師抽驗權不得放棄 |
failure-modes.md |
F1〜F6 失敗模式分類（假宣告 / 假 hash / 捏造數據 / 編號偏差 / 規則記憶失效 / F6 未驗證即宣告就緒含 surface-level vs structural-level sub-pattern v0.7.0） |
escalation-protocol.md |
連續失敗 → 強化抽驗 → 結構性失靈 → 使用者裁決 |
role-conflict-resolution.md |
角色決策分歧裁決協議（區隔 escalation：分歧無對錯，雙向 L0/L1/L2 階梯） |
multi-role-tracking.md |
1 AI 兼 ≥ 2 角色的審計規範（離岸/上岸宣告、身份戳、自抽自驗禁令） |
domain-axiom-slot.md |
領域公理槽位的位階 / 撰寫紀律 / 違反處置（與 core 衝突時領域公理優先） |
versioning-migration.md |
SemVer 對 charter 的具體含義 + 升級遷移流程 + 多 AI 版本一致性 |
evidence-first.md |
隱性 Bug 嚴禁盲猜；參數嚴禁假設值 |
structural-anti-fabrication.md |
事實宣告必含 stdout 區塊；不靠 AI 自我誠實，靠文檔結構強制 |
violation-reflection.md |
違規退稿後須補交反省；反省價值在「未來 AI / 集體記憶」而非矯正當前 AI |
charter-config.md |
mapping.yaml + profile.yaml schema；可插拔啟用條款，不需重組目錄 |
common-memory-root.md |
架構級約定 — 多 AI 共享資產必須位於單一根（預設 agent-commons/）；採用識別 |
output-mode-protocol.md |
eco / verbose 雙段式輸出 + 自動升級條件 |
completion-delivery.md |
工程師完工須附「PM 驗收測試計畫」（Directive Header / 雙保險 / 危險度標籤 / 期望錨點 / 失敗解讀表） |
handoff-chain.md |
Session 交接鏈與必含項目 |
cross-ai-handoff.md |
跨 AI 廠商接班：退出方轉移職責 + 接班方接收職責 + 強化抽驗狀態傳遞 |
working-stack-discipline.md |
DRAFT 暫存堆疊 + save 同步 git commit + session 內物理中斷再續（同身份接班） |
maintainer-discipline.md |
framework 維護者紀律（位階特殊：對採用方無關，三 preset 預設關）— spec sync check + DRAFT 紀律對 maintainer 也適用 |
init-template.md |
Role Init Mandate — 四大職責 + 多 AI 具象化 + AI 自我具象化機制（v0.5.10：七步驟含 step 5 schema 驗證強制點 / v0.7.0：step 6 簽名 Status 必為 PROVISIONAL/ACTIVE 二態 + slash command 引用紀律禁絕對路徑 / v0.9.0：七步驟 → 八步驟、加 step 0「讀過去違反紀錄」對應個體學習迴圈） |
ai-vendor-onboarding.md |
新 vendor / 新角色接入「邀請制」四步驟（v0.6.0）— 禁 charter 預先寫死 vendor 層；charter 寫概念層 → 邀請 vendor 寫 vendor 層 → 既有 vendor 校正 regression → maintainer 簽收 |
individual-learning-loop.md |
（v0.9.0 加、第 13 個架構級概念、補完接班場景四軸的第 4 軸） — 個體 AI 跨任務 / 跨 session 學習迴圈：寫紀律（雙寫個體 roles/<role>/reflections/ + 集體 state/failure_mode_log.md）+ 讀紀律（init step 0 強制讀）+ 跨 session 學習迴圈（接班 AI 紀律繼承） |
diagnose-remediate-protocol.md |
（v0.9.0 加）SSS S3 架構級條款化 — spec-as-data 結構（合規規定 / 修補方向 + 約束 / 反例 / 真實 stdout 證據）+ 弱保證項清單派生 + commit hook vendor 邀請制加固 + 真實 stdout 證據要求（純文字 PASS = violation-reflection §1 假宣告）；v0.10.0 §4 從精神 ship 實作層（git 原生 hook + agent-commons 共用 script、vendor 中立架構） |
adoption-lifecycle.md |
（v0.9.0 加）5 階段 lifecycle 完整化 — 全新接入 / 升版 / 棄用（含「保留最後的溫柔」精神）/ 重新採用 / vendor 升級 path 三路徑（A 維持現狀 / B 開 issue / C AI 自驅修復對齊 SSS S1 子集） |
condition-mutability.md |
（v0.9.0 加）condition mutability 紀律本體 — 三層 mutability（IMMUTABLE-by-AI / APPEND-ONLY / FULL-MUTABLE）+ 3-strike 刪除協議 + user-initiated consolidation + AI 修訂權限分層 |
每個角色含：
_spec.md— 該角色「做什麼 / 不做什麼 / 與其他角色的邊界」<ai-vendor>.md— 該 AI 在扮演此角色時的執行細節（如 Claude 用 hook，Gemini 用主動讀檔）
當前提供：
採用方角色（採用方視具體場景啟用）：
roles/engineer/_spec.md+roles/engineer/claude-code.md— Engineer 概念層 + Claude Code 工程師實作（v0.1 reference impl）roles/pm/_spec.md+roles/pm/gemini-cli.md— PM 概念層（v0.6.0 加 §3.3/§3.4 漸進 deprecate 抽驗）+ Gemini CLI PM 實作（v1.1，含 §3.5 sub-agent 跨界禁令）roles/validator/_spec.md— 抽驗權專職載體；漸進接管 PM 抽驗職責（v0.6.0 概念層 / v0.7.0 §3.6 擴 init 階段抽驗 — 採用方半邊 Phase 5b 載體）；vendor 層待邀請制流程
Maintainer-only 角色（採用方無關，charter repo 自身維護用）：
roles/auditor/_spec.md— charter repo 自身一致性抽驗；對應maintainer-discipline §3.1執行載體（v0.6.0 概念層 / v0.7.0 §8 加與 validator 對稱性反向引用）；vendor 層待邀請制流程
5 步流程：
# Step 1: clone charter
git clone https://github.com/moerasermax/AgentCharter ~/.agentcharter
cd ~/projects/<your-project># Step 2: 編 agent-commons/protocols/<YOUR_AXIOM>.md（先寫好鐵律；
# init Phase 5b 會驗 axiom 物理存在）
# Step 3: prompt AI 跑接入（AI 完成 + 自具象化 /charter-init）
我採用了 AgentCharter，charter 在 ~/.agentcharter/。
請依 ~/.agentcharter/tools/init-spec.md 跑接入流程：
- preset: standard
- domain-axioms-path: protocols/<YOUR_AXIOM>.md
- domain-axioms-alias: <SHORT_NAME>
完成後請順便具象化為 /charter-init slash command（依 init-template §3.3）。
# Step 4: prompt 雙 AI 自我具象化角色 init（依 init-template §3.3）
# Step 5: prompt AI 跑 doctor 驗證
請依 ~/.agentcharter/tools/doctor-spec.md 跑健康檢查。
# Step 6（v0.10.0+ 推薦）: 安裝 commit hook（vendor 中立 binary 攔截）
bash ~/.agentcharter/tools/vendor/commons/install-git-hooks.sh
v0.5.9 起 framework 不附 python / npm 等實作工具（純規範框架）。所有工具動作由 AI 依對應 spec 自具象化（對齊 A1「角色 ⊥ AI」+「framework 不代生成」原則）。
v0.10.0 例外：
tools/vendor/commons/charter-commit-checks.sh+install-git-hooks.sh是 reference bash 實作（不違反「不附 binary」精神 — bash script 是 git hook 接口層 + vendor 中立、charter 不能用 AI spec 表達 git pre-commit 觸發語意）。詳見tools/commit-hook-spec.md。
詳細指引見 QUICKSTART.md（5 分鐘小白入門）+ TUTORIAL.md（reference 工具書）。
本框架由 CryptoBot 專案的 S70 Dashboard PnL 誤判事件後沉澱啟動 — 該事件中 PM 連續 ≥7 次假宣告觸發強化抽驗 → 結構性失靈 → 使用者裁決。事件結束後，使用者要求把工程師（Claude）的協作守則抽象成跨 AI 框架。
詳見 examples/cryptobot/mapping.md。
GOVERNANCE.md— 誰可 merge、衝突如何處理、版本權威CONTRIBUTING.md— 如何提交新角色 / 新失敗模式 / 新 AI 實作版CHANGELOG.md— 版本紀錄
私有專案；公開化決定保留至 v1.0。
| 檔案 | 受眾 | 用途 | 何時讀 |
|---|---|---|---|
本檔（README.md） |
任何人 | 介紹 charter 是什麼 + 三公理 + 條款列表 | 第一次接觸 |
QUICKSTART.md |
人類採用方（小白） | 5 分鐘讀完，30 分鐘跑通第一個任務 | 接入時 |
TUTORIAL.md |
人類採用方（深入） | reference 工具書（章節獨立，可跳讀；含 troubleshooting） | 卡關 / 想深入 |
ADOPTION.md |
該團隊的 AI | AI 自含 context 採用指南（密集格式） | AI 接班時 |