diff --git a/CLAUDE.md b/CLAUDE.md index e76008b..c19b9f1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,9 +4,10 @@ Local dir is `repo-audit-action/`; the **published name is `wei18/upkeep`** — ## What this is -An AI repo auditor that catches drift (stale docs, spec/code mismatch, orphaned assets, convention violations). Pipeline: **discovery → parallel reviewers → synthesis → HTML report**. Two entry points, one engine: +An AI repo auditor that catches drift (stale docs, spec/code mismatch, orphaned assets, convention violations). Pipeline: **discovery → parallel reviewers → synthesis → HTML report**. Three entry points, one engine: - **CI**: reusable workflow `.github/workflows/audit.yml` (`on: workflow_call`) + composite actions under `.github/actions/`. Runs on the *caller's* checkout; Upkeep's code arrives via `uses: wei18/upkeep/.github/actions/@`. Each reviewer is an independent matrix job. Upserts one tracking issue. +- **Marketplace**: root `action.yml`, a composite action for the conventional `- uses: wei18/upkeep@` step syntax and a GitHub Marketplace listing. Same engine and inputs as the reusable workflow, but runs as a single job so reviewers execute sequentially instead of in parallel. - **Local**: `scripts/local-audit.sh ` — same flow, `claude -p` subprocesses, temp-dir intermediates via `--add-dir`. Never creates issues; prints the summary instead. `skills/upkeep-audit/SKILL.md` is a thin wrapper (clones engine to `~/.cache/upkeep`, runs script, summarizes). The CI workflow does **not** route through the skill. ## Hard invariants diff --git a/docs/en/design.md b/docs/en/design.md index 935153e..3729510 100644 --- a/docs/en/design.md +++ b/docs/en/design.md @@ -74,6 +74,10 @@ Key points: The same pipeline runs locally via `scripts/local-audit.sh `: discovery → parallel `claude -p` reviewer subprocesses → synthesis → report. All intermediates (inventory, prompts, findings, synthesis) live in a `mktemp` work dir granted to Claude via `--add-dir` — nothing is written into the target repo. Local runs produce the same self-contained HTML report; instead of upserting a GitHub issue, the issue markdown is printed as the terminal summary. `skills/upkeep-audit/SKILL.md` is a thin Claude Code wrapper around the script: it maintains a clone in `~/.cache/upkeep`, runs the audit, and summarizes findings in chat. The skill is distributed three ways, all pointing at the same directory: as a Claude Code plugin (`.claude-plugin/marketplace.json` at the repo root lists `skills/upkeep-audit/` as a single-skill plugin named `upkeep`, installed via `/plugin install upkeep@upkeep`), via `npx skills add wei18/upkeep --skill upkeep-audit` (vercel-labs/skills flat layout), or by manual copy into `~/.claude/skills/`. Distribution is packaging only — the CI workflow remains a direct pipeline entry and does not route through the skill. +### Marketplace Composite Action + +A third integration path packages the same engine as a composite action at the repo root (`action.yml`), giving callers the conventional `- uses: wei18/upkeep@v2` step syntax and a listing on the [GitHub Marketplace](https://github.com/marketplace). Because a composite action is a single job with no `strategy.matrix`, its `discovery` → `reviewer` (×7) → `synthesis` → `report` steps run sequentially instead of in parallel — same engine, same inputs, just slower on repos with many enabled reviewers. See `docs/why-reusable-workflow.md` for why the reusable workflow above remains the primary path. Distribution here is packaging only, same as the skill: `action.yml` calls the same `.github/actions/@v2` sub-actions the reusable workflow uses. + --- ## 2. Reviewer Team @@ -216,6 +220,7 @@ Expected structure: ``` repo-audit-action/ # local directory (published name: Upkeep) +├── action.yml # composite action (Marketplace listing): `uses: wei18/upkeep@v2`, sequential reviewer steps ├── .github/ │ ├── workflows/audit.yml # reusable workflow (on: workflow_call): jobs/matrix orchestration │ └── actions/ # composite sub-actions (used by the workflow's jobs; carry Upkeep's own code) diff --git a/docs/en/overview.md b/docs/en/overview.md index 25b42f9..fadeb3f 100644 --- a/docs/en/overview.md +++ b/docs/en/overview.md @@ -8,7 +8,7 @@ Periodic human review catches some of it, but it requires keeping the full conte ## The pipeline: fan-out → synthesis → report -Upkeep has two entry points that share one engine: a reusable `workflow_call` workflow for CI, and a local Claude Code skill / plugin (or plain script) for running on your machine. Either way the pipeline is the same five stages: Discovery, Consolidate, and Report are deterministic (no LLM); the parallel reviewers and Synthesis are the LLM-driven stages. +Upkeep has three integration paths that share one engine: a reusable `workflow_call` workflow for CI, a Marketplace composite action (`- uses: wei18/upkeep@v2`, same engine and inputs, reviewers run sequentially instead of in parallel) for callers who want the conventional step syntax, and a local Claude Code skill / plugin (or plain script) for running on your machine. Either way the pipeline is the same five stages: Discovery, Consolidate, and Report are deterministic (no LLM); the parallel reviewers and Synthesis are the LLM-driven stages. **1. Discovery** diff --git a/docs/ja/README.md b/docs/ja/README.md index 7c78c7e..ae98841 100644 --- a/docs/ja/README.md +++ b/docs/ja/README.md @@ -116,6 +116,44 @@ jobs: > まだ `@v1` をお使いですか？引き続き動作しますが凍結されています——タグを `@v2` に切り替えてください。インターフェースは同一です。 +### Marketplace action として使う場合 + +おなじみの `- uses:` step 構文を使いたい場合や、Upkeep を +[GitHub Marketplace](https://github.com/marketplace) に表示させたい場合は、 +**Upkeep Audit** action を代わりに使用してください——同じエンジン、同じ入力 +ですが、レビュアーは並列ではなく順番に実行されます（上記の reusable workflow +が主要なパスである理由については +[`docs/why-reusable-workflow.md`](why-reusable-workflow.md) を参照）： + +```yaml +name: repo audit +on: + schedule: + - cron: '0 3 * * 1' # weekly, Monday 03:00 UTC + workflow_dispatch: + +permissions: + contents: read + issues: write + id-token: write + +jobs: + audit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: wei18/upkeep@v2 + with: + model: claude-opus-4-8 # optional + issue_label: audit # optional; default: audit + rubric_lang: en # optional; reviewer language: en | zh-TW + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} +``` + +上記と同じ要件です：`CLAUDE_CODE_OAUTH_TOKEN` という名前のリポジトリ secret +（`claude setup-token` で生成）と `permissions` ブロック。step action は +自身の permissions を宣言できないため、今回は job 自体に付与します。 + ## レビュアー | 名前 | デフォルト | チェック内容 | diff --git a/docs/ja/design.md b/docs/ja/design.md index 921cca8..d0b03a4 100644 --- a/docs/ja/design.md +++ b/docs/ja/design.md @@ -74,6 +74,10 @@ 同じパイプラインは `scripts/local-audit.sh ` でローカルでも実行できる：discovery → 並列の `claude -p` レビュアーサブプロセス → synthesis → report。中間生成物（inventory、prompts、findings、synthesis）はすべて `mktemp` の作業ディレクトリに置かれ、`--add-dir` で Claude に許可される——対象リポジトリには何も書き込まない。ローカル実行でも同じセルフコンテインドな HTML レポートを生成する。GitHub issue の upsert は行わず、issue の markdown をターミナルサマリーとして出力する。`skills/upkeep-audit/SKILL.md` はこのスクリプトの薄い Claude Code ラッパーで、`~/.cache/upkeep` のクローンを維持し、監査を実行し、findings をチャットで要約する。この skill は 3 つの方法で配布され、いずれも同じディレクトリを指す：Claude Code plugin として（リポジトリルートの `.claude-plugin/marketplace.json` が `skills/upkeep-audit/` を `upkeep` という名前の single-skill plugin として登録し、`/plugin install upkeep@upkeep` でインストール）、`npx skills add wei18/upkeep --skill upkeep-audit` 経由（vercel-labs/skills のフラットレイアウト）、または `~/.claude/skills/` への手動コピー。配布はあくまでパッケージングであり——CI workflow は引き続き直接のパイプラインエントリのままで、skill を経由しない。 +### Marketplace Composite Action + +3 つ目の統合パスとして、同じエンジンをリポジトリルートの composite action（`action.yml`）としてパッケージ化し、おなじみの `- uses: wei18/upkeep@v2` step 構文と [GitHub Marketplace](https://github.com/marketplace) への掲載を可能にする。composite action は `strategy.matrix` を使えない単一 job であるため、その `discovery` → `reviewer`（×7）→ `synthesis` → `report` の各ステップは並列ではなく順番に実行される——エンジンと入力は同じだが、有効な reviewer が多いリポジトリでは実行が遅くなる。上記の reusable workflow が主要なパスであり続ける理由は `docs/why-reusable-workflow.md` を参照。ここでの配布も skill と同様にあくまでパッケージングであり、`action.yml` は reusable workflow が使うのと同じ `.github/actions/@v2` サブアクションを呼び出している。 + --- ## 2. Reviewer チーム @@ -216,6 +220,7 @@ report: ``` repo-audit-action/ # ローカルディレクトリ（公開名 Upkeep） +├── action.yml # composite action（Marketplace 掲載用）：`uses: wei18/upkeep@v2`、reviewer ステップは順番に実行 ├── .github/ │ ├── workflows/audit.yml # 再利用可能 workflow（on: workflow_call）：jobs/matrix オーケストレーション │ └── actions/ # composite サブ action（workflow の job が uses で参照、Upkeep コードを内包） diff --git a/docs/ja/overview.md b/docs/ja/overview.md index b4b0393..4e293e2 100644 --- a/docs/ja/overview.md +++ b/docs/ja/overview.md @@ -8,7 +8,7 @@ ## パイプライン: ファンアウト → 統合 → レポート -Upkeep には同一のエンジンを共有する2つのエントリーポイントがあります。CI 用の再利用可能な `workflow_call` workflow と、ローカルで実行する Claude Code skill / plugin（あるいは単なるスクリプト）です。いずれの場合もパイプラインは同じ5つのステージです。Discovery、Consolidate、Report は決定論的（LLM なし）であり、並列の reviewers と Synthesis が LLM 駆動のステージです。 +Upkeep には同一のエンジンを共有する3つの統合パスがあります。CI 用の再利用可能な `workflow_call` workflow、おなじみの step 構文を使いたい場合向けの Marketplace composite action（`- uses: wei18/upkeep@v2`。エンジンと入力は同じですが、reviewer は並列ではなく順番に実行されます）、そしてローカルで実行する Claude Code skill / plugin（あるいは単なるスクリプト）です。いずれの場合もパイプラインは同じ5つのステージです。Discovery、Consolidate、Report は決定論的（LLM なし）であり、並列の reviewers と Synthesis が LLM 駆動のステージです。 **1. ディスカバリー** diff --git a/docs/ko/README.md b/docs/ko/README.md index f685fbe..fa53c6b 100644 --- a/docs/ko/README.md +++ b/docs/ko/README.md @@ -116,6 +116,44 @@ jobs: > 아직 `@v1`을 사용 중인가요? 계속 동작하지만 동결되었습니다 — 태그를 `@v2`로 바꾸세요. 인터페이스는 동일합니다. +### 또는 Marketplace action으로 + +익숙한 `- uses:` step 문법을 선호하거나 Upkeep을 +[GitHub Marketplace](https://github.com/marketplace)에 노출하고 싶다면? +대신 **Upkeep Audit** action을 사용하세요 — 동일한 엔진, 동일한 입력이지만 +리뷰어가 병렬이 아니라 차례로 실행됩니다(위 reusable workflow가 기본 +경로인 이유는 [`docs/why-reusable-workflow.md`](why-reusable-workflow.md) +참조): + +```yaml +name: repo audit +on: + schedule: + - cron: '0 3 * * 1' # weekly, Monday 03:00 UTC + workflow_dispatch: + +permissions: + contents: read + issues: write + id-token: write + +jobs: + audit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: wei18/upkeep@v2 + with: + model: claude-opus-4-8 # optional + issue_label: audit # optional; default: audit + rubric_lang: en # optional; reviewer language: en | zh-TW + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} +``` + +위와 동일한 요구 사항입니다: `CLAUDE_CODE_OAUTH_TOKEN`라는 이름의 저장소 +secret(`claude setup-token`으로 생성)과 `permissions` 블록. step action은 +자체적으로 permissions를 선언할 수 없으므로, 이번에는 job 자체에 지정합니다. + ## 리뷰어 | 이름 | 기본값 | 검사 항목 | diff --git a/docs/ko/design.md b/docs/ko/design.md index 7348ef0..04dd2bb 100644 --- a/docs/ko/design.md +++ b/docs/ko/design.md @@ -74,6 +74,10 @@ 동일한 파이프라인을 `scripts/local-audit.sh `로 로컬에서 실행할 수 있다: discovery → 병렬 `claude -p` 리뷰어 서브프로세스 → synthesis → report. 모든 중간 산출물(inventory, prompts, findings, synthesis)은 `mktemp` 작업 디렉터리에 두고 `--add-dir`로 Claude에 권한을 부여한다 — 대상 저장소에는 아무것도 쓰지 않는다. 로컬 실행도 동일한 self-contained HTML 리포트를 생성하며, GitHub 이슈를 upsert하는 대신 이슈 markdown을 터미널 요약으로 출력한다. `skills/upkeep-audit/SKILL.md`는 이 스크립트의 얇은 Claude Code 래퍼로, `~/.cache/upkeep` 클론을 유지하고 감사를 실행한 뒤 findings를 채팅으로 요약한다. 이 skill은 세 가지 방식으로 배포되며 모두 동일한 디렉터리를 가리킨다: Claude Code plugin으로(저장소 루트의 `.claude-plugin/marketplace.json`이 `skills/upkeep-audit/`을 `upkeep`이라는 이름의 single-skill plugin으로 등록하며 `/plugin install upkeep@upkeep`으로 설치), `npx skills add wei18/upkeep --skill upkeep-audit`을 통해(vercel-labs/skills 플랫 레이아웃), 또는 `~/.claude/skills/`에 수동 복사. 배포는 패키징일 뿐이며 — CI workflow는 여전히 직접적인 파이프라인 진입점으로, skill을 거치지 않는다. +### Marketplace Composite Action + +세 번째 통합 경로는 동일한 엔진을 저장소 루트의 composite action(`action.yml`)으로 패키징하여, 익숙한 `- uses: wei18/upkeep@v2` step 문법과 [GitHub Marketplace](https://github.com/marketplace) 등재를 가능하게 한다. composite action은 `strategy.matrix`를 사용할 수 없는 단일 job이므로, `discovery` → `reviewer`(×7) → `synthesis` → `report` 각 step이 병렬이 아니라 순차적으로 실행된다 — 엔진과 입력은 동일하지만, 활성화된 리뷰어가 많은 저장소에서는 더 느려진다. 위 reusable workflow가 여전히 기본 경로인 이유는 `docs/why-reusable-workflow.md`를 참조. 여기서의 배포 역시 skill과 마찬가지로 패키징일 뿐이다: `action.yml`은 reusable workflow가 사용하는 것과 동일한 `.github/actions/@v2` 서브 action을 호출한다. + --- ## 2. Reviewer 팀 @@ -216,6 +220,7 @@ report: ``` repo-audit-action/ # 로컬 디렉터리（발행명 Upkeep） +├── action.yml # composite action（Marketplace 등재용）: `uses: wei18/upkeep@v2`, reviewer step 순차 실행 ├── .github/ │ ├── workflows/audit.yml # 재사용 가능한 workflow（on: workflow_call）: jobs/matrix 편성 │ └── actions/ # composite 서브 action（workflow의 job uses에서 참조, Upkeep 코드 포함） diff --git a/docs/ko/overview.md b/docs/ko/overview.md index 561d2d9..797baf0 100644 --- a/docs/ko/overview.md +++ b/docs/ko/overview.md @@ -8,7 +8,7 @@ ## 파이프라인: fan-out → 종합 → 보고 -Upkeep에는 동일한 엔진을 공유하는 두 개의 진입점이 있습니다. CI용 재사용 가능한 `workflow_call` workflow와, 로컬에서 실행하는 Claude Code skill / plugin(또는 순수 스크립트)입니다. 어느 쪽이든 파이프라인은 동일한 다섯 단계입니다. Discovery, Consolidate, Report는 결정적(LLM 없음)이며, 병렬 reviewers와 Synthesis가 LLM 기반 단계입니다. +Upkeep에는 동일한 엔진을 공유하는 세 가지 통합 경로가 있습니다. CI용 재사용 가능한 `workflow_call` workflow, 익숙한 step 문법을 선호하는 경우를 위한 Marketplace composite action(`- uses: wei18/upkeep@v2`, 동일한 엔진과 입력이지만 reviewer가 병렬이 아니라 차례로 실행됨), 그리고 로컬에서 실행하는 Claude Code skill / plugin(또는 순수 스크립트)입니다. 어느 쪽이든 파이프라인은 동일한 다섯 단계입니다. Discovery, Consolidate, Report는 결정적(LLM 없음)이며, 병렬 reviewers와 Synthesis가 LLM 기반 단계입니다. **1. 탐색(Discovery)** diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md index 00e80b5..a57954c 100644 --- a/docs/zh-CN/README.md +++ b/docs/zh-CN/README.md @@ -116,6 +116,43 @@ jobs: > 还在用 `@v1`？它仍可运行但已冻结——把 tag 换成 `@v2` 即可。接口完全相同。 +### 或作为 Marketplace action + +偏好熟悉的 `- uses:` step 语法，或想让 Upkeep 出现在 +[GitHub Marketplace](https://github.com/marketplace)？改用 **Upkeep Audit** +action——同一套引擎、同样的输入参数，但审查器会依次执行，而非并行执行（原因见 +[`docs/why-reusable-workflow.md`](why-reusable-workflow.md)，说明为何上面的 +reusable workflow 才是主要路径）： + +```yaml +name: repo audit +on: + schedule: + - cron: '0 3 * * 1' # weekly, Monday 03:00 UTC + workflow_dispatch: + +permissions: + contents: read + issues: write + id-token: write + +jobs: + audit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: wei18/upkeep@v2 + with: + model: claude-opus-4-8 # optional + issue_label: audit # optional; default: audit + rubric_lang: en # optional; reviewer language: en | zh-TW + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} +``` + +与上方相同的要求：一个名为 `CLAUDE_CODE_OAUTH_TOKEN` 的仓库 secret（通过 +`claude setup-token` 生成）以及 `permissions` 块，现在放在 job 本身上，因为 +step action 无法自行声明权限。 + ## 审查器 | 名称 | 默认状态 | 检查内容 | diff --git a/docs/zh-CN/design.md b/docs/zh-CN/design.md index 9d76fde..562cb14 100644 --- a/docs/zh-CN/design.md +++ b/docs/zh-CN/design.md @@ -74,6 +74,10 @@ 同一套 pipeline 可通过 `scripts/local-audit.sh ` 在本地执行：discovery → 并行 `claude -p` reviewer 子进程 → synthesis → report。所有中间产物（inventory、prompts、findings、synthesis）都放在 `mktemp` 工作目录，通过 `--add-dir` 授权给 Claude——不会写入目标 repo。本地执行产出同一份 self-contained HTML 报告；不会 upsert GitHub issue，而是把 issue markdown 打印出来作为终端摘要。`skills/upkeep-audit/SKILL.md` 是包装此脚本的 Claude Code 薄包装：维护 `~/.cache/upkeep` 的 clone、执行审计、在对话中总结 findings。此 skill 以三种方式发布，均指向同一个目录：作为 Claude Code plugin（repo 根目录的 `.claude-plugin/marketplace.json` 将 `skills/upkeep-audit/` 列为名为 `upkeep` 的 single-skill plugin，通过 `/plugin install upkeep@upkeep` 安装）、通过 `npx skills add wei18/upkeep --skill upkeep-audit`（vercel-labs/skills 扁平布局），或手动复制到 `~/.claude/skills/`。发布仅是打包层面——CI workflow 仍是直接的 pipeline 入口，不会绕经此 skill。 +### Marketplace Composite Action + +第三种集成形态把同一套引擎打包成 repo 根目录下的一个 composite action（`action.yml`），提供常见的 `- uses: wei18/upkeep@v2` step 语法，并可上架 [GitHub Marketplace](https://github.com/marketplace)。由于 composite action 是单一 job、不能使用 `strategy.matrix`，它的 `discovery` → `reviewer`（×7）→ `synthesis` → `report` 各 step 会依次执行而非并行——同一套引擎、同样的输入，只是在启用较多 reviewer 的 repo 上会更慢。为何上面的 reusable workflow 仍是主要路径，见 `docs/why-reusable-workflow.md`。这里的发布同样仅是打包层面，与 skill 相同：`action.yml` 调用的是 reusable workflow 所用的同一批 `.github/actions/@v2` 子 action。 + --- ## 2. Reviewer 团队 @@ -216,6 +220,7 @@ report: ``` repo-audit-action/ # 本地目录（发布名 Upkeep） +├── action.yml # composite action（用于 Marketplace 上架）：`uses: wei18/upkeep@v2`，reviewer step 依次执行 ├── .github/ │ ├── workflows/audit.yml # 可复用 workflow（on: workflow_call）：jobs/matrix 编排 │ └── actions/ # composite 子 action（被 workflow 的 job uses，自带 Upkeep 代码） diff --git a/docs/zh-CN/overview.md b/docs/zh-CN/overview.md index 8ed2c3a..4d0f58a 100644 --- a/docs/zh-CN/overview.md +++ b/docs/zh-CN/overview.md @@ -8,7 +8,7 @@ ## 流水线：扇出 → 汇总 → 报告 -Upkeep 有两个共用同一引擎的入口：CI 用的可复用 `workflow_call` workflow，以及在本地运行的 Claude Code skill / plugin（或纯脚本）。两者的流水线都是相同的五个阶段：Discovery、Consolidate 与 Report 为确定性（无 LLM）；并行的 reviewers 与 Synthesis 才是 LLM 驱动的阶段。 +Upkeep 有三种共用同一引擎的集成形态：CI 用的可复用 `workflow_call` workflow、供偏好常见 step 语法者使用的 Marketplace composite action（`- uses: wei18/upkeep@v2`，同一套引擎与输入，但 reviewer 依次执行而非并行），以及在本地运行的 Claude Code skill / plugin（或纯脚本）。三者的流水线都是相同的五个阶段：Discovery、Consolidate 与 Report 为确定性（无 LLM）；并行的 reviewers 与 Synthesis 才是 LLM 驱动的阶段。 **1. 发现（Discovery）** diff --git a/docs/zh-TW/README.md b/docs/zh-TW/README.md index 253a5bb..690e4a8 100644 --- a/docs/zh-TW/README.md +++ b/docs/zh-TW/README.md @@ -116,6 +116,43 @@ jobs: > 還在用 `@v1`？它仍可運作但已凍結——把 tag 換成 `@v2` 即可。介面完全相同。 +### 或作為 Marketplace action + +偏好熟悉的 `- uses:` step 語法，或想讓 Upkeep 出現在 +[GitHub Marketplace](https://github.com/marketplace)？改用 **Upkeep Audit** +action——同一套引擎、同樣的輸入參數，但審查員會依序執行，而非並行（原因見 +[`docs/why-reusable-workflow.md`](why-reusable-workflow.md)，說明為何上方的 +reusable workflow 才是主要路徑）： + +```yaml +name: repo audit +on: + schedule: + - cron: '0 3 * * 1' # weekly, Monday 03:00 UTC + workflow_dispatch: + +permissions: + contents: read + issues: write + id-token: write + +jobs: + audit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: wei18/upkeep@v2 + with: + model: claude-opus-4-8 # optional + issue_label: audit # optional; default: audit + rubric_lang: en # optional; reviewer language: en | zh-TW + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} +``` + +與上方相同的需求：一個名為 `CLAUDE_CODE_OAUTH_TOKEN` 的 repo secret（由 +`claude setup-token` 產生）以及 `permissions` 區塊，現在放在 job 本身上， +因為 step action 無法自行宣告 permissions。 + ## 審查員 | 名稱 | 預設 | 檢查項目 | diff --git a/docs/zh-TW/design.md b/docs/zh-TW/design.md index a2f0b37..5334ef7 100644 --- a/docs/zh-TW/design.md +++ b/docs/zh-TW/design.md @@ -74,6 +74,10 @@ 同一套 pipeline 可透過 `scripts/local-audit.sh ` 在本機執行：discovery → 平行 `claude -p` reviewer 子程序 → synthesis → report。所有中間產物（inventory、prompts、findings、synthesis）都放在 `mktemp` 工作目錄，透過 `--add-dir` 授權給 Claude——不會寫入目標 repo。本機執行產出同一份 self-contained HTML 報告；不會 upsert GitHub issue，而是把 issue markdown 印出作為終端機摘要。`skills/upkeep-audit/SKILL.md` 是包裝此腳本的 Claude Code 薄包裝：維護 `~/.cache/upkeep` 的 clone、執行稽核、在對話中摘要 findings。此 skill 以三種方式發佈，皆指向同一個目錄：作為 Claude Code plugin（repo 根目錄的 `.claude-plugin/marketplace.json` 將 `skills/upkeep-audit/` 列為名為 `upkeep` 的 single-skill plugin，透過 `/plugin install upkeep@upkeep` 安裝）、透過 `npx skills add wei18/upkeep --skill upkeep-audit`（vercel-labs/skills 扁平佈局），或手動複製到 `~/.claude/skills/`。發佈僅是打包層面——CI workflow 仍是直接的 pipeline 入口，不會繞經此 skill。 +### Marketplace Composite Action + +第三種整合形態把同一套引擎包成 repo 根目錄的一個 composite action（`action.yml`），提供慣用的 `- uses: wei18/upkeep@v2` step 語法，並可上架 [GitHub Marketplace](https://github.com/marketplace)。因為 composite action 是單一 job、不能用 `strategy.matrix`，它的 `discovery` → `reviewer`（×7）→ `synthesis` → `report` 各 step 會依序執行而非並行——同一套引擎、同樣的輸入，只是在啟用較多 reviewer 的 repo 上會較慢。為何上方的 reusable workflow 仍是主要路徑，見 `docs/why-reusable-workflow.md`。這裡的發佈同樣僅是打包層面，與 skill 相同：`action.yml` 呼叫的是 reusable workflow 所用的同一批 `.github/actions/@v2` 子 action。 + --- ## 2. Reviewer 團隊 @@ -216,6 +220,7 @@ report: ``` repo-audit-action/ # 本地目錄（發佈名 Upkeep） +├── action.yml # composite action（Marketplace 上架用）：`uses: wei18/upkeep@v2`，reviewer step 依序執行 ├── .github/ │ ├── workflows/audit.yml # 可重用 workflow（on: workflow_call）：jobs/matrix 編排 │ └── actions/ # composite 子 action（被 workflow 的 job uses，自帶 Upkeep 程式碼） diff --git a/docs/zh-TW/overview.md b/docs/zh-TW/overview.md index 7443475..b129895 100644 --- a/docs/zh-TW/overview.md +++ b/docs/zh-TW/overview.md @@ -8,7 +8,7 @@ Repo 會隨時間累積偏差。函式重構了，但文件區塊仍停留在舊 ## Pipeline 架構：展開 → 彙整 → 報告 -Upkeep 有兩個共用同一引擎的進入點：CI 用的可重用 `workflow_call` workflow，以及在本機執行的 Claude Code skill / plugin（或純腳本）。兩者的 pipeline 都是相同的五個階段：Discovery、Consolidate 與 Report 為確定性（無 LLM）；平行的 reviewers 與 Synthesis 才是 LLM 驅動的階段。 +Upkeep 有三種共用同一引擎的整合形態：CI 用的可重用 `workflow_call` workflow、給偏好慣用 step 語法者使用的 Marketplace composite action（`- uses: wei18/upkeep@v2`，同一套引擎與輸入，但 reviewer 依序執行而非並行），以及在本機執行的 Claude Code skill / plugin（或純腳本）。三者的 pipeline 都是相同的五個階段：Discovery、Consolidate 與 Report 為確定性（無 LLM）；平行的 reviewers 與 Synthesis 才是 LLM 驅動的階段。 **1. 探索（Discovery）** diff --git a/skills/upkeep-audit/.claude-plugin/plugin.json b/skills/upkeep-audit/.claude-plugin/plugin.json index 4190beb..8e59ef0 100644 --- a/skills/upkeep-audit/.claude-plugin/plugin.json +++ b/skills/upkeep-audit/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "upkeep", "description": "Run the Upkeep repo audit locally against any repository path — output-only drift report with evidence and severity.", - "version": "2.0.1", + "version": "2.1.1", "author": { "name": "Wei18" },