claudecode-omc 5.11.0 → 5.12.0

package/bundled/upstream/ecc/commands/orch-add-feature.md

@@ -0,0 +1,36 @@
+---
+description: Orchestrate building a brand-new feature end to end — research, plan, TDD, review, gated commit. Wrapper that kicks off the orch-add-feature skill.
+---
+
+# /orch-add-feature
+
+Manually launch the **orch-add-feature** orchestrator: a gated
+Research → Plan → TDD → Review → Commit pipeline for net-new capability.
+
+## Usage
+
+```
+/orch-add-feature <what to add>
+```
+
+Examples:
+
+```
+/orch-add-feature add OAuth2 login to nws-poller
+/orch-add-feature support CSV export in the dashboard
+```
+
+## What It Does
+
+Invoke the `orch-add-feature` skill with `$ARGUMENTS` as the request. The skill
+(via the shared `orch-pipeline` engine) will:
+
+1. Classify size and state the tier in one line.
+2. Research existing libraries/patterns, then plan a `task_list`. → **GATE 1** (approve plan).
+3. TDD each task (new failing tests → green), then `code-reviewer`
+   (+ `security-reviewer` if a security trigger is touched).
+4. Commit as conventional `feat:` commits. → **GATE 2** (confirm before commit).
+
+Honor both gates — do not write implementation before Gate 1, do not commit before Gate 2.
+
+If `$ARGUMENTS` is empty, ask the user what capability to add.

package/bundled/upstream/ecc/commands/orch-build-mvp.md

@@ -0,0 +1,36 @@
+---
+description: Orchestrate bootstrapping a working MVP from a design/spec doc — ingest, slice, scaffold, TDD, review, gated commit (reuses the GAN harness). Wrapper for the orch-build-mvp skill.
+---
+
+# /orch-build-mvp
+
+Manually launch the **orch-build-mvp** orchestrator: turn an SDD/PRD/system-design
+document into a running vertical slice.
+
+## Usage
+
+```
+/orch-build-mvp <path to design/spec doc>
+```
+
+Examples:
+
+```
+/orch-build-mvp civicpulse/docs/SDD-v0.6.md
+```
+
+## What It Does
+
+Invoke the `orch-build-mvp` skill with `$ARGUMENTS` as the doc path. The skill
+(via the shared `orch-pipeline` engine, full pipeline incl. Scaffold) will:
+
+1. Read the spec; extract scope, locked decisions, and a feature list ordered as
+**thin vertical slices** (one end-to-end path first). → **GATE 1** (approve slice plan).
+2. Scaffold the first end-to-end slice.
+3. Reuse the GAN harness: translate the SDD into `gan-harness/spec.md` +
+   `eval-rubric.md`, then drive `/gan-build "<brief>" --skip-planner`
+   (generator → evaluator loop) until the score passes or plateaus.
+4. `code-reviewer` (+ `security-reviewer` on any security-trigger slice), then
+   commit the scaffold and each slice as separate `feat:` commits. → **GATE 2**.
+
+If `$ARGUMENTS` is empty, ask the user for the path to the design/spec doc.

package/bundled/upstream/ecc/commands/orch-change-feature.md

@@ -0,0 +1,38 @@
+---
+description: Orchestrate altering an existing, working feature to new desired behavior — update tests to the new spec, change impl, review, gated commit. Wrapper for the orch-change-feature skill.
+---
+
+# /orch-change-feature
+
+Manually launch the **orch-change-feature** orchestrator: change behavior that
+already works to a new desired spec, tests-first.
+
+## Usage
+
+```
+/orch-change-feature <the new desired behavior>
+```
+
+Examples:
+
+```
+/orch-change-feature make nws-poller alert at 2 warnings instead of 3
+/orch-change-feature instead of sorting by date, sort by priority
+```
+
+## What It Does
+
+Invoke the `orch-change-feature` skill with `$ARGUMENTS` as the request. The skill
+(via the shared `orch-pipeline` engine) will:
+
+1. Classify size (default floor: small) and state the tier.
+2. Light plan only if the new behavior needs research. → **GATE 1** (approve changed-test plan).
+3. **Update the existing tests** to express the new behavior, then change the
+   implementation until green. (Changing the tests first is what makes this a
+   tweak, not a fix.)
+4. `code-reviewer` (+ `security-reviewer` on a security trigger), then commit. → **GATE 2**.
+
+Use this only when the feature **works** but should behave differently — not for
+bugs (`/orch-fix-defect`) or net-new capability (`/orch-add-feature`).
+
+If `$ARGUMENTS` is empty, ask the user what behavior should change.

