# ARS v3.7.0 Plugin Packaging Roadmap

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

---

## Update note 2026-05-05 (post-v3.6.7 ship retrospective patch)

This roadmap was drafted on 2026-04-30, before v3.6.7 Phase 6.1-6.8 shipped to main `a3b95fd`. The v3.6.7 ship cycle produced concrete artifacts and constraints that supersede some of the speculative wording below. **When the roadmap and this update note disagree, this update note wins.**

**Verified plugin manifest spec facts (claude-code-guide query, 2026-05-05):**
- ✅ Skills auto-discover from `skills/` directory at plugin root — no `skillsPaths` field exists.
- ✅ **Symlinks resolve transparently** ("Symlinks are preserved in the cache rather than dereferenced, and they resolve to their target at runtime" — `code.claude.com/docs/en/plugins-reference.md`). Phase 1 symlink approach is safe.
- ✅ Min manifest = `name` only required; `version` defaults to git commit SHA when omitted; `description` / `author` / `homepage` / `repository` / `license` / `keywords` all optional.
- ✅ Plugin loader **ignores SKILL.md `version` / `license` / `metadata` block** — no field collision with our existing 4 SKILL.md files.
- ⚠️ **`marketplace.json` schema differs from this roadmap's draft.** Correct shape (verified empirically with `claude plugin validate .` on 2026-05-05; see codex review F-001/F-002 closure):
  ```json
  {
    "name": "...",
    "owner": {"name": "Author Name", "url": "https://github.com/..."},
    "plugins": [
      {
        "name": "academic-research-skills",
        "source": "./"
      }
    ]
  }
  ```
  - `owner` is REQUIRED at marketplace top level (validator: `owner: Invalid input: expected object, received undefined`).
  - `plugins[].source` is a relative-path STRING starting with `./` for self-hosted directory plugins, NOT an object with `{source: "directory", path: "..."}`. Earlier doc-query iterations and the original Task 1.3 both got this wrong.
  - Task 1.3 in the original roadmap below uses `plugins[].path` directly — also wrong. **Treat the original Task 1.3 snippet as obsolete reference; the verified shape above wins.**

**v3.6.7-derived updates that change Phase 2-3 work:**
1. **Phase 2 hooks must wrap `scripts/run_codex_audit.sh`, NOT reinvent codex audit.** The wrapper exists on main with full §3-§4 contract (4 contract files + 3 diagnostic files, Bash 4+, atomic writes, SIGTERM trap, TOCTOU detection). Hook script invokes the wrapper as a subprocess; do not duplicate its logic.
2. **Phase 2 agent council list shrinks from 7 to 3.** v3.6.7 Phase 6.7 hardened **three** downstream agents with PATTERN PROTECTION (v3.6.7) blocks + INV-1/2/3 lint: `synthesis_agent`, `research_architect_agent` (survey-designer mode), `report_compiler_agent` (abstract-only mode). Plugin agents must mirror these three exactly. `bibliography-agent` per-pattern protection is v3.6.8+ work, not v3.7.0 plugin scope.
3. **Phase 2 plugin agent prompts MUST NOT drift from repo agent prompts.** Either symlink `agents/<agent>.md` → `deep-research/agents/<agent>.md` (relative symlink), or generate from a single source. A divergent copy would re-introduce the Pattern C3 attack surface that v3.6.7 §6 inversion sweep + INV-1/2/3 lint closes.
4. **Phase 3 version sweep checklist grows to 9 categories.** Original `feedback_version_bump_sweep_checklist.md` listed 7. v3.6.7 Step 7 + Phase 6.6 sweep extended to 8. Adding `.claude-plugin/plugin.json` makes it 9. Update the memory checklist at the same time as the first plugin version bump.
5. **Bash 4+ hook safety.** macOS stock `/bin/bash` is 3.2. `scripts/run_codex_audit.sh` already guards with a Bash version check — the new hook script must do the same OR explicitly probe Bash 4+. Silent failure on macOS stock Bash is a UX hazard for plugin users.
6. **Phase 0 inserted before Phase 1.** Spec verification + SKILL.md frontmatter check + CI baseline run (cost ~30 min). **Done as of 2026-05-05** on rebased branch `feat/plugin-packaging-roadmap` at HEAD `0764415` (rebased on `a3b95fd`).

