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

package/presets/generic-ts/preset.yaml

@@ -0,0 +1,44 @@
+id: generic-ts
+version: 1
+extends: base
+description: TypeScript repository with npm-compatible scripts and a standard test runner.
+detect:
+  files:
+    - package.json
+    - tsconfig.json
+  dependencies:
+    - typescript
+stack:
+  languages:
+    - typescript
+  packageManager: npm
+commands:
+  install: npm ci
+  build: npm run build
+  test: npm test
+  typecheck: npx tsc --noEmit
+  lint: npm run lint
+  verify: npm test
+paths:
+  source:
+    - src
+  tests:
+    - tests
+  docs:
+    - docs
+policy:
+  trunk: auto
+  guardMode: shadow
+  worktrees: true
+  optOuts: []
+rules: []
+agents:
+  publish:
+    - spec-author
+    - implementer-frontend
+    - implementer-backend
+    - reviewer-architecture
+    - reviewer-tests
+    - explorer-domain
+skills:
+  publish: []

package/presets/python/preset.yaml

@@ -0,0 +1,45 @@
+id: python
+version: 1
+extends: base
+description: Python project with pytest, mypy and ruff.
+detect:
+  files:
+    - pyproject.toml
+    - requirements.txt
+  dependencies:
+    - pytest
+stack:
+  languages:
+    - python
+  packageManager: pip
+commands:
+  install: pip install -e .
+  build: python -m build
+  test: pytest
+  typecheck: mypy .
+  lint: ruff check .
+  verify: pytest
+paths:
+  source:
+    - src
+  tests:
+    - tests
+  docs:
+    - docs
+policy:
+  trunk: auto
+  guardMode: shadow
+  worktrees: true
+  optOuts: []
+rules:
+  - rules/python.md
+agents:
+  publish:
+    - spec-author
+    - implementer-frontend
+    - implementer-backend
+    - reviewer-architecture
+    - reviewer-tests
+    - explorer-domain
+skills:
+  publish: []

package/presets/python/rules/python.md

@@ -0,0 +1,10 @@
+# Python rules
+
+- Type hints on every public function and module boundary.
+- `pytest` for tests; fixtures over global state.
+- `mypy` and `ruff` are part of the verification command.
+- No bare `except`, no mutable default arguments, no `print` in library code.
+- Use the `src/` layout when the project is a package; keep import roots explicit.
+- Prefer `pathlib` over string paths.
+- Run `ruff check .`, `mypy .` and `pytest` before marking a task complete.
+- Never commit virtual environments, `.pyc` files or local credentials.

package/rules/skill-quality/skill-behavior-rubric.md

