# KingClawArmy - Paperclip 組織規劃方案

> 日期：2026-04-11
> 用途：提供另一個 agent 作為修改依據；本文件定義規劃選項、推薦方案、實作範圍與 review 驗收標準

---

## 1. 目的與前提

這份文件的目的不是直接當成 Paperclip package 匯入，而是作為下一位實作 agent 的施工說明書。

Paperclip 需要的不是 `docs/` 內的說明稿，而是實際可匯入的 package 結構：

```text
COMPANY.md
.paperclip.yaml
agents/<slug>/AGENTS.md
teams/<slug>/TEAM.md
projects/<slug>/PROJECT.md
projects/<slug>/tasks/<slug>/TASK.md
skills/<slug>/SKILL.md
```

因此，下一位 agent 的任務應該是：

1. 保留 `docs/` 作為設計說明文件
2. 在 repo 根目錄建立真正的 Paperclip company package
3. 依照本文件選定的組織方案，產出第一版可 `paperclipai company import --dry-run` 通過的結構

---

## 2. Paperclip 導向的設計約束

| 項目 | 約束 |
|---|---|
| 公司根檔 | 必須有 repo root 的 `COMPANY.md` |
| Agent 定義 | 每個 agent 必須有自己的 `agents/<slug>/AGENTS.md` |
| Team 定義 | 每個 team 必須有 `teams/<slug>/TEAM.md`，且 `manager` 要能解析到真實 agent 檔案 |
| Project 定義 | pipeline 需要對應到 `PROJECT.md`，不能只寫在說明文件 |
| Routine 定義 | recurring work 需要 `TASK.md` 標記 `recurring: true`，排程細節再放到 `.paperclip.yaml` |
| Skills | `AGENTS.md` 內應以 shortname 關聯 skill，`SKILL.md` 保持 Agent Skills 相容 |
| Runtime 設定 | adapter、env inputs、budgets、permissions、routines 等放在 `.paperclip.yaml` |
| 溝通模型 | Paperclip V1 偏 task/comment，不是 OpenClaw 那種 session-first 規劃 |

---

## 3. 目前文件狀態摘要

| 項目 | 現況 | 結論 |
|---|---|---|
| `docs/company.md` | 已有完整藍圖 | 可當來源稿，但不是 import root |
| `docs/pipelines.md` | 已有 pipeline 與 routines | 還缺 `PROJECT.md` / `TASK.md` 實體 |
| `docs/schemas.md` | 已有多數輸出 schema | 可作為 agent instructions 的引用內容 |
| repo root | 沒有 `COMPANY.md`、`.paperclip.yaml` | 現在不能直接 import |
| 組織架構 | 18 agents / 5 teams | 當藍圖合理，當第一版上線偏重 |
| review 流程 | 有定義，但 revise 上限與 review 節點不完全一致 | 修改時要先收斂口徑 |

---

## 4. 規劃方案

### 方案 A：精實上線包

**定位：** 先做出第一個可匯入、可運行、成本可控的 Paperclip package。

**建議啟用角色：**

| Team | Agent | 狀態 |
|---|---|---|
| management | `ceo` | active |
| management | `secretary` | active |
| management | `reviewer` | active |
| quant-research | `quant-strategist` | active |
| quant-research | `finance-researcher` | active |
| quant-research | `market-structure-researcher` | active |
| quant-research | `quant-engineer` | active |
| quant-research | `data-analyst` | active |
| optional | `xiao-an` | paused |

**總計：** 8 active + 1 optional paused

**組織樹：**

```text
董事長
└── ceo
    ├── secretary
    ├── reviewer
    └── quant-strategist
        ├── finance-researcher
        ├── market-structure-researcher
        ├── quant-engineer
        └── data-analyst
```

**應建立的 team：**

1. `management`
2. `quant-research`

**應建立的 project：**

1. `daily-quant-pipeline`
2. `board-ops`

**應建立的 recurring tasks：**

1. `daily-quant-pipeline` -> assignee `ceo`
2. `daily-post-market` -> assignee `ceo`
3. `daily-data-summary` -> assignee `data-analyst`
4. `daily-secretary-digest` -> assignee `secretary`

**優點：**

1. 最容易先通過 Paperclip import
2. 組織深度夠用，管理跨度可控
3. 成本最低，適合先驗證量化閉環
4. 另一個 agent 修改時影響面最小