package/bundled/upstream/ecc/commands/orch-fix-defect.md

@@ -0,0 +1,38 @@
+---
+description: Orchestrate fixing a bug — reproduce it as a failing regression test, fix to green, review, gated commit. Wrapper for the orch-fix-defect skill.
+---
+
+# /orch-fix-defect
+
+Manually launch the **orch-fix-defect** orchestrator: prove the bug with a red
+test, then fix to green.
+
+## Usage
+
+```
+/orch-fix-defect <what is broken>
+```
+
+Examples:
+
+```
+/orch-fix-defect poller crashes on empty NWS response
+/orch-fix-defect login returns 500 when email has a plus sign
+```
+
+## What It Does
+
+Invoke the `orch-fix-defect` skill with `$ARGUMENTS` as the request. The skill
+(via the shared `orch-pipeline` engine) will:
+
+1. Classify size (default floor: small, often trivial); scope root cause with
+   `code-explorer` if unclear.
+2. **Write a new failing regression test** reproducing the bug, then fix until
+   it goes green. (Proving the bug first is what makes this a fix, not a tweak.)
+3. `code-reviewer` (+ `security-reviewer` if the defect sits in a sensitive path).
+4. Commit as a conventional `fix:` commit. → **GATE 2** (confirm before commit).
+
+Use this only when behavior is **broken/wrong** — not for intentional changes
+(`/orch-change-feature`) or new capability (`/orch-add-feature`).
+
+If `$ARGUMENTS` is empty, ask the user to describe the defect.

package/bundled/upstream/ecc/commands/orch-refine-code.md

@@ -0,0 +1,39 @@
+---
+description: Orchestrate a behavior-preserving refactor — confirm tests green, restructure without changing behavior, keep green, review, gated commit. Wrapper for the orch-refine-code skill.
+---
+
+# /orch-refine-code
+
+Manually launch the **orch-refine-code** orchestrator: improve structure while
+behavior stays identical, with the existing test suite as the safety net.
+
+## Usage
+
+```
+/orch-refine-code <what to restructure>
+```
+
+Examples:
+
+```
+/orch-refine-code extract the NWS HTTP client out of poller.py
+/orch-refine-code remove dead code and duplication in the dashboard module
+```
+
+## What It Does
+
+Invoke the `orch-refine-code` skill with `$ARGUMENTS` as the request. The skill
+(via the shared `orch-pipeline` engine) will:
+
+1. Classify size (default floor: standard — restructures touch multiple files).
+2. Confirm the relevant tests exist and are **green before** touching code; add
+   characterization tests first if coverage is thin. Plan the restructure. → **GATE 1**.
+3. Restructure in small steps, re-running tests after each (no new behavior
+   tests — the existing suite proves behavior is unchanged). Dead-code/dup sweeps
+   delegate to `refactor-cleaner`.
+4. `code-reviewer`, then commit as `refactor:` (the diff must be behavior-neutral). → **GATE 2**.
+
+Use this only when behavior must **not** change. If behavior should change at
+all, use `/orch-change-feature` or `/orch-fix-defect`.
+
+If `$ARGUMENTS` is empty, ask the user what to refine.