@@ -0,0 +1,63 @@
+# skill-behavior-rubric — how a skill's OUTPUT is graded (the behavioral gate)
+
+Sibling of `skill-rubric.md`. That one scores the skill as a **document**; this one scores what
+the skill **produces when run**. A skill ships only if BOTH gates are green.
+
+## How the behavioral eval works
+
+For each `capability` scenario in the skill's `evals/cases.yaml`, the engine
+(`scripts/skill-behavior-eval.workflow.js`) runs the scenario twice — once with the skill's
+`SKILL.md` injected (**treatment**), once without it (**baseline**) — and an independent, blind
+grader scores both outputs. The grader never learns which output used the skill; outputs are
+presented as X and Y, their slot varied by scenario index parity so a "first output" bias can't
+systematically favor the skill.
+
+## What the grader returns (per output)
+
+1. **must_include coverage.** For each `must_include` item: `satisfied` true/false **and a quoted
+   line** from the output that satisfies it. Evidence, not vibes. If unsure, mark unmet.
+2. **Quality, four axes 0-10:** `completeness`, `actionability`, `correctness`, `grounding`
+   (no invented facts / APIs / numbers).
+
+The grader returns raw signals only. It does **not** compute the score — that keeps the number
+deterministic and auditable.
+
+## Orientation signal (the brújula)
+
+User-facing, conversational skills should keep the user oriented. When a skill's capability scenario ends a turn the user acts on, the grader expects the output to:
+
+- **Situate** the user (where they are / what is built vs missing).
+- **Teach the why**, in the register `technical_level` sets (technical, or with analogies) — the voice is `orient`'s.
+- **Propose a next step phrased as a question** — never end in seco.
+
+Encode this as `must_include` items in those skills' capability scenarios (see `skills/orient/evals/cases.yaml` for the canonical pattern). It scores through the existing coverage axis — no separate formula. Skills that own a purely mechanical task (lint, a single rename) are exempt and should not be penalized.
+
+## How signals become the /10 (computed by `scripts/lib/behavior-score.js`)
+
+- Per output: `score = 0.6 × (satisfied / total × 10) + 0.4 × mean(quality axes)`.
+  Empty output → 0. No checklist → quality only.
+- Per scenario: `absolute` = treatment's score; `delta` = treatment − baseline.
+- Per skill: `absolute_score` = mean of absolutes; `lift` = mean of deltas.
+
+## The gate (both required)
+
+- `absolute_score ≥ 8.5` — the skill genuinely produces a good result.
+- `lift ≥ +1.0` — the skill measurably beats no-skill. `lift ≤ 0` is an automatic FAIL even at a
+  high absolute: the skill adds nothing the bare agent didn't already do.
+
+## Anti-gaming
+
+- Independent, blind grader; default-skeptical on coverage.
+- Errors fail closed: a scenario whose run or grade errored is dropped; if all drop, FAIL.
+- A skill with no `capability` scenario cannot be behaviorally evaluated → FAIL until one exists.
+- v1 uses a single grader per scenario. Upgrade path: N=3 graders, majority vote.
+
+## Running it
+
+```
+# 1) execute + grade — invoke the Workflow tool with the engine script and the skill id:
+#      scriptPath: scripts/skill-behavior-eval.workflow.js   args: "<skill-id>"
+#    capture the workflow's returned object to a JSON file (e.g. /tmp/<skill>-raw.json)
+# 2) score + gate (exit 0 pass / 1 fail):
+node scripts/skill-behavior-eval.js --score /tmp/<skill>-raw.json
+```

package/rules/skill-quality/skill-harden-rubric.md

