agentleFS
KealmanKealman/cland-v0/.agents/skills/code-review/SKILL.md

code-review

Skill1 starsChanged 16 days agoApache-2.0View on GitHub

Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to \"review since X\".

194 other projects use a version of this, 15 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use close-spec, design-with-images and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • dzhngSkill

    close-spec

    When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned task that produced a spec), archive it to specs/done/ and rewrite it from a build-plan into a durable rationale — the why, the principles, the invariants — pointing back to the real code for the how. Use when implementation has landed and the plan no longer matches what shipped, or the user says a feature/spec is finished. Pairs with [write-spec](../write-spec/SKILL.md) (the plan this closes) and [review](../review/SKILL.md) (run before closing).

    Also in 5 projects that use this

  • dzhngSkill

    design-with-images

    Explore UI and visual design with image generation, then iterate the real implementation against the user-selected concept. Use when brainstorming visual directions, offering mockup variants, or implementing an approved generated design; do not stop at the mockups or the first code approximation.

    Also in 5 projects that use this

  • PydanticSkill

    add-new-model

    Add support for a newly-released language or image generation model in pydantic-ai (e.g. openai:gpt-5.6, anthropic:claude-sonnet-5, openai:gpt-image-2). Use when a provider ships a new model id and you need to wire literals, profile flags, adapters, and tests to recognize it. Handles SDK-lag, gateway list conventions, capability probing, and direct image-model geometry.

    Also in 10 projects that use this

  • Microsoft AzureSkill

    azsdk-common-apiview-feedback-resolution

    Analyze and resolve APIView review feedback on Azure SDK PRs. **UTILITY SKILL**. USE FOR: APIView comments, API review feedback, SDK API surface changes. DO NOT USE FOR: general code review, non-APIView feedback. INVOKES: azure-sdk-mcp:azsdk_apiview_get_comments, azure-sdk-mcp:azsdk_customized_code_update, azure-sdk-mcp:azsdk_typespec_delegate_apiview_feedback, azure-sdk-mcp:azsdk_run_typespec_validation, azure-sdk-mcp:azsdk_package_generate_code.

    Also in 6 projects that use this

  • Microsoft AzureSkill

    azsdk-common-generate-sdk-locally

    Generate and finalize Azure SDKs locally from TypeSpec, including build, checks, tests, changelog, metadata, and version updates by default. WHEN: "generate SDK locally", "build SDK", "run SDK tests", "run CI checks", "validate package", "run checks", "update changelog", "fix SDK build errors", "resolve SDK generation errors", "customize TypeSpec", "rename SDK client", "rename SDK model", "hide operation from SDK", "fix analyzer errors", "resolve customization drift", "create subclient", "update metadata", "update version". INVOKES: azsdk_verify_setup, azsdk_package_generate_code, azsdk_package_build_code, azsdk_package_run_check, azsdk_package_run_tests, azsdk_customized_code_update, azsdk_package_update_changelog_content, azsdk_package_update_metadata, azsdk_package_update_version.

    Also in 6 projects that use this

  • ww-w-aiSkill

    bkend-auth

    bkend.ai authentication guide. Signup, login, JWT tokens, sessions, role-based access control, and password management with bkend.ai BaaS. Triggers: bkend auth, bkend login, bkend signup, JWT, session, RBAC, password, bkend 인증, 로그인, 회원가입, bkend認証, ログイン, 新規登録, bkend认证, 登录, 注册, autenticacion bkend, authentification bkend, bkend-Auth Do NOT use for: data operations (use $bkend-data), file storage (use $bkend-storage).

    Also in 4 projects that use this

  • +3 more from dzhng
  • +3 more from Azure

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 5 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 184 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If an accepted request is withdrawn, duplicate or owned elsewhere, use verification.decline with request equal to its delivered msg_id and …

    line 22
  2. Very specific:

    Use the fixed point named by the request or user (a commit SHA, branch name, tag, main, HEAD~5, etc.).

    line 42
  3. Very specific:

    Before going further, confirm the fixed point resolves (git rev-parse <fixed-point>) and the diff is non-empty.

    line 46
  4. Distinctive:

    Look for the originating spec, in this order:

    line 50
  5. Distinctive:

    If nothing is found, ask the user where the spec is.

    line 55
  6. Very specific:

    Search the repo for every file that documents how code should be written.

    line 59
  7. Distinctive:

    Standards sub-agent prompt: should include:

    line 85
  8. Distinctive:

    Spec sub-agent prompt: should include:

    line 91
  9. Distinctive:

    If the spec is missing, skip the Spec sub-agent and note this in the final report.

    line 97

“Common” is measured: kept by at least 6 in 10 of the 184 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Two-axis review of the diff between HEAD and a fixed point the user supplies:

  • Standards: does the code conform to this repo's documented coding standards?
  • Spec: does the code faithfully implement the originating issue / spec?

Both axes run as parallel sub-agents so they don't pollute each other's context, then this skill aggregates their findings.

The issue tracker should have been provided to you. If not, tell the user to run cland update to provision docs/agents/.

Hub review requests

When holding the Reviewer role, accept review request T-<n> from the item’s lead (the live claimant in task.view), a supervising Lead within its subtree, or the Coordinator. Take task.hold before reviewing the named branch/head and criteria. Ask the lead for missing review inputs. After recording the verdict, send kind report to lead T-<n> in the request’s topic with first line review clear T-<n> or review not clear T-<n> and the findings that matter. The claimant fixes findings and requests re-review itself; the supervising Lead or Coordinator merges on the hub’s ready event, without relaying verdicts. An unclaimed item’s lead address resolves to the nearest container Lead, then the Coordinator; for a closed or unknown item address coordinator directly.

