devlog-tracker 0.25.0 → 0.27.0

package/README.md

@@ -1,6 +1,6 @@
 # devlog-tracker
 
-**版本** 0.25.0
+**版本** 0.27.0
 
 在專案中維護一份 `.devlog/devlog.md`，把每一輪對話的請求、決策與結果寫成永久紀錄。對話一 `/clear` 或換 session 就沒了；這份檔案取代那個缺口，讓工作可以中斷再接。沒下過 `/devlog-tracker:start` 時，裝著也不會動任何檔案。
 
@@ -20,119 +20,91 @@
 
 ## 安裝
 
-作為 Claude Code plugin 安裝（會自動更新）：
+三個平台對等，各自獨立安裝；同一個專案要用哪個或哪幾個都可以，但同一個平台**不要同時**用 plugin marketplace 跟 `npx init` 兩條路線，會讓 hook 觸發兩次。
+
+### Claude Code
+
+**方式一：plugin marketplace（會自動更新）**
 
 ```
 /plugin marketplace add gogogohuang/devlog-tracker
 /plugin install devlog-tracker@devlog-tracker
 ```
 
-### npx（Cursor／Codex 用）
+指令用 `/devlog-tracker:*`（例如 `/devlog-tracker:start`）。
 
-Claude Code 請用上面的 `/plugin marketplace add` 安裝方式；這個 CLI 不會設定 Claude Code。
+**方式二：npx（vendor 進專案，版本可鎖定）**
 
 ```bash
-npx devlog-tracker init
+npx devlog-tracker init --claude
 ```
 
-沒帶 `--codex`／`--cursor` 時會互動式問要裝哪個平台；在沒有 TTY 的環境（例如 CI）且沒帶旗標時，`init` 不會詢問，直接安裝所有支援的平台（codex + cursor）。也可以直接指定：
+會把 hooks 合併進 `.claude/settings.local.json`（不是 `settings.json`——合併後的指令路徑含這台機器的絕對路徑，不該 commit；`settings.local.json` 是 Claude Code 預設 gitignore 的檔案），並把 `commands/*.md` 轉成 `.claude/skills/devlog-<名稱>/SKILL.md`，用 `/devlog-<名稱>` 執行；同時在 `CLAUDE.md` 加上一段 `<!-- devlog-tracker:begin/end -->` fallback 說明。
+
+### Codex
 
 ```bash
-npx devlog-tracker init --codex --cursor
+npx devlog-tracker init --codex
 ```
 
-會把 `hooks/scripts/`、`codex/hooks/`、`cursor/hooks/`、`skills/`、`commands/`
-複製進專案的 `.devlog-tracker/`，並把對應平台的 `hooks.json` 合併進專案（不覆蓋
-其他工具已設定的 hook）。重新執行 `npx devlog-tracker init` 可以升級到套件目前的
-版本；`npx devlog-tracker status` 可以查目前裝的版本是否落後。
+會把 `codex/hooks.json` 的 `hooks` 合併進專案 `.codex/hooks.json`，並從 `commands/*.md` 產生 `.agents/skills/devlog-<名稱>/SKILL.md`，用 `$devlog-<名稱>`（或 `/skills` 選）執行；同時在 `AGENTS.md` 加上同一種 fallback 說明區塊。舊版（0.25.0）寫到 `.codex/prompts/` 的檔案會在重跑 `init` 時清掉——Codex 不讀專案層級的 custom prompts。
 
-裝 Codex 時，`init` 會從 `.devlog-tracker/commands/*.md` 產生對應的專案指令到
-`.codex/prompts/`，例如以 `/prompts:devlog-start` 啟動追蹤。也會在專案根目錄的
-`AGENTS.md` 加上（或更新）一段以 `<!-- devlog-tracker:begin/end -->` 包住的 fallback
-說明。區塊外的內容不會動，重跑 `init` 只會換掉區塊本身；區塊裡只有相對路徑，可以 commit。
+**hook 需要審核才會執行。** Codex 對新增或有變動的 hook 要求先審核；沒核准的 hook 會被直接略過，而且**沒有任何警告**，看起來就像 devlog 沒在記錄。這跟專案有沒有設成 `trust_level = "trusted"` 是兩回事，專案信任不會讓 hook 生效。
 