package/bundled/upstream/ecc/commands/quality-gate.md

@@ -1,33 +1,51 @@
 ---
-description: Run the ECC quality pipeline for a file or project scope and report remediation steps.
+description: Run the ECC formatter quality gate for a single file and report remediation steps.
 ---
 
 # Quality Gate Command
 
-Run the ECC quality pipeline on demand for a file or project scope.
+Operator entry point for the formatter quality gate that normally runs as the
+`post:quality-gate` PostToolUse hook (`scripts/hooks/quality-gate.js`).
 
-## Usage
+## How it actually works
+
+The gate is a single-file formatter check driven by hook input, not CLI flags:
 
-`/quality-gate [path|.] [--fix] [--strict]`
+- The script reads the target from the hook's stdin JSON
+  (`tool_input.file_path`); it does not take a path argument.
+- Behavior toggles are environment variables:
+  - `ECC_QUALITY_GATE_FIX=true` - apply formatting fixes instead of check-only
+  - `ECC_QUALITY_GATE_STRICT=true` - log formatter failures as gate failures
+- Coverage by file type:
+  - `.ts/.tsx/.js/.jsx/.json/.md` - Biome `check` or Prettier `--check`,
+    whichever the project ships (JS/TS under Biome is skipped here because
+    `post-edit-format` already runs `biome check --write`)
+  - `.go` - `gofmt`
+  - `.py` - `ruff format`
+- Lint and type checks are not part of this gate. Use the `verification-loop`
+  skill or the language verification skills for lint/type/test pipelines.
 
-- default target: current directory (`.`)
-- `--fix`: allow auto-format/fix where configured
-- `--strict`: fail on warnings where supported
+## Usage
 
-## Pipeline
+To run the gate manually against one file, pipe hook-style JSON into the
+script (set the env toggles first if you want fix or strict behavior):
 
-1. Detect language/tooling for target.
-2. Run formatter checks.
-3. Run lint/type checks when available.
-4. Produce a concise remediation list.
+```bash
+echo '{"tool_input":{"file_path":"src/example.ts"}}' \
+  | ECC_QUALITY_GATE_FIX=true node scripts/hooks/quality-gate.js
+```
+
+Then report formatter findings and concrete remediation steps.
 
 ## Notes
 
-This command mirrors hook behavior but is operator-invoked.
+Hook wiring lives in `hooks/hooks.json` (`post:quality-gate`, profiles
+`standard`/`strict` via `run-with-flags.js`).
 
 ## Arguments
 
 $ARGUMENTS:
-- `[path|.]` optional target path
-- `--fix` optional
-- `--strict` optional
+
+- `[path]` optional file to check. The script itself takes no CLI
+  arguments - when a path is given, substitute it as `tool_input.file_path`
+  in the stdin JSON shown above before running the command

package/bundled/upstream/ecc/commands/vue-review.md

