@omega.js/manager 0.1.0

package/claude-plugin/hooks/inject/run.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# omega:inject — UserPromptSubmit hook
+# Reads the project's package.json and asks the session to invoke the matching
+# framework skill. At a BRAND root the nearest manifest carries the manager
+# alone, so the brand's targets are discovered too (config/omega.json5 and
+# every targets/*/package.json) and the whole set is asked for at once, with
+# the framework map named as required reading.
+# Once per session per skill; fails open on anything unexpected.
+
+set -euo pipefail
+
+input=$(cat)
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+session_id=$(jq -r '.session_id // ""' <<<"$input" 2>/dev/null || true)
+cwd=$(jq -r '.cwd // ""' <<<"$input" 2>/dev/null || true)
+[ -n "$cwd" ] && [ -d "$cwd" ] || exit 0
+
+# The project's package.json: the cwd's own, else the nearest one above it —
+# stopping at the git root, since past it is somebody else's project.
+manifest=""
+dir="$cwd"
+while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+  if [ -f "$dir/package.json" ]; then
+    manifest="$dir/package.json"
+    break
+  fi
+  [ -e "$dir/.git" ] && break
+  dir=$(dirname "$dir")
+done
+[ -n "$manifest" ] || exit 0
+
+# Backend apps keep @omega.js/backend in functions/package.json with a plain
+# app manifest at the root, so the functions manifest joins the dep pool.
+fn_manifest="$(dirname "$manifest")/functions/package.json"
+
+own_name=$(jq -r '.name // empty' "$manifest" 2>/dev/null || true)
+deps=$(jq -r '((.dependencies // {}) | keys) + ((.devDependencies // {}) | keys) | .[]' "$manifest" 2>/dev/null || true)
+if [ -f "$fn_manifest" ]; then
+  fn_deps=$(jq -r '((.dependencies // {}) | keys) + ((.devDependencies // {}) | keys) | .[]' "$fn_manifest" 2>/dev/null || true)
+  deps=$(printf '%s\n%s' "$deps" "$fn_deps")
+fi
+
+# package → skill lives in the shared table (hooks/lib/omega-skills.sh), the one
+# the gate hook reads too. These rows only say HOW a package matches: every row
+# matches the manifest's OWN name, which is what covers working inside
+# `packages/<pkg>` in the monorepo, and `name` rows match ONLY that way —
+# web, desktop, and extension all depend on the client runtime, so a dependency
+# on it says nothing about what the session works on.
+skills_lib="$(dirname "${BASH_SOURCE[0]}")/../lib/omega-skills.sh"
+[ -r "$skills_lib" ] || exit 0
+# shellcheck source-path=SCRIPTDIR source=../lib/omega-skills.sh
+. "$skills_lib"
+
+matched=()
+while read -r pkg signal; do
+  [ -n "$pkg" ] || continue
+  skill=$(omega_skill_for "$pkg")
+  [ -n "$skill" ] || continue
+  if [ "$own_name" = "$pkg" ]; then
+    matched+=("$skill")
+  elif [ "$signal" != "name" ] && grep -qxF "$pkg" <<<"$deps"; then
+    matched+=("$skill")
+  fi
+done <<'MAP'
+@omega.js/web any
+@omega.js/backend any
+@omega.js/desktop any
+@omega.js/extension any
+@omega.js/manager any
+@omega.js/client name
+omega name
+MAP
+
+# Brand-level discovery. A brand root's manifest carries @omega.js/manager and
+# nothing else, so the frameworks a brand actually runs live one level down, in
+# config/omega.json5 and each targets/*/package.json. Read them all: a session
+# at a brand root has to know about every target before it edits one.
+brand_root=$(omega_brand_root "$cwd")
+if [ -n "$brand_root" ]; then
+  while read -r skill; do
+    [ -n "$skill" ] || continue
+    matched+=("$skill")
+  done < <(omega_brand_skills "$brand_root")
+fi
+
+[ "${#matched[@]}" -gt 0 ] || exit 0
+
+# One injection per session per skill.
+marker_dir="${TMPDIR:-/tmp}/omega-inject"
+mkdir -p "$marker_dir" 2>/dev/null || true
+safe_session="${session_id//[^a-zA-Z0-9]/_}"
+
+fresh=()
+for skill in $(printf '%s\n' "${matched[@]}" | sort -u); do
+  marker="$marker_dir/${safe_session}__${skill//[:\/]/_}.loaded"
+  [ -f "$marker" ] && continue
+  : > "$marker" 2>/dev/null || true
+  fresh+=("$skill")
+done
+
+[ "${#fresh[@]}" -gt 0 ] || exit 0
+
+if [ "${#fresh[@]}" -eq 1 ]; then
+  ctx="OMEGA project detected: invoke the ${fresh[0]} skill via the Skill tool before responding. Follow its rules and the framework docs it routes to for any work in this project. (Injected once per session; do not re-invoke on later prompts unless the work shifts.)"
+else
+  skill_list=$(printf ', %s' "${fresh[@]}")
+  skill_list="${skill_list:2}"
+  ctx="OMEGA project detected: invoke these skills via the Skill tool before responding: ${skill_list}. Follow their rules and the framework docs they route to for any work in this project. (Injected once per session; do not re-invoke on later prompts unless the work shifts.)"
+fi
+
+# In a brand, the skills and the framework map are REQUIRED reading before the
+# first edit, not a suggestion — the gate hook refuses a target edit until the
+# skill that owns it was invoked.
+if [ -n "$brand_root" ]; then
+  ctx="$ctx
+This is an OMEGA brand monorepo: every skill above, plus the framework map it points at (the brand AGENTS.md import line — node_modules/@omega.js/AGENTS.md), is required reading BEFORE the first edit. Writes under targets/ and to config/omega.json5 are refused until the skill owning that surface has been invoked."
+fi
+
+jq -n --arg ctx "$ctx" '{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": $ctx
+  }
+}'
+exit 0

