{"id":51551343,"url":"https://github.com/wei18/Upkeep","last_synced_at":"2026-07-12T14:01:19.200Z","repository":{"id":362649105,"uuid":"1259987012","full_name":"wei18/Upkeep","owner":"wei18","description":"Upkeep — an AI audit crew for your repo. Catches docs/spec/asset drift with evidence; output-only. Claude Code plugin/skill + reusable CI workflow.","archived":false,"fork":false,"pushed_at":"2026-07-03T22:42:19.000Z","size":683,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T00:15:43.209Z","etag":null,"topics":["agent-skills","ai","anthropic","automation","claude","claude-code","claude-code-plugin","claude-skills","code-review","devtools","documentation","drift-detection","github-action","github-actions","reusable-workflow"],"latest_commit_sha":null,"homepage":"https://github.com/wei18/Upkeep/releases/latest","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wei18.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"wei18"}},"created_at":"2026-06-05T03:47:57.000Z","updated_at":"2026-07-03T22:42:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wei18/Upkeep","commit_stats":null,"previous_names":["wei18/upkeep"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/wei18/Upkeep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wei18%2FUpkeep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wei18%2FUpkeep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wei18%2FUpkeep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wei18%2FUpkeep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wei18","download_url":"https://codeload.github.com/wei18/Upkeep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wei18%2FUpkeep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35393398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai","anthropic","automation","claude","claude-code","claude-code-plugin","claude-skills","code-review","devtools","documentation","drift-detection","github-action","github-actions","reusable-workflow"],"created_at":"2026-07-10T00:00:52.212Z","updated_at":"2026-07-12T14:01:19.194Z","avatar_url":"https://github.com/wei18.png","language":"TypeScript","funding_links":["https://ko-fi.com/wei18"],"categories":["Linting","⭐ 精选第三方技能"],"sub_categories":["💻 开发效率"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/banner.svg\" alt=\"Upkeep — your AI writes fast, Upkeep keeps it honest\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# Upkeep\n\n**English** · [繁體中文](docs/zh-TW/README.md) · [简体中文](docs/zh-CN/README.md) · [日本語](docs/ja/README.md) · [한국어](docs/ko/README.md)\n\n**An AI audit crew for your repo, installed as a skill.** Upkeep dispatches focused AI reviewers in parallel to catch drift — stale docs, specs that no longer match the code, orphaned assets, broken conventions — and reports it with evidence before it compounds.\n\n\u003e 💳 **No separate API bill.** Upkeep runs on your existing **Claude Pro/Max subscription** — your logged-in `claude` CLI locally, or OAuth via `claude setup-token` in CI. No Anthropic API key, no per-token billing. And it's **output-only**: it reports drift with evidence and severity, but never edits or deletes your files.\n\n## Install\n\n**Claude Code** — install as a plugin:\n\n```\n/plugin marketplace add wei18/upkeep\n/plugin install upkeep@upkeep\n```\n\n**Other agents** (Cursor, Copilot, and any of the 70+ agents supported by [skills](https://github.com/vercel-labs/skills)):\n\n```bash\nnpx skills add wei18/upkeep --skill upkeep-audit\n```\n\n**Requirements:** a logged-in `claude` CLI (Pro/Max), Node 20+, git — the engine runs on your machine in every install mode.\n\nThen ask in any session:\n\n\u003e Run an upkeep audit on /path/to/repo\n\nOn first use the skill clones the Upkeep engine into `~/.cache/upkeep` and installs dependencies automatically. You get findings grouped by severity in chat, plus a self-contained HTML report.\n\n## What it does\n\n- Scans a repository and dispatches a team of **focused AI reviewers** in parallel.\n- Catches stale docs that drifted from code, specs that no longer match implementation, duplicate or orphaned files, convention violations, and out-of-sync translated docs.\n- **Reports divergence with evidence** — it does not assume one artifact is always the source of truth.\n- **Never edits or deletes anything** — output only.\n- Produces a self-contained **HTML report** — and, when run in CI, a **persistent GitHub tracking issue** (upserted, never duplicated).\n\n## How it compares\n\nUpkeep isn't a linter or a PR bot — it's a **whole-repo, semantic drift auditor**. Different tool, different job:\n\n| | **Upkeep** | Danger | Copilot / Cursor PR review |\n|---|---|---|---|\n| Looks at | The **whole repo** — docs, specs, assets, conventions | A PR's diff | A PR's diff |\n| Finds | **Semantic drift** (README promises X, code does Y) | Rule violations **you hand-write** | Code issues in the diff |\n| Rubric | Your repo's **own** conventions | Your custom rules | General code knowledge |\n| Cadence | Scheduled or on-demand, repo-wide | Per PR | Per PR |\n| Edits your code? | **Never** — output only | No | Suggests changes |\n| Cost | Your **Claude Pro/Max** plan | Free (you write the logic) | Copilot/Cursor subscription |\n\n## Run as a plain script\n\nNo agent at all? The same pipeline runs as a standalone script:\n\n```bash\ngit clone --depth 1 https://github.com/wei18/upkeep ~/.cache/upkeep\ncd ~/.cache/upkeep \u0026\u0026 npm ci\n./scripts/local-audit.sh /path/to/repo --out ~/upkeep-report.html\n```\n\n| Flag | Default | CI equivalent |\n|---|---|---|\n| `--model` | `claude-opus-4-8` | `model` |\n| `--rubric-lang` | `en` | `rubric_lang` |\n| `--max-turns` | `30` | `max_turns` |\n| `--out` | `./upkeep-report.html` | report artifact |\n\n**Requirements:** a logged-in `claude` CLI (Pro/Max; no `setup-token` and no GitHub access needed), Node 20+, git.\n\n**Output:** the same self-contained HTML report (`upkeep-report.html` by default) plus a terminal summary. Local runs never create GitHub issues.\n\nPrefer a manual skill install? Copy [`skills/upkeep-audit/`](skills/upkeep-audit/) into `~/.claude/skills/`.\n\n## Automate it in CI\n\nThe same audit crew, on a schedule. Create `.github/workflows/audit.yml` in your repo:\n\n```yaml\nname: repo audit\non:\n  schedule:\n    - cron: '0 3 * * 1'   # weekly, Monday 03:00 UTC\n  workflow_dispatch:        # also run manually\n\npermissions:\n  contents: read\n  issues: write\n  id-token: write\n\njobs:\n  audit:\n    uses: wei18/upkeep/.github/workflows/audit.yml@v2\n    with:\n      model: claude-opus-4-8     # optional\n      issue_label: audit         # optional; default: audit\n      rubric_lang: en            # optional; reviewer language: en | zh-TW\n    secrets:\n      claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}\n```\n\n**Requirements**\n\n- A repo secret named `CLAUDE_CODE_OAUTH_TOKEN` — generate it locally with `claude setup-token` (available to Claude Pro/Max subscribers; usage counts against your subscription).\n- The `permissions` block shown above (`contents: read` + `issues: write` + `id-token: write`).\n\n**Outputs**\n\n- A GitHub issue labeled `audit` — the same issue is updated on every run (upserted), not duplicated.\n- A self-contained HTML report uploaded as the `report-html` workflow artifact. The tracking issue links straight to it; otherwise find it under the run's **Artifacts** (Actions → the run) or grab it with `gh run download \u003crun-id\u003e -n report-html`. GitHub serves artifacts as a downloadable zip, and they expire per your repo's retention setting.\n\n\u003e Already on `@v1`? It keeps working but is frozen — switch the tag to `@v2`. The interface is identical.\n\n### Or as a Marketplace action\n\nPrefer the familiar `- uses:` step syntax, or want Upkeep to show up in the\n[GitHub Marketplace](https://github.com/marketplace)? Use the **Upkeep Audit**\naction instead — same engine, same inputs, but the reviewers run one after\nanother instead of in parallel (see\n[`docs/why-reusable-workflow.md`](docs/en/why-reusable-workflow.md) for why\nthe reusable workflow above is the primary path):\n\n```yaml\nname: repo audit\non:\n  schedule:\n    - cron: '0 3 * * 1'   # weekly, Monday 03:00 UTC\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  issues: write\n  id-token: write\n\njobs:\n  audit:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v7\n      - uses: wei18/upkeep@v2\n        with:\n          model: claude-opus-4-8               # optional\n          issue_label: audit                    # optional; default: audit\n          rubric_lang: en                       # optional; reviewer language: en | zh-TW\n          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}\n```\n\nSame requirements as above: a repo secret named `CLAUDE_CODE_OAUTH_TOKEN`\n(from `claude setup-token`) and the `permissions` block, now on the job\nitself since a step action can't declare its own permissions.\n\n## Reviewers\n\n| Name | Default | Checks |\n|---|---|---|\n| `docs_staleness` | on | Docs that drifted from code; out-of-sync multilingual READMEs and translated docs |\n| `code_hygiene` | on | Dead code, unused exports, commented-out blocks left in permanently |\n| `spec_flow` | on | Specs, diagrams, and flow charts that no longer match the implementation |\n| `visual_icon` | on | Outdated or mismatched images and icons |\n| `duplicate_orphan` | on | Duplicate files and orphaned/unreferenced assets |\n| `convention` | on | Violations of the repo's own conventions (CLAUDE.md, `.claude/skills`, workflows) |\n| `i18n` | **off** | Internationalization consistency across locale files |\n\n## Configuration\n\nThere are two separate configuration surfaces, by design:\n\n- **Workflow inputs** (the caller's `with:` block above; locally, the equivalent script flags) control *how the engine runs*: `model`, `max_turns`, `issue_label`, `rubric_lang`.\n- **`.claude/audit.yml`** (committed in the audited repo) controls *what gets audited*: which reviewers are enabled, per-reviewer rubric overrides, and `report.minSeverity`. Reviewer enablement lives here — not as a workflow input — because it is a per-repo policy that should evolve with the repo.\n\nEverything is optional. To turn on the off-by-default `i18n` reviewer, for example:\n\n```yaml\n# .claude/audit.yml\nreviewers:\n  i18n:\n    enabled: true\n```\n\nSee [`docs/design.md`](docs/en/design.md) for the full schema and options.\n\n## Docs\n\n- [`docs/overview.md`](docs/en/overview.md) — how the pipeline works\n- [`docs/design.md`](docs/en/design.md) — full design reference\n- [`docs/why-reusable-workflow.md`](docs/en/why-reusable-workflow.md) — why the CI layer is a reusable workflow, not a `- uses:` step action\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwei18%2FUpkeep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwei18%2FUpkeep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwei18%2FUpkeep/lists"}