@@ -0,0 +1,174 @@
+---
+description: Comprehensive Vue.js code review for Composition API correctness, reactivity, composable patterns, template security, accessibility, and Vue-specific performance. Invokes the vue-reviewer agent (and typescript-reviewer alongside on .vue/.ts changes).
+---
+
+# Vue Code Review
+
+This command invokes the **vue-reviewer** agent for Vue-specific code review. For pull requests touching `.vue` files or Vue-containing `.ts`/`.js` files, both `vue-reviewer` and `typescript-reviewer` should run — each owns a distinct lane.
+
+## What This Command Does
+
+1. **Identify Vue Changes**: Find modified `.vue` files and Vue-related `.ts`/`.js` files via `git diff`
+2. **Run Lint**: Execute `eslint` with `eslint-plugin-vue`
+3. **Typecheck**: Run `vue-tsc --noEmit` or the project's canonical typecheck command
+4. **Review Vue Lanes Only**: Reactivity, composables, template security, accessibility, Vue-specific performance
+5. **Generate Report**: Categorize issues by severity (CRITICAL / HIGH / MEDIUM)
+
+## When to Use
+
+Use `/vue-review` when:
+
+- A PR or commit touches `.vue` files
+- After writing or modifying Vue components, composables, or Pinia stores
+- Before merging Vue code
+- Auditing template security (`v-html`, URL bindings)
+- Reviewing a new composable for correctness
+- Auditing Vue Router guards and navigation
+- Reviewing Nuxt server routes or SSR-specific code
+
+For pure `.ts`/`.js` changes with no Vue imports, use `/code-review` (general) or invoke `typescript-reviewer` directly.
+
+## Scope vs `/code-review` and TypeScript Review
+
+| Tool | Scope |
+|---|---|
+| `vue-reviewer` (this command) | Reactivity, composables, template security, a11y, Vue performance, Pinia/Router |
+| `typescript-reviewer` | Generic TS/JS — `any` abuse, async correctness, Node security |
+| `security-reviewer` | Project-wide security audit |
+| `/code-review` | Generic uncommitted-changes or PR review |
+
+On a `.vue` / Vue-related PR, invoke both `vue-reviewer` and `typescript-reviewer`. Findings from each are non-overlapping by design.
+
+## Review Categories
+
+### CRITICAL (Must Fix)
+
+- `v-html` with unsanitized input
+- `:href`/`:src` with unvalidated user URLs (`javascript:`, `data:`)
+- Secret in client bundle (`VITE_*`, Nuxt `public` runtimeConfig)
+- Server endpoint without input validation (Nuxt Nitro)
+- `localStorage`/`sessionStorage` for session tokens
+- Destructuring reactive props in Vue < 3.5 (breaks reactivity)
+- `reactive()` object replacement (breaks watchers)
+- Watcher source tracking a ref object instead of `.value`
+
+### HIGH (Should Fix)
+
+- Composable with module-scope side effects
+- Missing cleanup in composable (watcher, interval, listener)
+- `v-for` without `:key` or with `key={index}`
+- `v-if` + `v-for` on same element
+- Props mutation
+- Missing prop validation
+- Route guard returning false without redirect
+- `useRoute().params` destructured at top-level (snapshot)
+- `v-model` bound to computed without setter
+- Accessibility violations (missing labels, non-semantic interactive elements)
+- Direct store property mutation outside actions
+
+### MEDIUM (Consider)
+
+- Options API in new Vue 3 code
+- Component over 300 lines
+- `v-show` where `v-if` is more appropriate (or vice versa)
+- Missing `:max` on `<KeepAlive>`
+- Missing `shallowRef` for large replaced data
+- Custom validation instead of vetted form library
+- `defineExpose` exposing more than necessary
+- `inheritAttrs` not disabled when using `v-bind="$attrs"`
+
+## Automated Checks Run
+
+```bash
+# Lint (required)
+npx eslint . --ext .vue,.ts,.js
+
+# Vue-specific typecheck
+vue-tsc --noEmit
+
+# Targeted security rules
+npx eslint . --rule 'vue/no-v-html: warn' \
+              --rule 'vue/no-template-target-blank: error'
+
+# Supply-chain
+npm audit
+```
+
+If `eslint-plugin-vue` or `vue-tsc` is not configured, the review will flag the gap as a HIGH config issue and continue.
+
+## Example Usage
+
+````text
+User: /vue-review
+
+Agent:
+# Vue Code Review Report
+
+## Files Reviewed
+- src/components/UserCard.vue (modified)
+- src/composables/useUser.ts (new)
+- src/stores/useUserStore.ts (modified)
+
+## Lint Results
+PASS: eslint clean
+PASS: vue-tsc clean
+
+## Issues Found
+
+[CRITICAL] Unsanitized v-html
+File: src/components/UserCard.vue:15
+Issue: User-controlled bio rendered as raw HTML via v-html.
+Why: XSS via stored script tags in user input.
+Fix: Sanitize with DOMPurify or render as text:
+```vue
+<script setup>
+import DOMPurify from "dompurify";
+const safeBio = computed(() => DOMPurify.sanitize(user.bio));
+</script>
+<template>
+  <div v-html="safeBio" />
+</template>
+```
+
+[HIGH] Watcher in composable missing cleanup
+File: src/composables/useUser.ts:22
+Issue: `watch` callback fires fetch without AbortController; stale responses can overwrite newer data.
+Fix: Use onCleanup to abort:
+```ts
+watch(userId, async (newId, _old, onCleanup) => {
+  const controller = new AbortController();
+  onCleanup(() => controller.abort());
+  const data = await fetch(`/api/users/${newId}`, { signal: controller.signal });
+  user.value = await data.json();
+});
+```
+
+## Summary
+- CRITICAL: 1
+- HIGH: 1
+- MEDIUM: 0
+
+Recommendation: FAIL: Block merge until CRITICAL issue is fixed
+````
+
+## Approval Criteria
+
+| Status | Condition |
+|---|---|
+| PASS: Approve | No CRITICAL or HIGH issues |
+| WARNING: Warning | Only MEDIUM issues (merge with caution) |
+| FAIL: Block | CRITICAL or HIGH issues found |
+
+## Integration with Other Commands
+
+- Run your project's build command first if the build is broken
+- Run tests to ensure component tests pass
+- Run `/vue-review` before merging Vue code
+- Use `/code-review` for non-Vue-specific concerns on the same PR
+
+## Related
+
+- Agent: `agents/vue-reviewer.md`
+- Companion agent: `agents/typescript-reviewer.md` (run alongside for Vue-related TS/JS)
+- Skills: `skills/vue-patterns/`
+- Rules: `rules/vue/`

