Sk Code Quality

Code Quality (quality)

quality is the author-side quality gate MODE child of the sk-code family. It runs after the surface skill (code-webflow / code-opencode) implements changes and before the surface's verification workflow or done-claim. It consumes the shared surface router, loads the right checklist for the detected surface and target path, fixes quality-gate failures in place, and leaves findings-only output to code-review.

---

1. WHEN TO USE

Activation Triggers

Use this mode when the request involves:

• Running the post-implementation quality gate before a completion claim.
• Applying P0/P1/P2 author-side checks to changed code, scripts, skills, agents, commands, MCP servers, or spec docs.
• Checking comment hygiene on modified files and removing ephemeral artifact references from comments while preserving durable WHY.
• Loading an OpenCode authoring checklist for .opencode/skills/, .opencode/agents/, .opencode/commands/, .opencode/specs/, MCP server source, or language-specific OpenCode files.
• Applying Webflow/frontend quality standards after implementation and before runtime verification.
• Fixing quality-gate failures in place with Edit when the fix belongs to the already-authored file.

Keyword triggers: quality gate, code quality, comment hygiene, surface checklist, P0, P1, P2, authoring checklist, OpenCode checklist, skill authoring, agent authoring, command authoring, MCP server authoring, spec folder authoring, check before done.

When NOT to Use

Skip this mode when:

• The user needs code written, files scaffolded, or behavior implemented. Use the appropriate surface skill (code-webflow / code-opencode) and its implementation workflow.
• A failure needs symptom-to-root-cause investigation or a single-cause bug fix. Use the surface's debugging workflow (workflow-debug.md).
• The task is to collect final non-mutating verification evidence. Use the surface's verification workflow (workflow-verify.md).
• The user asks for findings-first review output, severity-ranked findings, or PR review. Use code-review.
• The task is documentation-only prose with no code-work contract. Use sk-doc.

Family Boundary

This is an independently invokable member of the sk-code family. It owns the quality gate, not implementation planning, debugging, verification evidence, or formal review reporting. It may edit files that the surface skill already changed to satisfy gate failures, but it does not create new files and does not dispatch subagents.

Pairs well with:

• The surface skill (code-webflow / code-opencode) immediately before this gate, because implementation writes the files this mode checks.
• The surface's debugging workflow (workflow-debug.md) when a quality failure reveals a functional bug or failing command.
• The surface's verification workflow (workflow-verify.md) after P0 quality issues are clear, because verification gates the final claim.
• code-review when the user wants findings-only output rather than author-side correction.

---

2. SMART ROUTING

Primary Detection Signal

Surface identity is resolved once by the parent shared router. This mode consumes that result and then routes by target path and quality intent:

QUALITY TASK
    |
    +- Surface identity -> ../shared/references/stack-detection.md
    +- Phase lifecycle  -> ../shared/references/phase-detection.md
    +- Resource routing -> ../ROUTER.md
    |
    +- WEBFLOW target     -> assets/code-quality-checklist/overview-header-and-comments.md + shared web standards
    +- OPENCODE target    -> ../sk-code-opencode/assets/checklists/.md
    +- Comment hygiene    -> scripts/check-comment-hygiene.sh per modified file
    +- Dist staleness     -> scripts/check-dist-staleness.sh when generated artifacts are involved

Phase Detection

Phase 1 Implementation writes or changes files
    -> Phase 1.5 Code Quality Gate runs here
        -> load quality checklist before any completion claim
        -> select target-path authoring checklist
        -> run comment hygiene on every modified file
        -> apply P0/P1/P2 author checks
        -> edit in place only for gate failures
    -> Phase 2 Debugging if checks expose a failing symptom
    -> Phase 3 Verification after the gate is clean enough to verify

Resource Domains

• assets/code-quality-checklist/overview-header-and-comments.md is the Webflow/frontend quality checklist and the general post-implementation quality gate.
• ../sk-code-opencode/assets/checklists/ contains OpenCode authoring checklists for skills, agents, commands, MCP servers, language files, and config; the spec-folder checklist is owned by system-spec-kit.
• scripts/check-comment-hygiene.sh is the per-file comment-hygiene gate.
• scripts/check-dist-staleness.sh checks generated/distribution artifact drift when that is part of the target.
• scripts/hooks/claude-posttooluse.sh is the write-time warning hook for comment hygiene.
• ../shared/references/universal/code-quality-standards.md and ../shared/references/universal/code-style-guide.md define shared standards consumed by this packet.

Resource Loading Levels

