@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/shopify/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — shopify
+
+Run these against the repo's eval harness pointed at the `shopify` skill id. The
+`should_trigger` cases mirror the `description` triggers across all three surfaces (theme, app,
+checkout) and include the non-obvious ones — the "broke after the August upgrade" checkout-
+migration framing, the `MAX_COST_EXCEEDED` query-cost framing, and the Catalan phrasing — to
+confirm the skill fires when the surface is implicit. The `should_not_trigger` cases each route to
+a real sibling (`wordpress`, `stripe`, `nextjs`, `no-code-app`, `api-design`) and exist to catch
+surface confusion: WooCommerce/PHP, non-Shopify payments, the headless React layer, no-code
+builders, and generic API-contract design must *not* pull in Shopify. The single `capability` case
+is graded against its `must_include` rubric — a correct answer scaffolds an OS 2.0 section
+(`render` not `include`, a `presets` + `@app` block schema) plus a Remix loader on a pinned
+`apiVersion` with `admin.graphql()` and cost/throttle awareness, and never reaches for
+`checkout.liquid`.

package/skills/shared/shopify/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: shopify
+
+should_trigger:
+  - prompt: "Add a customizable section to my Shopify theme that merchants can edit in the theme editor without asking me to deploy."
+    why: "OS 2.0 section + {% schema %} with presets — the editable-content theme surface."
+  - prompt: "Build a Shopify app with Remix that reads orders from the Admin API and shows them in an embedded admin page."
+    why: "App surface: Remix template, admin.graphql(), App Bridge/Polaris."
+  - prompt: "Our checkout customizations stopped working after the August upgrade — how do I get them back?"
+    why: "Non-obvious: 2025-08-28 was the Plus self-migrate deadline; automatic upgrades begin 2026-01 → rebuild on checkout extensibility."
+  - prompt: "Replace the include tags in our Liquid snippets and stop the price from showing raw cents."
+    why: "Theme/Liquid rules: {% render %} over {% include %}, pipe through | money."
+  - prompt: "migrar el checkout.liquid a checkout extensibility i afegir un bloc d'app a la secció de producte"
+    why: "Catalan; checkout migration + @app block — both core surfaces of this skill."
+  - prompt: "We're getting MAX_COST_EXCEEDED from the Shopify Admin API on a big product export."
+    why: "Non-obvious: GraphQL query-cost/throttle model → bulk operations."
+
+should_not_trigger:
+  - prompt: "Build a WooCommerce store with a custom PHP theme and a few hooks in functions.php."
+    route_to: wordpress
+    why: "WooCommerce/PHP/WP plugin model, not Liquid + shopify.*.toml + GraphQL Admin API."
+  - prompt: "Integrate Stripe Checkout and subscription billing into our SaaS app."
+    route_to: stripe
+    why: "Non-Shopify payment system; Shopify Payments/checkout is in-platform only."
+  - prompt: "Build the React/React Server Components frontend and routing for our headless storefront."
+    route_to: nextjs
+    why: "The rendering/routing layer is Next.js; Shopify is only the data seam there."
+  - prompt: "Set up a no-code drag-and-drop online store, no developers involved."
+    route_to: no-code-app
+    why: "Non-developer store builder; this skill is the code surfaces (Liquid, CLI, GraphQL)."
+  - prompt: "Design our public REST API's versioning, pagination, and status-code conventions."
+    route_to: api-design
+    why: "Generic API contract design, not Shopify's specific versioned GraphQL + cost model."
+
+capability:
+  - scenario: "Scaffold an OS 2.0 section with {% schema %} + @app block support, and a Remix loader that queries products via the Admin GraphQL API."
+    must_include:
+      - "uses {% render %} (not {% include %})"
+      - "{% schema %} with a presets entry and a { type: '@app' } block"
+      - "pins a current apiVersion (2026-04 or another supported quarterly version) and uses admin.graphql()"
+      - "mentions query-cost / throttleStatus or bulk-operations awareness"
+      - "escapes/pipes dynamic output (| escape / | money) and does NOT touch checkout.liquid"

package/skills/shared/shopify/references/apps-graphql.md

