KingClawArmy/docs/paperclip_dev_review_2026-04-11.md

KingClawArmy - Paperclip Package Review（dev）

日期：2026-04-11 審查對象：origin/dev 初次審查 commit：43c1770 追蹤審查 commit：aceb1ba 最終追蹤 commit：cb44714 用途：記錄 dev branch 的 Paperclip package 審查結果、修正追蹤與最終 smoke test 驗證

---

1. 結論摘要

dev branch 已經完成第一版 Paperclip package 骨架，且可通過：

paperclipai company import <repo> --dry-run --json

這代表以下基礎能力已具備：

1. repo root 已有 COMPANY.md
2. 已有 .paperclip.yaml
3. 已有 agents/、teams/、projects/、tasks/、skills/ 基本結構
4. importer 可以成功解析 package

第二輪追蹤後，原本的 P1-P4 都已修正完成，包含：

1. recurring routine 與 task slug 已對齊
2. daily-secretary-digest 已移到正確 project 目錄
3. quant-strategist 的過大權限已移除
4. project 的 Paperclip 專屬 metadata 已改由 .paperclip.yaml 承載，dry-run 匯入後可正確保留

第三輪追蹤後，P5 也已修正完成，且額外完成了真正的 import smoke test。

目前結論是：

1. 這份 dev package 已通過本輪 Paperclip 規格審查
2. paperclipai company import --dry-run --json 可通過，warnings / errors 為空
3. 實際 import 到本地 Paperclip instance 也成功
4. recurring task 會被建立為 routines，而不是 one-off issues，行為符合 Paperclip 設計

---

2. 最終驗證結果

2.1 Dry-run 驗證

使用：

paperclipai company import <repo> --dry-run --json

確認結果：

1. ceo 匯入後的 role 為 ceo
2. projects 的 leadAgentSlug / status 有正確保留
3. 四個 recurring task 都有對應的 routine
4. warnings: []
5. errors: []

2.2 實際 import smoke test

使用：

paperclipai company import /Users/chirs/workspace/KingClawArmy_dev_review \
  --target new \
  --new-company-name "KingClawArmy Smoke Test 2026-04-11" \
  --yes \
  --json

實測結果：

1. 成功建立 company：KingClawArmy Smoke Test 2026-04-11
2. 成功建立 11 個 agents
3. 成功建立 2 個 projects
4. recurring task 沒有被當成一般 issues 匯入，而是建立為 4 個 active routines
5. GET /api/companies/{companyId}/routines 可查到：
   • 每日量化 Pipeline 啟動
   • 每日盤後情報整理
   • 每日資料摘要
   • 每日記憶壓縮與狀態摘要

補充：

1. 實際 import 回傳的 issues 數量是 0，這是正常的
2. 原因是這 4 個 recurring tasks 在 Paperclip 內會被提升為 routines，而不是預先建立 one-off issues
3. 真正的執行 issue 會在 routine 觸發時才產生

2.3 最終判定

就本輪審查範圍而言，dev branch 已可視為：

1. Paperclip importable package
2. 規格與實際匯入行為一致
3. 可進入下一階段整合或實跑驗證

---

3. 已修正問題（追蹤確認）

已修正 P5. ceo agent 的 role 不是 Paperclip 預期的 ceo

前次問題

agents/ceo/AGENTS.md 原本是：

role: manager

這會讓匯入後的執行長無法被 Paperclip 視為真正的 CEO，進而失去部分 CEO-safe 行為與公司層級權限。

追蹤結果：

已修正。origin/dev 的 cb44714 已將其改為：

role: ceo

而且 dry-run 匯入結果也已確認 ceo.role == "ceo"。

已修正 P1. 07:30 主排程沒有綁到真正的 recurring task

現況

• .paperclip.yaml 的 routine key：daily-quant-pipeline
• recurring task slug：daily-quant-run

參考：

• origin/dev:.paperclip.yaml 第 85-91 行
• origin/dev:projects/daily-quant-pipeline/tasks/daily-quant-run/TASK.md

影響

paperclipai company import --dry-run --json 的結果顯示：

• daily-quant-run 的 routine 是 null

也就是說，這個每日量化啟動任務匯入後不會自動被排程觸發。

建議修法

二選一，選一種即可：

1. 把 routine key 改成 daily-quant-run
2. 把 task slug 改成 daily-quant-pipeline

建議採用：

追蹤結果：

已修正。origin/dev 目前的 routine key 已改為 daily-quant-run，且 dry-run 匯入結果中 daily-quant-run.routine 已正確存在。

