---
name: plan-setup
description: feature-workflow 首次設定引導 —— 自動偵測 Notion 資料庫、匯入 bug-workflow 共用 ID、設定專案對應與技術棧、可選裝獨立 Agent。當使用者提到 /plan-setup、「設定 feature workflow」、「初始化 feature workflow」時觸發此 Skill。
---

# plan-setup — Workflow 首次設定

互動式引導使用者完成 Feature Workflow Plugin 的初始設定，產出設定檔供其他 Skill 使用。

---

## 前置條件

- 已安裝 Notion MCP Server（Claude Code 可使用 `notion-search`、`notion-fetch` 等工具）
- 擁有 Notion Workspace 存取權限

---

## 流程

### 1. 透過 portable resolver 檢查既有 Feature 設定並決定 canonical 寫入位置

> **設定解析邏輯**：詳見 plugin 根目錄 `references/config-resolver.md` 與 `references/config-contract.md`（相對 SKILL.md 為 `../../references/`）。

不要自行選擇 Host-specific 設定目錄。Feature 主設定的 read source 與 canonical write destination 都由 `feature/config` logical key 決定：

```bash
CREW_PLUGIN_ROOT="${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"

FEATURE_CONFIG_READ_JSON="$(python3 "${CREW_PLUGIN_ROOT}/scripts/crew-config.py" resolve \
  --key feature/config \
  --mode read \
  --format json)"

FEATURE_CONFIG_WRITE_PATH="$(python3 "${CREW_PLUGIN_ROOT}/scripts/crew-config.py" resolve \
  --key feature/config \
  --mode write \
  --format path)"

FEATURE_CONFIG_DIR="$(dirname "$FEATURE_CONFIG_WRITE_PATH")"
```

依 `FEATURE_CONFIG_READ_JSON` 判斷：

- `source=missing` → 視為首次設定，直接進入後續流程；不詢問使用者選 storage path。
- `source != missing` → 既有設定可讀，詢問使用者要「重新設定」還是「更新專案對應」。
- `representation=hierarchical` → 依既有 config.md parser 讀取 resolver 回傳的 `path`。
- `representation=legacy_monolith` → 沿用舊單一設定檔 parser；可提示 `/plan-setup --migrate`，但 legacy source 只作讀取來源，不直接覆寫或搬移。

所有本次 Feature **主設定**的新建／重新設定輸出一律寫 `FEATURE_CONFIG_WRITE_PATH`；resolver 本身無副作用，寫入前由 Skill 建立 parent directory。

`/plan-setup --migrate` 的 compatibility / migration ownership 依 `config-resolver.md`「舊格式相容與遷移」與 `config-contract.md`；本批不改內建／自訂 stack bundle 與 project mapping 的既有建立語意。

### 2. 檢查並匯入 bug-workflow 共用 ID

Bug workflow 主設定同樣透過 portable resolver 讀取，不自行判斷實體路徑：

```bash
BUG_CONFIG_JSON="$(python3 "${CREW_PLUGIN_ROOT}/scripts/crew-config.py" resolve \
  --key bug/config \
  --mode read \
  --format json)"
```

若 `BUG_CONFIG_JSON.source != missing`：

1. 從 resolver 回傳的 `path` 讀取 Bug 設定。
2. 擷取「任務追蹤工具」Data Source ID → 直接匯入。
3. 擷取「專案資料庫」Data Source ID → 直接匯入。
4. 擷取「CREW 工作區」metadata（若存在）供後續功能設計庫 parent 判斷使用。
5. 若既有 Bug 設定仍含舊「專案對應」表，保持既有相容讀取語意；project mapping 的建立／更新仍由 Step 4 的 `/project-add` 負責，本批不改其 storage contract。
6. 向使用者顯示匯入結果。

若 `source=missing` → 進入「偵測 Notion 資料庫」一節完整設定。

### 3. 偵測 Notion 資料庫

#### 3-1. 搜尋/驗證「任務追蹤工具」

若已從 bug-workflow 匯入，使用 `notion-fetch` 驗證並檢查「開發階段」欄位：
- 若「開發階段」欄位已存在 → 繼續
- 若不存在 → 使用 `notion-update-data-source` 新增「開發階段」Select 欄位，選項值：
  `需求分析` / `規格設計` / `DB 設計` / `架構設計` / `開發中` / `程式碼審查` / `測試中`

若未從 bug-workflow 匯入，使用 `notion-search` 搜尋包含「任務追蹤」的資料庫。