| Level | When to Load | Resources | | --- | --- | --- | | ALWAYS | Any quality-gate invocation | ../shared/references/stack-detection.md, ../ROUTER.md, ../shared/references/phase-detection.md | | ALWAYS | Before any implementation-done claim | assets/code-quality-checklist/overview-header-and-comments.md, ../shared/references/universal/code-quality-standards.md, ../shared/references/universal/code-style-guide.md | | ALWAYS | Any modified file with comments or comment-capable syntax | scripts/check-comment-hygiene.sh | | CONDITIONAL | .opencode/skills/ target | ../sk-code-opencode/assets/checklists/skill-authoring.md | | CONDITIONAL | .opencode/agents/ target | ../sk-code-opencode/assets/checklists/agent-authoring.md | | CONDITIONAL | .opencode/commands/ target | ../sk-code-opencode/assets/checklists/command-authoring.md | | CONDITIONAL | .opencode/specs/ target | ../../system-spec-kit/references/workflows/spec-folder-authoring-checklist.md (system-spec-kit) | | CONDITIONAL | MCP server source | ../sk-code-opencode/assets/checklists/mcp-server-authoring.md | | CONDITIONAL | OpenCode JavaScript, TypeScript, Python, Shell, Rust, JSON, or JSONC files | ../sk-code-opencode/assets/checklists/javascript-checklist.md, ../sk-code-opencode/assets/checklists/typescript-checklist.md, ../sk-code-opencode/assets/checklists/python-checklist.md, ../sk-code-opencode/assets/checklists/shell-checklist.md, ../sk-code-opencode/assets/checklists/rust-checklist/overview-and-p0-parity.md, ../sk-code-opencode/assets/checklists/rust-checklist/p0-safety-and-boundary-discipline.md, ../sk-code-opencode/assets/checklists/rust-checklist/p1-required.md, ../sk-code-opencode/assets/checklists/rust-checklist/p2-evidence-validation-and-resources.md, ../sk-code-opencode/assets/checklists/config-checklist.md as applicable | | CONDITIONAL | Generated distribution artifacts or mirrored outputs changed | scripts/check-dist-staleness.sh | | ON_DEMAND | Need hook behavior details | scripts/hooks/claude-posttooluse.sh |

Target-Path Checklist Map

| Target Path | Authoring Checklist | Gate Behavior | | --- | --- | --- | | .opencode/skills/ | ../sk-code-opencode/assets/checklists/skill-authoring.md | Check frontmatter, section structure, resource layout, routing, version, allowed tools, and validation path. | | .opencode/agents/ | ../sk-code-opencode/assets/checklists/agent-authoring.md | Check agent frontmatter, prompt boundary, tool access, and role clarity. | | .opencode/commands/ | ../sk-code-opencode/assets/checklists/command-authoring.md | Check command metadata, arguments, routing, and execution contract. | | .opencode/specs/ | ../../system-spec-kit/references/workflows/spec-folder-authoring-checklist.md (system-spec-kit) | Check spec-folder structure and packet-document consistency. | | MCP server source | ../sk-code-opencode/assets/checklists/mcp-server-authoring.md | Check tool contracts, input/output schemas, transport assumptions, and failure handling. | | OpenCode language/config files | language/config checklist in ../sk-code-opencode/assets/checklists/ | Check language-specific quality and style expectations. | | Webflow/frontend files | assets/code-quality-checklist/overview-header-and-comments.md | Check frontend style, maintainability, headers, comments, and platform expectations. |

Comment-Hygiene Enforcement Gates

This mode owns the author-side check and knows the three independent enforcement layers:

| Gate | Where | Effect | | --- | --- | --- | | Write-time warning | scripts/hooks/claude-posttooluse.sh | Warns during authoring when a comment carries ephemeral artifact labels. | | Pre-commit block | .opencode/hooks/git/pre-commit | Blocks commits with forbidden comment patterns across runtimes. | | CI block | .github/workflows/comment-hygiene.yml | Blocks pull requests with forbidden comment patterns. |

Note that the .opencode/hooks/git/pre-commit hook additionally enforces a staged agent-mirror-sync drift gate, independent of comment hygiene, documented in .opencode/hooks/git/README.md.

Run scripts/check-comment-hygiene.sh on each modified file that can contain comments. Zero violations are required before a quality pass.

2b. Machine-Readable Router (thin, Type-1 benchmark)

code-quality routes primarily by TARGET PATH (the surface + checklist map above), verified by a unit test — not by prompt keywords. Its parent-to-child discoverability is the hub quality signal. This thin prompt-intent projection exists only so the deterministic skill-benchmark router-replay can score code-quality's one routable checklist in Mode-A; it deliberately does not model the path-keyed dispatch.

# Thin prompt-intent router: code-quality owns a single routable checklist. Its
# real routing is target-path-keyed (the checklist map above, covered by a unit
# test) and its parent discoverability is the hub quality signal — this block only
# makes the one asset scoreable by the deterministic router-replay.
DEFAULT_RESOURCE = [
    "assets/code-quality-checklist/overview-header-and-comments.md",
    "assets/code-quality-checklist/naming-init-formatting-and-css.md",
    "assets/code-quality-checklist/verification-quick-reference-and-related.md",
]

