feat(v3.7.0 Phase 1 MVP): Claude Code plugin packaging — manifest + skills/ symlinks + dual-track install (3 codex rounds, 0 findings) (#68)

* docs(design): add v3.7.0 plugin packaging roadmap

Phase 1 MVP (1-2h): .claude-plugin/plugin.json + marketplace.json + skills/ symlinks
Phase 2 (1-2d): 10 slash commands + 7 agent council members + hooks (codex audit pipeline)
Phase 3 (0.5d): marketplace publish + auto-update guidance + version bump checklist update
Phase 4: traffic monitoring (clones / install ratio post-plugin)

Verified facts via claude-code-guide agent:
- Plugin auto-update: third-party plugins default OFF, user toggles per marketplace
- Platform support: CC CLI / VS Code / JetBrains only — claude.ai web / cowork / API NO
- Codex CLI: incompatible (separate AGENTS.md ecosystem); use academic-research-skills-codex fork
- Min manifest: name + description (+ optional version)

Isolation from concurrent v3.6.7 session: 0 path overlap, fetch-before-push.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(v3.7.0): patch roadmap with v3.6.7-derived updates + verified plugin spec facts

Post-v3.6.7 ship retrospective patch (2026-05-05). Added "Update note" block at top of roadmap that supersedes parts of the original 2026-04-30 draft:

- Verified plugin manifest spec facts (claude-code-guide query 2026-05-05): skills/ auto-discovery confirmed, symlinks resolve transparently per docs, min manifest = name only, marketplace.json shape uses source.{source: directory, path: ...} not plugins[].path.
- Phase 2 hooks must wrap scripts/run_codex_audit.sh (already on main from v3.6.7 Phase 6.1), not reinvent codex audit.
- Phase 2 agent council shrinks 7→3 (synthesis_agent / research_architect_agent / report_compiler_agent) per v3.6.7 Phase 6.7 inversion sweep.
- Phase 2 plugin agent prompts must symlink or single-source from repo agents to avoid Pattern C3 attack surface re-introduction.
- Phase 3 version sweep grows 7→9 categories (.claude-plugin/plugin.json added).
- Bash 4+ hook safety reminder for macOS stock Bash 3.2 users.
- Phase 0 inserted: spec verification + SKILL.md frontmatter check + CI baseline. Done as of this commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(v3.7.0 Phase 1 MVP): Claude Code plugin packaging — manifest + skills/ symlinks + dual-track install docs

Phase 1 of plugin packaging roadmap (docs/design/2026-04-30-ars-v3.7.0-plugin-packaging-roadmap.md). Lets users install ARS via `/plugin marketplace add Imbad0202/academic-research-skills` + `/plugin install academic-research-skills` while preserving the existing clone+symlink install path for the 4.3k clone+symlink user base.

What lands:
- .claude-plugin/plugin.json: name, version 3.7.0, description (covers v3.6.7 audit gate + v3.6.8 generator-evaluator contract), author, repo metadata, CC-BY-NC-4.0 license, 9 keywords.
- .claude-plugin/marketplace.json: self-hosted marketplace shape per code.claude.com docs (source.{source: directory, path: .}); supersedes the speculative plugins[].path shape in the original roadmap.
- skills/: relative symlinks pointing to the four sibling skill directories (deep-research, academic-paper, academic-paper-reviewer, academic-pipeline). Plugin loader resolves symlinks transparently per docs; legacy clone+symlink users unchanged.
- docs/SETUP.md + docs/SETUP.zh-TW.md: new "Method 0: Claude Code Plugin (v3.7.0+, recommended)" section with auto-update guidance + platform-scope caveats (CC CLI/IDE only; claude.ai web/Claude for Work/API not supported; Codex CLI uses fork).
- README.md + README.zh-TW.md: top of "Setup & installation" surfaces the one-line plugin install for Claude Code CLI/IDE users.

Verified pre-commit:
- python3 -c "import json; json.load(...)" parses both .claude-plugin/*.json.
- ls -la skills/ shows 4 relative symlinks; readability check on each `<skill>/SKILL.md` resolves OK.
- Repo regression: 742 pytest passed + 3 skipped (Bash 3.2 E2E gate) + 251 unittest = 993 green.
- spec_consistency + version_consistency lint scripts pass.
- No PII / hei-platform / HEEACT references in diff.

Phase 2 (slash commands + agent mirrors + hooks wrapping run_codex_audit.sh) and Phase 3 (marketplace publish + auto-update) ship as separate PRs per roadmap.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(v3.7.0 Phase 1): codex review round 1 — 2 P1 + 1 P2 closed

Round 1 trajectory: P1×2 + P2×1 + P3×0 → 0 (target).

Closures (codex empirically validated via `claude plugin validate .`):
- F-001 P1 marketplace_missing_owner: `claude plugin validate .` rejects with `owner: Invalid input: expected object, received undefined`. Earlier claude-code-guide spec query (2026-05-05) didn't surface owner as required. Fix: add top-level `"owner": {"name": "Cheng-I Wu", "url": "https://github.com/Imbad0202"}` per validator.
- F-002 P1 marketplace_invalid_source_shape: `plugins[0].source` is a RELATIVE PATH STRING starting with `./`, not the object shape `{"source": "directory", "path": "."}` that earlier docs query reported. Validator output: `plugins.0.source: Invalid input`. Fix: source → "./".
- F-003 P2 roadmap_documents_invalid_schema: roadmap update note's "Correct shape" block was based on the same erroneous spec. Fix: update note now shows the empirically-validated shape (owner + source as path string), explicitly marks the original Task 1.3 snippet below as obsolete.

References: code.claude.com/docs/en/plugins-reference, code.claude.com/docs/en/plugin-marketplaces, plus empirical `claude plugin validate .` run by codex.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(v3.7.0 Phase 1): codex review round 2 — 1 P2 closed (validator clean)

Round 2 trajectory: P2×1 → 0.

Closure:
- F-004 P2 plugin_update_command_misuse: docs used `/plugin marketplace update <name>` for manual plugin refresh, but that command only refreshes the marketplace source list — it doesn't update installed plugins. Correct command for refreshing an installed plugin is `/plugin update <name>`. Fix: docs/SETUP.md + docs/SETUP.zh-TW.md + roadmap Task 3.1 + Task 3.2 prose all updated to use `/plugin update` for plugin refresh, with a clarifying parenthetical about the marketplace-update distinction.

Codex empirically validated this round:
- `claude plugin validate .` passes
- `claude plugin validate .claude-plugin/plugin.json` passes
- `claude plugin tag --dry-run .` passes
- 4 symlinks resolve to all SKILL.md files

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Edward Cheng-I Wu
2026-05-05 16:52:27 +08:00
committed by GitHub
parent a3b95fd56b
commit 6006c5b5fa
11 changed files with 665 additions and 2 deletions
+17
View File
@@ -0,0 +1,17 @@
{
"name": "academic-research-skills",
"owner": {
"name": "Cheng-I Wu",
"url": "https://github.com/Imbad0202"
},
"description": "Academic Research Skills — production-grade research, writing, peer review, and pipeline orchestration for Claude Code.",
"plugins": [
{
"name": "academic-research-skills",
"source": "./",
"description": "4 skills + 35+ modes + Material Passport pipeline. Includes v3.6.7 cross-model audit gate and v3.6.8 generator-evaluator contract.",
"version": "3.7.0",
"license": "CC-BY-NC-4.0"
}
]
}
+23
View File
@@ -0,0 +1,23 @@
{
"name": "academic-research-skills",
"version": "3.7.0",
"description": "Production-grade academic research pipeline for Claude Code: research → write → review → revise → finalize. Ships 4 skills (deep-research, academic-paper, academic-paper-reviewer, academic-pipeline) covering 35+ modes, 32-agent ensemble, Material Passport handoff schema, v3.6.7 cross-model audit gate (synthesis + research-architect + report-compiler pattern protection layer), and v3.6.8 generator-evaluator contract for paper drafting.",
"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": "CC-BY-NC-4.0",
"keywords": [
"academic",
"research",
"writing",
"review",
"deep-research",
"literature-review",
"systematic-review",
"peer-review",
"scholarly-publishing"
]
}
+8 -1
View File
@@ -30,7 +30,14 @@ The architecture doc supersedes the sprawling pipeline description that used to
## Setup & installation
**👉 [docs/SETUP.md](docs/SETUP.md)** — install Claude Code, set up API keys, optional Pandoc/tectonic for DOCX/PDF, cross-model verification (`ARS_CROSS_MODEL`), and four installation methods including claude.ai Project import.
**Quick install for Claude Code CLI / IDE (v3.7.0+):**
```text
/plugin marketplace add Imbad0202/academic-research-skills
/plugin install academic-research-skills
```
**👉 [docs/SETUP.md](docs/SETUP.md)** — full guide: install Claude Code, set up API keys, optional Pandoc/tectonic for DOCX/PDF, cross-model verification (`ARS_CROSS_MODEL`), and five installation methods (Plugin, project skills, global skills, claude.ai Project, repo-cloned).
## Performance & cost
+8 -1
View File
@@ -30,7 +30,14 @@ v3.3 的靈感來自 [**PaperOrchestra**](https://arxiv.org/abs/2604.05018)So
## 安裝與設定
**👉 [docs/SETUP.zh-TW.md](docs/SETUP.zh-TW.md)** — 安裝 Claude Code、設定 API key、選用的 Pandoc/tectonicDOCX/PDF、跨模型驗證`ARS_CROSS_MODEL`),以及四種安裝方式含 claude.ai Project 匯入。
**Claude Code CLI / IDE 用戶一行裝v3.7.0+**
```text
/plugin marketplace add Imbad0202/academic-research-skills
/plugin install academic-research-skills
```
**👉 [docs/SETUP.zh-TW.md](docs/SETUP.zh-TW.md)** — 完整指南:安裝 Claude Code、設定 API key、選用的 Pandoc/tectonicDOCX/PDF、跨模型驗證`ARS_CROSS_MODEL`以及五種安裝方式Plugin、專案 skills、全域 skills、claude.ai Project、repo clone
## 效能與費用
+18
View File
@@ -175,6 +175,24 @@ Claude discovers skills at `<install-root>/<skill-name>/SKILL.md`. This repo con
Do not install the whole repository as one nested skill folder under `.claude/skills/academic-research-skills/`; that buries the four `SKILL.md` files one level too deep for discovery. See Anthropic's [Claude Code Skills documentation](https://code.claude.com/docs/en/skills).
### Method 0: Claude Code Plugin (v3.7.0+, recommended for Claude Code CLI / IDE users)
If you use Claude Code CLI, VS Code extension, or JetBrains extension, install ARS as a plugin:
```text
/plugin marketplace add Imbad0202/academic-research-skills
/plugin install academic-research-skills
```
The four skills (`deep-research`, `academic-paper`, `academic-paper-reviewer`, `academic-pipeline`) are auto-discovered from the plugin's `skills/` directory.
**Strongly recommended: open auto-update.** Open the `/plugin` UI, find `academic-research-skills`, and toggle auto-update on. ARS releases roughly every 12 weeks; auto-update keeps you in sync without manual refreshes. To refresh manually: `/plugin update academic-research-skills`. (`/plugin marketplace update academic-research-skills` only refreshes the marketplace source list, not the installed plugin itself.)
**Plugin platform scope:**
- ✅ Claude Code CLI / VS Code extension / JetBrains extension — full support
- ❌ claude.ai web / Claude for Work / Anthropic API direct calls — plugins not supported; use Method 1 / 2 / 3 below
- ❌ Codex CLI — use the [`academic-research-skills-codex`](https://github.com/Imbad0202/academic-research-skills-codex) fork
### Method 1: As project skills (recommended)
Use this when you want ARS available inside an existing Claude Code project.
+18
View File
@@ -175,6 +175,24 @@ Claude 會在 `<install-root>/<skill-name>/SKILL.md` 尋找 skills。這個 repo
不要把整個 repository 當成單一巢狀 skill 資料夾安裝到 `.claude/skills/academic-research-skills/`。那會讓四個 `SKILL.md` 比 Claude 可發現的位置多埋一層。請參考 Anthropic 的 [Claude Code Skills documentation](https://code.claude.com/docs/en/skills)。
### 方法零Claude Code Pluginv3.7.0+Claude Code CLI / IDE 用戶推薦)
如果你用的是 Claude Code CLI、VS Code extension 或 JetBrains extension可以一行指令安裝 ARS
```text
/plugin marketplace add Imbad0202/academic-research-skills
/plugin install academic-research-skills
```
四個 skill`deep-research``academic-paper``academic-paper-reviewer``academic-pipeline`)會從 plugin 的 `skills/` 目錄自動載入。
**強烈建議開啟 auto-update。** 進 `/plugin` UI 找到 `academic-research-skills`,把 auto-update 開起來。ARS 大約 12 週發新版,開了之後會自動同步。手動更新已安裝的 plugin`/plugin update academic-research-skills`。(`/plugin marketplace update academic-research-skills` 只重新拉 marketplace 來源,不會更新已裝 plugin。
**Plugin 平台支援範圍:**
- ✅ Claude Code CLI / VS Code extension / JetBrains extension — 完整支援
- ❌ claude.ai 網頁版 / Claude for Work / Anthropic API 直呼 — 不支援 plugin請改用方法一 / 二 / 三
- ❌ Codex CLI — 改用 [`academic-research-skills-codex`](https://github.com/Imbad0202/academic-research-skills-codex) fork
### 方法一:作為專案 Skills推薦
當你希望 ARS 可在既有 Claude Code 專案內使用時,請用此方式。
@@ -0,0 +1,569 @@
# 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.
---
**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 frontmattercommands/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.aiLLM 推薦鏈)
---
## 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`:相對路徑 symlinkfresh 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 Routing1-2 天)
**目標:** 把 10 個 mode 變成 slash commandagent council 變成 plugin agent把模型路由sonnet/opus禁 haiku寫死在 frontmatter。
**驗收:** 使用者在 session 跑 `/ars-full``/ars-revision``/ars-lit-review` 等 slash 指令直接觸發對應 modeagent 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 patternplugin 化時要在 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: 建立 hookscodex 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-updaterepo 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/PRplugin 化後預期社群貢獻會出現
**決策點:**
- 若 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 新增]
│ ├── research-agent.md
│ ├── write-agent.md
│ ├── review-agent.md
│ ├── bibliography-agent.md
│ ├── synthesis-agent.md
│ ├── survey-designer.md
│ └── abstract-compiler.md
├── hooks/ [Phase 2 新增]
│ └── hooks.json
├── scripts/
│ ├── codex-audit-on-phase-complete.sh [Phase 2 新增]
│ └── announce-ars-loaded.sh [Phase 2 新增]
├── 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 onlyCodex 用 academic-research-skills-codex」 |
---
## 與另一個 ARS Session 的隔離
**v3.6.7 sessionfeat/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
**本 roadmapfeat/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 + CHANGELOGPhase 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 loadv3.6.7 是當前主線。
**2. 平行 Phase 1 MVP1-2 小時)**—— Phase 1 不碰 spec、不碰 skill 內容,跟 v3.6.7 完全不衝突,可以即刻開工。
**3. 全部待命**—— roadmap 進 git列入 backlog需要時再啟動。
**選哪個?**
+1
View File
@@ -0,0 +1 @@
../academic-paper
+1
View File
@@ -0,0 +1 @@
../academic-paper-reviewer
+1
View File
@@ -0,0 +1 @@
../academic-pipeline
+1
View File
@@ -0,0 +1 @@
../deep-research