同時檢查「難度」欄位（bug-workflow 可能未建立）：
- 若不存在 → 新增「難度」Select 欄位，選項值：`小` / `中` / `大`

#### 3-2. 搜尋「功能設計庫」

搜尋包含「功能」、「設計」的資料庫。

**情境 A：找到現有資料庫**

用 `notion-fetch` 取得資料庫結構，驗證並補齊欄位（Name, Tags, 設計類型, 技術棧, 參考連結, 日期）。不移動既有資料庫。

**情境 B：找不到功能設計庫**

詢問使用者：
```
未找到「功能設計庫」資料庫，請選擇：
1. 建立新的「功能設計庫」（推薦，含標準欄位）
2. 指定一個現有資料庫
3. 跳過（/plan-close 結案時不同步設計庫）
```

若選擇建立，先決定 parent 位置：

1. **嘗試取得工作區頁面**：
   - 從 bug-workflow 設定檔讀取「CREW 工作區 → 工作區頁面 ID」
   - 若設定檔無此欄位 → 使用 `notion-search` 搜尋「CREW 工作區」頁面
   - 若找到工作區頁面 → **parent 設為工作區頁面**（不再詢問位置），記錄 `workspace_page_id`
   - 若找不到工作區頁面 → **退回原流程**（詢問要建立在哪個 Notion 頁面下）

2. 用 `notion-create-database` 建立（不含 Relation 欄位），再補上 `is_inline: true`、「專案資料庫」Relation、2 個 Views（Table + 按專案看板）。完整 Schema、`is_inline` 設定時機、Relation `ADD COLUMN` 語法、Views 定義皆見 plugin 根目錄 `references/db-templates.md`（相對 SKILL.md 為 `../../references/`）「建立順序」與「D. 功能設計庫」段
3. 記錄 Data Source ID

#### 3-3. 偵測或建立「專案資料庫」

若已從 bug-workflow 匯入 → 驗證並補齊欄位（特別確認「技術棧」欄位）。

**專案資料庫標準欄位**：

| 欄位 | 類型 | 必要性 |
|------|------|--------|
| 專案名稱 | Title | 必要 |
| Git Repo | Text | 必要 |
| 技術棧 | Select | 必要 |
| SIT/UAT/正式主機 | Text | 選用 |
| 部署方式 | Text | 選用 |
| 狀態 | Status | 建議 |

#### 3-4. 更新工作區頁面（追加功能設計庫）

若「搜尋『功能設計庫』」一節有建立或偵測到功能設計庫，且工作區頁面存在（`workspace_page_id` 有值）：

更新步驟（`notion-update-page` 的 `update_content`，插入位置）與最終排版順序見 plugin 根目錄 `references/db-templates.md`（相對 SKILL.md 為 `../../references/`）「E. CREW 工作區頁面」的「更新步驟（plan-setup 追加功能設計庫時）」與「排版順序」段。

> **注意**：若工作區頁面中已有功能設計庫的 linked view（重複執行 setup），則跳過此步驟。
> 若工作區頁面不存在（`workspace_page_id` 為空），跳過此步驟。

### 4. 設定專案對應

> **專案新增/偵測邏輯統一由 `/project-add` 處理**。

設定檔產出後，自動詢問是否執行 `/project-add` 新增當前專案。

### 5. Agent availability（Host-dependent）

plugin bundle 內含 feature-intake-refiner / feature-spec-analyst / feature-db-designer / feature-backend-designer / feature-code-generator 的 Agent 定義。它們不是 Slash Skills，不需要使用者逐一呼叫。

- Host 支援 named sub-agent / delegation → workflow 自動使用對應 Agent。
- Host 不支援 → 依 Host Capability Contract inline / sequential fallback。
- `/plan-start` 會自動使用 intake refinement；後續 `/plan spec|db|arch` 使用各自角色，不需手動啟動 Agent。

### 6. Chrome DevTools MCP 安裝（選用）

先依 `../../references/host-capabilities.md` 的 `tool_probe` 檢查目前 session 是否已有對應瀏覽器能力（如 `chrome-devtools`）；已可用就直接跳過，不依賴特定 Host CLI 清單。

若尚未安裝，且使用者計畫使用 `/plan-verify` 驗收驗證，詢問是否安裝：

```
是否安裝 Chrome DevTools MCP？（Google 官方維護，推薦）
1. 安裝（推薦，工具數量隨版本更新，Google 官方持續維護）
2. 跳過（使用內建 cdp.mjs，需 Node.js 22+）
```

