From 6006c5b5fa19acf0e99e091ecf1ab4207e3bc9a6 Mon Sep 17 00:00:00 2001 From: Edward Cheng-I Wu <132531341+Imbad0202@users.noreply.github.com> Date: Tue, 5 May 2026 16:52:27 +0800 Subject: [PATCH] =?UTF-8?q?feat(v3.7.0=20Phase=201=20MVP):=20Claude=20Code?= =?UTF-8?q?=20plugin=20packaging=20=E2=80=94=20manifest=20+=20skills/=20sy?= =?UTF-8?q?mlinks=20+=20dual-track=20install=20(3=20codex=20rounds,=200=20?= =?UTF-8?q?findings)=20(#68)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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) * 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) * 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.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) * 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) * 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 ` 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 `. 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) --------- Co-authored-by: Claude Opus 4.7 (1M context) --- .claude-plugin/marketplace.json | 17 + .claude-plugin/plugin.json | 23 + README.md | 9 +- README.zh-TW.md | 9 +- docs/SETUP.md | 18 + docs/SETUP.zh-TW.md | 18 + ...-30-ars-v3.7.0-plugin-packaging-roadmap.md | 569 ++++++++++++++++++ skills/academic-paper | 1 + skills/academic-paper-reviewer | 1 + skills/academic-pipeline | 1 + skills/deep-research | 1 + 11 files changed, 665 insertions(+), 2 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude-plugin/plugin.json create mode 100644 docs/design/2026-04-30-ars-v3.7.0-plugin-packaging-roadmap.md create mode 120000 skills/academic-paper create mode 120000 skills/academic-paper-reviewer create mode 120000 skills/academic-pipeline create mode 120000 skills/deep-research diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 00000000..9310e204 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -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" + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 00000000..a5fff55c --- /dev/null +++ b/.claude-plugin/plugin.json @@ -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" + ] +} diff --git a/README.md b/README.md index b3fdd302..fc4c3685 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/README.zh-TW.md b/README.zh-TW.md index 467bc70d..e14e6371 100644 --- a/README.zh-TW.md +++ b/README.zh-TW.md @@ -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/tectonic（DOCX/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/tectonic（DOCX/PDF）、跨模型驗證（`ARS_CROSS_MODEL`），以及五種安裝方式（Plugin、專案 skills、全域 skills、claude.ai Project、repo clone）。 ## 效能與費用 diff --git a/docs/SETUP.md b/docs/SETUP.md index df8eb5b6..f090fe77 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -175,6 +175,24 @@ Claude discovers skills at `//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 1–2 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. diff --git a/docs/SETUP.zh-TW.md b/docs/SETUP.zh-TW.md index abbc82a3..bc28bfc1 100644 --- a/docs/SETUP.zh-TW.md +++ b/docs/SETUP.zh-TW.md @@ -175,6 +175,24 @@ Claude 會在 `//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 Plugin（v3.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 大約 1–2 週發新版，開了之後會自動同步。手動更新已安裝的 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 專案內使用時，請用此方式。 diff --git a/docs/design/2026-04-30-ars-v3.7.0-plugin-packaging-roadmap.md b/docs/design/2026-04-30-ars-v3.7.0-plugin-packaging-roadmap.md new file mode 100644 index 00000000..87372dc8 --- /dev/null +++ b/docs/design/2026-04-30-ars-v3.7.0-plugin-packaging-roadmap.md @@ -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/.md` → `deep-research/agents/.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 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 新增] +│ ├── 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 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，需要時再啟動。 + +**選哪個？** diff --git a/skills/academic-paper b/skills/academic-paper new file mode 120000 index 00000000..3665c78e --- /dev/null +++ b/skills/academic-paper @@ -0,0 +1 @@ +../academic-paper \ No newline at end of file diff --git a/skills/academic-paper-reviewer b/skills/academic-paper-reviewer new file mode 120000 index 00000000..b52421bd --- /dev/null +++ b/skills/academic-paper-reviewer @@ -0,0 +1 @@ +../academic-paper-reviewer \ No newline at end of file diff --git a/skills/academic-pipeline b/skills/academic-pipeline new file mode 120000 index 00000000..6dea52ea --- /dev/null +++ b/skills/academic-pipeline @@ -0,0 +1 @@ +../academic-pipeline \ No newline at end of file diff --git a/skills/deep-research b/skills/deep-research new file mode 120000 index 00000000..2a894a8a --- /dev/null +++ b/skills/deep-research @@ -0,0 +1 @@ +../deep-research \ No newline at end of file