@@ -0,0 +1,103 @@
+# Shopify apps & the GraphQL Admin API — deep dive
+
+Companion to the App surface section of `../SKILL.md`. The template is `@shopify/shopify-app-remix`.
+
+## Template wiring
+
+```js
+// app/shopify.server.js
+import { shopifyApp, ApiVersion } from "@shopify/shopify-app-remix/server";
+import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma";
+
+const shopify = shopifyApp({
+  apiKey: process.env.SHOPIFY_API_KEY,
+  apiSecretKey: process.env.SHOPIFY_API_SECRET,   // env, never in shopify.app.toml
+  apiVersion: ApiVersion.April26,                  // pin; bump quarterly
+  scopes: process.env.SCOPES?.split(","),
+  sessionStorage: new PrismaSessionStorage(prisma),
+  webhooks: { ORDERS_CREATE: { deliveryMethod: "http", callbackUrl: "/webhooks" } },
+  future: { unstable_newEmbeddedAuthStrategy: true },
+});
+export const authenticate = shopify.authenticate;
+```
+
+OAuth, token exchange, and session storage are handled by the template — store sessions in a real
+DB (Prisma/SQL) in production, never in memory.
+
+## Queries & mutations
+
+```js
+export async function loader({ request }) {
+  const { admin } = await authenticate.admin(request);
+  const res = await admin.graphql(
+    `#graphql
+     query Products($n: Int!) {
+       products(first: $n) { nodes { id title totalInventory } }
+     }`,
+    { variables: { n: 20 } },
+  );
+  const { data, extensions } = await res.json();
+  return { products: data.products.nodes, cost: extensions.cost };
+}
+```
+
+Mutations follow the same shape and always select `userErrors { field message }` — Shopify returns
+validation failures there, not as thrown errors:
+
+```graphql
+mutation UpdatePrice($input: ProductVariantsBulkInput!, $productId: ID!) {
+  productVariantsBulkUpdate(productId: $productId, variants: [$input]) {
+    productVariants { id price }
+    userErrors { field message }
+  }
+}
+```
+
+## Query-cost, throttling & bulk operations
+
+Read `extensions.cost.throttleStatus` after every call. Over-budget = HTTP 200 + a
+`MAX_COST_EXCEEDED` entry in `errors`. Back off using `restoreRate` (points/sec). For large
+exports use bulk operations instead of `first:`/`after:` loops:
+
+```graphql
+mutation {
+  bulkOperationRunQuery(query: "{ products { edges { node { id title } } } }") {
+    bulkOperation { id status }
+    userErrors { field message }
+  }
+}
+```
+
+Poll `currentBulkOperation` until `status: COMPLETED`, then stream the JSONL from its `url`.
+
+## Webhooks (HMAC)
+
+```js
+// app/routes/webhooks.jsx
+export async function action({ request }) {
+  const { topic, shop, payload } = await authenticate.webhook(request); // verifies HMAC
+  // ... handle topic; return 200 fast, offload heavy work
+  return new Response();
+}
+```
+
+Never parse `request.body` directly — an unverified payload is untrusted input. Reconcile periodically;
+webhooks can be missed.
+
+## App Bridge & Polaris
+
+Embedded UI runs inside the Shopify admin iframe. App Bridge handles session-token auth, navigation,
+and toasts; Polaris React gives admin-consistent components. Keep app UI in Polaris so it matches the
+admin chrome — do not hand-roll admin-looking CSS.
+
+## App extensions & deploy
+
+Extensions live under `extensions/` (theme app extension, admin/customer-account UI extensions,
+Functions, Flow). Ship them with versioned releases:
+
+```bash
+shopify app deploy   # creates an app version bundling code + extensions; `app config push` is removed
+```
+
+Each `shopify app deploy` is an immutable, rollback-able version. Pin and bump `apiVersion`
+quarterly across both the app client and extension configs.

package/skills/shared/shopify/references/checkout-extensibility.md

