{"id":50139399,"url":"https://github.com/ctxr-dev/skill-code-review","last_synced_at":"2026-05-24T00:06:07.298Z","repository":{"id":350666713,"uuid":"1207812150","full_name":"ctxr-dev/skill-code-review","owner":"ctxr-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-21T00:51:53.000Z","size":3335,"stargazers_count":0,"open_issues_count":45,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T07:09:10.821Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/ctxr-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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}},"created_at":"2026-04-11T12:43:19.000Z","updated_at":"2026-05-02T21:04:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ctxr-dev/skill-code-review","commit_stats":null,"previous_names":["ctxr-dev/skill-code-review"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/ctxr-dev/skill-code-review","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctxr-dev%2Fskill-code-review","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctxr-dev%2Fskill-code-review/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctxr-dev%2Fskill-code-review/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctxr-dev%2Fskill-code-review/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ctxr-dev","download_url":"https://codeload.github.com/ctxr-dev/skill-code-review/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctxr-dev%2Fskill-code-review/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33416317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-05-24T00:06:06.471Z","updated_at":"2026-05-24T00:06:07.291Z","avatar_url":"https://github.com/ctxr-dev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Code Review Skill (Claude Code, Codex CLI)\n\n[![npm](https://img.shields.io/npm/v/@ctxr/skill-code-review)](https://www.npmjs.com/package/@ctxr/skill-code-review)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Claude%20Code%20%7C%20Codex%20CLI-blue)](https://agentskills.io)\n\n\u003e Supports Claude Code and OpenAI Codex CLI via the open Agent Skills standard. Sub-agent dispatch follows the [`subagent-dispatch-v1`](https://github.com/ctxr-dev/kit/blob/main/docs/subagent-dispatch-v1.md) envelope.\n\nMulti-specialist code review system for any Agent Skills harness ([Claude Code](https://claude.ai/code), OpenAI Codex CLI). Selects specialists from a wiki-organised corpus (~476 leaves under ~59 subcategories), runs the relevant ones in parallel, integrates external linters and analyzers, and produces structured reports with a GO / NO-GO verdict.\n\nAuto-detects your tech stack (Python, JS, TS, Swift, Go, Rust, Java, Kotlin, Scala, C#, Ruby, PHP, Dart, C, C++, Objective-C, shell, SQL, R, Lua) and activates only the relevant specialists from the wiki corpus.\n\n## Quick Start\n\n```bash\n# Install into your project\nnpx @ctxr/kit install @ctxr/skill-code-review\n```\n\nThen in Claude Code:\n\n```text\n/skill-code-review\n```\n\n## Prerequisites\n\n- An Agent Skills-compatible harness ([Claude Code](https://claude.ai/code) CLI/IDE, or OpenAI Codex CLI)\n- Git repository with commits to review\n\n## Installation\n\n### Manual\n\n```bash\ngit clone https://github.com/ctxr-dev/skill-code-review.git /tmp/skill-code-review\nmkdir -p .agents/skills\ncp -r /tmp/skill-code-review .agents/skills/skill-code-review\n```\n\n### Git Submodule\n\n```bash\ngit submodule add https://github.com/ctxr-dev/skill-code-review.git \\\n    .agents/skills/skill-code-review\n```\n\n## Usage\n\n```text\n/skill-code-review                                # diff review, auto-detect everything\n/skill-code-review help                           # show all arguments\n/skill-code-review full                           # review entire codebase\n/skill-code-review mode=thorough                  # max depth within detected stack\n/skill-code-review format=json                    # structured JSON output\n/skill-code-review tools=interactive              # ask to install missing linters\n/skill-code-review scope-dir=src/api              # only review src/api/\n/skill-code-review scope-reviewer=sec-owasp-a01   # force-activate a specific leaf id\n/skill-code-review max-reviewers=15               # tighter token budget (default 30)\n/skill-code-review base=origin/main head=HEAD     # explicit commit range\n```\n\nSee [report-format.md](report-format.md) for the full argument reference, output examples, and JSON schema.\n\n### How it works\n\nThe orchestrator runs eleven sequential steps:\n\n1. **Deep Project Scan** — detects languages, frameworks, monorepo structure from manifests.\n2. **Risk-Tier Triage** — buckets the diff into trivial / lite / full / sensitive; caps specialist count at 3 / 8 / 20 / 30; short-circuits trivial diffs with no risk signal.\n3. **Tree Descent** — deterministic walk of `reviewers.wiki/`; gathers candidate leaves by `focus` + `activation:`.\n4. **LLM Trim** — picks the final K = cap leaves from candidates with one-sentence justifications. Justifications become the audit trail in the manifest.\n5. **Tool Discovery** — collects external linters from picked leaves' `tools:` arrays and runs available ones.\n6. **Parallel Dispatch** — every picked leaf runs as a blind sub-agent in parallel.\n7. **Collect Findings** — deduplicates and categorises by severity.\n8. **Verify Coverage** — every diff file reviewed by ≥ 2 specialists.\n9. **Synthesize Release Readiness** — 8 gates aggregate findings via dimension/tag predicates.\n10. **Write Run Directory** — sharded `.skill-code-review/\u003cshard\u003e/\u003crun-id\u003e/` with `manifest.json` + `report.md` + `report.json`.\n11. **Stdout / Return Value** — prints the report in the chosen format.\n\n## Corpus\n\nSpecialists live in [`reviewers.wiki/`](reviewers.wiki/index.md) — a wiki-organised corpus of ~476 leaves under ~59 top-level subcategories, built from `reviewers.src/` via `skill-llm-wiki` (deterministic mode, fan-out target 6, max depth 5). Coverage spans:\n\n- **Languages** — every supported language as a `lang-\u003cname\u003e.md` leaf.\n- **Frameworks** — `fw-*.md` leaves for the frameworks named in the [Phase C detection table](docs/code-reviewer-design.md).\n- **Concerns** — security (decomposed across OWASP categories), correctness, tests, performance, architecture, readability, documentation, observability, CLI, API, domain footguns.\n- **Patterns / anti-patterns / DDD / clean-architecture / hexagonal / microservices** — each as their own leaf.\n\nSee [SKILL.md](SKILL.md) for the full architecture summary.\n\n## Report Format\n\nEvery review produces (markdown or JSON):\n\n- **Release Verdict** — GO / NO-GO / CONDITIONAL\n- **SOLID Compliance** — principle-by-principle status\n- **Issues** — clickable [file:line](file#Lline) links, severity, specialist, impact, fix\n- **Tool Results** — pass/fail/skipped for each external linter/analyzer\n- **Specialist Results** — per-reviewer status with issue counts\n- **Release Gates** — 8-gate assessment\n- **Coverage Matrix** — files × specialists\n\n## Architecture\n\n```text\nskill-code-review/\n├── SKILL.md                          # LLM entry point — single imperative dispatching scripts/run-review.mjs\n├── code-reviewer.md                  # Runtime-contract stub (redirect to SKILL.md + design doc)\n├── release-readiness.md              # 8-gate predicate reference (consumed by code, not LLMs)\n├── report-format.md                  # Report contract (consumed by code, not LLMs)\n├── docs/\n│   └── code-reviewer-design.md       # Eleven-step orchestrator design rationale (humans only)\n├── fsm/\n│   ├── code-reviewer.fsm.yaml        # Authoritative state machine\n│   └── workers/*.md                  # Per-state worker prompts (LLM-readable, self-contained)\n├── scripts/\n│   ├── run-review.mjs                # FSM-driver runner (the only LLM-facing entry point at runtime)\n│   ├── inline-states/*.mjs           # Deterministic per-state handlers\n│   └── lib/*.mjs                     # Validators (trim-output, activation-gate, fresh-run)\n├── reviewers.src/                    # Source corpus (gitignored; wiki is source of truth in repo)\n└── reviewers.wiki/\n    ├── index.md                      # Root index — entries[] of subcategories\n    ├── \u003csubcat\u003e/\n    │   ├── index.md                  # Subcategory index — entries[] of leaves\n    │   ├── \u003cleaf\u003e.md                 # Specialist (frontmatter + body checklist)\n    │   └── ...\n    └── ... (~59 subcategories, ~476 leaves total)\n```\n\n## Customization\n\n### Add a reviewer\n\n1. Author a new source file in `reviewers.src/\u003cid\u003e.md` with the v2 frontmatter (`id`, `type`, `focus`, `covers[]`, `dimensions[]`, `audit_surface[]`, `activation`, `tools[]`, `tags[]`).\n2. Run the validators: `npm run validate:src` (parses + body shape + dimensions taxonomy).\n3. Rebuild the wiki via `skill-llm-wiki`:\n\n   ```bash\n   node /path/to/skill-llm-wiki/scripts/cli.mjs build /path/to/skill-code-review/reviewers.src \\\n     --quality-mode deterministic --fanout-target 6 --max-depth 5 --soft-dag-parents --accept-dirty\n   ```\n\n4. Move the produced `reviewers.src.wiki/` over the existing `reviewers.wiki/`, validate the result, commit.\n\nThe wiki layer takes care of clustering, slug generation, soft-DAG parents, and balance — no manual placement under a subcategory is needed.\n\n### Add a language or framework\n\nSame procedure as a reviewer — the language/framework is just a `lang-\u003cname\u003e.md` or `fw-\u003cname\u003e.md` leaf in `reviewers.src/`. Update Phase C of [`docs/code-reviewer-design.md`](docs/code-reviewer-design.md) if the framework is new and the dependency-name detection needs to know about it.\n\n### Severity levels\n\n- **Critical** — must fix, blocks merge (security, data loss, correctness)\n- **Important** — should fix, blocks merge (SOLID violation, missing tests)\n- **Minor** — advisory, does not block (naming, style)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup and conventions.\n\n## Releasing\n\nReleases are PR-gated. Version bumps land on `main` through a review gate like any other change; only the tag push is automated.\n\n### One-time setup\n\nEnable these on the repo before your first release:\n\n- Repository secret `NPM_TOKEN` set to an npm access token with publish rights on the `@ctxr` scope (`npm token create`).\n- **Settings → Actions → General → Workflow permissions**: enable **Allow GitHub Actions to create and approve pull requests** so `release.yml` can open its version-bump PR with `GITHUB_TOKEN`. If the checkbox is greyed out, an organization-level Actions policy is restricting it; ask an org admin to unlock the setting first.\n- (Optional, recommended) GitHub-managed CodeQL default setup: Security → Code security → enable default setup for `javascript-typescript` and `actions`.\n- (Optional) A branch ruleset on `main` requiring PR review + code scanning. The release flow works without it; gates are strictly stricter when enabled.\n\n### Cutting a release\n\n1. **Actions → Release → Run workflow**.\n   - Branch selector: `main` (the workflow refuses any other ref).\n   - Version bump: `patch` / `minor` / `major`.\n   - Click **Run workflow**.\n2. The workflow bumps `package.json` on a fresh `release/v\u003cversion\u003e` branch and opens a PR to `main` titled `release: v\u003cversion\u003e`.\n3. Review the PR (diff is just version fields). Approve + merge.\n4. On merge, `tag-on-main.yml` fires automatically:\n   - Detects the version change.\n   - Creates and pushes the annotated `v\u003cversion\u003e` tag via `GITHUB_TOKEN`.\n5. **Actions → Publish to npm → Run workflow** on the `v\u003cversion\u003e` tag. The workflow runs `npm ci + validate:fsm + lint + test`, verifies the tag matches `package.json`, and publishes the package to npm.\n\n\u003e **Why a manual dispatch for step 5?** GitHub's built-in `GITHUB_TOKEN` cannot trigger further workflows (`on: push: tags` won't fire when a workflow pushed the tag). So the tag auto-creation stops at the tag. Publishing is one extra click. To make it fully automatic, swap the push credential in `tag-on-main.yml` for a GitHub App token or fine-grained PAT stored as a repo secret, then the `push: tags` trigger on `publish.yml` will fire and step 5 happens by itself.\n\nFrom **Run workflow** on Release to **published on npm** is one dispatch + one PR merge + one dispatch (or one dispatch + one PR merge, once a PAT/App-token is wired in).\n\nSee [GitHub Releases](https://github.com/ctxr-dev/skill-code-review/releases) for the changelog.\n\n### Troubleshooting\n\n- **Release workflow fails with \"dispatched from non-main ref\"** — you selected a feature branch in the Actions UI. Re-dispatch with `main`.\n- **`tag-on-main` fails with \"Tag vX.Y.Z exists but points at …\"** — a stale/orphan tag from a prior failed release. Delete and re-run:\n\n  ```bash\n  git push origin --delete vX.Y.Z\n  ```\n\n  Then merge a trivial no-op PR to `main` (or revert-and-re-merge the release PR) to retrigger `tag-on-main`. Direct pushes to `main` may be blocked by branch protection, so the PR path is the reliable retrigger.\n- **`publish.yml` fails on \"Verify version matches tag\"** — tag and `package.json` disagree. Investigate the merge commit; this should not happen under the PR-based flow.\n- **GitHub Actions is not permitted to create pull requests** — org or enterprise policy blocks the `GITHUB_TOKEN` from opening PRs. Enable **Allow GitHub Actions to create and approve pull requests** at the org level (Settings → Actions → General → Workflow permissions), or ask the enterprise admin to unlock the setting.\n\n## License\n\n[MIT](LICENSE)\n\n## Example\n\n### Prompt\n\n\u003e Use code review global skill to review frontend\n\n\u003cimg width=\"1330\" height=\"722\" alt=\"Screenshot 2026-04-11 at 22 00 35\" src=\"https://github.com/user-attachments/assets/e2009b02-3cba-422c-b92c-655901a575ff\" /\u003e\n\n\u003cimg width=\"1348\" height=\"1189\" alt=\"Screenshot 2026-04-11 at 22 00 59\" src=\"https://github.com/user-attachments/assets/b249d3be-3bde-468c-9cc2-3066af1aff2c\" /\u003e\n\n\u003cimg width=\"1352\" height=\"890\" alt=\"Screenshot 2026-04-11 at 22 01 22\" src=\"https://github.com/user-attachments/assets/dd350032-3d95-4657-a5cf-01d746ab595b\" /\u003e\n\n\u003cimg width=\"1334\" height=\"1035\" alt=\"Screenshot 2026-04-11 at 22 01 39\" src=\"https://github.com/user-attachments/assets/46e06599-211e-479b-a7af-bc80116524c6\" /\u003e\n\n\u003cimg width=\"1346\" height=\"888\" alt=\"Screenshot 2026-04-11 at 22 02 09\" src=\"https://github.com/user-attachments/assets/47c5507f-b6f6-4be9-a8c4-a4236ff4d6ed\" /\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctxr-dev%2Fskill-code-review","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fctxr-dev%2Fskill-code-review","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctxr-dev%2Fskill-code-review/lists"}