package/claude-plugin/hooks/lib/omega-gate.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# omega gate markers — sourced by the two writers of a gate marker: the gate
+# hook itself (PostToolUse Skill) and mark.sh (the one command an agent with no
+# Skill tool runs after reading the guide). ONE home for where a marker lives
+# and what it is called, so the two lanes can never disagree about the name.
+
+# omega_gate_state_dir
+# The marker directory. Under TMPDIR so it dies with the machine's temp state;
+# never created here — each caller decides what an unusable directory means.
+omega_gate_state_dir() {
+  printf '%s/omega-gate\n' "${TMPDIR:-/tmp}"
+}
+
+# omega_gate_marker <session_id> <skill>
+# The marker path for one skill in one session. Both halves are flattened to
+# safe filename characters, so a session id or a skill spelling can never walk
+# out of the state directory.
+omega_gate_marker() {
+  printf '%s/%s__%s.invoked\n' "$(omega_gate_state_dir)" "${1//[^a-zA-Z0-9]/_}" "${2//[:\/]/_}"
+}

package/claude-plugin/hooks/lib/omega-scope.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# omega scope guard — sourced by the hooks that police a FILE path (shape,
+# quality). One home for the question "is this file inside an omega project?",
+# so the two guards can never disagree about what they police.
+# The inject hook asks a different question (a project from a cwd, with its
+# functions/ manifest joined in) and keeps its own walk.
+
+# omega_scope <file_path>
+# Walks up from the file to the nearest package.json, stopping at the git root
+# (past it is somebody else's project), and succeeds only when that manifest IS
+# or DEPENDS ON an @omega.js/* package. Returns 1 on no manifest, no jq, or
+# unparseable JSON — the fail-open answer for a hook.
+omega_scope() {
+  local file_path="$1"
+  [ -n "$file_path" ] || return 1
+  command -v jq >/dev/null 2>&1 || return 1
+
+  local dir manifest omega_linked
+  dir=$(dirname "$file_path")
+  manifest=""
+  while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+    if [ -f "$dir/package.json" ]; then
+      manifest="$dir/package.json"
+      break
+    fi
+    if [ -e "$dir/.git" ]; then
+      break
+    fi
+    dir=$(dirname "$dir")
+  done
+  [ -n "$manifest" ] || return 1
+
+  omega_linked=$(jq -r '
+    [.name // ""] + ((.dependencies // {}) | keys) + ((.devDependencies // {}) | keys)
+    | map(select(startswith("@omega.js/"))) | length
+  ' "$manifest" 2>/dev/null || echo 0)
+  case "$omega_linked" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  [ "$omega_linked" -gt 0 ] || return 1
+}

package/claude-plugin/hooks/lib/omega-skills.sh

@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+# omega skill map — sourced by the hooks that answer "which skill owns this?"
+# (inject, gate). ONE home for the framework → skill table and for the brand
+# walk. The two hooks share the map but ask different questions of it: inject
+# also reads config target keys, while the gate resolves a target from its
+# manifest alone — a config-declared target with no manifest yet is asked for
+# and not gated (fail-open by design).
+# Every function fails open: unreadable files and unparseable JSON answer
+# "nothing here", never an error.
+
+# omega_skill_for <token>
+# The one table — every hook that maps a thing to a skill reads THIS. Takes a
+# package name (@omega.js/web), a config target key (web), or a monorepo
+# package directory name (web): three spellings of the same fact. Prints the
+# skill, or nothing when no skill owns the token:
+# a custom target, `mobile` (parked), and the internal packages (devkit,
+# config, account, analytics, monitoring, template-kit, mcp-router) all land
+# here deliberately.
+omega_skill_for() {
+  case "$1" in
+    @omega.js/web|web|website)         echo 'omega:web' ;;
+    @omega.js/backend|backend)         echo 'omega:backend' ;;
+    @omega.js/desktop|desktop)         echo 'omega:desktop' ;;
+    @omega.js/extension|extension)     echo 'omega:extension' ;;
+    @omega.js/manager|manager)         echo 'omega:manager' ;;
+    @omega.js/client|client)           echo 'omega:client' ;;
+    omega)                             echo 'omega:main' ;;
+  esac
+}
+
+# omega_manifest_deps <manifest>
+# Every dependency name in a package.json, both blocks, one per line.
+omega_manifest_deps() {
+  [ -f "$1" ] || return 0
+  jq -r '((.dependencies // {}) | keys) + ((.devDependencies // {}) | keys) | .[]' "$1" 2>/dev/null || true
+}
+
+# omega_brand_root <dir>
+# Walks up from a directory to the git root (inclusive) and prints the first
+# BRAND root it finds: a directory carrying config/omega.json5, or one whose
+# package.json depends on @omega.js/manager. Prints nothing when the walk
+# leaves no brand behind — a framework package, a plain project, the monorepo
+# root itself.
+omega_brand_root() {
+  local dir="$1"
+  [ -n "$dir" ] || return 0
+  # `dirname` bottoms out at "." for a relative path and stays there forever,
+  # so the walk below would never terminate. Nothing to resolve, answer nothing.
+  case "$dir" in /*) ;; *) return 0 ;; esac
+  while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+    if [ -f "$dir/config/omega.json5" ]; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+    if [ -f "$dir/package.json" ] && omega_manifest_deps "$dir/package.json" | grep -qxF '@omega.js/manager'; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+    [ -e "$dir/.git" ] && return 0
+    dir=$(dirname "$dir")
+  done
+}
+
+# omega_config_target_keys <config/omega.json5>
+# The immediate child keys of the config's `targets` block, one per line. The
+# config is JSON5 (comments, unquoted keys, trailing commas), so jq cannot read
+# it and a key scan is the whole job: brace-depth tracking from the `targets:`
+# line, printing keys at depth 1. Nothing here is load-bearing — a miss just
+# means the key's skill has to come from the target's own manifest.
+omega_config_target_keys() {
+  [ -r "$1" ] || return 0
+  awk '
+    BEGIN { started = 0; depth = 0 }
+    {
+      line = $0
+      # A comment starts at line start or after whitespace — never mid-token,
+      # which is what keeps a "https://…" value from eating its own braces.
+      sub(/^[[:space:]]*\/\/.*$/, "", line)
+      sub(/[[:space:]]\/\/.*$/, "", line)
+    }
+    !started {
+      if (line ~ /^[[:space:]]*"?targets"?[[:space:]]*:[[:space:]]*\{/) { started = 1; depth = 1 }
+      next
+    }
+    {
+      if (depth == 1 && line ~ /^[[:space:]]*["'"'"']?[A-Za-z_][A-Za-z0-9_-]*["'"'"']?[[:space:]]*:/) {
+        key = line
+        sub(/^[[:space:]]*/, "", key)
+        sub(/[[:space:]]*:.*$/, "", key)
+        gsub(/["'"'"']/, "", key)
+        print key
+      }
+      depth += gsub(/\{/, "{", line) - gsub(/\}/, "}", line)
+      if (depth <= 0) exit
+    }
+  ' "$1" 2>/dev/null || true
+}
+
+# omega_brand_skills <brand_root>
+# Every skill a brand session needs, one per line, unsorted and possibly
+# repeated: omega:main and omega:manager (always, in a brand), plus one skill
+# per target — read from every targets/*/package.json (and the functions/
+# manifest a Firebase backend keeps its framework in) AND from the config's
+# own target keys, so a target declared before its directory exists still
+# counts. A target no framework owns contributes nothing.
+omega_brand_skills() {
+  local root="$1" manifest dep key
+  echo 'omega:main'
+  echo 'omega:manager'
+
+  for manifest in "$root"/targets/*/package.json "$root"/targets/*/functions/package.json; do
+    [ -f "$manifest" ] || continue
+    while read -r dep; do
+      [ -n "$dep" ] || continue
+      omega_skill_for "$dep"
+    done < <(omega_manifest_deps "$manifest")
+  done
+
+  while read -r key; do
+    [ -n "$key" ] || continue
+    omega_skill_for "$key"
+  done < <(omega_config_target_keys "$root/config/omega.json5")
+}
+
+# omega_theme_surface <path-relative-to-a-package-or-target-root>
+# Whether a path is one of the theme cascade's OWN surfaces — the layers
+# `resolveThemeLayers`/`overrideLanes` walk (packages/web's packaged themes, a
+# consumer-local theme at src/themes/<id>, the section folders a consumer
+# shadows — `_sections` AND `_components`, which overrideLanes resolves as one
+# lane — and the tier-1 scss entry). One table serves the monorepo and a
+# brand alike, since the caller passes the path relative to the package or
+# target root.
+omega_theme_surface() {
+  case "$1" in
+    themes/*|src/themes/*|src/_sections/*|src/_components/*|src/assets/css/main.scss) return 0 ;;
+  esac
+  return 1
+}
+
+# omega_skill_for_file <file_path>
+# The skill(s) that OWN an editable surface, one per line, or nothing when no
+# skill does. The surface's own skill comes first; omega:theme joins it on a
+# theme surface (omega_theme_surface above), so a theme edit answers to both.
+# Three surfaces gate, and only these three:
+#   <brand>/targets/<t>/**   the target's own framework skill
+#   <brand>/config/omega.json5   omega:manager — the file the manage walk reconciles
+#   <monorepo>/packages/<pkg>/** that package's skill, where one exists
+# Everything else — docs, scripts, the plugin's own files, a brand's root
+# files, an internal package — answers nothing and stays free.
+omega_skill_for_file() {
+  local file_path="$1"
+  [ -n "$file_path" ] || return 0
+  command -v jq >/dev/null 2>&1 || return 0
+
+  local brand rest target manifest skill
+
+  # The monorepo's own packages, ASKED FIRST: a package tree owns everything
+  # inside it, so a brand-shaped fixture living in one (devkit's test fixtures)
+  # is that package's business and never a brand of its own. The FIRST
+  # packages/ segment names the package — a nested packages/ inside a fixture
+  # cannot answer — and the manifest has to BE @omega.js/<pkg>; any other
+  # repo's packages/ directory falls through to the brand walk below.
+  case "$file_path" in
+    */packages/*/*)
+      rest="${file_path#*/packages/}"
+      target="${rest%%/*}"
+      manifest="${file_path%/packages/"$rest"}/packages/$target/package.json"
+      if [ -f "$manifest" ] && [ "$(jq -r '.name // ""' "$manifest" 2>/dev/null || true)" = "@omega.js/$target" ]; then
+        skill=$(omega_skill_for "@omega.js/$target")
+        [ -n "$skill" ] && printf '%s\n' "$skill"
+        if [ "$skill" = 'omega:web' ] && omega_theme_surface "${rest#"$target"/}"; then
+          echo 'omega:theme'
+        fi
+        return 0
+      fi
+      ;;
+  esac
+
+  brand=$(omega_brand_root "$(dirname "$file_path")")
+  if [ -n "$brand" ]; then
+    case "$file_path" in
+      "$brand"/config/omega.json5)
+        echo 'omega:manager'
+        return 0
+        ;;
+      "$brand"/targets/*/*)
+        rest="${file_path#"$brand"/targets/}"
+        target="${rest%%/*}"
+        for manifest in "$brand/targets/$target/package.json" "$brand/targets/$target/functions/package.json"; do
+          [ -f "$manifest" ] || continue
+          while read -r dep; do
+            [ -n "$dep" ] || continue
+            skill=$(omega_skill_for "$dep")
+            if [ -n "$skill" ]; then
+              printf '%s\n' "$skill"
+              # The cascade is a web mechanism, so only a website target's own
+              # theme surfaces add it — a themes/ dir in a backend is not one.
+              if [ "$skill" = 'omega:web' ] && omega_theme_surface "${rest#"$target"/}"; then
+                echo 'omega:theme'
+              fi
+              return 0
+            fi
+          done < <(omega_manifest_deps "$manifest")
+        done
+        return 0
+        ;;
+    esac
+  fi
+}

package/claude-plugin/hooks/quality/run.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# omega:quality — PostToolUse (Write|Edit) + Stop hook
+# Fires the quality skills deterministically instead of by model judgment: a
+# write to a web surface asks for the skills that own it (omega:seo,
+# omega:accessibility, omega:brandcheck), a write to a flow or money surface
+# asks for omega:analytics, and the Stop pass refuses a sign-off
+# that never went through their checklists. One script for both events so the
+# surface table has ONE home; the event comes off hook_event_name.
+# Fails open on anything unexpected, and only polices projects that depend on
+# (or are) @omega.js/*.
+
+set -euo pipefail
+
+input=$(cat)
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+event=$(jq -r '.hook_event_name // ""' <<<"$input" 2>/dev/null || true)
+session_id=$(jq -r '.session_id // ""' <<<"$input" 2>/dev/null || true)
+
+state_dir="${TMPDIR:-/tmp}/omega-quality"
+safe_session="${session_id//[^a-zA-Z0-9]/_}"
+pending="$state_dir/${safe_session}.pending"
+
+# --- Stop: the re-check -------------------------------------------------------
+# Blocks once on the web surfaces edited since the last block, then clears the
+# list so a re-armed session needs a fresh edit. stop_hook_active means the
+# block already ran on this turn.
+if [ "$event" = "Stop" ]; then
+  stop_hook_active=$(jq -r '.stop_hook_active // false' <<<"$input" 2>/dev/null || true)
+  if [ "$stop_hook_active" = "true" ]; then
+    exit 0
+  fi
+  [ -s "$pending" ] || exit 0
+
+  # TAB-delimited on both sides: a path may contain spaces.
+  files=$(cut -d"$(printf '\t')" -f1 <"$pending" | sort -u)
+  skills=$(cut -d"$(printf '\t')" -f2 <"$pending" | tr ',' '\n' | sed '/^$/d' | sort -u | tr '\n' ',' | sed 's/,$//; s/,/, /g')
+  count=$(printf '%s\n' "$files" | grep -c . || true)
+  rm -f "$pending" 2>/dev/null || true
+
+  ctx="omega:quality — $count web surface(s) were edited this session:
+$files
+
+Before signing off, walk each edited surface against the checklists in: ${skills}. Invoke the skill via the Skill tool if it is not loaded, report what you checked, and fix what fails. If a checklist item does not apply to the change, say so — do not skip the pass silently."
+
+  jq -n --arg ctx "$ctx" '{
+    "decision": "block",
+    "reason": "omega:quality — edited web surfaces have not been reviewed against the quality checklists.",
+    "hookSpecificOutput": {
+      "hookEventName": "Stop",
+      "additionalContext": $ctx
+    }
+  }'
+  exit 0
+fi
+
+# --- PostToolUse: the surface match ------------------------------------------
+file_path=$(jq -r '.tool_input.file_path // ""' <<<"$input" 2>/dev/null || true)
+[ -n "$file_path" ] || exit 0
+
+# The surface table: a path pattern → the skills that own that surface. Rows
+# accumulate, so head.html matches both its include row and its seo row.
+matched=()
+while read -r pattern skills; do
+  [ -n "$pattern" ] || continue
+  # The unquoted pattern is the point — case globs it.
+  # shellcheck disable=SC2254
+  case "$file_path" in
+    $pattern) matched+=("$skills") ;;
+  esac
+done <<'MAP'
+*/pages/*.html omega:seo,omega:accessibility
+*/pages/*.md omega:seo,omega:accessibility
+*/_layouts/* omega:seo,omega:accessibility
+*.liquid omega:seo,omega:accessibility
+*/_includes/core/head.html omega:seo
+*/_includes/core/foot.html omega:seo
+*/_includes/*.html omega:accessibility
+*/sections/*.html omega:accessibility
+*/components/*.html omega:accessibility
+*/assets/js/*.js omega:accessibility
+*/core/js/*.js omega:accessibility
+*.scss omega:accessibility,omega:brandcheck
+*.css omega:accessibility,omega:brandcheck
+*/omega.json5 omega:brandcheck
+*/_includes/*.json omega:brandcheck
+*/sections/*.json5 omega:brandcheck
+*/core/js/pages/* omega:analytics
+*/core/js/libs/auth/* omega:analytics
+*/routes/payments/* omega:analytics
+*/events/firestore/payments-webhooks/* omega:analytics
+*/events/auth/* omega:analytics
+*/packages/analytics/* omega:analytics
+MAP
+
+[ "${#matched[@]}" -gt 0 ] || exit 0
+
+# Scope guard: only police projects that depend on (or are) @omega.js/*.
+scope_lib="$(dirname "${BASH_SOURCE[0]}")/../lib/omega-scope.sh"
+[ -r "$scope_lib" ] || exit 0
+# shellcheck source-path=SCRIPTDIR source=../lib/omega-scope.sh
+. "$scope_lib"
+omega_scope "$file_path" || exit 0
+
+owners=$(printf '%s\n' "${matched[@]}" | tr ',' '\n' | sort -u | paste -sd, -)
+
+# Arm the Stop re-check with this surface.
+mkdir -p "$state_dir" 2>/dev/null || true
+printf '%s\t%s\n' "$file_path" "$owners" >>"$pending" 2>/dev/null || true
+
+# The reminder itself is once per session per skill — the same rule the inject
+# hook follows. The Stop pass is what carries the per-file accounting.
+fresh=()
+for skill in $(printf '%s' "$owners" | tr ',' '\n'); do
+  marker="$state_dir/${safe_session}__${skill//[:\/]/_}.asked"
+  [ -f "$marker" ] && continue
+  : > "$marker" 2>/dev/null || true
+  fresh+=("$skill")
+done
+[ "${#fresh[@]}" -gt 0 ] || exit 0
+
+skill_list=$(printf ', %s' "${fresh[@]}")
+skill_list="${skill_list:2}"
+
+jq -n --arg ctx "omega:quality — web surface edited ($file_path): invoke ${skill_list} via the Skill tool and hold this work to the checklists you find there. (Named once per session per skill; the Stop pass re-checks every edited surface before sign-off.)" '{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": $ctx
+  }
+}'
+exit 0

package/claude-plugin/hooks/shape/run.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# omega:shape — PreToolUse (Write|Edit) hook
+# Bounces test files written in the three always-wrong shapes for this
+# ecosystem: a __tests__/ path segment, a *.spec.js filename, and a
+# test/tests/ nesting. The layer CHOICE stays judgment (docs/shared/testing.md
+# owns the mantra); this guards only the mechanical suite shape. Fails open on
+# anything unexpected, and only polices projects that depend on @omega.js/*.
+
+set -euo pipefail
+
+input=$(cat)
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+file_path=$(jq -r '.tool_input.file_path // ""' <<<"$input" 2>/dev/null || true)
+[ -n "$file_path" ] || exit 0
+
+# Only test-shaped writes are in scope at all.
+base=$(basename "$file_path")
+case "$file_path" in
+  *__tests__/*|*/test/tests/*) ;;
+  *)
+    case "$base" in
+      *.spec.js|*.spec.ts|*.spec.mjs|*.spec.cjs) ;;
+      *) exit 0 ;;
+    esac
+    ;;
+esac
+
+# Scope guard: only police projects that depend on (or are) @omega.js/*.
+scope_lib="$(dirname "${BASH_SOURCE[0]}")/../lib/omega-scope.sh"
+[ -r "$scope_lib" ] || exit 0
+# shellcheck source-path=SCRIPTDIR source=../lib/omega-scope.sh
+. "$scope_lib"
+omega_scope "$file_path" || exit 0
+
+cat >&2 <<EOF
+omega:shape — test suite shape violation: $file_path
+The omega ecosystem's mirrored suite shape (docs/shared/testing.md in the
+Omega repo) has one home for tests: top-level test/ mirroring the source
+tree, *.test.js filenames (desktop/extension FRAMEWORK suites live at
+src/test/ — the recorded exception). Never __tests__/ directories, *.spec.*
+names, or test/tests/ nesting. Write it as test/<mirror>/<name>.test.js.
+EOF
+exit 2

package/claude-plugin/mcp-router-launch.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * The plugin's MCP entry — ONE launcher, correct in both eras
+ * ([#144](https://github.com/Omega-JS-Stack/omega/issues/144)).
+ *
+ * `.mcp.json` points at this file through `${CLAUDE_PLUGIN_ROOT}`, so the
+ * declaration never addresses a path outside the plugin. Node resolution from
+ * the plugin's OWN directory then finds the router wherever it lives: the
+ * workspace copy when the plugin is read live from this monorepo, and the
+ * installed `@omega.js/mcp-router` — wherever npm hoisted it — when the plugin
+ * is vendored into `@omega.js/manager` inside a consumer brand.
+ *
+ * The router package declares no `exports` map, so its bin is resolvable by
+ * subpath; requiring it starts the stdio server (which self-bootstraps its own
+ * dependencies on a bare checkout). Stdout is the MCP wire — the failure path
+ * speaks on stderr only, in the router's own voice.
+ */
+
+const ROUTER_BIN = '@omega.js/mcp-router/bin/mcp-router.js';
+
+let entry;
+try {
+  entry = require.resolve(ROUTER_BIN, { paths: [__dirname] });
+} catch {
+  process.stderr.write(`[mcp-router fatal] cannot resolve ${ROUTER_BIN} from ${__dirname} — install @omega.js/mcp-router beside the plugin\n`);
+  process.exit(1);
+}
+
+require(entry);

