Agent-Skills.md

Agent Skills: Code Quality Gate

Fresh-subagent code quality review gate after implementation and before verification. Use when code changes are complete and the orchestrator needs APPROVE_CODE, REVISE_CODE, or ASK_USER based on plan fidelity, simplicity, tests, repo style, security, and maintainability. Does not implement or write files.

UncategorizedID: iamhenry/ai-project-starter-kit/code-quality-gate
53

Install this agent skill to your local

pnpm dlx add-skill https://github.com/iamhenry/ai-project-starter-kit/tree/HEAD/.agents/skills/code-quality-gate

Skill Files

Browse the full folder contents for code-quality-gate.

Download Skill

Loading file tree…

.agents/skills/code-quality-gate/SKILL.md

Skill Metadata

Name
code-quality-gate
Description
Fresh-subagent code quality review gate after implementation and before verification. Use when code changes are complete and the orchestrator needs APPROVE_CODE, REVISE_CODE, or ASK_USER based on intent and plan fidelity, simplicity, tests, repo style, security, and maintainability. Does not implement or write files.
<!-- Quality principles: - Quality approval is not done. Green tests, builds, and typechecks are mechanical signals — they support done, they are not done. - Judge whether the user-observable outcome surface has been exercised, not just whether the implementation layer is sound; flag the gap when it hasn't. - Smallest code that satisfies the plan wins; speculative abstractions and unplanned features are defects, not bonus work. -->

Code Quality Gate

Use this skill after implementation and before final acceptance verification. For an explicitly selected assurance: combined-low-risk run that satisfies verification-gate's combined low-risk assurance contract, this standalone gate may be skipped; verification-gate performs the quality precheck and decisive verification together. APPROVE_CODE approves code quality only; it never means the task is complete or that the behavior works for users. This ordering does not prohibit safe, disposable previews or risk probes during implementation; those are diagnosis, not acceptance or permission for unsafe live installation or mutation.

For the standard route, run it as a fresh subagent review gate, separate from the implementer and followed by a fresh verification session. A same-agent skill invocation is not independence. Fresh context reduces self-confirmation bias; it does not guarantee unbiased review. Small changes still receive fresh review, focused on the diff, intent, and concrete risks; expand depth for uncertainty, coupling, security, or consequential failure. It returns a decision and never edits files. The combined route is the sole exception and does not waive this quality review: one fresh qa agent performs the documented precheck before verification. This gate does not classify eligibility or infer the combined route.

Mode Dispatch

  • The default, when mode is omitted, is the existing issue mode below. Any mode other than the explicit mode: isa request uses the existing issue-mode contract; do not auto-detect ISA inputs.
  • When the caller explicitly supplies mode: isa, use the alternate contract in references/isa-mode.md. Do not require, read, create, or infer {ISSUE_DIR}/plan.md for that invocation.
  • The two modes have separate inputs and output contracts. Do not mix issue artifacts into ISA review or ISA inputs into issue review.
  • assurance is independent of mode; assurance: combined-low-risk only selects the explicitly documented exception and does not change issue/ISA dispatch.

Inputs

Read the minimum available context:

  • Required: {ISSUE_DIR}/plan.md for pipeline calls; for a standalone call, an explicit approved scope, acceptance criteria, boundaries, and any named Mechanical commands may be supplied directly instead. Below, plan.md means that approved contract for standalone review; do not create pipeline artifacts just to review a diff.
  • Required: changed files and/or git diff
  • Required to judge intent: {ISSUE_DIR}/issue.md, or an explicit statement of the problem, user, and desired outcome in standalone calls.
  • Optional but useful: implementation summary from the implementation agent
  • Required when plan.md names Mechanical command(s): raw output for those commands. Missing output is an evidence gap, not a code defect. This gate may run them if they are read-only and finish in under 2 minutes; it never edits files or tests.
  • Optional but useful: _ai/prompts/quality/code-review.md as the review standard
  • Optional but useful: _ai/prompts/quality/code-guidelines.md as the quality standard

If the approved contract or changed code/diff is missing, return ASK_USER naming the missing input and its owner. The caller repairs pipeline-owned gaps from approved context before redispatch; only unresolved intent or permission needs a human decision. A missing pipeline plan is not permission to silently switch to standalone inputs.

Artifact Contract

  • ISSUE_DIR is the artifact directory created by gather-context for the current pipeline run.
  • Required: the approved contract above, plus changed files and/or git diff and exact candidate identity (commit or base plus uncommitted diff).
  • Optional but useful: issue.md, implementation summary, and quality docs.
  • If plan.md names Mechanical command(s) and their raw output is missing, run them yourself when they are read-only and finish in under 2 minutes; otherwise return ASK_USER identifying the missing receipt and its owner. For pipeline calls, the caller repairs that owned input without asking the human. Resume this review against the same candidate after the receipt arrives; do not request source changes, create a new candidate, or invalidate prior review conclusions.
  • If command output is missing because the plan has no Mechanical field (legacy plan), do not invent a requirement here.