@@ -0,0 +1,71 @@
+# Checkout extensibility — migration off `checkout.liquid`
+
+Companion to the Checkout surface section of `../SKILL.md`. The old model (`checkout.liquid`,
+additional scripts, script tags, Script Editor) is deprecated and being removed.
+
+## The dated deadlines
+
+- **2024-08-13** — Information / Shipping / Payment steps stopped supporting `checkout.liquid`.
+- **2025-08-28** — Plus self-migrate deadline for Thank-you and Order-status page customizations
+  (additional scripts, script tags, `checkout.liquid`). This is the date to *act by*, not the
+  auto-upgrade date.
+- **2026-01** — **automatic upgrades** of Thank-you and Order-status pages begin. Shopify gives a
+  30-day email notice, then upgrades the store; any remaining additional-scripts, script-tag, or
+  `checkout.liquid` customizations stop running. (Non-Plus stores have a later self-migrate deadline
+  of 2026-08-26.)
+- **2026-04-15** — legacy Shopify Scripts can no longer be **edited or published** (existing
+  published scripts keep running until the shutdown below — so a bug after this date has no in-Script fix).
+- **2026-06-30** — legacy Shopify Scripts (Script Editor) **stop executing**. Replace with Functions.
+
+If a store says "checkout customizations broke after the August upgrade," they usually mean the
+2025-08-28 deadline passed and they were caught by the automatic upgrade (rolling out from 2026-01) —
+the old script no longer runs. Rebuild it on the seam below.
+
+## Migration map
+
+| Old mechanism | New seam | What you build |
+|---|---|---|
+| `checkout.liquid` markup / additional scripts (UI) | **Checkout UI extensions** | a sandboxed extension targeting a checkout location |
+| Script Editor discount logic | **Discount Function** | Wasm function returning discount operations |
+| Script Editor shipping/delivery logic | **Delivery customization Function** | reorder/rename/hide shipping options |
+| Script Editor payment logic | **Payment customization Function** | reorder/rename/hide payment methods |
+| `<script>` analytics/tracking in checkout | **Web Pixels** (+ server-side events) | sandboxed pixel; subscribe to standard events |
+| custom checkout CSS / branding | **Checkout Branding API** | GraphQL mutations on the checkout profile |
+
+## Checkout UI extensions
+
+React/JS extensions that render at defined **targets** (e.g. `purchase.checkout.block.render`,
+`purchase.checkout.delivery-address.render-before`). You get a typed API and components — **no DOM
+access**, by design (PCI + stability). Configure target + capabilities in the extension's TOML.
+
+```jsx
+import { reactExtension, Banner } from "@shopify/ui-extensions-react/checkout";
+export default reactExtension("purchase.checkout.block.render", () => <Banner>Free gift over 50</Banner>);
+```
+
+## Functions
+
+Deterministic server-side logic compiled to Wasm — author in Rust or JavaScript. A Function takes a
+typed input (a GraphQL query you define against the function's input schema) and returns operations.
+Categories: product discount, order discount, shipping discount, delivery customization, payment
+customization, cart/checkout validation. Generate with `shopify app generate extension`, build, and
+ship with `shopify app deploy`.
+
+```rust
+#[shopify_function]
+fn run(input: input::ResponseData) -> Result<output::FunctionRunResult> {
+    // return discount operations from typed input
+}
+```
+
+## Web Pixels
+
+For tracking/analytics that previously lived in checkout `<script>` tags. A pixel runs in a sandbox
+and subscribes to standard customer events (`checkout_completed`, `product_viewed`, …). It cannot
+reach the page DOM; send events to your endpoint or a destination.
+
+## Plus-only surfaces
+
+Full checkout UI customization and some Function/branding capabilities are **Shopify Plus-only**.
+Non-Plus stores get a constrained set of UI extension targets. Confirm the merchant's plan before
+promising a checkout customization.

package/skills/shared/shopify/references/liquid-themes.md

@@ -0,0 +1,89 @@
+# Liquid & Online Store 2.0 themes — deep dive
+
+Companion to the Theme surface section of `../SKILL.md`. Everything here is OS 2.0 (GA 2021).
+
+## The architecture, end to end
+
+A storefront page is assembled top-down:
+
+1. `layout/theme.liquid` — the HTML shell. Renders `{{ content_for_header }}` and
+   `{{ content_for_layout }}`. One per theme (plus optional `checkout` layout on Plus).
+2. A **JSON template** (`templates/product.json`, `templates/index.json`, …) declares which
+   sections render and their order — not Liquid, pure JSON the theme editor mutates.
+3. Each **section** (`sections/*.liquid`) is markup + a `{% schema %}` of settings and blocks.
+4. **Section groups** (`sections/header.json`, `sections/footer.json`) make header/footer
+   editable as section lists.
+5. **Snippets** (`snippets/*.liquid`) are partials, always via `{% render %}`.
+
+```json
+// templates/product.json
+{
+  "sections": {
+    "main": { "type": "main-product" },
+    "related": { "type": "related-products", "settings": { "heading": "You may also like" } }
+  },
+  "order": ["main", "related"]
+}
+```
+
+## `{% schema %}` setting types & presets
+
+The schema is JSON inside the `.liquid` file. Common setting types: `text`, `textarea`,
+`richtext`, `image_picker`, `url`, `product`, `collection`, `product_list`, `color`, `range`,
+`select`, `checkbox`, `font_picker`, `metaobject`/`metaobject_list`.
+
+```liquid
+{% schema %}
+{
+  "name": "Featured collection",
+  "tag": "section",
+  "settings": [
+    { "type": "collection", "id": "collection", "label": "Collection" },
+    { "type": "range", "id": "limit", "min": 2, "max": 12, "step": 1, "default": 8, "label": "Products" }
+  ],
+  "blocks": [
+    { "type": "text", "name": "Text", "settings": [{ "type": "richtext", "id": "body", "label": "Body" }] },
+    { "type": "@app" }
+  ],
+  "presets": [{ "name": "Featured collection", "blocks": [{ "type": "text" }] }]
+}
+{% endschema %}
+```
+
+- `presets` is what makes the section show up in "Add section" in the editor. No preset → the
+  section exists but a merchant can't add it.
+- `blocks` with `{ "type": "@app" }` accepts app-provided blocks (theme app extensions).
+- Iterate blocks in render order: `{% for block in section.blocks %}{% render block.type, block: block %}{% endfor %}`
+  and emit `{{ block.shopify_attributes }}` on the block's root element so the editor can target it.
+
+## Theme blocks (OS 2.0 reusable blocks)
+
+`blocks/*.liquid` define reusable, nestable blocks usable across sections — distinct from a
+section's inline `blocks`. They have their own `{% schema %}` and can accept child blocks via
+`"blocks": [{ "type": "@theme" }]`. Use them to avoid copy-pasting block markup between sections.
+
+## Dynamic sources, metafields & metaobjects
+
+Bind structured content instead of hardcoding. A setting can carry a **dynamic source** so a
+merchant connects it to a metafield in the editor. Read metafields in Liquid:
+
+```liquid
+{{ product.metafields.custom.care_instructions | metafield_tag }}
+{% assign spec = product.metafields.custom.spec.value %}  {# metaobject reference #}
+```
+
+Prefer this over an `if product.type == ...` ladder: the branch becomes a metafield lookup, so
+new product types need data, not a theme deploy.
+
+## Storefront performance
+
+- Responsive images: `{{ image | image_url: width: 800 | image_tag: loading: 'lazy', sizes: '...', widths: '300,600,800,1200' }}`.
+- `loading="eager"` + a `<link rel="preload">` only for the LCP hero image; lazy-load the rest.
+- Defer non-critical media and scripts; avoid render-blocking app embeds.
+- Always `limit:` collection/loop output; unbounded loops dominate render time.
+
+## Theme Check
+
+`shopify theme check` (config: `.theme-check.yml`) flags deprecated `include`, unused
+assigns, missing `{{ block.shopify_attributes }}`, untranslated strings, and parser errors. Run
+it locally and in CI. `theme dev` gives hot reload as the inner loop.

package/skills/shared/shopify/scripts/verify.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+#
+# verify.sh — advisory quality scan for a Shopify theme or app directory.
+#
+# Usage:
+#   ./scripts/verify.sh [TARGET_PATH]
+#
+# Read-only by default. Greps a theme/app dir for high-signal Shopify foot-guns and prints
+# WARN / FAIL advisories. WARN = a smell to review; FAIL = a deprecated/removed mechanism that
+# will break. Exits non-zero only when a FAIL-level issue is found in a real Shopify dir.
+# On an empty or non-Shopify target it SKIPs and exits 0 (no false failure).
+#
+# Compatible with stock macOS bash 3.2: no mapfile, no associative arrays, find-based globbing.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ -t 1 ]; then
+  RED=$'\033[0;31m'; GREEN=$'\033[0;32m'; YELLOW=$'\033[0;33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+warn() { printf '%sWARN%s %s\n' "$YELLOW" "$RESET" "$*"; }
+ok()   { printf '%s%s%s\n' "$GREEN" "$*" "$RESET"; }
+fail() { printf '%sFAIL%s %s\n' "$RED" "$RESET" "$*"; }
+
+WARNS=0; FAILS=0
+
+# A Shopify dir has either theme structure (sections/ or templates/*.json or *.liquid) or an
+# app/theme config TOML. Neither → nothing to verify, SKIP (exit 0).
+shopify_present() {
+  if [ -f "$TARGET/shopify.app.toml" ] || [ -f "$TARGET/shopify.theme.toml" ]; then return 0; fi
+  if [ -n "$(find "$TARGET" -type f -name '*.liquid' -print -quit 2>/dev/null)" ]; then return 0; fi
+  if [ -d "$TARGET/sections" ] || [ -d "$TARGET/extensions" ]; then return 0; fi
+  return 1
+}
+
+if ! shopify_present; then
+  warn "no Shopify theme/app found under '${TARGET}' (no *.liquid, no shopify.*.toml, no sections/ or extensions/)"
+  ok "verify.sh: ok (nothing to verify)"
+  exit 0
+fi
+
+# grep_count <pattern> <find-name-filter...> — count matching lines across files, 0 if none.
+# Uses find + grep so it stays bash-3.2 / BSD-grep safe and never errors on no match.
+scan() { # scan <label> <level:warn|fail> <regex> <file-glob>
+  local label="$1" level="$2" regex="$3" glob="$4"
+  local hits
+  hits=$(find "$TARGET" -type f -name "$glob" -print0 2>/dev/null \
+    | xargs -0 grep -nE "$regex" 2>/dev/null || true)
+  if [ -n "$hits" ]; then
+    if [ "$level" = "fail" ]; then
+      fail "$label"; FAILS=$((FAILS + 1))
+    else
+      warn "$label"; WARNS=$((WARNS + 1))
+    fi
+    printf '%s\n' "$hits" | sed 's/^/    /' | head -10
+  fi
+}
+
+# 1. Deprecated {% include %} in Liquid (prefer {% render %}).
+scan "deprecated {% include %} — use {% render %} (scoped, cacheable)" warn \
+  '\{%-?[[:space:]]*include[[:space:]]' '*.liquid'
+
+# 2. Raw money output without a | money filter (heuristic: .price echoed without 'money').
+scan "price output without | money — renders raw cents/locale wrong" warn \
+  '\{\{[^}]*\.price[^}|]*\}\}' '*.liquid'
+
+# 3. checkout.liquid present — deprecated; automatic upgrades roll out starting 2026-01.
+if find "$TARGET" -type f -name 'checkout.liquid' -print -quit 2>/dev/null | grep -q . ; then
+  fail "checkout.liquid present — deprecated/removed; migrate to checkout extensibility"
+  FAILS=$((FAILS + 1))
+fi
+
+# 4. ScriptTag / additional-script usage — deprecated checkout/tracking mechanism.
+scan "ScriptTag / additional-scripts usage — deprecated; use Web Pixels / UI extensions" warn \
+  'ScriptTag|additional_scripts|additional scripts' '*'
+
+# 5. REST Admin API calls in app source — legacy; prefer GraphQL.
+scan "REST Admin API call (/admin/api/.../.json) — legacy; use admin.graphql()" warn \
+  '/admin/api/[0-9]{4}-[0-9]{2}/[^"'"'"' ]+\.json' '*'
+
+# 6. apiVersion pinned and within the supported window (2025-10 .. 2026-04 at time of writing;
+#    2025-07 is sunsetting ~2026-07-16, so flag it). Unpinned or an older literal → warn.
+APIV=$(find "$TARGET" -type f \( -name '*.js' -o -name '*.ts' -o -name '*.toml' \) -print0 2>/dev/null \
+  | xargs -0 grep -hoE 'apiVersion[^0-9]*(2[0-9]{3}-[0-9]{2})' 2>/dev/null \
+  | grep -oE '2[0-9]{3}-[0-9]{2}' | head -1 || true)
+if [ -f "$TARGET/shopify.app.toml" ] || find "$TARGET" -type f -name '*.server.*' -print -quit 2>/dev/null | grep -q .; then
+  if [ -z "$APIV" ]; then
+    warn "no pinned apiVersion found in app config/server — pin a supported version (e.g. 2026-04)"
+    WARNS=$((WARNS + 1))
+  else
+    case "$APIV" in
+      2026-04|2026-01|2025-10) : ;;
+      2025-07) warn "apiVersion '2025-07' is sunsetting (accessible only until 2026-07-16) — bump to a current version"; WARNS=$((WARNS + 1)) ;;
+      *) warn "apiVersion '$APIV' is outside the supported window (2025-10..2026-04) — bump it"; WARNS=$((WARNS + 1)) ;;
+    esac
+  fi
+fi
+
+# 7. Run Theme Check if a config and the CLI are both present (still read-only).
+if [ -f "$TARGET/.theme-check.yml" ] || [ -f "$TARGET/.theme-check.yaml" ]; then
+  if command -v shopify >/dev/null 2>&1; then
+    printf '==> shopify theme check\n'
+    if ! shopify theme check "$TARGET"; then
+      warn "theme check reported issues"; WARNS=$((WARNS + 1))
+    fi
+  else
+    warn ".theme-check.yml present but shopify CLI not installed — skipping theme check"
+  fi
+fi
+
+printf '\n%d warn, %d fail\n' "$WARNS" "$FAILS"
+if [ "$FAILS" -gt 0 ]; then
+  fail "verify.sh: deprecated/removed mechanisms detected"
+  exit 1
+fi
+ok "verify.sh: ok"
+exit 0