**缺點：**

1. 少了 bull/bear 對抗式分析
2. 行銷與內容團隊尚未進 package
3. 工程團隊先不落地

**適用情境：**

1. 你想先讓 Paperclip package 匯入成功
2. 你想先把量化閉環跑通
3. 你希望 review 範圍小、改動風險低

---

### 方案 B：平衡擴編包

**定位：** 保留完整量化閉環，並放入行銷策略團隊的基礎骨架。

**建議啟用角色：**

| Team | Agent | 狀態 |
|---|---|---|
| management | `ceo` | active |
| management | `secretary` | active |
| management | `reviewer` | active |
| quant-research | `quant-strategist` | active |
| quant-research | `finance-researcher` | active |
| quant-research | `market-structure-researcher` | active |
| quant-research | `bullish-researcher` | active |
| quant-research | `bearish-researcher` | active |
| quant-research | `quant-engineer` | active |
| quant-research | `data-analyst` | active |
| marketing | `strategy-director` | active |
| marketing | `market-researcher` | active |
| marketing | `ads-analyst` | paused |
| optional | `xiao-an` | paused |

**總計：** 12 active + 2 paused

**組織樹：**

```text
董事長
└── ceo
    ├── secretary
    ├── reviewer
    ├── quant-strategist
    │   ├── finance-researcher
    │   ├── market-structure-researcher
    │   ├── bullish-researcher
    │   ├── bearish-researcher
    │   ├── quant-engineer
    │   └── data-analyst
    └── strategy-director
        ├── market-researcher
        └── ads-analyst
```

**應建立的 team：**

1. `management`
2. `quant-research`
3. `marketing`

**應建立的 project：**

1. `daily-quant-pipeline`
2. `market-intel`
3. `board-ops`

**應建立的 recurring tasks：**

1. 方案 A 的全部 recurring tasks
2. `morning-market-intel` -> assignee `market-researcher`
3. `evening-market-intel` -> assignee `market-researcher`
4. `weekly-market-report` -> assignee `market-researcher`

**優點：**

1. 量化 pipeline 比方案 A 更完整
2. 行銷 team 先有骨架，不用之後重做 package
3. 比 18 agent 藍圖更適合先上線

**缺點：**

1. package 複雜度明顯上升
2. review 範圍變大
3. 匯入後需要更多 paused/active 狀態管理

**適用情境：**

1. 你希望量化 full pipeline 一次到位
2. 你預計很快就會接上市場研究與行銷節奏
3. 你接受另一個 agent 需要改比較多檔案

---

### 方案 C：完整藍圖包

**定位：** 直接把目前 `docs/company.md` 的 18 agents 全部落成 Paperclip package。

**建議啟用角色：**

| Team | Agent | 狀態 |
|---|---|---|
| management | `ceo` | active |
| management | `secretary` | active |
| management | `reviewer` | active |
| quant-research | `quant-strategist` | active |
| quant-research | `finance-researcher` | active |
| quant-research | `market-structure-researcher` | active |
| quant-research | `bullish-researcher` | active |
| quant-research | `bearish-researcher` | active |
| quant-research | `quant-engineer` | active |
| quant-research | `data-analyst` | active |
| marketing | `strategy-director` | active |
| marketing | `market-researcher` | active |
| marketing | `ads-analyst` | active |
| content | `creative-director` | active |
| content | `copywriter` | active |
| engineering | `frontend-engineer` | paused |
| engineering | `backend-engineer` | paused |
| optional | `xiao-an` | paused |

**總計：** 15 active + 3 paused

**優點：**

1. 與現有藍圖最一致
2. 未來擴編時不需再補 package 結構
3. 全公司模型一次成形

**缺點：**

1. 第一版 package 實作成本最高
2. 很多 agent 只有規格，沒有第一波實際任務
3. 工程團隊目前沒有真正的 team lead，結構上較勉強
4. review 與驗收難度最高

**適用情境：**

1. 你要做的是展示型、藍圖型 package
2. 你接受第一版不是最精實，而是最完整
3. 另一個 agent 有足夠時間把 package 全部補齊

---

## 5. 推薦方案

**推薦採用：方案 A 作為第一版 import package**

原因：