INTENT_SIGNALS = {
    "QUALITY": {"weight": 1, "keywords": ["quality gate", "comment hygiene", "p0 p1 p2", "code smell", "dist staleness", "naming", "standards", "checklist", "author quality gate"]},
}

RESOURCE_MAP = {
    "QUALITY": ["assets/code-quality-checklist/overview-header-and-comments.md"],
}

Machine-Readable Router Call Sequence

discover_markdown_resources()
    -> _guard_in_skill() + load_if_available()
    -> score_intents()/select_intents() for the thin QUALITY projection
    -> get_routing_key() from target path, then select the path-keyed checklist
    -> UNKNOWN_FALLBACK when no routable target path is available

The target-path checklist map remains authoritative; the prompt-intent projection only makes the default quality resources scoreable.

---

3. HOW IT WORKS

Quality Gate Workflow

1. Resolve the surface and lifecycle state through the shared router. If no implementation changed files yet, route to the appropriate surface skill (code-webflow / code-opencode) unless the user explicitly asked for a standalone quality audit.
2. Collect the changed-file set from the task context or targeted paths. Read each target before editing.
3. Load assets/code-quality-checklist/overview-header-and-comments.md before any completion claim, then load the target-path checklist from ../sk-code-opencode/assets/checklists/ when the target is OpenCode-owned.
4. Run scripts/check-comment-hygiene.sh for every modified comment-capable file.
5. Apply the P0/P1/P2 model: P0 blocks completion, P1 should be fixed before handoff unless explicitly accepted, P2 can be documented when there is a clear reason.
6. Fix gate failures in place with Edit when the correction is limited to already-authored files.
7. If a gate failure requires new files, broader implementation, or behavior design, hand back to the surface skill (code-webflow / code-opencode).
8. If a gate failure is caused by an unclear runtime failure, hand to the surface's debugging workflow (workflow-debug.md) with the observed command, output, and failing target.
9. When P0 items are clear, hand to the surface's verification workflow (workflow-verify.md) for non-mutating evidence before any done-claim.

P0/P1/P2 Author Checks

| Severity | Meaning | Gate Effect | | --- | --- | --- | | P0 | Correctness, safety, broken contract, forbidden comment metadata, unchecked generated drift, or missing required checklist evidence | Blocks completion until fixed or escalated. | | P1 | Maintainability, routing, style, or authoring-contract issue likely to confuse future work | Fix before handoff unless the user accepts a documented risk. | | P2 | Local polish, clarity, or minor consistency issue with low behavioral risk | Fix when cheap; otherwise document the deferral and why it is safe. |

Author-Side, Not Review-Side

Quality mode is allowed to edit because it is part of the implementation lifecycle. It should leave the workspace better than it found it, but only inside the current scope. If the requested output is a review report, use code-review; if the requested output is evidence that commands pass, use the surface's verification workflow (workflow-verify.md).

Comment Hygiene

Comments should explain durable WHY and constraints. They must not embed temporary artifact labels, spec paths, packet labels, ticket labels, or phase bookkeeping. When this mode finds a violation, it edits the comment to preserve the durable reason or removes the comment if it has no durable value.

Advisory Evidence-Handoff Envelope

When the orchestrator or surface workflow requests structured evidence, append this advisory envelope after the prose handoff. Never place it in a position that reads as a status verdict, and never let it stand in for the handoff to the surface's verification workflow (workflow-verify.md).

CODE_QUALITY_RESULT v1
schema_version: code-quality/v1
status: advisory
modified_files: 
resolved_surface: 
checklists_loaded: 
checker_outputs: 
p0_p1_p2_decisions: 
accepted_deferrals: 
verification_handoff: workflow-verify.md
remaining_accepted_risk: 

This envelope is advisory and additive only: its status is fixed to advisory and MUST NOT be pass, success, or done. Its presence NEVER reads as a completion, done, works, or passing claim, and it never replaces the handoff to the surface's verification workflow (workflow-verify.md) — it reinforces, and does not relax, the §4 NEVER rule that this mode makes no passing claims.

---

4. RULES

✅ ALWAYS

1. Read target files before editing them.
2. Load assets/code-quality-checklist/overview-header-and-comments.md before any implementation-done or quality-pass claim.
3. Resolve surface identity through ../shared/references/stack-detection.md; do not re-author surface detection in this packet.
4. Load the correct OpenCode authoring checklist by target path before checking .opencode/ work.
5. Run scripts/check-comment-hygiene.sh on each modified comment-capable file.
6. Fix P0 issues before handing to verification unless the only safe action is escalation.
7. Keep fixes scoped to quality-gate failures in files already in scope.
8. Hand failures that need root-cause investigation to the surface's debugging workflow (workflow-debug.md) with the exact symptom and evidence.

⛔ NEVER

1. Never create new files; this mode has no Write auth

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MichelKerkmeester
• Source: MichelKerkmeester/skilled-harness_spec-driven-agent-loops
• License: MIT

Install and usage instructions live in the source repository linked above.