package/skills/shared/simplify-code/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: simplify-code
+description: "Use when correct working code is unnecessarily hard to read, change or verify and needs behaviour-preserving simplification in a bounded scope. Characterizes the observable contract, removes accidental complexity one concept at a time and proves equivalence. NOT fixing a failure (`debug`), NOT read-only diff judgment (`review`/`code-review`)."
+tags: [code-simplification, refactoring, readability, complexity, behavior-preservation]
+recommends: [code-review, review, verify, debug, performance]
+profiles: [core, full]
+origin: ai-hub
+---
+
+# simplify-code — fewer moving parts, same contract
+
+Use this when the code already works and the desired change is easier reasoning, not new behaviour. The output is a smaller or clearer implementation plus proof that callers cannot tell the difference.
+
+Default scope is the files or symbols the user named, or the recently changed slice. Expanding into adjacent cleanup requires a concrete dependency and must be stated. Never “clean the whole repository” as a side effect.
+
+## The equivalence loop
+
+```text
+BOUND → CHARACTERIZE → BASELINE → REDUCE → VERIFY → EXPLAIN
+```
+
+### 1. BOUND the work
+
+Record:
+
+- target files/symbols and why they are difficult;
+- callers and public interfaces that must remain stable;
+- generated/vendor code and project-marked protected regions to leave alone;
+- performance, ordering, compatibility or serialization constraints;
+- unrelated dirty-worktree changes that belong to someone else.
+
+Respect protected regions through repository instructions and explicit comments. Do not hide them by rewriting files on disk, swapping placeholders in and out, or relying on a cleanup hook to restore them later.
+
+### 2. CHARACTERIZE the observable contract
+
+Tests are necessary but may be incomplete. Write down what must remain the same:
+
+- return values and data shapes;
+- thrown/rejected error types, messages when contractual, and timing;
+- ordering, deduplication and mutation behaviour;
+- I/O, logs, analytics and other side effects;
+- async/concurrency semantics;
+- hot-path allocations or latency when performance is part of the contract.
+
+If the behaviour cannot be stated or observed, add characterization tests before refactoring. When the current behaviour is a bug, stop and route to `../debug/SKILL.md`; simplification must not smuggle in a fix.
+
+### 3. BASELINE current evidence
+
+Run the narrow tests first and preserve their output. Then run type/lint/build checks appropriate to the slice. For a performance-sensitive path, capture a representative benchmark under named conditions. A baseline proves what “same” means and prevents a cleaner-looking regression.
+
+### 4. REDUCE one source of accidental complexity
+
+Prefer changes with a visible reasoning payoff:
+
+- remove dead branches, duplicate calculations or needless state;
+- replace nested control flow with guard clauses when ordering stays identical;
+- extract a name for a real concept, not every three lines;
+- collapse pass-through wrappers that enforce no policy;
+- replace clever compact expressions with direct ones;
+- make data flow single-directional and ownership explicit;
+- reuse an existing local abstraction when it is simpler than both copies.
+
+Change one concept at a time and inspect the diff. Complexity moved into a new helper, generic abstraction or dependency is not removed. Lines of code are supporting evidence, never the target.
+
+Do not redesign a public API, rename unrelated symbols, update formatting across untouched files, add features, change error policy, or create a speculative framework “for future reuse.”
+
+### 5. VERIFY after every coherent step
+
+Run the focused characterization tests, then the relevant repository gate. Compare benchmark conditions when applicable; keep a performance claim only when the difference exceeds normal run-to-run noise. Review the diff specifically for contract drift and accidental scope growth.
+
+If a step is neutral or worse for understandability, revert **that step only** using a targeted edit. Never use `git reset --hard`, overwrite the working tree, or discard unrelated user changes. Do not commit automatically.
+
+### 6. EXPLAIN the gain
+
+Report:
+
+- scope simplified;
+- complexity removed, not merely relocated;
+- observable contract preserved;
+- tests/checks/benchmark run and results;
+- anything intentionally left complex and the invariant that justifies it.
+
+“Cleaner” is too vague. Prefer: “removed three mutable states and one duplicate parse; preserved error type/message, insertion order and one-read I/O semantics; 18 focused tests plus full typecheck pass.”
+
+## Stop rule
+
+Stop when another edit would trade one defensible style for another without lowering the number of states, branches, concepts or proof obligations. Readability has diminishing returns. A bounded, verified improvement is done even if neighbouring legacy code remains ugly.
+
+## Anti-patterns
+
+| Smell | Correction |
+|---|---|
+| A failing behaviour is “cleaned up” | Diagnose with `debug`; simplification must not smuggle in a fix. |
+| A read-only review starts editing | Keep verdict work in `review`/`code-review`. |
+| A speed hunch justifies a refactor | `performance` measures first; preserve a benchmark when speed is contractual. |
+| An odd public behaviour is silently normalized | Preserve it until a behaviour change is explicitly authorized. |
+| Cleanup commits, pushes, resets or deploys on its own | These are separate authorized operations; use targeted edits only. |
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/shared/simplify-code/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — simplify-code
+
+The cases distinguish correct-but-complex code from debugging, review, verification, performance and API redesign. The capability case requires an explicit behavioural contract, characterization baseline, one-concept reductions, full evidence and safe worktree handling.