@@ -0,0 +1,102 @@
+# skill-harden-rubric — how the fix-loop diagnoses and guards a fix
+
+The `skill-harden` workflow turns a FAILING behavioral score into edits, without gaming the eval.
+These are the rules its agents follow.
+
+The three guards below — **diff judge**, **hold-out**, **Generalization gate** — are mandatory *and*
+mechanised: `tests/harden-generalization-gate.test.js` asserts, for each of those three, that the
+loop implements what this file promises. **Adding a fourth guard here means adding its pair to that
+test**; a guard documented but unchecked gives the safety without the protection, which is the
+failure mode this repo has now hit ten times (constitution P2).
+
+## Diagnosis (skill-fault vs eval-fault vs capability)
+
+Given the failing `mustFix`, both A/B outputs, and the grader's per-item evidence, decide the FAULT:
+
+- **skill** — the treatment output genuinely misses real capability (weak method, missing depth,
+  no concrete output). Fix the SKILL.md body and/or references/.
+- **eval** — the failure is the eval's, not the skill's. Two known biases:
+  1. **Self-describing scenario** — the `scenario` text enumerates its own `must_include`, so a
+     bare agent gets the same guidance the skill would give and the lift collapses artificially.
+  2. **Phantom-context must_include** — an item demands workspace artifacts the isolated eval
+     agent cannot have (e.g. `user-profile.md`, a real sibling skill to delegate to), capping the
+     absolute unfairly.
+- **capability** — the gap cannot be closed by words in a skill body. It needs an **executable
+  capability**: something that fires on a real execution event and returns to the agent information
+  it cannot obtain on its own — a hook, a script, a tool, a sub-agent. Advice that merely tells the
+  agent to remember something is **not** a capability: it is not anchored to any observable event, so
+  it can fire when it should not and stay silent when it should not.
+
+This loop can only ever write **guidance** (SKILL.md, references/). So `capability` is not a fix
+route, it is the honest exit: the loop edits nothing, names the missing capability and the surface it
+would live on, and stops. Writing a paragraph that pretends to cover a missing capability raises the
+score without the capability existing — the worst outcome available.
+
+A `capability` verdict **must name** the capability and its surface. One that cannot is an excuse,
+not a diagnosis → choose `skill`.
+
+Default to **skill** when unsure: blaming the eval or the surface area is the easier, less honest path.
+
+## The Generalization gate (ex-ante — it binds before the edit is written)
+
+This gate governs the **content** of every line the fixer writes, and it travels **in the fixer's own
+instruction**, not in a review afterwards. Writing freely and reverting later burns the round, and the
+loop only has two.
+
+Everything added to a skill is global context that will apply to cases the skill has never seen. So:
+
+- **Allowed:** a reusable criterion that carries its own **applicability condition** — something the
+  agent can evaluate on a case it has never encountered.
+- **Banned outright:** identifiers or titles from the eval scenario; names of its files, symbols or
+  fixtures; rules that branch on its specific data; and reciting the finding as if it were a rule
+  ("the last round showed X needs Y" — that is an answer, not a criterion).
+
+**Litmus test, before every line:** *would this still help on a case in this domain I have never
+seen?* If no → rewrite it as a criterion, or drop it. Not knowledge → not in the skill.
+
+Why ex-ante and not only as review: moving this constraint from after-the-edit to
+before-the-edit is what buys generalization cheaply. The measured version of this result — plus the
+warning that richer feedback **without** this gate makes held-out performance *worse* — is in
+[HarnessCompass](https://arxiv.org/abs/2608.01918); the reasoning it drove is recorded in
+`02-DOCS/wiki/sdd/specs/generalization-gate.md`.
+
+## Eval-fix guard (independent judge)
+
+An eval edit ships ONLY if a judge certifies it corrects one of the two biases above and does NOT
+lower the bar — i.e. it makes the scenario less self-describing or removes a phantom-context item,
+but never deletes a legitimate quality criterion to make a weak skill pass. Rejected → treat as a
+skill-fault this round.
+
+## Skill-fix guards (both required)
+
+1. **Diff judge.** Read the SKILL.md/references diff and check BOTH: does it add genuine capability
+   (method, decision rules, concrete guidance) rather than echoing the `must_include` wording into
+   the body? *and* does every added line survive the Generalization gate above? Fail either → revert
+   the edit; it is not a fix.
+2. **Hold-out.** Re-score the EDITED skill on a FRESH scenario from its domain that the fixer never
+   saw. A real improvement generalizes; a memorized one does not.
+   - The eval engine runs every scenario with **and** without the skill, so the fresh scenario
+     already carries its own lift. No pre-fix baseline is needed.
+   - The verdict is computed by `node scripts/skill-behavior-eval.js --holdout <raw.json>` — a
+     comparison of numbers, deterministic and reproducible, never an agent's opinion (P1). Exit 0
+     passes, exit 1 blocks.
+   - **Blocks on `lift <= 0`** (`regression`): on unseen work the edited skill does not beat the bare
+     agent, so the edit did not transfer. Also blocks when the fresh scenario could not be run or
+     graded (`indeterminate`) — failing closed, because an unverified edit is not a verified one.
+   - The bar is deliberately **not** the main gate's `lift >= 1.0`: one fresh scenario graded once is
+     noisy, so only the unambiguous signal acts. Upgrade path if it proves too noisy in practice:
+     N=3 fresh scenarios, majority.
+   - **A block reverts the edit.** The round produced nothing and is recorded with its reason.
+
+## Stopping & honesty
+
+- Max 2 rounds. On give-up, report the honest final score and a recommendation — never a faked pass.
+- **A main-gate pass whose last surviving edit failed the hold-out does not commit.** It is a fix
+  tuned to the cases it was measured against; the loop reverts it and reports why. Conservative on
+  purpose: a lost commit costs one re-run, a certified overfit costs the catalog.
+- A `capability` verdict never commits either: it returns the missing capability and its surface, and
+  routes the work to `specify`.
+- Every non-commit says which condition failed, in the returned result. A denial without its exit is
+  abandonment (P6).
+- Persistent lift-fail at a high absolute → recommend deprecate/merge: the skill does not justify
+  its own existence.

package/rules/skill-quality/skill-migration-brief.md

@@ -0,0 +1,200 @@
+# skill-migration-brief — how to move one skill to the Claude-5-era rubric
+
+This is the working brief for the catalog-wide migration. One agent, one skill, one worktree, one
+branch, one PR. `scripts/skill-rubric.md` is the spec; this is how to apply it to an existing skill.
+
+## Why this exists
+
+Anthropic's *The new rules of context engineering for Claude 5 generation models* (Jul 2026) reports
+that >80% of Claude Code's system prompt was removed with no measurable eval loss, and names the
+patterns that stopped paying: **repeating yourself across layers**, **over-constraining with rules
+where judgment suffices**, and **enumerating examples where an expressive interface would do**.
+
+Applied here: a skill's `description` is in context on **every turn it is installed**, invoked or
+not. Across 257 skills that was 207 KB. The body is loaded when the skill fires. Both are paid for
+by every user, so length is a cost, never a credit.
+
+## The pass
+
+1. `git checkout -b skill/<id>`
+2. Read `scripts/skill-rubric.md`, then `skills/<id>/SKILL.md`.
+
+### The description
+
+Shape: **what it does · when to use it · an explicit `NOT <x> (that is \`sibling\`)` boundary.**
+
+- Delete any `Triggers: '…', '…'` phrase list. The model matches by meaning; keyword lists in three
+  languages are pure per-turn cost, and the body usually instructs semantic matching right next to
+  them — a self-contradiction.
+- Name a **real** sibling in the boundary. Verify it exists under `skills/`.
+- Target ≤350 chars. Hard limit 1024 (schema-enforced). Third person, opens with "Use when/to".
+- The test is **discrimination, not coverage**: could a reader choose this skill over its nearest
+  sibling from the description alone?
+
+### The body
+
+The goal is the smallest body that still routes correctly. 400 lines is a ceiling; there is no floor.
+
+**Remove:**
+
+- Rule banks that restate the flow — "Iron rules (non-negotiable)", "Rationalizations — STOP".
+  A rule worth keeping moves next to the step it governs, and says *why* it is absolute instead of
+  shouting NON-NEGOTIABLE. A rule in an appendix is skimmed; a rule in context is followed.
+- Re-teaching of what another skill owns. The register (`technical_level` in the profile, set by `init`) and
+  the voice that applies it belong to `orient`; the SDD method belongs to `sdd`. Read the profile and point; do not restate, or the two drift apart.
+- "When to use" sections that restate the description, and trailing reference indexes whose links
+  already appear inline at point of use.
+
+**Keep — these are not padding:**
+
+- The **anti-patterns table**. The rubric requires one, and it is a different animal from a
+  rationalization table: it names concrete failure modes, not rules already stated above it.
+
+  **The hybrid case, which is common:** a table titled something like *"Anti-patterns /
+  rationalizations — STOP"*, with an *Excuse → Reality* framing. Do not delete it and do not leave
+  it as-is. **Keep every row, re-column it to `Anti-pattern | Do instead`, and drop the STOP /
+  excuse framing.** The rows are the value; the borrowed urgency wrapper is what dimension 7
+  forbids. Handling this the same way everywhere is what keeps the catalog consistent — deleting it
+  in one skill and keeping it in the next is worse than either choice applied uniformly.
+- Decision tables where the flow genuinely branches.
+- Tables specific to *this* skill's phase (e.g. what to show at each checkpoint) — that is not the
+  retired verbosity levels.
+- Worked bad/good pairs that teach judgment by demonstration.
+- Result-envelope blocks, chain position, and output contracts where they already exist. Do **not**
+  add one that was never there: that is a content change, not a format change.
+
+**Invariant:** every file under `skills/<id>/references/` must be linked from the body. An unlinked
+reference is never loaded, so it is dead weight in the package. Folding a tail index into inline
+mentions is fine — the link just has to survive. `scripts/`, `evals/` and `assets/` need no link.
+
+**Preserve substance exactly.** This is a context-engineering pass, not a content rewrite. Do not
+change recommendations, versions, commands, figures, or add claims.
+
+## Verify
+
+Your worktree has **no `node_modules`**, so:
+
+- Run: `bash scripts/eval-lint.sh 2>&1 | grep -i '^<id>'` → must report PASS.
+- Check the description length and that every `references/` file is linked.
+- Do **not** run `npm test` or `npm run validate` — they need dependencies you do not have. The
+  orchestrator runs them once, globally, after merge.
+- Do **not** edit `manifest.json`. It is derived, and parallel edits from hundreds of agents would
+  all conflict on the same lines. The orchestrator regenerates it once at the end.
+
+## Ship
+
+Commit only `skills/<id>/`. Subject `refactor(<id>): <what you actually did>`. The body says what you
+removed **and why**, and — just as important — what you deliberately **kept** and why.
+
+**Authorship belongs to Daner Alejandro Salazar Colorado; never attribute a commit to an AI.** No `Co-Authored-By` for any AI, no "Generated with Claude Code"
+footer, nothing attributing the work to a tool — in the commit *or* the PR body. This is the hard
+rule the `ship` skill enforces (`skills/ship/SKILL.md`), and it applies to this migration like
+everything else in the repo. Verify before pushing:
+
+```bash
+git log -1 --format='%b' | grep -iE 'co-authored-by.*(claude|anthropic|ai)|generated with|claude code' \
+  && echo "AUTHORSHIP VIOLATION — strip it" || echo "authorship clean"
+```
+
+Then `git push -u origin skill/<id>` and `gh pr create`. The PR body carries before/after description
+chars, before/after body bytes, what went, what stayed, and the eval-lint result — and no AI
+attribution line.
+
+## Judgment
+
+If the skill already meets the rubric, **say so and change only the description.** A small honest
+diff beats a large invented one. Several skills in the pilot needed 5-line diffs; that is a good
+outcome, not a failed pass. Never pad, and never cut substance to hit a number.
+
+---
+
+# For the orchestrator
+
+Everything above is for the agent doing one skill. This half is for whoever is driving the fleet.
+
+## Resuming, from nothing
+
+There is no state file to keep in sync, on purpose. **The content is the ledger** — a migrated skill
+no longer carries a `Triggers:` list in its description:
+
+```bash
+node -e "const fs=require('fs');const out=[];for(const d of fs.readdirSync('skills')){const p='skills/'+d+'/SKILL.md';if(!fs.existsSync(p))continue;const m=/^---\n([\s\S]*?)\n---/.exec(fs.readFileSync(p,'utf8'));if(m&&/Triggers:/i.test(m[1]))out.push(d)}console.log(out.join('\n'))"
+```
+
+So a cold session resumes with: *read this brief, run that, launch one agent per remaining skill in
+its own worktree.* Nothing from any previous conversation is required.
+
+**An earlier version of this section said the remote `skill/*` branches were the ledger. They are
+not, and the failure is instructive**: once integration PRs started merging with `--delete-branch`,
+the branches for finished skills vanished, so a branch-based check re-offered work that was already
+on main — and an agent duly re-migrated `harness` a second time before anyone noticed. The
+instruction was true when written and was invalidated by a later change to the merge flow, with
+nothing to catch the drift. That is the same failure this whole migration keeps finding in the
+catalog; the brief was not exempt from it. Prefer a check against the artifact over a check against
+bookkeeping that something else can quietly change.
+
+## Order: by profile, not alphabetically
+
+A skill's `description` is in context for everyone who installs it, so migrate by blast radius:
+
+1. `minimal` profile — in every ai-hub install.
+2. `core` profile — the default install (the SDD chain plus the control plane).
+3. High-install stack skills — `nextjs`, `react`, `fastapi`, `postgresdb`, `design`, `typescript`,
+   `python`, `go`, `flutter`, `secure-coding`, `deployment`.
+4. Everything else.
+
+If a run is cut short, this ordering means the part that was finished is the part that everyone pays for.
+
+## Sharp edges (each one cost a real mistake)
+
+- **`manifest.json` is derived.** Agents must never touch it — hundreds of parallel edits collide on
+  the same lines. Regenerate once, centrally, with `npm run manifest` after merging.
+- **A fresh worktree has no `node_modules`** (it is gitignored, so it is not checked out). `npm test`
+  and `npm run validate` cannot run there. `scripts/eval-lint.sh` can — it uses python3.
+- **Result-envelope blocks are asymmetric.** `specify`, `tasks`, `implement`, `verify`, `ship`,
+  `parallel` and `sdd` have one; `plan`, `analyze`, `clarify`, `constitution`, `review` and `debug`
+  do not. Tell each agent which case it is in, or it will helpfully invent one.
+- **`author-skill` is special.** It teaches how to write skills, so it documented the *old*
+  conventions. There, rewriting the guidance IS the migration — and the change has to reach its
+  `references/` and `evals/`, which graded produced skills against the old rubric.
+- **Short ids break greps.** `go`, `rag`, `php` match half of `eval-lint`'s output. Give those agents
+  an anchored pattern (`grep -E '^go +'`).
+- **Compound bash commands are denied whole.** The `ship-guard` hook rejects the entire call if any
+  part matches `git checkout main`, so a chained `commit && push && checkout main` runs *nothing*.
+  Split them.
+- **The id `parallel` is unusable in a git command.** A sandbox guard aimed at GNU `parallel` matches
+  the substring, so `git checkout -b skill/parallel` is refused. That skill's branch has to be
+  created from the pushed commit with `gh api` instead. Any future id containing a blocked tool name
+  will behave the same way.
+
+## Content problems found while migrating — do NOT fix them in a format pass
+
+Agents surfaced these and correctly left them alone. They need their own change:
+
+- `sdd` claims every phase ends with a parseable envelope; six phases have none (see above).
+- **`evals/cases.yaml` files carry stale claims about what the catalog contains, in both
+  directions.** Three agents hit this independently: `course-storytelling` routes a negative to
+  `deep-research`, which does not exist; `flutter` routes its Compose/SwiftUI negatives to `"none"`
+  on the grounds those skills are "not in this catalog", though `compose-multiplatform` and
+  `swift-ios` now are; `postgresdb` said the same of ORM traps, stale since `prisma-orm` and
+  `drizzle-orm` shipped. This drifts every time the catalog grows.
+
+  The root cause is that `eval-lint` does not actually verify a `route_to` names a real skill,
+  even though the rubric lists exactly that as a deterministic gate — so the gate is decorative.
+  (The 1024-char description limit had the same problem; that one is now enforced in
+  `schema/frontmatter.schema.json`.) Fixing the linter is worth more than fixing the instances:
+  it converts a recurring drift into a build error.
+- `clarify`'s body calls itself "the fourth phase" while the chain it prints puts it third.
+- `cold-outreach` never names `linkedin-outreach` in its route table, though the reverse link exists.
+- `data-policy` says "walk five columns" and then lists six.
+- `marketing/references/seo-geo.md` (20 KB) and marketing's landing-section material substantially
+  duplicate the standalone `seo-geo` and `landing-copy` skills. Three skills, one body of content,
+  paid for three times by anyone who installs all three. Needs a content-level de-duplication pass,
+  not a format one.
+
+## Return value
+
+```json
+{"skill":"<id>","pr":"<url|null>","descBefore":0,"descAfter":0,"bytesBefore":0,"bytesAfter":0,
+ "evalLint":"PASS|FAIL","removed":["…"],"kept":["…"],"notes":"anything the orchestrator must know"}
+```

package/rules/skill-quality/skill-rubric.md

@@ -0,0 +1,40 @@
+# skill-rubric — the objective test every ai-hub skill must pass before shipping
+
+This is **the test, written before any skill is built.** A reviewer scores a finished skill
+0–10 on seven weighted dimensions, then the deterministic gates run (pass/fail, not gradeable).
+A skill **ships only at a weighted score ≥ 8.5 AND all deterministic gates green.** The reviewer
+is adversarial and independent of the author; it must cite evidence (line counts, char counts,
+quoted source dates), never vibes. No grade inflation — an honest 7.0 that drives a fix beats a
+dishonest 9.
+
+## Weighted dimensions (0–10 each)
+
+| # | Dimension | Weight | What a 10 looks like |
+|---|---|---|---|
+| 1 | **Triggering & description** | 0.15 | Third-person, `Use when …` lead, an explicit `NOT … (that is <sibling>)` boundary, and nothing else it can do without. Judged on **discriminative power, not coverage**: could a reader pick this skill over its nearest sibling from the description alone? Aim ≤350 chars; ≤1024 is the hard limit. Parses as single-line quoted YAML. |
+| 2 | **Scope & boundary** | 0.10 | One job. Body never drifts into a sibling's territory; it delegates by name. Near-miss prompts route to the correct existing sibling. |
+| 3 | **Body craft & progressive disclosure** | 0.15 | **The smallest body that routes correctly** — ≤400 lines is a ceiling, not a target, and there is no minimum: a skill that does its job in 60 lines scores higher than the same skill padded to 200. Every `references/` file is pointed to inline from this body (an unlinked reference is never loaded, so it is dead weight). ai-hub voice, every fence language-tagged, a checklist/decision table only where the flow branches, an anti-patterns table present. |
+| 4 | **Correctness, grounding & freshness** | **0.25** | Every load-bearing claim is accurate and **current (2025–2026)**: real library/API versions, no hallucinated flags/endpoints. The spec cites **authoritative sources with dates**; nothing rests on stale or invented facts. This is the heaviest dimension by design. |
+| 5 | **Actionability** | 0.15 | Concrete and runnable: real numbers, paths, commands, decision rules — not adjectives. A practitioner could act from it without leaving the skill. |
+| 6 | **Evals quality** | 0.10 | ≥5 `should_trigger` (incl. non-obvious), ≥4 `should_not_trigger` each with a `route_to` that resolves — a **real** catalog id, `none`, or `external:<name>` (enforced by `eval-lint`), ≥1 `capability` with a meaningful `must_include` rubric. The cases are genuine, not filler. |
+| 7 | **Originality & safety** | 0.10 | ai-hub voice, not a clone of any external catalog (no borrowed urgency blocks / rationalization tables / `*-reviewer-prompt.md` conventions / verbatim flowcharts). `verify.sh` present iff there is a checkable artifact. No destructive or unsafe advice presented without guardrails. |
+
+**Weighted score** = Σ(subscore × weight), rounded to 1 decimal. **Ship gate: ≥ 8.5.**
+
+## Deterministic gates (pass/fail — not part of the 0–10, but block shipping)
+
+1. `name` matches the directory id; `origin: ai-hub` present.
+2. Frontmatter validates against `schema/frontmatter.schema.json` (`node scripts/build-manifest.js --validate`).
+3. Every `recommends` id is a **real** skill in the catalog (no dangling refs — `--validate` enforces).
+4. `scripts/eval-lint.sh` reports PASS for the skill (≥5/≥4/≥1 and the keys are lists).
+5. Every `../<sibling>/SKILL.md` link resolves to a skill that exists.
+6. `description` is ≤ 1024 characters and parses as YAML.
+7. If a `scripts/verify.sh` exists, it is executable, read-only by default, and exits 0 on a clean/empty target (no false failure).
+
+## How the reviewer must work (anti-cheat)
+
+- **Independent pass.** Review the artifact as written; do not assume the author's intent filled a gap.
+- **Evidence, not vibes.** For dimension 1 quote the char count **and name the sibling the description distinguishes this skill from**; for 3 quote the SKILL.md line count **and name anything that could be cut without losing routing**; for 4 quote at least two source titles **with their dates** from the spec and name any claim you could not verify; for 6 count the entries.
+- **Length is a cost, never a credit.** Do not reward a longer description or body for being thorough. Every line is paid for in context on every turn the skill is installed, whether or not it is invoked. If two versions route the same, the shorter one scores higher.
+- **Freshness is mandatory.** If the skill names a version, API, or pricing that is plausibly out of date, dimension 4 is capped at 6 until a current source is cited. "Looks right" is not a source.
+- **Fix loop.** Below 8.5, return a concrete `mustFix` list; the author applies it and re-scores. Up to two fix rounds. If still < 8.5, **record the real score and flag it** — never round up to pass.

package/schema/engine.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AiHubEngineV2",
+  "type": "object",
+  "required": ["version", "roles", "commands", "labels", "targets"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 2 },
+    "roles": {
+      "type": "array",
+      "minItems": 8,
+      "maxItems": 8,
+      "items": {
+        "type": "object",
+        "required": ["id", "canonical", "derived", "can_modify", "cannot_modify", "commands", "gate"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "canonical": { "type": "string", "minLength": 1 },
+          "derived": { "type": "boolean" },
+          "description": { "type": "string" },
+          "can_modify": { "type": "array", "items": { "type": "string" } },
+          "cannot_modify": { "type": "array", "items": { "type": "string" } },
+          "commands": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+          "gate": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "commands": {
+      "type": "array",
+      "minItems": 17,
+      "maxItems": 17,
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "lane", "artifacts", "exit", "role", "skill"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "name": { "type": "string", "pattern": "^/speckit[.-]" },
+          "lane": { "enum": ["assessment", "feature", "bug"] },
+          "artifacts": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+          "exit": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+          "role": { "type": "string", "minLength": 1 },
+          "co_roles": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+          "skill": { "type": "string", "pattern": "^speckit-" }
+        }
+      }
+    },
+    "labels": {
+      "type": "array",
+      "minItems": 7,
+      "maxItems": 7,
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "ai::todo",
+          "ai::in-spec",
+          "ai::spec-ready",
+          "ai::in-dev",
+          "ai::in-review",
+          "ai::done",
+          "ai::blocked"
+        ]
+      }
+    },
+    "targets": {
+      "type": "array",
+      "minItems": 5,
+      "uniqueItems": true,
+      "items": { "enum": ["claude", "opencode", "pi", "cursor", "copilot"] }
+    }
+  }
+}