package/bundled/upstream/ecc/skills/accessibility/SKILL.md

@@ -2,7 +2,8 @@
 name: accessibility
 description: Design, implement, and audit inclusive digital products using WCAG 2.2 Level AA
   standards. Use this skill to generate semantic ARIA for Web and accessibility traits for Web and Native platforms (iOS/Android).
-origin: ECC
+metadata:
+  origin: ECC
 ---
 
 # Accessibility (WCAG 2.2)

package/bundled/upstream/ecc/skills/agent-architecture-audit/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: agent-architecture-audit
 description: Full-stack diagnostic for agent and LLM applications. Audits the 12-layer agent stack for wrapper regression, memory pollution, tool discipline failures, hidden repair loops, and rendering corruption. Produces severity-ranked findings with code-first fixes. Essential for developers building agent applications, autonomous loops, or any LLM-powered feature.
-origin: oh-my-agent-check
+metadata:
+  origin: oh-my-agent-check
 tools: Read, Write, Edit, Bash, Grep, Glob
 ---
 

package/bundled/upstream/ecc/skills/agent-eval/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: agent-eval
 description: Head-to-head comparison of coding agents (Claude Code, Aider, Codex, etc.) on custom tasks with pass rate, cost, time, and consistency metrics
-origin: ECC
+metadata:
+  origin: ECC
 tools: Read, Write, Edit, Bash, Grep, Glob
 ---
 

package/bundled/upstream/ecc/skills/agent-harness-construction/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: agent-harness-construction
 description: Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates.
-origin: ECC
+metadata:
+  origin: ECC
 ---
 
 # Agent Harness Construction

package/bundled/upstream/ecc/skills/agent-introspection-debugging/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: agent-introspection-debugging
 description: Structured self-debugging workflow for AI agent failures using capture, diagnosis, contained recovery, and introspection reports.
-origin: ECC
+metadata:
+  origin: ECC
 ---
 
 # Agent Introspection Debugging

package/bundled/upstream/ecc/skills/agent-payment-x402/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: agent-payment-x402
 description: Add x402 payment execution to AI agents with per-task budgets, spending controls, and non-custodial wallets. Supports Base through agentwallet-sdk and X Layer through OKX Payments / OKX Agent Payments Protocol.
