qoq

Applies the QoQ — quality over quantity — standard to a JS/TS codebase: a few high-confidence, intention-revealing changes over a long list of nitpicks. Every suggestion is staged as a reviewable git patch and applied one at a time behind the project's own lint/test/build gate.

Setup

Two things are true for every command, so establish them before routing into one. They are the shared engine that review, refactor, bump packages, and gate all build on.

1. Confirm a clean working tree. Run git status. Most commands edit files and revert them as their safety net, so a dirty tree gets tangled in that. If there are uncommitted changes, point them out and ask the user to commit, stash, or confirm stashing is fine before continuing. Exception: gate. It is invoked precisely because a producer just wrote code, so its scope is the dirty working tree — it does not demand a clean one and uses a git stash create snapshot as its safety net instead (see reference/gate.md).

2. Locate the QoQ engine. The linters and formatters (Prettier, ESLint, Knip, JSCPD, Stylelint) and their --json digest are owned by one place — reference/engine.md. Work out how qoq is invoked in this project (a qoq:check / qoq:fix npm script, npx qoq, or a build-first monorepo) and read its config, exactly as that file describes. Every command that needs tool-backed findings (review, refactor) or a lint gate (all three) defers to the engine rather than re-deriving flags or parsing raw reports. If a project has no qoq set up at all, the engine documents the fallback to the project's own ESLint/Knip/JSCPD/Prettier scripts.

Skipping these produces output that fights the project's own tools or corrupts the patch workflow's safety net.

Shared principles

These hold across all three commands; the command reference is the source of truth for everything specific.

• One shared workspace, .qoq/. Every command stages its patches, reports, and digest under a single .qoq/ directory at the repo root, git-ignored for the duration of the run (a labeled block each command adds to .gitignore and reverts at the end) so its scratch files never show up in git status or trip the Prettier gate. On a fully successful run the command removes .qoq/ entirely, leaving only the real code change; on an aborted run it leaves .qoq/ in place as the record of what's left.
• Plan, then execute. Gather everything and stage each change as a git apply-able patch in .qoq/ without touching the working tree; get the user's sign-off; only then apply.
• One patch at a time. Apply patches sequentially, re-running the validation gate (the project's lint/test/build) after each, so any breakage is attributable to exactly one patch and trivially reverted.
• Patches via edit → diff → restore → check. Edit in place, capture with git diff > <workspace>/<name>.patch, git restore to keep the tree clean, then git apply --check to confirm it applies. A malformed patch is regenerated, never forced.
• Quality over quantity. An empty result is a fine result. Recommend dropping valid-but-low-value patches. A short list of confident fixes beats a churn of nitpicks.
• Stop at decision points. These commands mutate a real repo. Pause at the marked approval points rather than pushing through — but if the user has already stated preferences (base branch, scope, excluded packages, whether subagents are allowed, whether to auto-apply), honor them and don't re-ask. gate is the deliberate exception: it runs to completion without interactive approval (its caller already authorized it), auto-applying only the safe fixes and reporting the judgment calls as advisories rather than blocking.

Commands

Command	Description	Reference
review	Review a branch's changes against a base branch and stage fixes as patches	reference/review.md
refactor	Run the same analysis over a scope you choose (path/package/directory/whole project)	reference/refactor.md
bump packages	Safely update npm dependencies in stages — minor/patch first, then majors one at a time	reference/bump.md
gate	Non-interactive quality gate over a producer's just-written changes; returns PASS/FAIL	reference/gate.md

gate is the integration entry point — the command another skill (or you, mid-task) calls before declaring work done. It auto-fixes against the standards and returns a verdict rather than running an interactive plan. See Consuming /qoq from another skill.

The engine that every command reuses is documented separately and is not a user-facing command: reference/engine.md (qoq CLI discovery, the qoq --check --json run, and the compact digest from scripts/summarize.mjs). The shared analysis worker the commands fan out to is agents/qoq-analyzer.md.

Routing rules

1. No argument: render the commands table above as a menu and ask what the user would like to do.
2. First word matches a command (review, refactor, bump, gate): load its reference file and follow it. Everything after the command name is the target (e.g. refactor packages/cli/src; gate src/foo.test.ts src/foo.ts; bump packages → command bump, the word packages is just confirming the noun). Setup has already run, so the command reference picks up from its own first phase without re-doing the engine handoff.
3. First word doesn't match: infer the closest command from the request — "is this ready to merge?" → review; "clean up the auth module" → refactor; "our deps are stale" → bump packages; "check the code I just generated meets our standards" → gate — then load that reference.

The command reference owns its own phases (scoping, analysis, presentation, execution, cleanup); this file owns only the shared setup, principles, and routing.

Consuming /qoq from another skill

/qoq is meant to be a reusable quality gate that other skills fall back to before they declare a task done. A producer skill — one that generates tests, scaffolds a feature, writes a migration, applies a codegen step — should not call itself finished until what it produced meets the project's QoQ standards. Rather than each skill re-implementing "run the linters, fix the findings, refactor the rough edges", it delegates that last mile to the gate command here.

The contract. A producer invokes the gate over the files it just changed and treats the verdict as a release gate:

• Invocation — run the gate command (/qoq gate <paths…>, or read reference/gate.md and follow it) passing the explicit list of files the producer created or edited. With no paths, gate infers its scope from the working tree (git status + git diff).
• What it does — autonomously brings that scope up to standard: auto-applies the safe fixes (formatting, naming, conventions, clear complexity wins) behind the project's own qoq --check + test/build gate, and lists the judgment-heavy findings (dead-code deletion, de-duplication, pattern changes) as advisories instead of forcing them.
• What it returns — a structured verdict: QoQ GATE — PASS or FAIL, the fixes applied, the advisories left, and the validation result. PASS means the scope meets the standards and validation is green; FAIL means validation could not be made green or a hard standard is violated and couldn't be auto-fixed.
• How the producer reacts — on PASS, declare done (surface any advisories to the user). On FAIL, do not declare done: address the reported blockers (or hand them back to the user) and re-gate.

Definition-of-done snippet — a producer skill adds a final step like this so the fallback is explicit:

Before declaring done: run /qoq gate <the files you changed> and wait for its verdict. If it returns FAIL, fix the reported blockers and re-run it. Only declare the task complete on PASS; pass along any advisories it reported.

This keeps one definition of "quality" — review's seven dimensions and the engine — and lets every other skill borrow it without duplicating any of it.