Levix-Digital/plan-memory

📐 專案方案記憶技能（plan-memory）

路徑：<skills_root> 是包含此技能（即 SKILL.md 所在資料夾的上一層）的資料夾。執行命令時請使用真實的絕對路徑。

plan-memory 技能為每位參與專案的人員，保留 100% 完整、未經壓縮的架構方案、策略藍圖與多步驟實施計畫。

• 真相來源：每個方案在專案儲存庫中對應一個 Markdown 檔案，位於 docs/plans/<plan_id>.md（包含 YAML 前置資料與方案主體）。方案會與程式碼一同進行版本控制、審查與合併。可透過專案的 .dev-cycle.json 中的 "plans_dir" 來變更資料夾位置。
• 搜尋索引：本機 ChromaDB 位於 ~/.ai-code-agent-memory/plan-memory/db（可透過 PLAN_MEMORY_DB 環境變數覆寫），集合名稱為 plan_index。此索引是可拋棄的：每次執行命令時都會根據檔案（透過 SHA-256 雜湊）重新同步，而 rebuild_index（引擎指令）則會完全重建它。
• 專案：從當前目錄的 Git 儲存庫（或 --dir 參數指定的目錄）解析：優先讀取 .dev-cycle.json 中的 project_name，否則使用儲存庫資料夾名稱，並正規化為 kebab-case。--project 參數可強制覆蓋。
• 層級：待辦事項清單（docs/BACKLOG.md）無需探索即可迅速捕捉工作，並歸類於史詩（epics）之下；藍圖（docs/ROADMAP.md）則列出發佈順序，並將項目指派到各個發佈版本中；方案是在使用者提升（promote）待辦項目時建立，包含發現與規劃過程（詳見「待辦事項清單」與「藍圖」部分）。
• Spec Kit 信封：當專案使用 Spec Kit 時，功能方案即為一個信封（spec_dir），指向一個 Spec Kit 資料夾（specs/NNN-slug/），其中包含詳細規格。搜尋、漂移偵測與 get_plan 會讀取該資料夾中的工件與方案內容（詳見「搭配 Spec Kit 的方案」）。
• 核心原則：零壓縮 / 零遺失。方案會以其完整樣貌（Mermaid 圖表、表格、步驟、公式、理由）被保存，作為每位開發者與每個會話的持久知識。

---

🏛️ 方案檔案格式

---
plan_id: my_app_blueprint_v1_2_0_two_stage_search
project: my-app
title: 具本地重新排序的兩階段搜尋
kind: feature              # feature（預設）| bug
version: v1.2.0
status: in_progress        # draft | planned | active | in_progress | completed | superseded
author: Jane Doe           # 建立者的 git user.name
created_at: '2026-10-15T16:36:00'
updated_at: '2026-10-16T09:10:00'
session_id: 8abbc3bf-...   # 構思此方案的對話（選填）
tags: [search, reranker]
supersedes: my_app_blueprint_v1_1_0_search
superseded_by: null
parent_plan_id: null
backlog_items: [FEAT-004]  # 此方案所交付的待辦項目（選填）
spec_dir: specs/004-reranker  # 包含方案詳細規格的 Spec Kit 資料夾（選填）
milestones:
- name: M1 執行時期基礎
  done: true
  done_at: '2026-10-15'
  by: Jane Doe
- name: M2 重新排序器
  done: false
status_log:
- at: '2026-10-15T16:36:00'
  by: Jane Doe
  status: active
  note: 方案已建立
---

# 方案標題

...以 Markdown 撰寫的完整方案主體...

• 腳本僅會改寫前置資料；方案主體由 save_plan 寫入一次（或手動編輯）。里程碑與狀態的變更會產生小而可讀的差異（diff）。
• 檔案名稱即為方案 ID。譜系欄位（supersedes、superseded_by、parent_plan_id）參考其他方案 ID。
• 腳本不會執行提交（commit）。代理應將方案檔案連同其所描述的工作一起提交（詳見「團隊工作流程」）。

---

⚙️ 命令

所有腳本均位於 <skills_root>/plan-memory/，並接受 --dir <專案目錄>（預設為當前目錄）與 --project <名稱> 參數。

1. 儲存／更新方案並建立譜系（save_plan）

將完整方案（未經刪減或摘要）寫入 docs/plans/<plan_id>.md。若儲存已存在的 ID，則會更新標題、主體與欄位，但保留作者、建立日期與里程碑進度。--supersedes 會將舊方案標記為 superseded。save_plan 在原生引擎上執行。在 sh shell（Linux、macOS、Git Bash）中：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory save_plan \
  --title "整合藍圖：Python -> Rust、模型路由器與模型工具包" \
  --file "path/to/plan.md" \
  --version "v1.2.0" \
  --tags "roadmap,rust_refactor,model_router" \
  --milestones "優先級 1,優先級 2,里程碑 3" \
  --status "active" \
  --session-id "<session_id>" \
  --supersedes "<old_plan_id>"