If an accepted request is withdrawn, duplicate or owned elsewhere, use verification.decline with request equal to its delivered msg_id and a nonempty one-line reason. It returns work to the requester without a verdict. Release any acquired tracker hold separately with task.hold. A missing requester identity or incomplete delivery admission retains the reservation; report the blocker instead of fabricating a verdict. Relaunch verifiers after upgrading to expose the tool; explicit inherited Reviewer/QA tool lists need its grant.

Default subscriptions deliver item status/verdict and verifier death or long idle to the lead, digested at its next turn. Use subscribe to watch additional subjects and subscriptions to inspect them instead of polling. Routine updates use kind progress; requests and verdict reports use report; blockers use question or report.

Review source first, before the full verification run. A clear source verdict at the exact reviewed head lets the Implementer run cland verify there. A fix or changed head needs a new source review before another run. When the post-verdict result arrives, check that it names the reviewed head and record the final verdict; a failed run is not clear. An unchanged head may reuse an earlier green run through the tree-hash cache. A source verdict alone is not final verification evidence.

Review every new or changed test against "Test levels" in docs/agents/tests.md. A new real process without a lifecycle reason, a wall-clock wait or a missing tier is a finding. Never ask for a full run on a task head.

Record every review verdict with --scope full|delta|evidence (MCP task.comment: scope). Use full for a first review or reworked design, delta after dev moved under a reviewed branch, and evidence for suite evidence alone. Older unscoped verdicts remain unknown; QA carries no scope.

Process

1. Pin the fixed point

Use the fixed point named by the request or user (a commit SHA, branch name, tag, main, HEAD~5, etc.). If none is specified, ask the requester for it.

Capture the diff command once: git diff <fixed-point>...HEAD (three-dot, so the comparison is against the merge-base). Also note the list of commits via git log <fixed-point>..HEAD --oneline.

Before going further, confirm the fixed point resolves (git rev-parse <fixed-point>) and the diff is non-empty. A bad ref or empty diff should fail here, not inside two parallel sub-agents.

2. Identify the spec source

Look for the originating spec, in this order:

  1. The request’s T-<n> item or item references in the commit messages, fetched via the workflow in the tracker doc.
  2. A path the user passed as an argument.
  3. A spec file under docs/, specs/, or .scratch/ matching the branch name or feature.
  4. If nothing is found, ask the user where the spec is. If they say there isn't one, the Spec sub-agent will skip and report "no spec available".

3. Identify the standards sources

Search the repo for every file that documents how code should be written. When CODING_STANDARDS.md or CONTRIBUTING.md exists, it must be on the list.

On top of whatever the repo documents, the Standards axis always carries the smell baseline below: a fixed set of Fowler code smells (Refactoring, ch.3) that applies even when a repo documents nothing. Two rules bind it:

  • The repo overrides. A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
  • Always a judgement call. Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation. Like any standard here, skip anything tooling already enforces.

Each smell reads what it is → how to fix; match it against the diff:

  • Mysterious Name: a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
  • Duplicated Code: the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
  • Feature Envy: a method that reaches into another object's data more than its own. → move the method onto the data it envies.
  • Data Clumps: the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
  • Primitive Obsession: a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
  • Repeated Switches: the same switch/if-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
  • Shotgun Surgery: one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
  • Divergent Change: one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
  • Speculative Generality: abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
  • Message Chains: long a.b().c().d() navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
  • Middle Man: a class or function that mostly just delegates onward. → cut it, call the real target direct.
  • Refused Bequest: a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.

4. Spawn both sub-agents in parallel

Issue both sub-agent calls together, in the foreground, and aggregate the reports they return.

Standards sub-agent prompt should include:

  • The full diff command and commit list.
  • The list of standards-source files you found in step 3, plus the smell baseline from step 3 pasted in full (the sub-agent has no other access to it).
  • The brief: "Report, per file/hunk where relevant, (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls: documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."

Spec sub-agent prompt should include:

  • The diff command and commit list.
  • The path or fetched contents of the spec.
  • The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."

If the spec is missing, skip the Spec sub-agent and note this in the final report.

5. Verify the criteria

When holding the Reviewer role, use the item's task.view criteria as the checklist. Record which stable ids the review established and which failed. Write a source review verdict with task.comment: verdict: "review", result, run, scope and the reviewed commit. A clear verdict includes verified: "C1,C3" for source-established criteria; leave run-dependent criteria unverified until the same-head post-verdict result arrives, then write the final verdict with all criteria checked across source review and that result. Use verified: "all" only when every criterion was checked. Record every finding, lows included, as findings: [{severity: "high" | "medium" | "low", text, file?, line?}] (CLI: repeat --finding severity:text[@file:line]). Use findings: [] when none. A clear verdict still records and lists its low findings; clear means nothing high or medium remains. A not-clear verdict includes failed: [{ criterion: "C2", note: "what failed" }] for each failed criterion. Each note is nonempty and single-line. For a separate mark use task.criterion verify with the criterion id and run, or fail with the id and note. Unchecked criteria remain unverified. The hub records the marks and lists them in the verdict report.

6. Aggregate

Present the two reports under ## Standards and ## Spec headings, verbatim or lightly cleaned. Do not merge or rerank findings, because the two axes are deliberately separate (see Why two axes).

End with a one-line summary: total findings per axis, and the worst issue within each axis (if any). Don't pick a single winner across axes: that's the reranking the separation exists to prevent.

Why two axes

A change can pass one axis and fail the other:

  • Code that follows every standard but implements the wrong thing → Standards pass, Spec fail.
  • Code that does exactly what the issue asked but breaks the project's conventions → Spec pass, Standards fail.

Reporting them separately stops one axis from masking the other.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.