**Risks added since the original roadmap:**
- Plugin marketplace.json schema shape was guessed; this patch corrects it.
- Repo CI workflow `spec-consistency.yml` runs unconditionally on push/PR. After Phase 1 commits the new `.claude-plugin/` and `skills/` paths, CI may surface unanticipated lint failures. Phase 1.4 adds an explicit "run CI as baseline" step.
- `git clone --filter=blob:none` and sparse-checkout users may not pull symlink targets correctly. Document Phase 1 commit message advises plugin users to regular-clone.

**Strategic stance** (post-v3.6.7 ship): proceed with Phase 1 MVP now. v3.6.8+ work (`bibliography_agent` pattern protection extension) is parallel-track and not a v3.7.0 blocker.

---

## Update note 2026-05-05 (Phase 2.2 scope reduction)

After Phase 2.1 shipped (PR #69, merge commit `e841319`), Phase 2.2 was scoped down from "hooks for SessionStart announce + SubagentStop codex audit" to **SessionStart announce only**. The original Task 2.4 below — `PostToolUse` matcher `Write|Edit` invoking `scripts/codex-audit-on-phase-complete.sh` — was abandoned during Phase 2.2 design review for two compounding reasons:

1. **Wrong invoker class.** `scripts/run_codex_audit.sh` lines 4–7 explicitly forbid same-session in-LLM invocation (Pattern C3 attack surface). `PostToolUse` matcher `Write|Edit` would fire from inside the LLM session that produced the deliverable — exactly the case the wrapper bans. `SubagentStop` is a permitted invoker class, but…
2. **Contract gap.** `run_codex_audit.sh` requires `--stage <1-6> --agent <name> --deliverable <repo-relative-path>`. The `SubagentStop` hook payload only carries `agent_id`, `agent_type`, `session_id`, `cwd`, `transcript_path`. There is no documented propagation path from ARS pipeline state (current stage + which deliverable just landed) into the hook payload. Building a hook that half-infers stage/deliverable would be design lying — either the wrapper runs against the wrong file, or the hook degrades to "remind the user to invoke the wrapper externally," which is no better than documenting the wrapper's CLI in the README.

Decision: **Phase 2.2 ships only the SessionStart announce hook.** A real SubagentStop → `run_codex_audit.sh` integration is deferred to v3.6.8+ when ARS gains a stage/deliverable propagation contract (likely as a passport ledger entry that the hook can read from `${CLAUDE_PROJECT_DIR}` or a fixed location under `audit_artifacts/`). The sections below describing Step 1–3 of the original Task 2.4 are retained as historical context but treated as obsoleted reference; the actual Phase 2.2 implementation lives at `hooks/hooks.json` and `scripts/announce-ars-loaded.sh`.

The `feedback_no_haiku.md` model-floor concern that motivated PostToolUse-based audit triggering is partially addressed at a different layer: ARS slash commands pin `opus`/`sonnet` in their frontmatter, plugin agents use `model: inherit`, and the user's PreToolUse `warn-agent-no-model.sh` hook enforces no-haiku at Agent dispatch. The remaining gap is "did codex actually audit the deliverable?" — that gate stays human-driven (CI workflow step or external terminal) for v3.7.0.

---

**Goal:** 將 ARS 從「git clone + symlink 到 `~/.claude/skills/`」的分發模式，升級成 Claude Code Plugin（`/plugin install` 一行裝），同時保留 GitHub repo 作為 source of truth 與教學內容主入口。

**Architecture:** 雙軌並行——同一個 repo 同時支援 (a) 傳統 clone+symlink 安裝、(b) Claude Code plugin marketplace 安裝。Plugin 化只新增 `.claude-plugin/`、`commands/`、`agents/`、`hooks/` 四個目錄，不動 `deep-research/`、`academic-paper/`、`academic-paper-reviewer/`、`academic-pipeline/` 四個既有 skill 目錄的 SKILL.md 內容。

**Tech Stack:** Claude Code Plugin Manifest spec、JSON manifest、Markdown frontmatter（commands/agents）、JSON hooks config、既有 SKILL.md（不變）。

**Platform scope（必讀）：**
- ✅ Claude Code CLI / VS Code 擴充 / JetBrains 擴充：plugin 完整支援
- ❌ claude.ai 網頁版 / Claude for Work / Anthropic API 直呼：**完全不支援 plugin**，這條路繼續靠 GitHub README + 教學內容
- ❌ Codex CLI：用 `academic-research-skills-codex` fork，不在本 roadmap 範圍

**前置條件：**
- v3.6.7 pattern protection 工作已 ship 到 main（另一個 session 在做）
- 本 roadmap 在 `feat/plugin-packaging-roadmap` branch，與 v3.6.7 工作面 0 路徑重疊
- Push 前依 `feedback_multi_agent_repo_collision.md`：`git fetch && git diff origin/main..HEAD` 驗無漂移

**Traffic baseline（決策依據）：**
- 14d clones: 10,414 / unique cloners: 4,313（日均 ~308 裝機）
- 14d views: 49,511 / UV: 13,262
- UV → cloner 轉換 ≈ 32.5%（dev tool repo 高水位）
- 流量主來源：Google 41% / github.com 19% / chatgpt.com + claude.ai（LLM 推薦鏈）

---

## Phase 1: MVP — 讓 plugin 能裝（1-2 小時）

**目標：** 最小工程量讓使用者可以 `/plugin marketplace add Imbad0202/academic-research-skills` + `/plugin install ars`，4 個既有 skill 自動被載入。

**驗收：** 在乾淨的 Claude Code session 跑 `/plugin install`，4 個 skill 出現在 skill 清單，`/skill deep-research` 可正常觸發。

### Task 1.1: 建立 plugin manifest

**Files:**
- Create: `.claude-plugin/plugin.json`

- [ ] **Step 1: 寫 manifest**

```json
{
  "name": "academic-research-skills",
  "version": "3.7.0",
  "description": "Academic Research Skills for Claude Code: research → write → review → revise → finalize. 4 skills + 10 modes + Material Passport pipeline.",
  "author": {
    "name": "Cheng-I Wu",
    "url": "https://github.com/Imbad0202"
  },
  "homepage": "https://github.com/Imbad0202/academic-research-skills",
  "repository": "https://github.com/Imbad0202/academic-research-skills",
  "license": "Other",
  "keywords": ["academic", "research", "writing", "review", "deep-research", "literature-review"]
}
```

- [ ] **Step 2: 確認 schema 合法**

Run: `python3 -c "import json; json.load(open('.claude-plugin/plugin.json'))"`
Expected: 無輸出（JSON valid）

### Task 1.2: 確認 skill 自動探索

**Files:**
- Verify: `deep-research/SKILL.md` `academic-paper/SKILL.md` `academic-paper-reviewer/SKILL.md` `academic-pipeline/SKILL.md`

- [ ] **Step 1: 確認 4 個 skill 都有合法 frontmatter**

Run: `for f in deep-research/SKILL.md academic-paper/SKILL.md academic-paper-reviewer/SKILL.md academic-pipeline/SKILL.md; do head -10 "$f"; echo "---"; done`
Expected: 每個檔案前 10 行包含 `name:` 和 `description:`

- [ ] **Step 2: Plugin spec 規定 skill 要在 `skills/` 目錄，需決策**

兩個選擇：
- **A. 移動目錄**（破壞性）：`mv deep-research skills/deep-research` ── 既有 clone 用戶的 symlink 會壞
- **B. 雙路徑**（保守）：`.claude-plugin/plugin.json` 加 `"skillsPaths": ["./", "skills/"]`（如 spec 支援），或在 manifest 列出顯式 skill 路徑

**決策：採 B**。優先保留既有 4.3k clone 用戶不破。Phase 2 再評估是否乾淨遷移到 `skills/`。

- [ ] **Step 3: 查 plugin.json 是否支援自訂 skill 路徑**

Run: `gh search repos --json name,url "topic:claude-code-plugin" | head -20`
Action: 用 claude-code-guide agent 確認 manifest schema 是否有 `skillsPaths` 或等效欄位；若無，Phase 1 採目錄符號連結方案：

```bash
mkdir -p skills
ln -s ../deep-research skills/deep-research
ln -s ../academic-paper skills/academic-paper
ln -s ../academic-paper-reviewer skills/academic-paper-reviewer
ln -s ../academic-pipeline skills/academic-pipeline
```

依 `feedback_relative_symlinks_in_repos.md`：相對路徑 symlink，fresh clone 才不會壞。

### Task 1.3: 建立 marketplace metadata

**Files:**
- Create: `.claude-plugin/marketplace.json`

- [ ] **Step 1: 寫 marketplace 描述（讓 `/plugin marketplace add` 抓得到）**

```json
{
  "name": "academic-research-skills",
  "displayName": "Academic Research Skills",
  "description": "Production-grade academic research pipeline: research → write → review → revise → finalize. 4 skills, 10 modes, Material Passport.",
  "plugins": [
    {
      "name": "academic-research-skills",
      "path": "."
    }
  ]
}
```

### Task 1.4: README 加 plugin 安裝段落

**Files:**
- Modify: `README.md`（最上方 Installation 段）
- Modify: `README.zh-TW.md`（同步）

- [ ] **Step 1: 加雙軌安裝說明**

在 Installation 章節最前面插入：

```markdown
## Installation

### Option A: Claude Code Plugin (recommended)

\`\`\`
/plugin marketplace add Imbad0202/academic-research-skills
/plugin install academic-research-skills
\`\`\`

建議在 `/plugin` UI 開啟 auto-update，這樣 ARS 每次發新版會自動拉到本地。

### Option B: Manual clone + symlink (legacy, still supported)

[既有的 clone 安裝步驟保留不動]
```

### Task 1.5: 在乾淨環境測試安裝

- [ ] **Step 1: 用 `claude --plugin-dir` 本地測試**

Run: `cd /tmp && claude --plugin-dir ~/Projects/academic-research-skills`
Expected: Claude Code 啟動後 `/skill list` 看得到 deep-research / academic-paper / academic-paper-reviewer / academic-pipeline

- [ ] **Step 2: 觸發其中一個 skill 驗證**

Run: 在 session 內 `/skill deep-research`
Expected: skill 正常載入，無 "skill not found" 錯誤

### Task 1.6: Phase 1 commit + tag

- [ ] **Step 1: Commit**

```bash
git add .claude-plugin/ skills/ README.md README.zh-TW.md
git commit -m "feat(v3.7.0): add Claude Code plugin manifest + marketplace metadata

- .claude-plugin/plugin.json: name, version 3.7.0, repo metadata
- .claude-plugin/marketplace.json: marketplace listing
- skills/: relative symlinks to existing 4 skill dirs (preserves legacy clone install)
- README: dual-track install (plugin + manual clone)

Phase 1 of plugin packaging roadmap. Skills, modes, and pipeline unchanged."
```

- [ ] **Step 2: 不 push**（依用戶 auto-push 規則，等指示）

---

## Phase 2: Slash Commands + Agent Routing（1-2 天）

**目標：** 把 10 個 mode 變成 slash command，agent council 變成 plugin agent，把模型路由（sonnet/opus，禁 haiku）寫死在 frontmatter。

**驗收：** 使用者在 session 跑 `/ars-full`、`/ars-revision`、`/ars-lit-review` 等 slash 指令直接觸發對應 mode；agent council 派工自動走 sonnet/opus 不掉到 haiku。

### Task 2.1: 列出 10 個 mode 對映表

**Files:**
- Reference: `MODE_REGISTRY.md`
- Create: `docs/design/2026-04-30-ars-mode-to-command-mapping.md`

- [ ] **Step 1: 從 MODE_REGISTRY.md 抽 10 mode + 寫對映**

| Mode | Slash command | 觸發條件 | 預設 model |
|---|---|---|---|
| full | `/ars-full` | 完整 pipeline | opus（架構決策）|
| plan | `/ars-plan` | 只規劃不寫 | sonnet |
| outline | `/ars-outline` | 大綱 | sonnet |
| revision | `/ars-revision` | 改稿 | sonnet |
| revision-coach | `/ars-revision-coach` | 改稿教練 | opus |
| abstract | `/ars-abstract` | 摘要 | sonnet |
| lit-review | `/ars-lit-review` | 文獻回顧 | sonnet |
| format-convert | `/ars-format-convert` | 格式轉換 | sonnet |
| citation-check | `/ars-citation-check` | 引用檢查 | sonnet |
| disclosure | `/ars-disclosure` | AI disclosure | sonnet |

依 `feedback_no_haiku.md`：**任何情境絕不用 haiku**。

### Task 2.2: 建立 commands/ 目錄

**Files:**
- Create: `commands/ars-full.md` 至 `commands/ars-disclosure.md`（10 個檔）

- [ ] **Step 1: 寫第一個 command 作為 template**

```markdown
---
name: ars-full
description: ARS full pipeline — research → write → review → revise → finalize
model: opus
---

Trigger ARS full mode. Load academic-pipeline skill and execute the complete academic research workflow.

ARS spec: docs/design/2026-04-29-ars-v3.6.7-downstream-agent-pattern-protection-spec.md
Mode registry: MODE_REGISTRY.md
```

- [ ] **Step 2: 為剩 9 個 mode 複製 + 改 frontmatter**（每個 2-3 分鐘）

- [ ] **Step 3: Commit**

```bash
git add commands/
git commit -m "feat(v3.7.0): add 10 slash commands for ARS modes

Maps MODE_REGISTRY entries to /ars-* slash commands with explicit model
routing (opus for full/revision-coach, sonnet for everything else).
No haiku per project policy."
```

### Task 2.3: 建立 agents/ 目錄（agent council）

**Files:**
- Create: `agents/research-agent.md` `agents/write-agent.md` `agents/review-agent.md` `agents/bibliography-agent.md` `agents/synthesis-agent.md` `agents/survey-designer.md` `agents/abstract-compiler.md`

- [ ] **Step 1: 從既有 ARS spec 抽 agent 定義 → frontmatter**

依 `feedback_ars_bibliography_agent_hallucination_patterns.md` 跟 `feedback_ars_phase2_phase3_downstream_agent_patterns.md`，這 7 個 agent 各有已知 hallucination pattern；plugin 化時要在 agent prompt 內含 pattern protection guard。

```markdown
---
name: bibliography-agent
description: ARS bibliography agent — generates citations with hallucination guards
model: sonnet
tools: Read, Write, WebFetch, WebSearch
---

[既有 agent prompt + 5 種 hallucination pattern guard]
```

- [ ] **Step 2: 7 個 agent 各別產出**（每個 5 分鐘）

- [ ] **Step 3: Commit**

```bash
git add agents/
git commit -m "feat(v3.7.0): add 7 agent council members as plugin agents

Each agent ships with documented hallucination pattern guards from
feedback_ars_*_patterns memory. Model routing baked into frontmatter."
```

### Task 2.4: 建立 hooks（codex audit pipeline）

**Files:**
- Create: `hooks/hooks.json`

- [ ] **Step 1: 寫 PostToolUse hook 觸發 codex audit**

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "scripts/codex-audit-on-phase-complete.sh",
        "description": "Run codex consult after writing phase artifacts"
      }
    ],
    "SessionStart": [
      {
        "command": "scripts/announce-ars-loaded.sh",
        "description": "Announce ARS plugin loaded with active mode hint"
      }
    ]
  }
}
```

- [ ] **Step 2: 寫對應 script**

```bash
# scripts/codex-audit-on-phase-complete.sh
#!/bin/bash
# 只在 phase artifact 寫入時觸發
case "$CLAUDE_TOOL_FILE_PATH" in
  *passport*.json|*deliverables/*) /usr/bin/which codex && codex consult --base ... ;;
esac
```

依 `feedback_anaconda_curl_recurring_ssl.md`：永遠用 `/usr/bin/which`、`/usr/bin/curl`，避免 anaconda PATH 污染。

- [ ] **Step 3: Commit**

```bash
git add hooks/ scripts/codex-audit-on-phase-complete.sh scripts/announce-ars-loaded.sh
git commit -m "feat(v3.7.0): add hooks — codex audit on phase complete + session announce"
```

### Task 2.5: Plugin self-test on real session

- [ ] **Step 1: 在新 worktree 跑完整 mode**

```bash
cd /tmp && git clone ~/Projects/academic-research-skills ars-plugin-test
cd ars-plugin-test
claude --plugin-dir .
# In session: /ars-lit-review "test topic"
```

Expected: slash command 觸發、agent dispatch、hook 跑、無 haiku 出現

---

## Phase 3: Marketplace + Auto-Update（半天）

**目標：** 推到 GitHub-hosted marketplace，使用者開 auto-update 後 push commit 即等於 publish。

**驗收：** 在另一台機器 `/plugin marketplace add Imbad0202/academic-research-skills` 後開 auto-update，repo push 新 commit 後重啟 Claude Code 自動拉新版。

### Task 3.1: 確認 marketplace 自動更新行為

**重要事實（claude-code-guide 已查證；2026-05-05 codex review F-004 校正）：**
- 第三方 plugin（如 ARS）預設 **auto-update OFF**
- 使用者要在 `/plugin` UI 切 marketplace 為 auto-update on
- 手動更新已安裝 plugin：`/plugin update academic-research-skills`
- 重新拉 marketplace 來源：`/plugin marketplace update academic-research-skills`（這個只 refresh 來源清單，不會更新已裝 plugin）

**對 push 工作流的影響：**
- 你 push commit 後，**已開 auto-update 的人**下次開 CC 自動拿到
- **沒開的人**要手動 refresh 或重新安裝
- 所以 README 必須教使用者開 auto-update

### Task 3.2: README 補 auto-update 指引

**Files:**
- Modify: `README.md` `README.zh-TW.md`

- [ ] **Step 1: 在 Installation 段補一段**

```markdown
> **強烈建議開啟 auto-update：** 進 `/plugin` UI → 找到 academic-research-skills → 開 auto-update。
> ARS 每 1-2 週發新版，開了 auto-update 才能自動同步。
> 沒開 auto-update 的話：手動跑 `/plugin update academic-research-skills`。
```

### Task 3.3: 規劃 release / changelog 策略

**Files:**
- Modify: `CHANGELOG.md`
- Modify: `.claude-plugin/plugin.json`（每次 release 同步 version）

- [ ] **Step 1: 將 plugin.json `version` 與 git tag 綁死**

每次 `git tag v3.7.x` 前必須先 bump `.claude-plugin/plugin.json` `version` 欄位。

依 `feedback_version_bump_sweep_checklist.md`：major version bump 時要 sweep 7 類地點。新增第 8 類：`.claude-plugin/plugin.json`。

- [ ] **Step 2: 更新 sweep checklist 文件**

Modify: 既有的 version bump checklist memory + ARCHITECTURE.md 提及 plugin.json

### Task 3.4: 第一次 plugin release

- [ ] **Step 1: Codex review pass**

依 `feedback_codex_iterative_spec_review_to_zero.md`：高 blast radius spec 跑 codex 直到 1 輪 0 finding。

```bash
codex review --base main
```

- [ ] **Step 2: PR 開啟（依 `feedback_ruleset_blocks_routine_commits.md`，public repo 一律走 PR）**

```bash
gh pr create --title "feat(v3.7.0): plugin packaging — Phase 1+2+3" \
  --body "[依 ARS PR template]"
```

- [ ] **Step 3: Merge + tag v3.7.0 + GitHub release**

---

## Phase 4: 觀察 + 取捨（持續）

**目標：** 監測 plugin 化是否真的降摩擦，還是反而傷量（GitHub Traffic 已經 32.5% UV→clone 轉換很高）。

**監測指標（每 14 天看 Traffic 頁）：**
- Clones 趨勢：plugin 化後 clones 不應該掉超過 30%（plugin 安裝可能不算 clone）
- 新增追蹤：GitHub Releases 下載數 + plugin marketplace install 計數（若 Anthropic 提供 API）
- Issue/PR：plugin 化後預期社群貢獻會出現

**決策點：**
- 若 plugin 化後 clones 大幅掉但安裝量沒漲（marketplace API 看不出來）→ 表示 plugin marketplace 曝光度不足，主推道仍是 GitHub
- 若 plugin 安裝量超過 clone → 可考慮把 README 主推 plugin、clone 變 advanced/dev 用法

---

## File Structure 總覽

```
academic-research-skills/
├── .claude-plugin/                    [Phase 1 新增]
│   ├── plugin.json
│   └── marketplace.json
├── skills/                             [Phase 1 新增——symlink]
│   ├── deep-research -> ../deep-research
│   ├── academic-paper -> ../academic-paper
│   ├── academic-paper-reviewer -> ../academic-paper-reviewer
│   └── academic-pipeline -> ../academic-pipeline
├── commands/                           [Phase 2 新增]
│   ├── ars-full.md
│   ├── ars-plan.md
│   ├── ars-outline.md
│   ├── ars-revision.md
│   ├── ars-revision-coach.md
│   ├── ars-abstract.md
│   ├── ars-lit-review.md
│   ├── ars-format-convert.md
│   ├── ars-citation-check.md
│   └── ars-disclosure.md
├── agents/                             [Phase 2.1 新增 — 3 個 v3.6.7 hardened agent symlinks]
│   ├── synthesis_agent.md -> ../deep-research/agents/synthesis_agent.md
│   ├── research_architect_agent.md -> ../deep-research/agents/research_architect_agent.md
│   └── report_compiler_agent.md -> ../deep-research/agents/report_compiler_agent.md
│   # NOTE: original draft listed 7 agents (research-agent / write-agent / review-agent /
│   # bibliography-agent / synthesis-agent / survey-designer / abstract-compiler).
│   # Per Update note 2026-05-05 §1, plugin agent council shrank to 3 because v3.6.7 §6
│   # inversion sweep + INV-1/2/3 lint only hardened those three. bibliography_agent and
│   # the others remain in-skill prompt templates (v3.6.8+ scope).
├── hooks/                              [Phase 2.2 新增]
│   └── hooks.json                          # SessionStart announce only
├── scripts/
│   └── announce-ars-loaded.sh              [Phase 2.2 新增 — Bash 3.2 compatible]
│   # NOTE: original draft also listed `codex-audit-on-phase-complete.sh` here.
│   # That script is ABANDONED per the Update note 2026-05-05 (Phase 2.2 scope reduction).
│   # SubagentStop → run_codex_audit.sh integration deferred to v3.6.8+.
├── deep-research/                      [既有，不動]
├── academic-paper/                     [既有，不動]
├── academic-paper-reviewer/            [既有，不動]
├── academic-pipeline/                  [既有，不動]
├── shared/                             [既有，不動]
├── docs/                               [既有，不動]
├── tests/                              [既有，不動]
├── CHANGELOG.md                        [Phase 3 更新]
├── README.md                           [Phase 1+3 更新]
└── README.zh-TW.md                     [Phase 1+3 更新]
```

---

## 風險與緩解

| 風險 | 嚴重度 | 緩解 |
|---|---|---|
| `skillsPaths` 欄位不存在於 manifest spec → Phase 1 卡住 | 高 | Task 1.2 step 3 已備 symlink fallback |
| 移動目錄破壞既有 4.3k clone 用戶的 symlink | 高 | 採雙路徑（symlink 進 skills/）不搬目錄 |
| 跟 v3.6.7 session 撞 push | 中 | 新 branch + push 前 fetch（依 feedback_multi_agent_repo_collision） |
| Plugin marketplace 曝光低於 GitHub 直接搜 | 中 | Phase 4 監測，雙軌不二選一 |
| Plugin auto-update 預設關，使用者拿不到新版 | 中 | README 強烈建議開 auto-update + 寫手動 refresh 指令 |
| Codex CLI 用戶誤裝 plugin | 低 | README 明寫「plugin = Claude Code only；Codex 用 academic-research-skills-codex」 |

---

## 與另一個 ARS Session 的隔離

**v3.6.7 session（feat/v3.6.7-pattern-protection-step-1-references）工作面：**
- `scripts/check_v3_6_7_pattern_protection.py`
- `docs/design/2026-04-29-ars-v3.6.7-downstream-agent-pattern-protection-spec.md`
- pattern reference markdown 檔（IRB / psychometric / hedging glossary）

**本 roadmap（feat/plugin-packaging-roadmap）工作面：**
- `.claude-plugin/`
- `skills/`（symlink only）
- `commands/`
- `agents/`
- `hooks/`
- `docs/design/2026-04-30-ars-v3.7.0-plugin-packaging-roadmap.md`（本檔）
- README + CHANGELOG（Phase 3 才動，到時 v3.6.7 應已 merge）

**0 路徑重疊**。Push 前依規 `git fetch && git diff origin/main..HEAD` 驗證即可。

---

## Self-Review

**1. Spec coverage：** 用戶五個問題全部回答並落到任務上：
- 自動更新機制 → Task 3.1 + Task 3.2
- Codex 不能用 plugin → 風險表 + Phase 4
- 平台支援限制（claude.ai / cowork / API 不支援）→ 文件最上方 Platform scope
- 工程量 → Phase 1 (1-2h) / Phase 2 (1-2d) / Phase 3 (0.5d)
- 與另一個 session 的隔離 → 專章「與另一個 ARS Session 的隔離」

**2. Placeholder 掃描：** Task 1.2 step 3 還是有「需要 claude-code-guide agent 確認 manifest schema」的動作，但已給出 fallback 路徑（symlink），不算 placeholder。所有 commit message 都是完整可貼的字串，無 TBD/TODO。

**3. Type consistency：** plugin.json `name` = "academic-research-skills"、marketplace.json `name` 同字串、skill 目錄名 deep-research / academic-paper / academic-paper-reviewer / academic-pipeline 全程一致。Slash command 命名 `/ars-*` 一致。

---

## Execution Handoff

**Plan complete and saved to `docs/design/2026-04-30-ars-v3.7.0-plugin-packaging-roadmap.md`. 三個執行選項：**

**1. 等 v3.6.7 ship 後再啟動**（建議）—— 避免 cognitive load，v3.6.7 是當前主線。

**2. 平行 Phase 1 MVP（1-2 小時）**—— Phase 1 不碰 spec、不碰 skill 內容，跟 v3.6.7 完全不衝突，可以即刻開工。

**3. 全部待命**—— roadmap 進 git，列入 backlog，需要時再啟動。

**選哪個？**