package/skills/shared/simplify-code/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: simplify-code
+
+should_trigger:
+  - prompt: "This parser works and its tests are green, but the nested branches are impossible to follow; simplify it without changing behavior."
+    why: "Correct code needs bounded behaviour-preserving simplification."
+  - prompt: "Simplifica esta función, pero conserva exactamente errores, orden y efectos laterales."
+    why: "Spanish request explicitly names observable contract preservation."
+  - prompt: "The feature is done; now remove the accidental complexity from only the files we changed."
+    why: "Post-feature bounded cleanup is the default scope."
+  - prompt: "Fes el codi menys enginyós i més directe, amb tests de caracterització abans de tocar-lo."
+    why: "Catalan request for characterization-led simplification."
+  - prompt: "Collapse these pass-through wrappers and duplicate state if callers cannot observe a difference."
+    why: "Specific removable complexity with an equivalence condition."
+  - prompt: "Refactor this hot path for clarity, but keep the benchmark and allocation profile within noise."
+    why: "Performance is part of the observable simplification contract."
+
+should_not_trigger:
+  - prompt: "The parser throws on valid quoted values; reproduce the bug and fix it."
+    route_to: debug
+    why: "Behaviour is incorrect, so diagnosis precedes any cleanup."
+  - prompt: "Review this pull request and list correctness issues, but do not edit it."
+    route_to: code-review
+    why: "Read-only spec-less diff judgment."
+  - prompt: "Verify the finished SDD implementation against every acceptance criterion."
+    route_to: verify
+    why: "Evidence gate rather than code editing."
+  - prompt: "The page is slow; profile Core Web Vitals and fix the measured bottleneck."
+    route_to: performance
+    why: "Measured speed work owns the task."
+  - prompt: "Redesign the public API and migrate all callers to the new contract."
+    route_to: api-design
+    why: "The requested behaviour/interface change is not simplification."
+
+capability:
+  - scenario: "Simplify an 80-line configuration parser whose current tests cover the happy path but whose callers depend on comment handling, quoting, numeric conversion, insertion order and ignored malformed lines."
+    must_include:
+      - "Bounds the target and inspects callers, dirty-worktree state, generated code, and explicit protected regions without mutating files to hide content."
+      - "States the observable contract including return shape, ignored input, type conversion, order, errors and side effects."
+      - "Adds characterization cases for uncovered contract edges and records a green baseline before refactoring."
+      - "Removes one source of complexity at a time without adding features, redesigning public APIs, or relocating complexity into speculative abstractions."
+      - "Runs focused tests plus relevant lint/type/build gates after coherent steps and compares a benchmark when performance is contractual."
+      - "Uses targeted edits for a bad step and never resets, auto-commits, pushes, deploys, or discards unrelated changes."