---

已修正 P2. quant-strategist 權限過大

現況

在 .paperclip.yaml 中：

agents:
  quant-strategist:
    permissions:
      canCreateAgents: true

影響

在 Paperclip 中，canCreateAgents 比「可分派工作」更高，是接近 agent creator / manager 級別的權限。

目前設計目標只是讓策略師主導量化 pipeline，不是讓他具備建立 agent 的高權限。

建議修法

1. 若只是要策略師能主導任務分配，先移除 canCreateAgents: true
2. 若未來真的需要額外委派能力，再由 Paperclip 的顯式 permission / grant 機制處理

建議採用：

追蹤結果：

已修正。quant-strategist 的 canCreateAgents 已移除。

---

已修正 P3. PROJECT.md 的 owner / status 意圖沒有被保留下來

現況

兩個 project 使用了：

leadAgentSlug: ...
status: active

參考：

• origin/dev:projects/daily-quant-pipeline/PROJECT.md
• origin/dev:projects/board-ops/PROJECT.md

影響

實際 dry-run 匯入結果顯示：

• leadAgentSlug: null
• status: null

也就是說，這兩個欄位現在雖然寫在檔案裡，但 importer 沒有保留成有效 project metadata。

建議修法

1. 先把 PROJECT.md 保持為 vendor-neutral、最小可攜欄位
2. 若需要 Paperclip 專屬 fidelity，改放到 .paperclip.yaml 或 metadata.paperclip
3. project owner 可優先改成 base spec 較接近的欄位，例如 owner

建議採用：

追蹤結果：

已修正。PROJECT.md 已收斂成較乾淨的 base package 內容，project 的 leadAgentSlug / status 目前改由 .paperclip.yaml 承載，且 dry-run 匯入結果可正確保留。

---

已修正 P4. daily-secretary-digest 放在錯的 project 資料夾底下

現況

檔案位置：

projects/daily-quant-pipeline/tasks/daily-secretary-digest/TASK.md

但 frontmatter 內容是：

project: board-ops

影響

雖然 importer 目前會依 frontmatter 匯入成功，但這違反 package 本身的資料夾慣例，之後非常容易造成：

1. 維護時誤判任務歸屬
2. reviewer 看目錄就被誤導
3. 後續 agent 做批次修改時把任務放錯地方

建議修法

將該檔案移到：

projects/board-ops/tasks/daily-secretary-digest/TASK.md

同時保持：

追蹤結果：

已修正。該檔案已移到：

projects/board-ops/tasks/daily-secretary-digest/TASK.md

---

4. 建議但非阻塞問題

S1. 第一版 package 已經不是方案 A，而是接近量化完整版

目前 dev branch 實際包含：

1. 管理團隊 3 位
2. 量化團隊 7 位
3. xiao-an 1 位 paused

也就是：

• 10 active
• 1 paused

這已經比原規劃文件的方案 A 更接近「完整量化版」。

建議

1. 更新 docs/INDEX.md 與相關說明，明確寫成「第一版 package = 管理 + 完整量化團隊」
2. 不要再沿用「精實版 8 active」的敘述，避免文檔口徑不一致

---

S2. 可以補一份簡短的 import 驗收說明

建議在 docs/ 追加一段簡單說明，讓之後的人知道該怎麼驗：

paperclipai company import . --dry-run --json

最低驗收應包含：

1. 沒有 missing COMPANY.md
2. 所有 recurring task 都有對應 routine
3. projects 與 tasks 的目錄與 frontmatter 一致
4. .paperclip.yaml 沒有秘密值與機器相依路徑

---

5. 後續建議

接下來如果要繼續往前推，建議順序是：

1. 在本地或測試環境做一次 routine 實跑驗證，確認觸發後會建立 execution issue
2. 若要正式採用，補一份簡短的 import / smoke test 操作說明到 docs/
3. 若後續要擴充行銷或內容團隊，再以相同模式擴展 package 結構

---

6. 本輪驗收標準

本輪已確認：

1. agents/ceo/AGENTS.md 的 frontmatter 為 role: ceo
2. paperclipai company import --dry-run --json 成功通過
3. 匯入後 CEO 在系統中被辨識為真正的 CEO，而不是一般 manager
4. recurring task 在真實 import 後會建立為 routines
5. 文件敘述與 package 實際內容一致

---

7. 一句話結論

origin/dev 的 KingClawArmy Paperclip package 已完成本輪修正並通過 dry-run 與實際 import smoke test，可進入下一階段驗證或整合。