若選擇安裝，安裝指令與說明：plugin 根目錄 `references/mcp-install.md`（相對 SKILL.md 為 `../../references/`）「chrome-devtools-mcp」段。

### 7. 產出設定目錄

以 plugin 根目錄 `references/config.template.md`（相對 SKILL.md 為 `../../references/`）為模板。主設定固定寫入 Step 1 的 canonical `FEATURE_CONFIG_WRITE_PATH`；其 parent directory 為 `FEATURE_CONFIG_DIR`。

先建立既有階層式 bundle 所需目錄（本批不改 stacks/projects 的建立語意）：

```bash
mkdir -p "$FEATURE_CONFIG_DIR"
mkdir -p "$FEATURE_CONFIG_DIR/stacks"
mkdir -p "$FEATURE_CONFIG_DIR/projects"
```

#### 7-1. 建立 config.md

填入偵測到的 Notion IDs、工作區資訊、欄位對照，寫入 `FEATURE_CONFIG_WRITE_PATH`。若 Step 1 的 read source 是 legacy path，也不得原地覆寫該 legacy source。

#### 7-2. 建立 stacks/_builtin.md

從模板複製內建技術棧總表。

#### 7-3. 建立專案對應檔案（若「設定專案對應」一節有新增專案）

每個專案一個檔案，寫入 `projects/{sanitized-repo-id}.md`。

**檔名規則**：Git Repo 識別碼中的 `/` 替換為 `--`。例如 `ORG01P2401/PushAPIService` → `ORG01P2401--PushAPIService.md`。

### 8. 回傳結果

```
Workflow 設定完成！

主設定檔：{FEATURE_CONFIG_WRITE_PATH}
設定目錄：{FEATURE_CONFIG_DIR}
  ├── config.md          — Notion IDs + 欄位對照
  ├── stacks/_builtin.md — 內建技術棧（既有 bundle 語意）
  └── projects/          — 專案對應（既有流程）

開始使用：
  /plan-start <功能簡述>   — 建立任務
  /plan-spec               — 技術規格
  /plan-db                 — DB 設計
  /plan-arch               — 架構設計
  /plan-build              — 產生程式碼
  /plan-verify             — 驗收驗證
  /plan-review             — 程式碼審查
  /plan-close              — 結案
```

---

## 何時不用

- 一鍵完成 bug + feature 全部設定 → 建議改用 `/crew-init`
- 只設定 bug 側 → 建議改用 `/bug-setup`
- 初始化程式專案 / 專案指令 → Codex 建立 `AGENTS.md`；Claude Code 可用內建 `/init`
- 註冊專案 → 建議改用 `/project-add`
- 自訂技術棧 → 建議改用 `/plan-stack`

---

## Gotchas

- **匯入 bug-workflow ID 時不要盲目信任**：bug-workflow 設定檔中的 Data Source ID 可能過期（資料庫被刪除或 Workspace 變更）。匯入後務必用 `notion-fetch` 驗證每個 ID 仍然有效，無效的 ID 要重新搜尋。
- **「開發階段」欄位的 Select 選項建立順序**：`notion-update-data-source` 新增 Select 欄位時，選項的顯示順序等於建立順序。所以 `需求分析` 要第一個加，`測試中` 最後加，確保在 Notion UI 中按流程階段排列。
- **功能設計庫搜尋關鍵字衝突**：搜尋「功能」「設計」可能命中使用者的其他資料庫（如「功能需求清單」）。額外比對是否有「設計類型」或「技術棧」欄位來確認是目標資料庫。
- **Chrome DevTools MCP 安裝後需重啟**：使用者容易忘記重啟 Claude Code，導致後續 `/plan-verify` 找不到 MCP 工具而失敗。安裝後要明確提醒「必須重啟 Claude Code」。

---

## 邊界情況

- **Notion MCP 未安裝**：提示使用者先安裝 Notion Plugin
- **Workspace 中有多個類似資料庫**：列出候選讓使用者選擇
- **bug-workflow 設定檔部分資訊不全**：僅匯入有效的 ID
- **設定目錄被意外刪除**：重新執行 `/plan-setup` 即可重建
- **舊格式遷移後殘留 .bak 檔案**：遷移完成後舊檔案會被重新命名為 `.bak`，使用者可手動刪除確認無誤後的 `.bak`
- **Agent 目標目錄已有同名檔案**：詢問是否覆蓋