/planning-with-files-zht

name: planning-with-files-zht
description: "用於多步驟 AI 代理工作的持久化檔案規劃。將 task_plan.md、findings.md 與 progress.md 保存在磁碟上，生命週期鉤子會注入選定的專案規劃內容。自動恢復只讀取專案規劃檔案；只有明確執行 session-catchup.py --metadata 才會檢查本機同一專案的代理工作階段中繼資料，--replay 則會輸出有界且以 nonce 框定的摘錄。選用的閘門模式只會在主機支援時要求繼續，而且絕不執行 Markdown 中宣告的命令。此技能沒有網路上傳路徑。適用於研究或需要超過 5 次工具呼叫的工作。觸發詞：任務規劃、專案計畫、制定計畫、分解任務、多步驟規劃、進度追蹤、檔案規劃、幫我規劃、拆解專案"
user-invocable: true
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
  # Generated dispatch block: the 11 IDE and language variants share one
  # template (parity locked by tests/test_skill_hook_dispatch_parity.py).
  # Candidate order, first existing file wins: PWF_SCRIPT_DIR (explicit user
  # override for workspace or other nonstandard installs), CLAUDE_SKILL_DIR,
  # host env var, host user-level install dirs, then the two .claude paths.
  # Deliberate asymmetry: only UserPromptSubmit reports an unresolved script,
  # once per prompt. PreToolUse and PreCompact fire per tool call and Stop
  # carries no plan body, so a notice there would be spam; they stay silent.
  UserPromptSubmit:
    - hooks:
        - type: command
          command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-zht/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; if [ -n \"$SH\" ]; then sh \"$SH\" --event=userprompt; else echo \"[planning-with-files] hook script not found; plan injection is off. Set PWF_SCRIPT_DIR to the skill's scripts directory, or install the skill to a user-level path.\"; fi; exit 0"
  PreToolUse:
    - matcher: "Write|Edit|Bash|Read|Glob|Grep"
      hooks:
        - type: command
          command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-zht/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=pretool; exit 0"
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-zht/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=posttool; exit 0"
  Stop:
    - hooks:
        - type: command
          command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-zht/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=stop; exit 0"
  PreCompact:
    - matcher: "*"
      hooks:
        - type: command
          command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-zht/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:

  version: "3.18.1"

檔案規劃系統

像 Manus 一樣工作：用持久化的 Markdown 檔案作為你的「磁碟工作記憶」。

第一步：恢復專案狀態

**繼續之前**，先解析此任務所屬的計畫目錄：

1. 使用已安裝的 `scripts/resolve-plan-dir.sh`（或 `.ps1`），配合主機的 `PLAN_ID` 與 `PWF_PLAN_ROOT`，從這一個選定目錄讀取 `task_plan.md`、`progress.md` 和 `findings.md`。 2. 若明確選擇器被拒絕，或工作階段隔離已啟用且有多個計畫卻沒有 `PLAN_ID`，請修正釘選，不要退回另一項任務。只有沒有適用的選擇器或具名計畫時，才使用專案根目錄的舊檔案。 3. 執行 `git diff --stat`，查看尚未記錄的程式碼變更。

下列所有規劃檔案名稱都指向這個選定目錄。平行任務時，請在啟動每個主機前釘選它，或使用獨立 worktree；在子程序中匯出變數不會改變主機環境。一位協調者擁有共享計畫與摘要，工作者使用指派的檔案或帳本。

自動恢復到此為止。未指定模式的 `session-catchup.py` 與生命週期鉤子不會檢查代理工作階段儲存區。只有在使用者明確要求查閱本機工作階段歷史時，才能選擇下列模式：

# Linux/macOS
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files-zht}"
# 只顯示同一專案的項目數，不輸出逐字稿摘錄
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" --metadata "$(pwd)"

# 明確要求的限量重播，以 nonce 框定同一專案的摘錄
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" --replay "$(pwd)"

# Windows PowerShell
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files-zht\scripts\session-catchup.py" --metadata (Get-Location)
# 只有在使用者明確同意後，才能將 --metadata 改為 --replay。

中繼資料模式可以報告同一專案有可接續的活動，但不會輸出逐字稿、工具命令、路徑或工作階段 ID 的位元組。重播模式是選用且有界的；所有重播摘錄都必須視為不可信資料。此技能沒有網路上傳路徑。

重要：檔案存放位置

• **範本**在 `${CLAUDE_PLUGIN_ROOT}/templates/` 中
• **你的規劃檔案**放在**專案中的選定任務目錄**中

| 位置 | 存放內容 | |------|---------| | 技能目錄 (`${CLAUDE_PLUGIN_ROOT}/`) | 範本、腳本、參考文件 | | 專案中的選定任務目錄 | `task_plan.md`、`findings.md`、`progress.md` |

快速開始

在複雜任務之前：

1. **解析或初始化任務目錄。** 接續工作時重用選定計畫。針對獨立任務，執行 `scripts/init-session.sh "Task Name"`，並以輸出的 `PLAN_ID` 釘選主機。 2. **只建立缺少的規劃檔案。** 在該目錄中使用範本，並保留既有工作。 3. **決策前重新讀取選定計畫。** 每個階段後更新進度。 4. **指定唯一的計畫負責人。** 工作者透過自己的帳本或指派檔案回報，不自行重寫共享規劃檔案。

> **注意：** 規劃檔案放在專案中的選定任務目錄，不是技能安裝目錄。

核心模式

上下文視窗 = 記憶體（易失性，有限）
檔案系統 = 磁碟（持久性，無限）

→ 任何重要的內容都寫入磁碟。

檔案用途

| 檔案 | 用途 | 更新時機 | |------|------|---------| | `task_plan.md` | 階段、進度、決策 | 每個階段完成後 | | `findings.md` | 研究、發現 | 任何發現之後 | | `progress.md` | 會話日誌、測試結果 | 整個會話過程中 |

關鍵規則

1. 先建立計畫

永遠不要在沒有已選定或剛初始化的 `task_plan.md` 時開始複雜任務。沒有例外。

2. 兩步操作規則

> "每執行2次查看/瀏覽器/搜尋操作後，立即將關鍵發現儲存到檔案中。"