-裝完 Codex 之後，第一次還要在 Codex 裡核准這些 hook，否則不會記錄（見下方〈Codex（選用）〉的「hook 需要審核」）。
+- 互動模式：第一次開啟時 Codex 會提示有 hook 需要審核，核准後才會執行。之後 hook 的設定有變動（例如重跑 `init` 讓路徑或指令改變）也可能要再核准一次。
+- 非互動的 `codex exec`（CI、腳本）：未審核的 hook 會被靜默略過。`--dangerously-bypass-hook-trust` 可以讓它們跑起來，但那個旗標會略過所有 hook 的信任檢查，只適合已經自己確認過 hook 來源的自動化環境。
+- 想確認有沒有生效：`start` 之後送一則訊息，看 `.devlog/.round-current.md` 有沒有出現這一輪的 User Input skeleton；沒有就代表 hook 沒被執行。
 
-`init` 會把這台機器專屬的絕對路徑寫進 `.codex/hooks.json`、`.cursor/hooks.json` 與
-`.devlog-tracker/env.sh`。如果你把這些檔案 commit 進 git，每位隊友都要在自己的機器上
-跑一次 `npx devlog-tracker init`（路徑每台機器不同）；或者改成把 `.devlog-tracker/` 與
-產生出來的 hooks.json 加進 `.gitignore`。
+Codex 目前沒有對應「使用者中斷」（Claude Code 的 `PostToolUseFailure`／`is_interrupt`）與「這輪異常結束」（`StopFailure`）的事件，這兩種細節狀態在 Codex 上不會被標記成 `INTERRUPTED`；核心強制記錄機制（`Stop` 事件擋住未寫完的輪次）不受影響。
 
-### Cursor（選用）
+### Cursor
 
-Claude Code 仍是主要安裝方式。若要在 Cursor workspace 使用，先設定
-`DEVLOG_TRACKER_ROOT` 為本 plugin 的絕對路徑，再把 `cursor/hooks.json` 的
-`hooks` 合併進專案 `.cursor/hooks.json`。也可以把整個 `cursor/hooks/` 與
-`hooks/scripts/` vendoring 到專案，並調整 command 路徑；兩者的相對目錄必須維持可用。
+```bash
+npx devlog-tracker init --cursor
+```
 
