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

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

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# verify.sh — deployment gate. Run inside YOUR project; CI runs the same file (parity).
+#
+# Usage:
+#   bash scripts/verify.sh
+#
+# Checks (each skips with a yellow warning if its tool is missing — never fails on absence):
+#   1. discover Dockerfiles / compose / workflows  (no artifacts -> exit 0)
+#   2. hadolint     each Dockerfile
+#   3. actionlint   .github/workflows
+#   4. trivy config (Dockerfile/compose/IaC misconfig)
+#   5. docker build smoke  (skippable: SKIP_DOCKER_BUILD=1)
+#   6. trivy image  (only if step 5 built an image)
+#   7. hosting config lint  (vercel.json JSON validity — detect-or-skip)
+#   8. summary; exit non-zero only on a real failure
+#
+# Hosting targets (Vercel / Hetzner+Coolify / …) are documented in
+# references/hosting-targets.md. Most are config-light: there is nothing to lint for a
+# Hetzner box or a Coolify resource (state lives in the platform, not the repo). The one
+# repo-local artifact worth a sanity check is vercel.json, and only if it exists.
+#
+# Env: SKIP_DOCKER_BUILD=1 to skip the build smoke; NO_COLOR=1 to disable color.
+#
+# Portability: runs on stock macOS bash 3.2 (no `mapfile`, no bash-4 features) and
+# on CI's bash 5 — that local<->CI parity is the whole point. Arrays are populated
+# without `mapfile` and always pre-initialised so `set -u` can't abort on an empty
+# array under bash 3.2.
+set -euo pipefail
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# bash 3.2 aborts on `"${arr[@]}"` when arr is empty *and* unset under `set -u`.
+# Initialise every array up front and guard expansions with `${arr[@]+...}` so an
+# empty array is never an unbound-variable error. Never use `mapfile` (bash 4+).
+DOCKERFILES=()
+
+if [[ -n "${NO_COLOR:-}" ]]; then YEL=""; GRN=""; RED=""; RST=""
+else YEL=$'\033[33m'; GRN=$'\033[32m'; RED=$'\033[31m'; RST=$'\033[0m'; fi
+warn() { printf '%s[skip]%s %s\n' "$YEL" "$RST" "$*"; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GRN" "$RST" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RST" "$*"; }
+
+FAILED=0
+BUILT_IMAGE=""
+SMOKE_TAG="verify-smoke:local"
+
+# 1. discover
+# Parenthesize the `-name ... -o -name ...` group so the path filter (-not -path)
+# applies to BOTH name patterns — otherwise the second pattern matches vendored or
+# example Dockerfiles and we'd smoke-build the wrong one. Read results with a while
+# loop (bash-3.2-safe; no `mapfile`). NUL-delimited so paths with spaces survive.
+while IFS= read -r -d '' df; do
+  DOCKERFILES+=("$df")
+done < <(find . \
+  \( -path '*/node_modules/*' -o -path '*/vendor/*' -o -path '*/.git/*' \
+     -o -path '*/examples/*' -o -path '*/example/*' -o -path '*/testdata/*' \) -prune \
+  -o \( -name 'Dockerfile' -o -name 'Dockerfile.*' \) -type f -print0 2>/dev/null)
+
+WORKFLOWS_DIR=".github/workflows"
+HAVE_WORKFLOWS=0; [[ -d "$WORKFLOWS_DIR" ]] && HAVE_WORKFLOWS=1
+COMPOSE=$(find . -maxdepth 2 \( -name 'compose*.y*ml' -o -name 'docker-compose*.y*ml' \) 2>/dev/null | head -n1 || true)
+if [[ ${#DOCKERFILES[@]} -eq 0 && $HAVE_WORKFLOWS -eq 0 && -z "$COMPOSE" ]]; then
+  printf 'No Dockerfiles, compose files, or workflows found — nothing to gate.\n'; exit 0
+fi
+
+# 2. hadolint
+if [[ ${#DOCKERFILES[@]} -eq 0 ]]; then
+  warn "no Dockerfile found — skipping Dockerfile lint"
+elif have hadolint; then
+  # `${arr[@]+"${arr[@]}"}` guards the expansion so an empty array is safe under
+  # `set -u` on bash 3.2 (we already know it's non-empty here, but stay consistent).
+  for df in ${DOCKERFILES[@]+"${DOCKERFILES[@]}"}; do
+    if hadolint --failure-threshold warning "$df"; then ok "hadolint $df"
+    else fail "hadolint $df"; FAILED=1; fi
+  done
+else warn "hadolint not installed — skipping Dockerfile lint"; fi
+
+# 3. actionlint
+if [[ $HAVE_WORKFLOWS -eq 1 ]]; then
+  if have actionlint; then
+    if actionlint; then ok "actionlint"; else fail "actionlint"; FAILED=1; fi
+  else warn "actionlint not installed — skipping workflow lint"; fi
+fi
+
+# 4. trivy config
+if have trivy; then
+  if trivy config --exit-code 1 --severity HIGH,CRITICAL .; then ok "trivy config"
+  else fail "trivy config"; FAILED=1; fi
+else warn "trivy not installed — skipping config/image scan"; fi
+
+# 5. docker build smoke
+if [[ -n "${SKIP_DOCKER_BUILD:-}" ]]; then
+  warn "SKIP_DOCKER_BUILD set — skipping build smoke"
+elif have docker && [[ ${#DOCKERFILES[@]} -gt 0 ]]; then
+  DF="${DOCKERFILES[0]}"
+  if DOCKER_BUILDKIT=1 docker build --pull -t "$SMOKE_TAG" -f "$DF" "$(dirname "$DF")"; then
+    ok "docker build $DF"; BUILT_IMAGE="$SMOKE_TAG"
+  else fail "docker build $DF"; FAILED=1; fi
+else warn "docker not available or no Dockerfile — skipping build smoke"; fi
+
+# 6. trivy image (only if we built one)
+if [[ -n "$BUILT_IMAGE" ]]; then
+  if have trivy; then
+    if trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed "$BUILT_IMAGE"; then
+      ok "trivy image $BUILT_IMAGE"
+    else fail "trivy image $BUILT_IMAGE"; FAILED=1; fi
+  else warn "trivy not installed — skipping image scan"; fi
+fi
+
+# 7. hosting config lint — vercel.json JSON validity (detect-or-skip).
+# Only runs if a vercel.json exists. Prefer python3/node: they set a reliable non-zero
+# exit on malformed JSON. jq is the last resort and MUST use `-e` — some jq builds (e.g.
+# Apple's jq-1.6) print a parse error to stderr but still exit 0 without it. If none of
+# the three is installed, skip — never fail on a missing linter.
+VERCEL_JSON=$(find . -maxdepth 2 -name 'vercel.json' -not -path '*/node_modules/*' 2>/dev/null | head -n1 || true)
+if [[ -n "$VERCEL_JSON" ]]; then
+  if have python3; then
+    if python3 -c 'import json,sys; json.load(open(sys.argv[1]))' "$VERCEL_JSON" >/dev/null 2>&1; then
+      ok "vercel.json valid JSON ($VERCEL_JSON)"
+    else fail "vercel.json is not valid JSON ($VERCEL_JSON)"; FAILED=1; fi
+  elif have node; then
+    if node -e 'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"))' "$VERCEL_JSON" >/dev/null 2>&1; then
+      ok "vercel.json valid JSON ($VERCEL_JSON)"
+    else fail "vercel.json is not valid JSON ($VERCEL_JSON)"; FAILED=1; fi
+  elif have jq; then
+    if jq -e . "$VERCEL_JSON" >/dev/null 2>&1; then ok "vercel.json valid JSON ($VERCEL_JSON)"
+    else fail "vercel.json is not valid JSON ($VERCEL_JSON)"; FAILED=1; fi
+  else warn "no python3/node/jq — skipping vercel.json validation"; fi
+fi
+
+# 8. summary
+if [[ $FAILED -eq 0 ]]; then ok "all checks passed (skips are not failures)"
+else fail "one or more checks failed"; fi
+exit "$FAILED"

package/skills/shared/deprecation/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: deprecation
+description: "Use when retiring a public API, feature, integration, service or legacy path without abandoning consumers. Inventories usage, classifies advisory vs compulsory migration, ships compatibility/tooling, assigns owners and gates removal on evidence. NOT live schema expand-contract (`db-migrations`), NOT replacement API design (`api-design`)."
+tags: [deprecation, migration, compatibility, consumer-migration, removal]
+recommends: [api-design, db-migrations, deployment, git-workflow, monitoring]
+profiles: [core, full]
+origin: ai-hub
+---
+
+# deprecation — removal is a consumer migration
+
+Deprecation is not a date in a changelog. It is the controlled transfer of real consumers from an old contract to a supported replacement, followed by evidence that removal no longer breaks anyone important.
+
+This skill owns the cross-consumer program. It delegates the replacement interface to `../api-design/SKILL.md`, live schema mechanics to `../db-migrations/SKILL.md`, release/version mechanics to `../git-workflow/SKILL.md`, and rollout/rollback execution to `../deployment/SKILL.md`.
+
+## The retirement sequence
+
+```text
+INVENTORY → CLASSIFY → ENABLE → NOTIFY → MIGRATE → OBSERVE → REMOVE
+```
+
+### 1. INVENTORY the contract and consumers
+
+Identify:
+
+- exact endpoints, events, schemas, flags, SDK methods, jobs, services and docs being retired;
+- internal and external consumers, owners and contractual notice periods;
+- traffic/usage by consumer, version and operation;
+- data written only by the old path and compatibility obligations;
+- support, reseller or offline consumers invisible to runtime telemetry;
+- current fallback and restoration options.
+
+“No known users” is not an inventory. Query telemetry, code search, dependency graphs, access keys, support records and account owners. Record where visibility is incomplete.
+
+### 2. CLASSIFY the migration
+
+- **Advisory:** the old path remains supported; migration is encouraged for benefit or future-proofing.
+- **Compulsory:** support will end or continued use creates unacceptable security, reliability, legal or operating risk.
+
+Only compulsory migrations justify a removal deadline. State the forcing reason and who has authority to accept exceptions. A deadline should respect contracts, effort and evidence; do not import a universal 30/60/90-day calendar.
+
+### 3. ENABLE migration before announcing removal
+
+The replacement must be usable first:
+
+- compatible contract or adapter where feasible;
+- migration guide with old → new mappings and changed semantics;
+- tooling, codemod, SDK or dual-write/read path for repetitive work;
+- test/sandbox path and representative examples;
+- rollback or temporary compatibility mode;
+- ownership for data backfill and reconciliation.
+
+For database changes, use expand → backfill → switch reads/writes → contract through `../db-migrations/SKILL.md`. Do not promise a generic `down` migration for irreversible data transformations; prove the actual restoration/reconciliation path instead.
+
+### 4. NOTIFY through machine and human channels
+
+Use the channels the consumer will actually see: response headers, compiler/runtime warnings, API dashboards, release notes, direct account contact, support and status communications. A warning must name the replacement, action, consequence, evidence link and earliest removal condition.
+
+Versioned public APIs should follow their compatibility policy and SemVer where it applies. Machine warnings without a migration guide create noise; an email without runtime identification misses the real owner. Use both when the surface permits.
+
+### 5. MIGRATE with explicit ownership
+
+The team introducing the deprecation owns the common migration path: inventory, docs, automation, default internal consumers and escalation. Consumer teams own domain-specific acceptance and scheduling, not rediscovering the replacement.
+
+Track each consumer as: uncontacted, acknowledged, testing, migrated, exempted with expiry, unreachable, or blocked. Give blockers an owner and next action. Reseller-managed or unknown consumers need a separate reachability plan; do not silently exclude them from the denominator.
+
+### 6. OBSERVE real cutover
+
+Instrument old-path usage by consumer and operation, plus errors on the replacement. Where risk warrants it, shadow or dual-run and compare results before switching authority. Dashboards must distinguish legitimate residual traffic, retries and synthetic probes from active dependency.
+
+Define the removal gate up front, for example:
+
+- no non-exempt production use for a representative window;
+- every contractually covered consumer notified and migrated or explicitly exempted;
+- replacement error/SLO health acceptable;
+- rollback/compatibility response tested;
+- support, docs and on-call ready for late discoveries.
+
+The representative window depends on consumer cadence. A monthly batch needs more than a quiet week.
+
+### 7. REMOVE in a reversible order
+
+Disable entry first, observe, then delete implementation, flags, compatibility code, credentials, dashboards and documentation that exist only for the old path. Preserve audit/history records. Update dependency and ownership maps so the retired system does not remain a zombie operational obligation.
+
+If unexpected material traffic appears, re-enable the bounded compatibility path and return to migration. Do not restore an undocumented permanent fork.
+
+## Deprecation record
+
+```markdown
+# Deprecation — <old> → <replacement>
+
+## Classification and reason
+Advisory/compulsory · forcing reason · authority · notice constraints.
+
+## Inventory
+Contracts · consumers · owners · baseline usage · visibility gaps.
+
+## Migration path
+Compatibility · guide/tooling · data plan · rollback/reconciliation.
+
+## Consumer ledger
+Consumer · state · owner · last old-path use · blocker/exception expiry.
+
+## Removal gate and evidence
+Window · zero-use evidence · replacement health · support/rollback readiness.
+
+## Removal log
+Disabled · observed · deleted · residual artifacts.
+```
+
+## Anti-patterns
+
+| Smell | Correction |
+|---|---|
+| The calendar arrives while material traffic remains | Hold removal; the gate is evidence, not date alone. |
+| Every consumer writes the same adapter | The deprecating team owns common tooling and default migrations. |
+| Internal code search proves external zero-use | Combine runtime identity, contracts, support and account ownership. |
+| Temporary compatibility has no owner or expiry | Track an explicit exception with accountable owner and end condition. |
+| Deprecation silently grants deploy authority | Keep live rollout/rollback explicit through `deployment`. |
+
+## 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/deprecation/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — deprecation
+
+Routing separates the consumer-migration program from schema mechanics, replacement API design, Git versioning, deployment and ADR authoring. The capability case requires consumer completeness, contractual timing, migration enablement, multichannel notice, measured cutover and a reversible removal sequence.

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

@@ -0,0 +1,42 @@
+skill: deprecation
+
+should_trigger:
+  - prompt: "We need to retire the v1 public API without stranding 200 external consumers."
+    why: "Public contract retirement with consumer migration is the core workflow."
+  - prompt: "Planifica la retirada del login legado: inventario, avisos, migración, telemetría y puerta de borrado."
+    why: "Spanish request names the complete deprecation program."
+  - prompt: "This SDK method is deprecated; ship a codemod and prove no supported clients still call it before removal."
+    why: "Migration tooling plus measured zero-use gate."
+  - prompt: "Hem de retirar una integració antiga, però alguns clients només executen un batch mensual."
+    why: "Catalan case where the observation window must match consumer cadence."
+  - prompt: "Classify this migration as advisory or compulsory and define who can grant expiring exceptions."
+    why: "The forcing model and exception authority are deprecation decisions."
+  - prompt: "Track every consumer from uncontacted to migrated and gate deletion on replacement health and tested rollback."
+    why: "Consumer ledger and evidence-based removal gate."
+
+should_not_trigger:
+  - prompt: "Add a nullable column, backfill ten million rows in batches, then enforce NOT NULL without downtime."
+    route_to: db-migrations
+    why: "Concrete live schema expand-contract mechanics."
+  - prompt: "Design the v2 API resources, error envelope, pagination and OpenAPI contract."
+    route_to: api-design
+    why: "Replacement interface design precedes the migration program."
+  - prompt: "Choose the SemVer tag and write the Conventional Commit for this breaking release."
+    route_to: git-workflow
+    why: "Version and Git release conventions."
+  - prompt: "Deploy the compatibility adapter to production with a healthcheck and rollback command."
+    route_to: deployment
+    why: "Authorized live rollout execution."
+  - prompt: "Write an ADR explaining why the team chose v2 over extending v1."
+    route_to: decision-records
+    why: "Durable decision rationale, not consumer migration execution."
+
+capability:
+  - scenario: "Deprecate a v1 REST API used by 200 organizations; v2 is live, current telemetry sees 173 active keys, twelve accounts are reseller-managed, and the largest contract requires 90 days' notice."
+    must_include:
+      - "Inventories exact v1 surfaces, all consumer classes, owners, contractual notice, baseline usage, data obligations, and telemetry/reachability gaps."
+      - "Classifies advisory versus compulsory with a forcing reason, authority, and expiring exception policy rather than an arbitrary universal timeline."
+      - "Makes v2 usable first through compatibility, guide, tooling/SDK, test path, data reconciliation, and a real restoration strategy."
+      - "Uses both machine-visible warnings and direct human channels, including a plan for reseller-managed and unreachable consumers."
+      - "Maintains a per-consumer migration ledger and assigns common migration work to the deprecating team rather than every consumer."
+      - "Defines a representative zero-use and replacement-health removal gate, then disables, observes, and deletes in reversible order."

package/skills/shared/design/IMPECCABLE-LICENSE.txt

@@ -0,0 +1,191 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on
+      behalf of the copyright owner. For the purposes of this definition,
+      "submitted" means any form of electronic, verbal, or written
+      communication sent to the Licensor or its representatives, including
+      but not limited to communication on electronic mailing lists, source
+      code control systems, and issue tracking systems that are managed by,
+      or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Paul Bakaus
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/skills/shared/design/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: design
+description: "Use when designing, redesigning, restyling or reviewing a web page or app screen (landing, product site, portfolio, dashboard, docs) or when a UI looks generic or AI-made. Deals a researched direction, takes the idea from the subject, uses real pictures, proves it in a browser. NOT the words (landing-copy), NOT component state (ui-engineering)."
+tags: [design, ui, ux, landing, dashboard, frontend, taste]
+recommends: [landing-copy, ui-engineering, accessibility, brand-identity, nextjs]
+profiles: [minimal, core, full]
+origin: ai-hub
+---
+
+# design
+
+A model left to design picks the average of every page it has seen. This skill takes those
+decisions away from the model and makes it look at what it built.
+
+- **A script deals the direction.** You choose among researched directions; you never invent one.
+- **The idea comes from the subject,** not from the category.
+- **Real pictures and full content,** never empty space dressed as restraint.
+- **A real browser measures the page** at three widths. A `FAIL` means it is not done.
+- **You look at the screenshots,** fix the worst, and look again.
+
+The engine is [taste-skill](https://github.com/Leonxlnx/taste-skill) (MIT), shipped unmodified in
+`engine/`. The modes, the fresh review and the design record adapt
+[impeccable](https://github.com/pbakaus/impeccable) by Paul Bakaus (Apache-2.0). Credits and what
+changed: `THIRD_PARTY.md`.
+
+## 0. Name the surface and its mode
+
+Decide before anything else. The mode is chosen from the surface, not from the product.
+
+| Mode | The visitor… | Surfaces | Run |
+| --- | --- | --- | --- |
+| **Persuade** | decides and acts | landing, marketing, product site, pricing, event, local business | `engine/RUN.md`, the page run |
+| **Experience** | is inside the work | portfolio, gallery, showcase | `engine/RUN.md`, the page run |
+| **Operate** | completes a task | dashboard, admin, settings, inbox, editor | `engine/references/app-screens.md` |
+| **Read** | understands something | docs, guide, article, changelog | the page run, under the Read rules |
+
+What each mode allows and refuses: [references/modes.md](references/modes.md).
+
+## 1. Brand first, when there is one
+
+Look for an existing identity before dealing anything: `02-DOCS/wiki/brand/`, a `DESIGN.md` in the
+repo, or a coherent identity already in the code. If one exists, its colours and faces win: pass
+`--keep palette,type` to the draw and take only the composition. If none exists, do not stop to
+interview the user about brand; the draw is how a starting point is made.
+
+## 2. Run the engine
+
+Follow [`engine/RUN.md`](engine/RUN.md) step by step. Read it whole before starting. In its commands,
+`<skill>` is this skill's `engine/` folder. Nothing in it is optional:
+
+1. Brief and inventory (eight to twelve things only this client has).
+2. The argument: one claim per section; no claim, no section.
+3. Deal three directions with `draw.mjs`, choose one against the inventory, write why.
+4. The idea sentence, the competitor test, and one live thing.
+5. The whole copy deck before markup. Never invent proof: customers, quotes, numbers, logos.
+6. Build still: tokens, hero, sections, at least four real pictures (`assets.mjs`), the live thing.
+7. Gate: `lint.mjs`, then `inspect.mjs` at 1440, 768 and 390. Zero `FAIL`.
+8. Look: open every screenshot, critique with `engine/references/critique.md`. At most three rounds.
+9. Move: the motion layer, then inspect again.
+
+For a single component or section inside an existing design, skip the draw, inherit the system,
+and still run the gate.
+
+## 3. Fresh review
+
+The builder believes its own page. When the gate passes, hand the screenshots to a reviewer with no
+history of this conversation (a fresh subagent where the harness has one). It returns one of four
+words: `recapture`, `rebuild`, `fix` or `ship`. Act on the word. The packet and the checks:
+[references/finish-review.md](references/finish-review.md).
+
+## 4. Record the system
+
+A new or replaced visual system is written to `DESIGN.md` at the project root, from what was built,
+so later edits keep the look. Format: [references/design-md.md](references/design-md.md). Extending
+an existing surface does not rewrite it.
+
+## When the browser cannot run
+
+`inspect.mjs` and `scenes.mjs` need Node 22+ and an installed Chrome, Edge or Chromium. Without them:
+run `lint.mjs` (Node 18+), take screenshots with any browser tool you have, critique those, and
+write in the report: **"inspector not run: <reason>"**. Never report a gate as passed that did not
+run. Without network, draw the pictures and say the open collections could not be searched.
+
+## Report
+
+Say briefly: the surface and mode; the direction dealt (name and seed) and any redraw with its
+reason; the idea sentence and the live thing; the inspector result per width, or that it did not
+run; the reviewer's word; every found picture with its credit; sample content to replace before
+launch. Do not claim a check you did not run.
+
+## Hand-offs
+
+- The words on a conversion page → `../landing-copy/SKILL.md`.
+- Component boundaries, state, loading and error behaviour → `../ui-engineering/SKILL.md`.
+- WCAG conformance work → `../accessibility/SKILL.md`.
+- A full brand system (logo, print colours, usage rules) → `../brand-identity/SKILL.md`.
+- The App Router build → `../nextjs/SKILL.md`.
+- A hero that is a pre-rendered camera flight in video, scrubbed by scroll → `../scroll-film/SKILL.md`.
+
+## Files
+
+| File | What |
+| --- | --- |
+| `engine/RUN.md` | The run, the house rules and the laws of the craft. |
+| `engine/references/` | App screens, type, colour, layout, imagery, motion, scenes, copy, critique, tells, research. |
+| `engine/scripts/` | `draw`, `assets`, `lint`, `inspect`, `scenes`. |
+| `engine/library/` | The data the draw reads. Never read it whole; use the script. |
+| `engine/UPSTREAM.json` | Which upstream versions are shipped here. |
+| [references/modes.md](references/modes.md) | The four modes. |
+| [references/finish-review.md](references/finish-review.md) | The fresh reviewer. |
+| [references/design-md.md](references/design-md.md) | The `DESIGN.md` record. |

package/skills/shared/design/THIRD_PARTY.md

@@ -0,0 +1,26 @@
+# Third-party work in this skill
+
+## taste-skill: the engine
+
+- **Source:** https://github.com/Leonxlnx/taste-skill (`skills/taste-skill`). The exact commit and
+  version shipped are in `engine/UPSTREAM.json`.
+- **Licence:** MIT, Copyright (c) 2026 Leonxlnx. Full text: `engine/LICENSE`.
+- **What is here:** `engine/scripts/`, `engine/library/`, `engine/assets/` and
+  `engine/references/`, copied unmodified. `engine/RUN.md` is the upstream `SKILL.md` with its YAML
+  front matter removed so it is not discovered as a second skill; the text is unchanged.
+- **Data inside:** `library/photos.json` lists Lorem Picsum IDs (photographs from Unsplash, under
+  the Unsplash licence); `library/sites.json` describes studied sites from One Page Love and
+  Awwwards and copies none of them; `library/type.json` links Fontshare and Google Fonts.
+- **Updating:** `npm run design:upstream` reports a newer upstream version. Bringing it in means
+  copying a reviewed checkout over `engine/` (`--sync`), never an automatic download.
+
+## impeccable: modes, fresh review, the design record
+
+- **Source:** https://github.com/pbakaus/impeccable by Paul Bakaus. Version in `engine/UPSTREAM.json`.
+- **Licence:** Apache-2.0, Copyright 2025 Paul Bakaus. Full text: `IMPECCABLE-LICENSE.txt`.
+- **What is here:** no code. `references/modes.md`, `references/finish-review.md` and
+  `references/design-md.md` are adaptations of impeccable's `reference/mode-*.md`,
+  `agents/impeccable-finish-reviewer.md` and `reference/document.md`. **Modified:** rewritten,
+  shortened, and pointed at taste-skill's inspector and screenshots instead of impeccable's
+  detector, comps and build phases.
+- impeccable's NOTICE concerns its iOS and Android references, which are not used here.

package/skills/shared/design/engine/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonxlnx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.