在 PowerShell 中，請改為執行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory save_plan [參數]。 選項：--id（預設為 <project>_<title> 的 slug 格式）、--parent-id、使用 --content 替代 --file、--kind feature|bug、--backlog-items "BUG-001,FEAT-002"（連結項目，使其狀態變為 planned）、--spec-dir specs/NNN-slug（此方案即為該 Spec Kit 資料夾的信封）。

2. 里程碑與進度追蹤器（check_milestone）

check_milestone 在原生引擎上執行。在 sh shell（Linux、macOS、Git Bash）中：

# 列出最新 active 方案的進度與檢查清單（或使用 --id <plan_id>）：
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --list

# 將里程碑標記為完成（會記錄日期與作者）：
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "優先級 1" --notes "透過 PR #319 完成"

# 將里程碑恢復為待處理：
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "優先級 1" --uncheck

在 PowerShell 中，請改為執行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory check_milestone [參數]。 完成第一個里程碑會將狀態為 active 的方案轉為 in_progress；完成最後一個則會將其轉為 completed。

3. 架構漂移偵測器（detect_drift）

將任何實作提案、問題或新的提示詞與當前生效方案進行比對：語意相似度、里程碑涵蓋範圍與順序，以及專案自身的反模式規則。detect_drift 在原生引擎上執行。在 sh shell（Linux、macOS、Git Bash）中：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --proposal "優先級 1：用 Rust 構建原生 ReAct 協調器，取代 Python LangGraph"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --file "path/to/proposal.md" --strict   # 若衝突則退出碼不為 0

在 PowerShell 中，請改為執行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory detect_drift [參數]。

反模式規則位於專案 .dev-cycle.json（從 --dir 往上尋找）的 drift_rules 鍵中。若無規則，則僅檢查相似度與里程碑。

"drift_rules": [
  { "tech": "langchain", "conflict_msg": "基準方案已移除 LangChain。" },
  {
    "tech": "parallel database",
    "negative_markers": ["single source", "settings.db"],
    "proposal_allow": [],
    "conflict_msg": "提案暗示使用平行資料庫，違反了單一事實來源原則。"
  }
]

當生效方案（active / in_progress）提及某個 tech 並伴隨拒絕標記，且提案也提及該 tech 但未包含允許的短語時，規則便會引發衝突。

• negative_markers（選填）：表示拒絕的詞彙。預設值為：remove、replace、without、forbidden...以及它們的葡萄牙文對應詞。在既有方案尚未翻譯完成前，會保留這些詞彙。
• proposal_allow（選填）：使提及可被接受的短語。預設值為：without <tech>、remove <tech>、replace <tech>...以及它們的葡萄牙文對應詞。

4. 列出方案（list_plans）

list_plans 在原生引擎上執行。在 sh shell（Linux、macOS、Git Bash）中：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory list_plans [--status active] [--kind bug]

在 PowerShell 中，請改為執行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory list_plans [參數]。

5. 讀取完整方案（get_plan）

get_plan 在原生引擎上執行。在 sh shell（Linux、macOS、Git Bash）中：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan --id "<plan_id>"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan                  # 最新的 active 方案

在 PowerShell 中，請改為執行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory get_plan [參數]。

6. 語意搜尋（search_plans）

search_plans 在原生引擎上執行。在 sh shell（Linux、macOS、Git Bash）中：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory search_plans --query "如何在意見中實作模型路由器" [--limit 5] [--all-projects]

在 PowerShell 中，請改為執行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory search_plans [參數]。

7. 更新生命週期狀態（update_plan_status）

設定方案狀態，將其記錄在狀態日誌中，並同步更新連結的待辦項目。update_plan_status 在原生引擎上執行。在 sh shell（Linux、macOS、Git Bash）中：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory update_plan_status --id "<plan_id>" --status "completed" --notes "優先級 1 和 2 已交付。"

在 PowerShell 中，請改為執行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory update_plan_status [參數]。

8. 匯出（export_plan）

將方案複製到其他位置，格式可為 JSON 或 Markdown（可選擇是否包含前置資料）。export_plan 在原生引擎上執行。在 sh shell（Linux、macOS、Git Bash）中：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory export_plan --id "<plan_id>" --format json --output-dir "out/"

在 PowerShell 中，請改為執行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory export_plan [參數]。

9. 重建索引（rebuild_index）

rebuild_index 在原生引擎上執行。在 sh shell（Linux、macOS、Git Bash）中：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory rebuild_index [--project <名稱>] [--dir <路徑>]