-Cursor cloud agent 不執行 `sessionStart`，因此不會自動注入接手摘要；其他已設定的
-hook 仍依 Cursor 支援的事件執行。
+會把 `cursor/hooks.json` 的 `hooks` 合併進專案 `.cursor/hooks.json`。Cursor 沒有 slash 指令面，hooks 裝好後照 commands/*.md 的步驟手動執行對應腳本。Cursor cloud agent 不執行 `sessionStart`，因此不會自動注入接手摘要；其他已設定的 hook 仍依 Cursor 支援的事件執行。
 
-Cursor 沒有 `/devlog-tracker:*` slash 指令面；hooks 裝好後，請用與 Claude commands
-相同的腳本（`commands/*.md` 會優先讀 `CLAUDE_PLUGIN_ROOT`，否則讀
-`DEVLOG_TRACKER_ROOT`）：
+### 三平台共通
 
 ```bash
-export DEVLOG_TRACKER_ROOT=/absolute/path/to/devlog-tracker
-export CLAUDE_PROJECT_DIR="$(pwd)"
-bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/start-devlog.sh"
-bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/status-devlog.sh"
-bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/segment-watch-set.sh" 600
-bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/checkpoint-set.sh" 20
-# pause / span-open / span-close / compact / keep-move / clean / resume：見 commands/*.md
+npx devlog-tracker init
 ```
 
-### Codex（選用）
+沒帶 `--claude`／`--codex`／`--cursor` 時會互動式問要裝哪個平台；在沒有 TTY 的環境（例如 CI）且沒帶旗標時，`init` 不會詢問，直接安裝全部三個平台。也可以組合指定，例如 `npx devlog-tracker init --claude --codex`。
 
-Claude Code 仍是主要安裝方式。若要在 Codex CLI 使用，先設定
-`DEVLOG_TRACKER_ROOT` 為本 plugin 的絕對路徑，再把 `codex/hooks.json` 的
-`hooks` 合併進專案（或 `~/.codex/`）的 `hooks.json`。也可以把整個 `codex/hooks/` 與
-`hooks/scripts/` vendoring 到專案，並調整 command 路徑；兩者的相對目錄必須維持可用。
+會把 `core/scripts/`、`claude/hooks.json`、`codex/hooks/`、`cursor/hooks/`、`skills/`、`commands/` 複製進專案的 `.devlog-tracker/`。重新執行 `npx devlog-tracker init` 可以升級到套件目前的版本；`npx devlog-tracker status` 可以查目前裝的版本是否落後。
 
-**hook 需要審核才會執行。** Codex 對新增或有變動的 hook 要求先審核；沒核准的 hook 會被
-直接略過，而且**沒有任何警告**，看起來就像 devlog 沒在記錄。這跟專案有沒有設成
-`trust_level = "trusted"` 是兩回事，專案信任不會讓 hook 生效。
+`init` 會把這台機器專屬的絕對路徑寫進各平台的 hooks 設定檔與 `.devlog-tracker/env.sh`。如果你把這些檔案 commit 進 git，每位隊友都要在自己的機器上跑一次 `npx devlog-tracker init`（路徑每台機器不同）；或者改成把 `.devlog-tracker/` 與產生出來的 hooks 設定檔加進 `.gitignore`。
 
-- 互動模式：第一次開啟時 Codex 會提示有 hook 需要審核，核准後才會執行。之後 hook 的設定
-  有變動（例如重跑 `init` 讓路徑或指令改變）也可能要再核准一次。
-- 非互動的 `codex exec`（CI、腳本）：未審核的 hook 會被靜默略過。`--dangerously-bypass-hook-trust`
-  可以讓它們跑起來，但那個旗標會略過所有 hook 的信任檢查，只適合已經自己確認過 hook 來源的
-  自動化環境。
-- 想確認有沒有生效：`start` 之後送一則訊息，看 `.devlog/.round-current.md` 有沒有出現這一輪的
-  User Input skeleton；沒有就代表 hook 沒被執行。
-
-Codex 目前沒有對應「使用者中斷」（Claude Code 的 `PostToolUseFailure`／
-`is_interrupt`）與「這輪異常結束」（`StopFailure`）的事件，這兩種細節狀態在
-Codex 上不會被標記成 `INTERRUPTED`；核心強制記錄機制（`Stop` 事件擋住未寫完的
-輪次）不受影響。
-
-Codex 使用 `/prompts:devlog-<名稱>`（例如 `/prompts:devlog-start`）執行指令；它們會
-讀與 Claude commands 相同的內容。若使用的 Codex 環境沒有載入 custom prompts，仍可直接
-使用以下腳本（`commands/*.md` 會優先讀 `CLAUDE_PLUGIN_ROOT`，否則讀
-`DEVLOG_TRACKER_ROOT`）：
+若要手動裝（不透過 npx），設定 `DEVLOG_TRACKER_ROOT` 為本 plugin 的絕對路徑，把對應平台的 `hooks.json` 的 `hooks` 合併進專案設定；`commands/*.md` 會優先讀 `DEVLOG_TRACKER_ROOT`，否則讀 `CLAUDE_PLUGIN_ROOT`：
 
 ```bash
 export DEVLOG_TRACKER_ROOT=/absolute/path/to/devlog-tracker
-export CLAUDE_PROJECT_DIR="$(pwd)"
-bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/start-devlog.sh"
-bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/status-devlog.sh"
-bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/segment-watch-set.sh" 600
-bash "$DEVLOG_TRACKER_ROOT/hooks/scripts/checkpoint-set.sh" 20
+export DEVLOG_PROJECT_DIR="$(pwd)"
+bash "$DEVLOG_TRACKER_ROOT/core/scripts/start-devlog.sh"
+bash "$DEVLOG_TRACKER_ROOT/core/scripts/status-devlog.sh"
+bash "$DEVLOG_TRACKER_ROOT/core/scripts/segment-watch-set.sh" 600
+bash "$DEVLOG_TRACKER_ROOT/core/scripts/checkpoint-set.sh" 20
 # pause / span-open / span-close / compact / keep-move / clean / resume：見 commands/*.md
 ```
 
 ## 快速開始
 
-在專案裡下一次：
+在專案裡下一次（依安裝方式擇一）：
 
 ```
-/devlog-tracker:start
+/devlog-tracker:start   # Claude Code plugin
+/devlog-start           # npx init --claude
+$devlog-start           # npx init --codex
 ```
 
-之後正常跟 Claude 對話即可，每一輪結束前都會被強制檢查、補上 `.devlog/devlog.md` 的紀錄。`/clear` 之後 context 是空的；要接著做上一題，下 `/devlog-tracker:continue`。暫停、歸檔、具名搬走、狀態與 span 見下方指令表（完整 namespace，plugin 名稱是 `devlog-tracker`）。
+之後正常對話即可，每一輪結束前都會被強制檢查、補上 `.devlog/devlog.md` 的紀錄。`/clear` 之後 context 是空的；要接著做上一題，下對應的 `continue` 指令。暫停、歸檔、具名搬走、狀態與 span 見下方指令表。
 
 ## 指令
 
+下表以 plugin 的 `/devlog-tracker:*` namespace 表示；`npx init --claude` 裝的是 `/devlog-<名稱>`，`npx init --codex` 裝的是 `$devlog-<名稱>`，指令內容相同。
+
 | 指令 | 做什麼 |
 |---|---|
 | `/devlog-tracker:start` | 跑腳本建立 `.devlog/.enabled`（缺的 state 檔會補上，已有門檻不重置）。讀檔對進度，不自動開工。`.devlog/` 含 prompt，會建議加進 `.gitignore`，要你同意才改。 |
@@ -244,7 +216,7 @@ Claude 用純文字結尾提出問題、下一則訊息才拿到答案時，不
 ## 測試
 
 ```
-bash hooks/scripts/run-tests.sh
+bash core/scripts/run-tests.sh
 ```
 
 含 Cursor adapter。

package/claude/hooks.json

@@ -0,0 +1,75 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact|fork",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/core/scripts/session-start-devlog.sh\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/core/scripts/round-start.sh\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/core/scripts/segment-watch.sh\""
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/core/scripts/on-tool-failure.sh\""
+          }
+        ]
+      }
+    ],
+    "StopFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/core/scripts/on-stop-failure.sh\""
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/core/scripts/on-session-end.sh\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/core/scripts/enforce-devlog.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/cli/agents-md.js

@@ -5,19 +5,20 @@ const path = require('path');
 const BEGIN = '<!-- devlog-tracker:begin -->';
 const END = '<!-- devlog-tracker:end -->';
 
-const BLOCK = `${BEGIN}
+function codexBlock() {
+  return `${BEGIN}
 ## devlog-tracker
 
-這個專案用 devlog-tracker 在 \`.devlog/devlog.md\` 維護逐輪紀錄（Claude Code 與 Codex 共用同一份）。Codex 指令在 \`.codex/prompts/\`，以 \`/prompts:devlog-<名稱>\` 執行；若 slash command 不可用，請照下面對照做：
+這個專案用 devlog-tracker 在 \`.devlog/devlog.md\` 維護逐輪紀錄（Claude Code 與 Codex 共用同一份）。Codex 指令是 \`.agents/skills/devlog-<名稱>/\` 底下的 skill，用 \`/skills\` 選或打 \`$devlog-<名稱>\` 執行；若 skill 不可用，請照下面對照做：
 
 1. 先 \`source .devlog-tracker/env.sh\`（設定 \`DEVLOG_TRACKER_ROOT\`）。
-2. 依使用者意圖讀對應的 \`.devlog-tracker/commands/<名稱>.md\`，照裡面的步驟做（腳本在 \`.devlog-tracker/hooks/scripts/\`，執行時 \`CLAUDE_PROJECT_DIR\` 設成專案根目錄）。
+2. 依使用者意圖讀對應的 \`.devlog-tracker/commands/<名稱>.md\`，照裡面的步驟做（腳本在 \`.devlog-tracker/core/scripts/\`，執行時 \`DEVLOG_PROJECT_DIR\` 設成專案根目錄）。
 
 | 使用者說 | 讀這份 |
 |---|---|
-| 開始追蹤 / start | \`/prompts:devlog-start\`；\`commands/start.md\` |
-| 暫停 / pause | \`/prompts:devlog-pause\`；\`commands/pause.md\` |
-| 狀態 / status | \`/prompts:devlog-status\`；\`commands/status.md\` |
+| 開始追蹤 / start | \`$devlog-start\`；\`commands/start.md\` |
+| 暫停 / pause | \`$devlog-pause\`；\`commands/pause.md\` |
+| 狀態 / status | \`$devlog-status\`；\`commands/status.md\` |
 | 接續上一題 / continue（換過工具或 \`/clear\` 之後） | \`commands/continue.md\` |
 | 歸檔 / compact | \`commands/compact.md\` |
 | 清空重編 / clean（不可復原，先問使用者確認） | \`commands/clean.md\` |
@@ -29,23 +30,28 @@ const BLOCK = `${BEGIN}
 寫 devlog 的格式與規則見 \`.devlog-tracker/skills/devlog-tracker/SKILL.md\`。每輪結束前必須把當輪寫進 \`.devlog/\`；已 \`start\` 的專案，Stop hook 會擋沒寫完的輪次。
 ${END}
 `;
+}
 
-function upsertAgentsMd(targetDir) {
-  const filePath = path.join(targetDir, 'AGENTS.md');
+function upsertMarkdown(targetDir, { fileName = 'AGENTS.md', block = codexBlock() } = {}) {
+  const filePath = path.join(targetDir, fileName);
   const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
   const begin = existing.indexOf(BEGIN);
   const end = existing.indexOf(END);
 
   let next;
   if (begin !== -1 && end > begin) {
-    next = existing.slice(0, begin) + BLOCK + existing.slice(end + END.length).replace(/^\n/, '');
+    next = existing.slice(0, begin) + block + existing.slice(end + END.length).replace(/^\n/, '');
   } else if (existing.trim() === '') {
-    next = BLOCK;
+    next = block;
   } else {
-    next = `${existing.replace(/\n*$/, '\n')}\n${BLOCK}`;
+    next = `${existing.replace(/\n*$/, '\n')}\n${block}`;
   }
   if (next !== existing) fs.writeFileSync(filePath, next);
   return filePath;
 }
 
-module.exports = { upsertAgentsMd, BEGIN, END };
+function upsertAgentsMd(targetDir) {
+  return upsertMarkdown(targetDir, { fileName: 'AGENTS.md', block: codexBlock() });
+}
+
+module.exports = { upsertAgentsMd, upsertMarkdown, codexBlock, BEGIN, END };

package/cli/agents-md.test.js

@@ -4,7 +4,7 @@ const assert = require('node:assert/strict');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { upsertAgentsMd, BEGIN, END } = require('./agents-md');
+const { upsertAgentsMd, upsertMarkdown, BEGIN, END } = require('./agents-md');
 const { run } = require('./init');
 
 function tmp() {
@@ -40,29 +40,57 @@ test('is idempotent and replaces the block in place', () => {
   assert.equal(once.split(BEGIN).length, 2);
 });
 
-test('block mentions every command doc and Codex prompt naming convention', () => {
+test('block mentions every command doc and Codex skill naming convention', () => {
   const commandsDir = path.join(__dirname, '..', 'commands');
   const text = fs.readFileSync(upsertAgentsMd(tmp()), 'utf8');
   for (const file of fs.readdirSync(commandsDir).filter((f) => f.endsWith('.md'))) {
     assert.ok(text.includes(`commands/${file}`), `AGENTS.md block is missing commands/${file}`);
   }
-  assert.ok(text.includes('/prompts:devlog-start'));
+  assert.ok(text.includes('$devlog-start'));
 });
 
-test('init --codex writes AGENTS.md and custom prompts; --cursor alone does not', async () => {
+test('init --codex writes AGENTS.md and project skills; --cursor alone does not', async () => {
   const repoRoot = path.join(__dirname, '..');
   const withCodex = tmp();
   await run(['--codex'], { repoRoot, targetDir: withCodex, version: '0.0.0' });
   assert.ok(fs.existsSync(path.join(withCodex, 'AGENTS.md')));
   for (const file of fs.readdirSync(path.join(repoRoot, 'commands')).filter((file) => file.endsWith('.md'))) {
-    const prompt = fs.readFileSync(
-      path.join(withCodex, '.codex', 'prompts', `devlog-${path.basename(file, '.md')}.md`),
-      'utf8'
-    );
-    assert.match(prompt, /\$ARGUMENTS/);
+    const name = `devlog-${path.basename(file, '.md')}`;
+    const skill = fs.readFileSync(path.join(withCodex, '.agents', 'skills', name, 'SKILL.md'), 'utf8');
+    assert.match(skill, new RegExp(`^---\\nname: ${name}\\ndescription: ".+"\\n---\\n`));
   }
+  assert.ok(!fs.existsSync(path.join(withCodex, '.codex', 'prompts')));
+
+  const upgraded = tmp();
+  const legacy = path.join(upgraded, '.codex', 'prompts');
+  fs.mkdirSync(legacy, { recursive: true });
+  fs.writeFileSync(path.join(legacy, 'devlog-start.md'), 'old');
+  fs.writeFileSync(path.join(legacy, 'mine.md'), 'keep');
+  await run(['--codex'], { repoRoot, targetDir: upgraded, version: '0.0.0' });
+  assert.ok(!fs.existsSync(path.join(legacy, 'devlog-start.md')));
+  assert.ok(fs.existsSync(path.join(legacy, 'mine.md')));
 
   const cursorOnly = tmp();
   await run(['--cursor'], { repoRoot, targetDir: cursorOnly, version: '0.0.0' });
   assert.ok(!fs.existsSync(path.join(cursorOnly, 'AGENTS.md')));
 });
+
+test('upsertMarkdown writes to a custom file name with a custom block', () => {
+  const targetDir = tmp();
+
+  const filePath = upsertMarkdown(targetDir, {
+    fileName: 'CLAUDE.md',
+    block: `${BEGIN}\n## custom\n${END}\n`,
+  });
+
+  assert.equal(filePath, path.join(targetDir, 'CLAUDE.md'));
+  assert.equal(fs.readFileSync(filePath, 'utf8'), `${BEGIN}\n## custom\n${END}\n`);
+});
+
+test('upsertAgentsMd keeps writing AGENTS.md by default (back-compat)', () => {
+  const targetDir = tmp();
+
+  const filePath = upsertAgentsMd(targetDir);
+
+  assert.equal(filePath, path.join(targetDir, 'AGENTS.md'));
+});

package/cli/init.js

@@ -1,18 +1,20 @@
 'use strict';
 const readline = require('readline');
 const { vendor } = require('./vendor');
+const claude = require('./platforms/claude');
 const codex = require('./platforms/codex');
 const cursor = require('./platforms/cursor');
 
-const PLATFORMS = { codex, cursor };
+const PLATFORMS = { claude, codex, cursor };
 
 function parseArgs(argv) {
   const platforms = [];
   for (const arg of argv) {
-    if (arg === '--codex') platforms.push('codex');
+    if (arg === '--claude') platforms.push('claude');
+    else if (arg === '--codex') platforms.push('codex');
     else if (arg === '--cursor') platforms.push('cursor');
     else if (arg.startsWith('-')) {
-      throw new Error(`Unknown option: ${arg} (supported: --codex, --cursor)`);
+      throw new Error(`Unknown option: ${arg} (supported: --claude, --codex, --cursor)`);
     }
   }
   return { platforms };
@@ -22,7 +24,7 @@ function promptPlatforms() {
   if (!process.stdin.isTTY) return Promise.resolve(Object.keys(PLATFORMS));
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
-    rl.question('要裝哪個平台？(codex/cursor，逗號分隔，留空=全部): ', (answer) => {
+    rl.question('要裝哪個平台？(claude/codex/cursor，逗號分隔，留空=全部): ', (answer) => {
       rl.close();
       const trimmed = answer.trim();
       if (!trimmed) return resolve(Object.keys(PLATFORMS));

package/cli/init.test.js

@@ -6,16 +6,17 @@ const os = require('os');
 const path = require('path');
 const { parseArgs, run } = require('./init');
 
-test('parseArgs accepts --codex and --cursor', () => {
+test('parseArgs accepts --claude, --codex and --cursor', () => {
+  assert.deepEqual(parseArgs(['--claude']), { platforms: ['claude'] });
   assert.deepEqual(parseArgs(['--codex']), { platforms: ['codex'] });
-  assert.deepEqual(parseArgs(['--codex', '--cursor']), { platforms: ['codex', 'cursor'] });
+  assert.deepEqual(parseArgs(['--claude', '--codex', '--cursor']), { platforms: ['claude', 'codex', 'cursor'] });
   assert.deepEqual(parseArgs([]), { platforms: [] });
 });
 
 test('parseArgs throws a clear error for unknown options', () => {
   assert.throws(
-    () => parseArgs(['--claude']),
-    { message: 'Unknown option: --claude (supported: --codex, --cursor)' }
+    () => parseArgs(['--foo']),
+    { message: 'Unknown option: --foo (supported: --claude, --codex, --cursor)' }
   );
   assert.throws(() => parseArgs(['--codex', '-x']), /Unknown option: -x/);
 });

package/cli/merge-hooks.js

@@ -30,9 +30,12 @@ function readExisting(targetPath) {
   return parsed;
 }
 
-function mergeHooksTemplate({ templatePath, targetPath, vendorRoot }) {
+function mergeHooksTemplate({ templatePath, targetPath, vendorRoot, placeholders = ['${DEVLOG_TRACKER_ROOT}'] }) {
   const escapedRoot = JSON.stringify(vendorRoot).slice(1, -1);
-  const rawTemplate = fs.readFileSync(templatePath, 'utf8').split('${DEVLOG_TRACKER_ROOT}').join(escapedRoot);
+  let rawTemplate = fs.readFileSync(templatePath, 'utf8');
+  for (const placeholder of placeholders) {
+    rawTemplate = rawTemplate.split(placeholder).join(escapedRoot);
+  }
   const template = JSON.parse(rawTemplate);
 
   const existing = readExisting(targetPath);

package/cli/merge-hooks.test.js

@@ -185,3 +185,55 @@ test('real templates quote the vendor path so project paths with spaces work', (
     }
   }
 });
+
+test('placeholders parameter substitutes multiple placeholder strings when provided', () => {
+  const dir = tmpdir();
+  const templatePath = path.join(dir, 'template.json');
+  fs.writeFileSync(
+    templatePath,
+    JSON.stringify({
+      hooks: {
+        SessionStart: [{ hooks: [{ type: 'command', command: 'bash "${CLAUDE_PLUGIN_ROOT}/script.sh"' }] }],
+        Stop: [{ hooks: [{ type: 'command', command: 'bash "${DEVLOG_TRACKER_ROOT}/other.sh"' }] }],
+      },
+    })
+  );
+  const targetPath = path.join(dir, 'hooks.json');
+  const vendorRoot = '/proj/.devlog-tracker';
+
+  mergeHooksTemplate({
+    templatePath,
+    targetPath,
+    vendorRoot,
+    placeholders: ['${DEVLOG_TRACKER_ROOT}', '${CLAUDE_PLUGIN_ROOT}'],
+  });
+
+  const written = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+  assert.equal(written.hooks.SessionStart[0].hooks[0].command, `bash "${vendorRoot}/script.sh"`);
+  assert.equal(written.hooks.Stop[0].hooks[0].command, `bash "${vendorRoot}/other.sh"`);
+});
+
+test('unlisted placeholders remain verbatim when placeholders parameter is provided', () => {
+  const dir = tmpdir();
+  const templatePath = path.join(dir, 'template.json');
+  fs.writeFileSync(
+    templatePath,
+    JSON.stringify({
+      hooks: {
+        Stop: [{ hooks: [{ type: 'command', command: 'bash "${UNLISTED_PLACEHOLDER}/script.sh"' }] }],
+      },
+    })
+  );
+  const targetPath = path.join(dir, 'hooks.json');
+  const vendorRoot = '/proj/.devlog-tracker';
+
+  mergeHooksTemplate({
+    templatePath,
+    targetPath,
+    vendorRoot,
+    placeholders: ['${DEVLOG_TRACKER_ROOT}'],
+  });
+
+  const written = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+  assert.equal(written.hooks.Stop[0].hooks[0].command, 'bash "${UNLISTED_PLACEHOLDER}/script.sh"');
+});

package/cli/platforms/claude.js

@@ -0,0 +1,55 @@
+'use strict';
+const path = require('path');
+const { mergeHooksTemplate } = require('../merge-hooks');
+const { upsertMarkdown, BEGIN, END } = require('../agents-md');
+const { generateSkillsFromCommands } = require('../skills-from-commands');
+
+function claudeBlock() {
+  return `${BEGIN}
+## devlog-tracker
+
+這個專案用 devlog-tracker 在 \`.devlog/devlog.md\` 維護逐輪紀錄。指令是 \`.claude/skills/devlog-<名稱>/\` 底下的 skill，用 \`/devlog-<名稱>\` 執行；若 skill 不可用，請照下面對照做：
+
+1. 先 \`source .devlog-tracker/env.sh\`（設定 \`DEVLOG_TRACKER_ROOT\`）。
+2. 依使用者意圖讀對應的 \`.devlog-tracker/commands/<名稱>.md\`，照裡面的步驟做（腳本在 \`.devlog-tracker/core/scripts/\`，執行時 \`DEVLOG_PROJECT_DIR\` 設成專案根目錄）。
+
+| 使用者說 | 讀這份 |
+|---|---|
+| 開始追蹤 / start | \`/devlog-start\`；\`commands/start.md\` |
+| 暫停 / pause | \`/devlog-pause\`；\`commands/pause.md\` |
+| 狀態 / status | \`/devlog-status\`；\`commands/status.md\` |
+| 接續上一題 / continue（換過工具或 \`/clear\` 之後） | \`commands/continue.md\` |
+| 歸檔 / compact | \`commands/compact.md\` |
+| 清空重編 / clean（不可復原，先問使用者確認） | \`commands/clean.md\` |
+| 保存主題 / keep、接續具名檔 / resume、跨主題總覽 / overview | \`commands/keep.md\`、\`commands/resume.md\`、\`commands/overview.md\` |
+| 長任務定期記錄 / span | \`commands/span.md\` |
+| 調整沉默門檻 / checkpoint、segment-watch | \`commands/checkpoint.md\`、\`commands/segment-watch.md\` |
+| 開發歷程教訓 / lessons、lessons-on、lessons-off、lessons-drift | \`commands/lessons.md\`、\`commands/lessons-on.md\`、\`commands/lessons-off.md\`、\`commands/lessons-drift.md\` |
+
+寫 devlog 的格式與規則見 \`.devlog-tracker/skills/devlog-tracker/SKILL.md\`。每輪結束前必須把當輪寫進 \`.devlog/\`；已 \`start\` 的專案，Stop hook 會擋沒寫完的輪次。
+
+注意：若同時透過 Claude Code plugin marketplace 安裝了 devlog-tracker，這兩條安裝路線的 hook 都會生效，導致同一輪被記錄兩次；二選一即可。
+${END}
+`;
+}
+
+function installSkills({ targetDir, vendorRoot }) {
+  generateSkillsFromCommands({
+    commandsDir: path.join(vendorRoot, 'commands'),
+    targetSkillsDir: path.join(targetDir, '.claude', 'skills'),
+    namePrefix: 'devlog',
+  });
+}
+
+function install({ repoRoot, targetDir, vendorRoot }) {
+  mergeHooksTemplate({
+    templatePath: path.join(repoRoot, 'claude', 'hooks.json'),
+    targetPath: path.join(targetDir, '.claude', 'settings.local.json'),
+    vendorRoot,
+    placeholders: ['${DEVLOG_TRACKER_ROOT}', '${CLAUDE_PLUGIN_ROOT}'],
+  });
+  installSkills({ targetDir, vendorRoot });
+  upsertMarkdown(targetDir, { fileName: 'CLAUDE.md', block: claudeBlock() });
+}
+
+module.exports = { install, installSkills };