Review Process

  1. Reconstruct the task's intent from issue.md and the approved scope from plan.md. The plan is one interpretation of the task, not the definition of intent. If they disagree, record it for the decision; do not silently prefer either.
  2. Review the diff and directly affected code first.
  3. Use the local ponytail-review skill only as an optional, read-only, diff-focused lens when over-engineering is material or the review request explicitly calls for complexity review. Use its complexity-only findings to inform the simplicity/YAGNI judgment; it does not apply fixes, and this gate retains responsibility for correctness, security, performance, error handling, and maintainability. Do not run ponytail-audit or ponytail-debt automatically; they remain standalone reports only when explicitly requested. ponytail-gain and ponytail-help are informational, not gate steps.
  4. Trigger wider dependency review only when the change touches shared modules, public interfaces, global state, async side effects, security-sensitive paths, or common components.
  5. Compare implementation against the referenced quality docs without copying them into the report.
  6. Heavily weight simplicity: prefer the smallest code that satisfies plan.md; penalize speculative abstractions, extra surfaces, duplicate state, and unplanned features.
  7. Check provided Mechanical / test / build / lint / typecheck output. Judge coverage by the distinct changed failure modes it protects, not by test quantity. Distinguish demonstrated code failures from commands blocked by environment prerequisites; identify prerequisite repair in the findings, not speculative source changes. Do not invent results. You may run plan-named and read-only commands (git diff/show/log, rg, tests, typecheck, lint) to confirm or refute a finding and quote their output; never edit files or tests, start servers, or open browsers.
  8. Return a concise structured decision to the orchestrator.

Intent Check

Intent fidelity means the change produces the outcome the task was raised to produce, not just the steps the plan listed. Before scoring, answer three questions from the artifacts: what outcome is the task trying to produce for the user, what would the user notice if it worked, and did "done" move to fit what was built? Then map each changed file to a plan item or to that outcome; anything that serves neither is extra. A clear intent miss is blocking; a conflict between the task and the plan is ASK_USER, not a code defect.

Weighted Rubric

Score out of 100:

| Category | Weight | Subcriteria | | --- | ---: | --- | | Intent and correctness | 30 | Delivers the task's stated outcome, not just the plan's steps; respects scope/out-of-scope; has no obvious regressions against acceptance criteria. | | Simplicity / KISS / YAGNI | 25 | Uses the smallest solution that satisfies the plan; avoids speculative abstractions/features; avoids duplicate state or sources of truth. | | Tests / build / typecheck | 15 | Plan-named Mechanical output is present and passing; coverage matches changed risk. | | Architecture / repo style | 15 | Follows existing patterns; respects boundaries/interfaces; avoids unnecessary dependencies. | | Security / error handling | 10 | Has no privacy/security regression; handles failure paths safely. | | Readability / maintainability | 5 | Names and structure are understandable; code is easy to review/change. |

Scoring anchors:

  • Full credit: clear artifact or code evidence supports the item.
  • Half credit: partially satisfied, thinly evidenced, or has non-blocking gaps.
  • Zero credit: missing, contradicted, unverifiable, or unsafe.

Hard Fails

Return REVISE_CODE regardless of score if any are true:

  • Relevant test, build, lint, or typecheck output fails.
  • Plan-named Mechanical command output is failing.
  • New or changed Mechanical test that asserts no relevant condition of the Objective (compile/lint/typecheck-only oracle). Mechanical and Observable may cover different parts of the outcome; do not demand a new end-to-end harness when focused assertions plus actual-surface proof suffice.
  • High severity bug with direct code evidence.
  • Security or privacy issue.
  • The implementation misses a clear, stated intent from the task.
  • Implementation contradicts plan.md.
  • Unplanned scope drift.
  • Overengineered solution where a simpler approach satisfies plan.md.

Return ASK_USER instead when the blocker is missing context or evidence, ambiguous product intent, unclear plan scope, or conflicting artifacts. Name the missing input and its owner.

Decision Rules

  • APPROVE_CODE: no hard fail, score is 85 or higher, and remaining issues are low-risk or clearly optional.
  • REVISE_CODE: hard fail applies, or score is below 85 with actionable implementation changes.
  • ASK_USER: required inputs or receipts are missing, product behavior is ambiguous, or deciding would require guessing beyond the artifacts.

If REVISE_CODE, the caller routes demonstrated defects to implementation and failed prerequisites to setup, then obtains fresh review of the resulting candidate. Identify which prior findings and evidence remain valid and which need rechecking; a narrow correction need not repeat unrelated review, while coupled, uncertain, or consequential changes may warrant full fresh assurance. If ASK_USER identifies a pipeline-owned evidence gap, repair that input and resume the same review against the unchanged candidate; this is not a revision attempt and does not restart acceptance. For a re-review after a fix, check the fix diff and the earlier findings only, unless the fix touches new files or risk. Compare repeated findings before proposing another edit; an unchanged failure calls for reconsideration. After 2 REVISE_CODE verdicts the caller stops with EXHAUSTED; carry prior verdicts across dispatches. If fresh delegation is unavailable, report the limitation, not APPROVE_CODE from self-review.

Output Format

Return exactly this structure:

## Code Quality Gate Result

- Decision: `APPROVE_CODE|REVISE_CODE|ASK_USER`
- Score: [0-100 or `N/A`]
- Intent: `faithful|drifted|unclear`
- Reviewed: [plan.md, issue.md, diff/changed files, implementation summary, command outputs, quality docs]

### Findings

- [severity] [file:line or artifact] [specific issue or approval reason]
- [severity] [file:line or artifact] [specific issue or approval reason]

### Required Changes

- [Only for REVISE_CODE or ASK_USER; otherwise `None`]

### Next Action

- [run verification-gate / revise implementation / ask user]

Constraints

  • Do not edit files.
  • Do not implement fixes.
  • Do not create review artifacts or helper files.
  • Do not run Mechanical commands, tests, or broad QA. Require attached output; use verification-gate after approval in a separate fresh session for the standard route. For the explicitly selected combined route, do not invoke this gate; verification-gate owns and evaluates the combined low-risk assurance contract and the fresh quality precheck.
  • Do not duplicate the full quality docs; reference _ai/prompts/quality/code-review.md and _ai/prompts/quality/code-guidelines.md.
  • Do not commit changes.
  • Keep findings concise and evidence-based. Speculative risks must be marked low confidence or omitted.