1. 這是最符合 Paperclip 第一階段匯入需求的方案
2. 可以先驗證 `COMPANY.md + AGENTS.md + TEAM.md + PROJECT.md + TASK.md + .paperclip.yaml` 的完整鏈路
3. 量化是目前最清楚、最成熟的閉環，先落地它最划算
4. 另一個 agent 可以先把結構做好，再逐步擴到方案 B 或方案 C

**推薦 roadmap：**

1. 第一版 import package 採 `方案 A`
2. 量化 pipeline 穩定後升級到 `方案 B`
3. 行銷與內容成熟後再收斂成 `方案 C`

---

## 6. 另一個 Agent 的修改範圍

### 必做

| 路徑 | 動作 |
|---|---|
| `COMPANY.md` | 新建真正的 company root，frontmatter 採 `agentcompanies/v1` |
| `.paperclip.yaml` | 新建 Paperclip sidecar，放 adapter、inputs、permissions、routines、status |
| `agents/<slug>/AGENTS.md` | 為方案 A 中的每個 agent 建立真正 agent 檔 |
| `teams/management/TEAM.md` | 新建 team package |
| `teams/quant-research/TEAM.md` | 新建 team package |
| `projects/daily-quant-pipeline/PROJECT.md` | 新建 project package |
| `projects/board-ops/PROJECT.md` | 新建 project package |
| `projects/.../tasks/<slug>/TASK.md` | 為 recurring routines 建立任務檔 |
| `skills/deep-research/SKILL.md` | 新建相容 skill |
| `skills/code-reviewer/SKILL.md` | 新建相容 skill |

### 建議做

| 路徑 | 動作 |
|---|---|
| `docs/company.md` | 保留為說明稿，但內容要標示「藍圖版」或「未來擴編版」 |
| `docs/pipelines.md` | 對齊 recurring tasks 與實際 project/task 命名 |
| `docs/schemas.md` | 對齊第一版 active agents，只保留需要的 schema 或標示 phase |
| `docs/INDEX.md` | 明確區分「設計文件」與「可匯入 package」 |

### 不建議第一輪做太多

1. 不要第一輪就把 18 agents 全部做成 active
2. 不要把 OpenClaw 的 session 協定硬塞進 Paperclip runtime 配置
3. 不要在 `.paperclip.yaml` 複製整份 agent prompt
4. 不要先做太多機器環境相依設定，例如本機絕對路徑與 secret 值

---

## 7. 具體修改原則

1. `AGENTS.md` frontmatter 只放 agent identity、title、reportsTo、skills 等可攜欄位
2. agent 的行為規範與 instructions 寫在 `AGENTS.md` body
3. adapter、model、env inputs、permissions、status、routines 全放 `.paperclip.yaml`
4. `skills` 在 `AGENTS.md` 內用 shortname，如 `deep-research`、`code-reviewer`
5. recurring work 先在 `TASK.md` 標 `recurring: true`，排程再由 `.paperclip.yaml` 補
6. team manager 路徑要用正確的相對路徑，不要沿用 `docs/company.md` 內的示意錯路徑
7. review revise 上限統一成一個數字，建議固定為 `3`
8. 若工程團隊暫不落地，第一版 package 不必建立 `engineering` team

---

## 8. Review 驗收標準

未來我 review 時，至少會檢查以下項目：

1. `paperclipai company import <repo> --dry-run` 不再報 `missing COMPANY.md`
2. root `COMPANY.md` 能被解析，且 `schema`、`slug`、`name` 正確
3. 所有 `TEAM.md` 的 `manager` 路徑都能解析
4. 所有 `AGENTS.md` 的 `reportsTo` 與 team 結構一致
5. recurring routines 都有對應 `TASK.md`
6. `.paperclip.yaml` 沒有機器相依路徑與 secret 值
7. active / paused 狀態與本文件選定方案一致
8. `docs/` 說明稿與真正 package 內容不互相矛盾

---

## 9. 決策建議

如果沒有特別要求一次做完整藍圖，建議直接照以下決策執行：

1. 採用 `方案 A`
2. 將 `方案 B` 寫成後續擴編計畫
3. 將 `方案 C` 保留在 `docs/company.md` 作為最終藍圖

這樣最符合 Paperclip 的第一波落地方式，也最方便之後讓我做結構與合理性 review。