package/claude-plugin/skills/README.md

@@ -0,0 +1,48 @@
+# Skills — the authoring contract
+
+One directory per skill, holding a `SKILL.md`. The directory name and the frontmatter `name` must match exactly, and both are BARE — no namespace. The plugin supplies the namespace, so `skills/web` surfaces in a session as `omega:web`.
+
+The roster follows the packages a session works in: `main` (the hub) plus `web`, `backend`, `desktop`, `extension`, `client`, and `manager` — plus `browser`, which is not a package router but the usage pattern for the plugin's one MCP declaration, the `@omega.js/mcp-router` endpoint.
+
+Four more are checklists rather than routers, and the quality hook fires them on the surfaces they own (the table is in the plugin README):
+
+| Skill | The checklist |
+|---|---|
+| `seo` | A page's search surface: meta title/description, canonical + social tags, structured data, one h1, sitemap/robots, link shape |
+| `accessibility` | Front-end surfaces: landmarks and heading order, alt text, control names, color through the tokens, focus visibility, reduced motion |
+| `brandcheck` | Config and copy consistency: brand facts read from omega.json5, one brand hex, the merge chain, no secrets in config |
+| `analytics` | Event tracking: every flow fires through the catalog, a new event is a catalog entry first, the placement rule, consent and attribution carried not hand-rolled |
+
+One more is a checklist the GATE fires, not the quality hook — the theme surfaces it owns are the same ones the gate refuses without it (the table is in the plugin README):
+
+| Skill | The checklist |
+|---|---|
+| `theme` | The theme cascade: which layer a change belongs to, base/skin/fork and the declared forks, the tokens, whole-folder overrides and `inherit`, the two consumer tiers |
+
+```
+skills/
+└── <name>/
+    └── SKILL.md
+```
+
+## Frontmatter
+
+```yaml
+---
+name: <name>
+description: <when to use it — one sentence, 300 characters or less>
+user-invocable: true
+---
+```
+
+The `description` is the whole loading decision — it is the only part Claude reads before choosing to load the skill — and every skill's sits in EVERY session, so it is a shared context budget. One tight sentence naming WHEN to invoke this skill: the package, the surfaces, the situations. Nothing about what the skill knows — the body and the docs carry that. `scripts/skill-descriptions.test.js` fails the structure lane on anything over 300 characters.
+
+## The body points; the repo docs are the source
+
+A skill is a router. It names where the truth lives for BOTH worlds — `docs/<framework>/index.md` plus `docs/shared/` when the session is in this monorepo, the top-level map through `node_modules/@omega.js/AGENTS.md` (the scope symlink the workspace service maintains) plus `docs/manager/brand.md` when the session is in a consumer project — and carries only what a session needs before it knows which document to open: the hard rules, the shape of the thing, and the paths.
+
+Content copied out of the docs into a skill is a second home for the same fact, and the copy is what goes stale. Point instead.
+
+## Keeping it honest
+
+Every skill has to be checkable against the code it describes. Prefer claims a test can verify — an exported name, a config key, a CLI command, a file path — over prose that can drift without any signal. See the "staleness mechanism" section in the plugin README.