-origin: community
+metadata:
+  origin: community
 ---
 
 # Agent Payment Execution (x402)

package/bundled/upstream/ecc/skills/agent-self-evaluation/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: agent-self-evaluation
+description: Use after completing any non-trivial task. The agent self-rates its output on 5 axes — accuracy, completeness, clarity, actionability, conciseness — with concrete evidence per criterion. Produces a structured 1-5 scorecard with specific improvement suggestions.
+origin: ECC
+---
+
+# Agent Self-Evaluation
+
+After completing a complex task, the agent pauses to rate its own output against a structured 5-axis rubric. This is NOT a pass/fail gate — it's a deliberate reflection step that catches omissions, flags overconfidence, and surface areas for improvement before the user has to.
+
+## When to Activate
+
+- After writing code that spans 3+ files or 50+ lines
+- After completing a multi-step workflow (implement → test → review)
+- After a debugging session that involved 3+ attempts
+- After producing a design document, architecture decision, or written analysis
+- When the user asks "how good was that?" or "rate yourself"
+- At the end of any session Stop hook (if configured — see `references/hook-integration.md`)
+
+## Core Concepts
+
+### The 5 Evaluation Axes
+
+| Axis | Question | What it catches |
+|---|---|---|
+| **Accuracy** | Are the facts, claims, and outputs correct? | Hallucinations, wrong API names, incorrect syntax, false statements |
+| **Completeness** | Did it cover everything the user asked for? | Missed edge cases, unhandled error paths, forgotten requirements, skipped subtasks |
+| **Clarity** | Is the explanation understandable and well-structured? | Confusing explanations, jargon without definition, missing context, rambling |
+| **Actionability** | Can the user act on the output immediately? | Vague suggestions, missing steps, "you should X" without showing how, no verification path |
+| **Conciseness** | Did it use the minimum words/tokens needed? | Redundancy, over-explanation, repeating the user's question verbatim, filler content |
+
+### Scoring Scale
+
+```
+5 — Exceptional: no reasonable improvement possible
+4 — Good: minor nits only, no substantive gaps
+3 — Adequate: meets the request but has a notable weakness on at least one axis
+2 — Weak: has a clear gap that affects usability or correctness
+1 — Poor: fundamentally misses the request or contains significant errors
+```
+
+### The Evidence Rule
+
+Every score below 5 MUST cite specific evidence. A score of 3 cannot just say "could be better" — it must say exactly what is missing or wrong. The mantra: **"Show the gap, don't just name it."**
+
+## Workflow
+
+### Step 1: Collect the Raw Material
+
+Gather what you'll evaluate:
+
+```
+- The original user request (read back from conversation)
+- Your final response/output (the deliverable)
+- Any tool outputs that verify correctness (test results, exit codes, lint output)
+- Any user feedback received during the task (corrections, "try again", "that's not right")
+```
+
+### Step 2: Score Each Axis Independently
+
+Work through the 5 axes one at a time. For each:
+
+1. Read the axis question
+2. Find evidence (or lack of evidence) in the output
+3. Assign a score 1-5
+4. If score < 5, write a one-sentence improvement note citing the gap
+
+Do NOT average the scores in your head first and then work backwards. Score each axis fresh.
+
+### Step 3: Produce the Evaluation Report
+
+Use the template from `templates/evaluation-report.md`. The report must include:
+
+```
+- One-line summary
+- 5-axis scorecard (score + evidence per axis)
+- Overall score (simple average, rounded to 1 decimal)
+- 1-3 specific improvements ranked by impact
+- Self-check: "Would the user agree with this assessment?"
+```
+
+### Step 4: Apply the Improvement
+
+If any axis scored 3 or below:
+
+1. State what you would do differently
+2. If the gap is fixable in < 30 seconds (missing link, unclear phrasing), fix it now
+3. If the gap requires rework, flag it explicitly: "This axis scored [reason] because [evidence]. Re-running with [specific fix] would likely raise it to [score]."
+
+## Code Examples
+
+### Example: Good Evaluation (Score 4+)
+
+```
+Task: Add retry logic to HTTP client
+
+Scorecard:
+  Accuracy:    5 — All API calls correct. Verified: retries use
+                  exponential backoff. No hallucinated methods.
+  Completeness: 4 — Covered happy path + 3 error cases. Missing:
+                  timeout handling for hung connections.
+  Clarity:      5 — Code comments explain backoff formula.
+                  PR description links to incident that motivated this.
+  Actionability:5 — Single merge. No follow-up tasks. Tests pass.
+  Conciseness:  4 — 47 lines total. The retry loop could be extracted
+                  into a helper to drop ~8 lines.
+
+Overall: 4.6 — One gap (timeout handling). Fix before merging.
+```
+
+### Example: Weak Evaluation (Score 2-3)
+
+```
+Task: Add retry logic to HTTP client
+
+Scorecard:
+  Accuracy:    2 — Used urllib3 which doesn't match our
+                  httpx-based codebase. Wrong library.
+  Completeness: 3 — Works for GET. POST/PUT not handled (user
+                  said "all HTTP requests").
+  Clarity:      4 — Code is readable. Good variable names.
+  Actionability:2 — "Add tests" mentioned but no test file created.
+                  User has to write tests before merging.
+  Conciseness:  3 — 120 lines. The retry config is duplicated in
+                  3 places instead of one shared RetryConfig object.
+
+Overall: 2.8 — Wrong library used. Needs httpx rewrite.
+  Fix accuracy first (switch to httpx), then extend to all
+  HTTP methods, then consolidate config.
+```
+
+## Anti-Patterns
+
+### "Everything is a 5"
+
+```
+FAIL: Accuracy:    5 — All good.
+   Completeness: 5 — Everything covered.
+   Clarity:      5 — Clear.
+```
+
+No evidence cited. This is self-congratulation, not evaluation. A real 5 requires proving there's nothing to improve.
+
+### Over-penalizing for scope creep
+
+```
+FAIL: Completeness: 2 — Didn't handle WebSocket connections or
+   gRPC streaming (user didn't ask for these)
+```
+
+Only evaluate against what the user actually requested, not what you could have additionally built.
+
+### Using the evaluation to re-litigate
+
+```
+FAIL: "As I said earlier, this approach is wrong. Score: 1"
+```
+
+The evaluation is about the delivered output, not about re-arguing design decisions that were already made. If the approach was wrong, that should have been caught before delivery.
+
+### Mixing personal preference with objective gaps
+
+```
+FAIL: "Score: 3. I don't like Python decorators."
+```
+
+"Don't like" is not evidence. Cite a concrete readability, testability, or correctness concern, or leave the score at 4+.
+
+## Best Practices
+
+- **Evaluate the output, not the process.** The user cares about what you delivered, not how many iterations you took.
+- **One improvement per weak axis.** Don't list 5 things for one axis — pick the highest-impact gap.
+- **Tie improvements to user impact.** "Missing error handling means the user's API call will crash silently" beats "add error handling."
+- **Be specific about what 'fixed' looks like.** "Re-run with httpx transport configured for retries" beats "fix the library issue."
+- **Use tool outputs as evidence.** If tests passed, cite them. If lint is clean, cite it. Don't guess — grep for the proof.
+- **If you can't find any gaps, try harder.** A perfect score across all 5 axes is rare. Ask: "If I were the user, what would annoy me about this output?"
+
+## Related Skills
+
+- `agent-eval` — Head-to-head comparison of different coding agents on benchmark tasks
+- `verification-loop` — Systematic verification of outputs against expected results
+- `security-review` — Security-focused code review checklist