在 PowerShell 中，請改為執行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory rebuild_index [參數]。

---

📥 待辦事項清單（backlog）

規劃的第一個層級：一個 Markdown 檔案（位於 .dev-cycle.json 中 backlog.file 所指定的位置，預設為 docs/BACKLOG.md），由第一次執行 add 命令時從 templates/BACKLOG_TEMPLATE.md 範本建立。

## 錯誤 | 功能 | 改善 | 調整 | 史詩 | 已關閉

### BUG-001：邊境預設選取了過時的模型 ID
- **嚴重性**：高              # 錯誤：critical | high | medium | low
- **狀態**：開啟                # open | planned | in_progress（已關閉下：done | dropped | duplicate | superseded）
- **發現於**：2026-10-16, v0.45.0, PR #333
- **方案**：-                     # 提升後的方案 ID
- **描述**：`/preset frontier` 設定為 `claude-3-7-sonnet`，供應商可能拒絕此模型。

功能（FEAT-NNN）、改善（IMP-NNN）與調整（ADJ-NNN）使用 優先級（高、中、低）而非 嚴重性。任何項目（史詩除外）都可能包含 - **Epic**: EPIC-NNN。史詩（EPIC-NNN，位於 ## Epics 章節）用來歸納完整產品的項目；它們有 優先級、狀態（open 直到關閉）、發現於 與 描述，但沒有 方案，且永遠不會被提升（promote）：其下的項目才會被提升。validate 會對那些所有項目都已關閉但仍保持開啟狀態的史詩發出警告。ID 永不重複使用：已關閉的項目會留在 ## Closed 章節下，並附上 - **Closed**: 備註（日期與拉取請求、原因、duplicate of <ID> 或 superseded by <ID>[, <ID>...]）。取代（superseded）表示項目被另一個不同且定義更佳的項目所取代（一個想法在產生後被拆分或重塑）；重複（duplicate）則表示同一個請求被記錄了兩次。

backlog 在原生引擎上執行：在 sh shell（Linux、macOS、Git Bash）中為 "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory backlog <命令> [參數]。在 PowerShell 中，請改為執行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory backlog [參數]。

任務	命令
捕捉	backlog add --type bug|feature|improvement|adjustment|epic --title "<t>" --description "<d>" [--severity S] [--priority P] [--epic EPIC-NNN] [--found-in "v1.2.0, PR #12"]
捕捉失敗的手動測試	backlog add --from-failed --run vX.Y.Z-rc.N [--severity S]
摘要（優先顯示錯誤，再顯示新的工作項目）	backlog summary [--json]
列出、顯示	backlog list [--type T] [--status S] [--epic EPIC-NNN] [--all] [--json], backlog show <ID>
變更	backlog set <ID> [--title] [--description] [--severity] [--priority] [--status] [--plan] [--epic ID|-]
提升為方案	backlog promote <ID> [<ID> ...] [--title T] [--id PLAN_ID] [--version V] 或 --into <PLAN_ID>
關閉	backlog close <ID> [--ref "PR #12"], drop <ID> --reason R, duplicate <ID> --of <ID>, supersede <ID> --by <ID>[,<ID>...], reopen <ID>
驗證	backlog validate

• 捕捉幾乎不耗費成本：不需探索，也無需建立方案。使用者可透過 /backlog 命令進行；若代理在當前範圍之外發現錯誤，則由代理執行。
• 提升會從 templates/BUG_PLAN_TEMPLATE.md（若所有項目皆為錯誤：包含重現步驟、證據與根本原因、修正設計、回歸測試）或 templates/FEATURE_PLAN_TEMPLATE.md 建立一個 draft 方案，並將項目複製到其 待辦項目 區塊中，同時建立雙向連結。探索過程會記錄在該方案中；隨後會再次儲存為 active 狀態（包含里程碑）以供核准。
• 連結的項目會跟隨其方案的狀態：當方案為 draft 或 active 時，項目狀態為 planned；方案為 in_progress 時，項目狀態為 in_progress；方案完成時（透過引擎的 check_milestone 與 update_plan_status），項目關閉為 done。
• 分類（triage）是用戶的決定：代理不得自行進行提升、丟棄或重新設定優先級。
• 腳本不會執行提交（commit），且會拒絕改寫其無法讀取結構的檔案，因此手動編輯的內容永遠不會遺失。

---

🗺️ 藍圖（roadmap）

產品依交付順序排列的發佈版本（位於 .dev-cycle.json 中 roadmap.file 所指定的位置，預設為 docs/ROADMAP.md），由第一次執行 add 命令時從 templates/ROADMAP_TEMPLATE.md 範本建立。

[因內容截斷停止翻譯]