aw-ecc 1.4.31 → 1.4.47

package/skills/aw-adk/references/registry-structure.md

@@ -0,0 +1,152 @@
+# Registry Structure & Path Resolution
+
+How CASRE artifacts are organized in the AW registry and rules system.
+
+## Two Namespace Models
+
+### Platform namespace (shared, read-only)
+
+Platform is flat — no team/sub_team level. Domains are the primary organization:
+
+```
+.aw/                                    # ← root anchor — all registry paths start here
+  .aw_registry/
+    platform/
+      <domain>/                     # core, frontend, infra, data, sdet, review, design, services
+        skills/<slug>/SKILL.md
+        agents/<slug>.md
+        commands/<slug>.md
+        evals/<type>/<slug>/eval-*.md   # colocated evals
+```
+
+**Domains:** core, frontend, infra, data, sdet, review, design, services
+
+### Team namespaces
+
+Teams always have `<team>/<sub_team>` and optionally nest further by domain:
+
+```
+.aw/
+  .aw_registry/
+    <team>/                         # crm, leadgen, revex, mobile
+      <sub_team>/                   # users, events, forms, courses, memberships, core
+        [<domain>/]                 # OPTIONAL: backend, core, frontend, infra, design, product, quality
+          skills/<slug>/SKILL.md
+          agents/<slug>.md
+          commands/<slug>.md
+```
+
+**Key differences:**
+- **`platform`** uses `platform/<domain>/CAS` — no team layer
+- **Teams** use `<team>/<sub_team>/CAS` or `<team>/<sub_team>/<domain>/CAS`
+- Some teams put CAS directly: `crm/users/agents/` (no domain nesting)
+- Others nest fully: `leadgen/events/backend/agents/` (with domain)
+
+### Rules structure (separate hierarchy)
+
+Rules live outside the registry in `.aw/.aw_rules/`:
+
+```
+.aw/
+  .aw_rules/                      # Platform-level (shared)
+    platform/
+      <domain>/                   # universal, security, frontend, backend, data, infra, sdet, mobile
+        AGENTS.md                 # Main rules file
+        references/<slug>.md      # Individual rule references
+        evals/<slug>/eval-*.md    # Colocated rule evals
+        <stack>/                  # Optional stack overlays
+          AGENTS.md
+          references/<slug>.md
+    rule-manifest.json            # Registry of all platform rules
+
+  .aw_rules.local/                # Team/repo-level (planned)
+    rule-manifest-local.json
+    render.json                   # Target mapping between platform + local layers
+    <path>/AGENTS.md              # e.g., apps/billing/AGENTS.md
+```
+
+**Stack overlays:** `backend/nestjs/`, `backend/go-connect/`, `frontend/vue/`, `frontend/nuxt/`
+
+## Path Resolution Flow
+
+Use this decision tree to **construct** the exact target path. The rules are deterministic — walk the tree, substitute your variables, and you'll have the path. Searching is unnecessary because every combination of namespace + domain + type produces exactly one path.
+
+```
+1. Is this a RULE?
+   ├── YES → Platform rule?
+   │         ├── YES → .aw/.aw_rules/platform/<domain>/references/<slug>.md
+   │         └── NO  → .aw/.aw_rules.local/<path>/AGENTS.md
+   └── NO  → continue
+
+2. Is this PLATFORM work?
+   ├── YES → Ask: which domain?
+   │         (core, frontend, infra, data, sdet, review, design, services)
+   │         → .aw/.aw_registry/platform/<domain>/<type>/<slug>
+   └── NO  → continue
+
+3. Is this TEAM work?
+   → Ask: which team? (crm, leadgen, revex, mobile)
+   → Ask: which sub_team? (users, events, courses, memberships, core, etc.)
+   → Ask: need domain nesting? (optional)
+   ├── NO domain  → .aw/.aw_registry/<team>/<sub_team>/<type>/<slug>
+   └── YES domain → .aw/.aw_registry/<team>/<sub_team>/<domain>/<type>/<slug>
+```
+
+## Naming Conventions
+
+`aw link` creates symlinks across all IDE directories (`.claude/`, `.cursor/`, `.codex/`) using **all-hyphens** names. The formula comes from `link.mjs`: it takes every directory name between the namespace root and the artifact type directory, appends the artifact slug, and joins them all with hyphens. When a team uses optional domain nesting (e.g., `revex/reselling/backend/agents/`), the domain becomes an extra segment in the name.
+
+| Type | Platform | Team (flat) | Team (with domain) | Stage/core |
+|---|---|---|---|---|
+| Command | `aw:platform-core-plan` | `aw:revex-reselling-<slug>` | `aw:revex-reselling-backend-<slug>` | `aw:build` |
+| Agent | `platform-data-db-engineer` | `revex-reselling-redis-reviewer` | `revex-reselling-backend-<slug>` | `code-reviewer` |
+| Skill | `platform-core-architecture-design` | `revex-reselling-redis-patterns` | `revex-reselling-backend-<slug>` | `skill-creator` |
+| Rule | `<domain>/<slug>` | repo-local path | repo-local path | — |
+
+Platform and team (flat) examples are real names from the live system. When in doubt, verify against what `aw link` actually created — the symlinks are the source of truth:
+- Skills: `ls ~/.claude/skills/` (or `.cursor/`, `.codex/`)
+- Agents: `ls ~/.claude/agents/`
+- Commands: `ls ~/.claude/commands/aw/`
+
+**Examples of cross-artifact references (all use the hyphen-joined symlink name):**
+
+```yaml
+# Agent loading skills
+skills:
+  - revex-reselling-redis-patterns
+  - platform-data-mongodb-patterns
+
+# Command loading agents
+agents:
+  - platform-review-security-reviewer
+  - platform-review-performance-reviewer
+
+# subagent_type in commands/skills
+subagent_type: "platform-review-security-reviewer"
+```
+
+These all match the symlink names in `~/.claude/skills/` and `~/.claude/agents/` that `aw link` creates.
+
+## Colocated Eval Placement
+
+Evals live next to their parent artifact, not in a top-level `evals/` directory:
+
+| Parent Type | Eval Location |
+|---|---|
+| Skill | `skills/<slug>/evals/eval-*.md` (inside skill dir) |
+| Agent | `agents/evals/<slug>/eval-*.md` (sibling evals/ dir) |
+| Command | `commands/evals/<slug>/eval-*.md` (sibling evals/ dir) |
+| Rule | `rules/evals/<slug>/eval-*.md` or within `.aw/.aw_rules/` references |
+| Eval (meta) | `evals/evals/eval-*.md` (self-referential) |
+
+## How `aw pull` Maps to IDE Paths
+
+After `aw pull`, registry artifacts are synced to IDE-local locations:
+
+| Registry | Claude Code | Cursor | Codex |
+|---|---|---|---|
+| `skills/<slug>/SKILL.md` | `.claude/skills/<slug>/SKILL.md` | `.cursor/rules/<slug>.mdc` | `.codex/<slug>/` |
+| `agents/<slug>.md` | `.claude/agents/<slug>.md` | `.cursor/rules/<slug>.mdc` | `.codex/<slug>/` |
+| `commands/<slug>.md` | `.claude/commands/<slug>.md` | N/A (manual) | N/A |
+
+`skills-lock.json` tracks installed skills with SHA256 integrity hashes (like package-lock.json for skills).

package/skills/aw-adk/references/rubric-agent.md

@@ -0,0 +1,36 @@
+# Rubric: Agent Quality (10 dimensions, /100)
+
+Evaluates the quality of an AW agent definition file.
+
+## Scoring Table
+
+| # | Dimension | 0 (Missing) | 5 (Partial) | 10 (Complete) |
+|---|-----------|-------------|-------------|---------------|
+| 1 | **Identity & Personality** | No identity defined | Has role but missing personality, memory, or experience | Full 4-field identity: role, personality, memory, experience |
+| 2 | **Core Mission** | Missing or vague | 1 generic sentence | 2-3 specific sentences naming domain, outcomes, scope boundaries |
+| 3 | **Critical Rules** | Missing or soft suggestions | 1-2 rules without BLOCK/NEVER keywords | 3-5 hard rules with BLOCK/NEVER/ALWAYS and measurable thresholds |
+| 4 | **Process / Workflow** | Missing | Numbered list without code or commands | Step-by-step with input/output per step, code examples, bash commands |
+| 5 | **Deliverables** | Missing | Table with names only | Table with format + quality bar + inline template for each deliverable |
+| 6 | **Communication Style** | Missing or 1 sentence | 2 personality traits described | 3-4 example phrases showing distinct voice and tone |
+| 7 | **Code Examples** | No code blocks | 1 generic block | 2+ domain-specific blocks showing good vs. bad patterns |
+| 8 | **Learning & Memory** | Missing | Lists what to remember | Pattern recognition + anti-patterns + cross-session learning protocol |
+| 9 | **Success Metrics** | Missing or vague | 2-3 metrics without numbers | 4-5 quantified targets with explicit thresholds |
+| 10 | **Advanced Capabilities** | Missing | 1-2 bullets | 3+ mastery areas showing growth trajectory from basic to expert |
+
+## Tier Thresholds
+
+| Tier | Score | Interpretation |
+|------|-------|----------------|
+| **S** | 90-100 | Production-grade. Agent is distinctive, reliable, and self-improving. |
+| **A** | 75-89 | Strong. Minor gaps in voice, metrics, or advanced capabilities. |
+| **B** | 60-74 | Functional. Usable but lacks personality depth or measurable targets. |
+| **C** | 40-59 | Draft. Core mission exists but workflow and deliverables need work. |
+| **D** | 0-39 | Stub or broken. Not usable without significant rewrite. |
+
+## How to use this rubric
+
+1. Open the agent definition file.
+2. Score each dimension independently (0, 5, or 10).
+3. Sum all 10 scores for a total out of 100.
+4. Map the total to a tier using the thresholds above.
+5. Prioritize fixing dimensions that scored 0 -- these represent missing sections that block agent effectiveness.

package/skills/aw-adk/references/rubric-command.md

@@ -0,0 +1,36 @@
+# Rubric: Command Quality (10 dimensions, /100)
+
+Evaluates the quality of an AW command definition file.
+
+## Scoring Table
+
+| # | Dimension | 0 (Missing) | 5 (Partial) | 10 (Complete) |
+|---|-----------|-------------|-------------|---------------|
+| 1 | **Frontmatter** | Missing | `name` + `description` present | `name` + `description` + `argument-hint` + `mcp` list |
+| 2 | **Protocol Reference** | Missing | Generic mention of a protocol | Explicit AW-PROTOCOL reference + skill loading gate requirement |
+| 3 | **Agent Roster** | Missing | Informal mentions of agents in prose | Table with phase, agent name, tier, and skills loaded per agent |
+| 4 | **Skill Loading Gate** | Missing | Partial mention of skill loading | Full blocking gate: agent -> skills -> learnings chain before execution |
+| 5 | **Phase Structure** | No phases defined | Phases listed without I/O contracts | Numbered phases with input, output, and human checkpoints per phase |
+| 6 | **Output Format** | Missing | Vague description | Concrete markdown template with placeholders and field names |
+| 7 | **Human Checkpoints** | None defined | 1 vague mention of review | Explicit gates with approval criteria and proceed/halt behavior |
+| 8 | **Learning / Transparency** | Missing | Mentions learning broadly | Per-step .md artifacts + transparency JSON + learnings append protocol |
+| 9 | **User Communication** | Silent execution | Some status messages | Status message per phase with progress indicator format |
+| 10 | **Error Handling** | Missing | "Retry if failed" | Per-phase failure paths, fallback agents, and halt conditions |
+
+## Tier Thresholds
+
+| Tier | Score | Interpretation |
+|------|-------|----------------|
+| **S** | 90-100 | Production-grade. Fully orchestrated with checkpoints and error recovery. |
+| **A** | 75-89 | Strong. Minor gaps in error handling or transparency artifacts. |
+| **B** | 60-74 | Functional. Phases exist but missing checkpoints or fallback paths. |
+| **C** | 40-59 | Draft. Basic structure present but no orchestration rigor. |
+| **D** | 0-39 | Stub or broken. Not executable as a command. |
+
+## How to use this rubric
+
+1. Open the command definition file.
+2. Score each dimension independently (0, 5, or 10).
+3. Sum all 10 scores for a total out of 100.
+4. Map the total to a tier using the thresholds above.
+5. Commands scoring below B-tier should not be shipped to users -- focus on phase structure and error handling first.

package/skills/aw-adk/references/rubric-eval.md

@@ -0,0 +1,36 @@
+# Rubric: Eval Quality (10 dimensions, /100)
+
+Evaluates the quality of an AW eval definition file used for benchmarking agent and skill performance.
+
+## Scoring Table
+
+| # | Dimension | 0 (Missing) | 5 (Partial) | 10 (Complete) |
+|---|-----------|-------------|-------------|---------------|
+| 1 | **Frontmatter** | Missing | `name` + `target` present | `name` + `target` + `category` + `difficulty` |
+| 2 | **Task Clarity** | Missing or vague | Describes intent in general terms | Concrete task with specific artifact type, namespace, and domain |
+| 3 | **Context** | Missing | Minimal (just a path or name) | Namespace, domain, target path, existing related work, key packages |
+| 4 | **Expected Outcomes** | Missing | 1-2 vague expectations | 4+ specific, verifiable checkboxes with concrete acceptance criteria |
+| 5 | **Grading Criteria** | Missing | Just PASS/FAIL | PASS/PARTIAL/FAIL with clear thresholds for each grade |
+| 6 | **Evaluation Method** | Missing | Unspecified or implied | Explicit: deterministic, model-based, or hybrid with rationale |
+| 7 | **Scenario Diversity** | Single happy path only | Happy path + 1 edge case | Happy + failure + edge case + adversarial scenario |
+| 8 | **False-Pass Resistance** | Would pass a clearly wrong artifact | Some specificity in assertions | Assertions target quality dimensions, not just existence checks |
+| 9 | **Reproducibility** | Non-deterministic or vague setup | Mostly reproducible with minor variance | Fully deterministic or clearly bounded stochastic with seed/tolerance |
+| 10 | **Baseline Tracking** | No baseline mentioned | Mentions baseline informally | Explicit with/without comparison methodology and stored baseline scores |
+
+## Tier Thresholds
+
+| Tier | Score | Interpretation |
+|------|-------|----------------|
+| **S** | 90-100 | Production-grade. Reliable, reproducible, and resistant to false passes. |
+| **A** | 75-89 | Strong. Good coverage; minor gaps in diversity or baseline tracking. |
+| **B** | 60-74 | Functional. Tests the right thing but may miss edge cases or allow false passes. |
+| **C** | 40-59 | Draft. Task is defined but grading criteria or scenarios need work. |
+| **D** | 0-39 | Stub or broken. Not usable for benchmarking. |
+
+## How to use this rubric
+
+1. Open the eval definition file.
+2. Score each dimension independently (0, 5, or 10).
+3. Sum all 10 scores for a total out of 100.
+4. Map the total to a tier using the thresholds above.
+5. Evals below B-tier should not be included in benchmark suites -- prioritize false-pass resistance and scenario diversity to avoid misleading results.

package/skills/aw-adk/references/rubric-meta-eval.md

@@ -0,0 +1,132 @@
+# Rubric: Meta-Evaluation
+
+Score an eval's quality across 5 dimensions. Total: /50.
+
+## Dimensions
+
+### 1. Scenario Diversity (0-10)
+
+How broadly does the eval cover the artifact's behavior space?
+
+| Score | Description |
+|-------|-------------|
+| 0 | Single happy-path scenario only |
+| 2 | Happy path with minor input variations |
+| 5 | Happy path + at least one edge case or failure scenario |
+| 7 | Happy path + failure + edge case coverage |
+| 10 | Happy path + failure + edge case + adversarial/ambiguous inputs |
+
+**What to look for:**
+- Does the eval test what happens when required fields are missing?
+- Are boundary conditions exercised (empty input, maximum length, special characters)?
+- Is there at least one scenario where the artifact should refuse or fail gracefully?
+- Are adversarial prompts included (conflicting instructions, prompt injection attempts)?
+
+### 2. Grader Determinism (0-10)
+
+How reproducible are the eval results across runs?
+
+| Score | Description |
+|-------|-------------|
+| 0 | Fully subjective -- human judgment with no rubric |
+| 3 | Model-based grader with vague instructions ("is this good?") |
+| 5 | Model-based grader with specific criteria and examples |
+| 7 | Mix of deterministic checks and bounded model grading |
+| 10 | Fully deterministic script or model grader with explicit pass/fail boundaries |
+
+**What to look for:**
+- Are pass/fail criteria unambiguous enough that two reviewers would agree?
+- Does the grader use exact-match, regex, or structured checks where possible?
+- If model-based, does the grader prompt include concrete examples of pass and fail?
+- Could you automate this grader in CI without human intervention?
+
+### 3. False-Pass Resistance (0-10)
+
+Would a clearly wrong artifact still pass the eval?
+
+| Score | Description |
+|-------|-------------|
+| 0 | A boilerplate or empty artifact would pass |
+| 3 | Checks for presence of output but not correctness |
+| 5 | Some specificity -- checks named sections or keywords |
+| 7 | Targeted assertions on content, structure, and relationships |
+| 10 | Assertions that demonstrably fail on known-wrong artifacts |
+
+**What to look for:**
+- Does the eval check content meaning, not just content existence?
+- Are there negative assertions (artifact must NOT contain X)?
+- Would a copy-paste of the prompt back as output pass? If yes, score low.
+- Does the eval verify relationships between parts (e.g., summary matches detail)?
+
+### 4. Criteria Specificity (0-10)
+
+How precisely are success criteria defined?
+
+| Score | Description |
+|-------|-------------|
+| 0 | Vague ("output should be good", "looks correct") |
+| 3 | Named qualities without measurement ("should be comprehensive") |
+| 5 | Named sections or fields to check with qualitative descriptions |
+| 7 | Quantified thresholds for most criteria (counts, percentages, sizes) |
+| 10 | All criteria have quantified thresholds with evidence requirements |
+
+**What to look for:**
+- Can you turn each criterion into a binary pass/fail without interpretation?
+- Are numeric thresholds stated (e.g., "at least 3 scenarios", "under 200 words")?
+- Does the eval require evidence citations or examples in the output?
+- Are edge cases in the criteria themselves addressed (what counts as "partial")?
+
+### 5. Baseline Tracking (0-10)
+
+Does the eval support measuring improvement over time?
+
+| Score | Description |
+|-------|-------------|
+| 0 | No baseline, no comparison methodology |
+| 3 | Mentions that results should be compared but no method |
+| 5 | References a baseline or before/after comparison |
+| 7 | Explicit with/without methodology with defined metrics |
+| 10 | Reproducible baseline with versioned artifacts, stored results, and diff method |
+
+**What to look for:**
+- Is there a "before" snapshot or known-good baseline to compare against?
+- Can you re-run the eval on an older version and get comparable results?
+- Does the eval track scores over time (not just pass/fail)?
+- Is the comparison methodology documented enough for someone else to reproduce?
+
+## Tier Thresholds
+
+| Tier | Score | Interpretation |
+|------|-------|----------------|
+| **S** | 45-50 | Production-grade eval. Ship it. |
+| **A** | 38-44 | Strong eval. Minor gaps acceptable for non-critical artifacts. |
+| **B** | 30-37 | Adequate eval. Acceptable for first iteration; improve before relying on it for regressions. |
+| **C** | 20-29 | Weak eval. Provides some signal but has significant blind spots. |
+| **D** | 0-19 | Eval provides negligible quality signal. Rewrite before using. |
+
+## How to Use
+
+1. **Score each eval after writing it.** Fill in the 5 dimensions honestly. If you authored the eval, have someone else score it -- author bias inflates scores by 5-10 points on average.
+
+2. **Gate on tier before merging.** New evals for skills and agents should be B-tier or above. Critical-path artifacts (commands, platform rules) should target A-tier.
+
+3. **Use dimension scores to guide improvements.** A low Scenario Diversity score is fixed by adding scenarios. A low Grader Determinism score requires rewriting the grader. Address the lowest-scoring dimension first for maximum impact.
+
+4. **Re-score after changes.** When you modify an eval, re-run the rubric. Track the score in the eval's frontmatter or a changelog comment.
+
+5. **Compare across evals.** Use tier distribution to gauge overall eval maturity for a project. If most evals are C-tier, invest in eval quality before adding more artifacts.
+
+### Scoring Template
+
+```markdown
+## Meta-Eval Score
+
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| Scenario Diversity | /10 | |
+| Grader Determinism | /10 | |
+| False-Pass Resistance | /10 | |
+| Criteria Specificity | /10 | |
+| Baseline Tracking | /10 | |
+| **Total** | **/50** | **Tier: ?** |
+```

package/skills/aw-adk/references/rubric-rule.md

@@ -0,0 +1,36 @@
+# Rubric: Rule Quality (10 dimensions, /100)
+
+Evaluates the quality of an AW rule definition file. Expands the original 5-dimension /50 rubric from aw-rules to 10 dimensions /100.
+
+## Scoring Table
+
+| # | Dimension | 0 (Missing) | 5 (Partial) | 10 (Complete) |
+|---|-----------|-------------|-------------|---------------|
+| 1 | **Frontmatter** | Missing | `id` + `severity` present | `id` + `severity` + `domains` + `paths` glob patterns |
+| 2 | **Rule Statement** | Missing | Vague or ambiguous phrasing | One clear sentence stating the requirement and why it matters |
+| 3 | **WRONG Example** | Missing | Generic or hypothetical violation | Real violation pattern drawn from actual codebase conventions |
+| 4 | **RIGHT Example** | Missing | Generic fix | Verified fix grounded in platform docs or referenced skills |
+| 5 | **Skill Link** | Missing | Wrong or broken link | Correct link to an existing, relevant skill |
+| 6 | **Severity Justification** | Missing | Just states MUST/SHOULD without rationale | Explains why this severity: risk, blast radius, precedent |
+| 7 | **Automation Path** | Missing | "Can be linted" without specifics | Specific lint rule, pre-commit hook, or CI script that enforces this |
+| 8 | **Scope Precision** | Too broad ("all code") | Domain-scoped (e.g., "backend" or "frontend") | Path-scoped with glob patterns (e.g., `services/*/src/**/*.ts`) |
+| 9 | **Exceptions** | No mention of edge cases | "Edge cases exist" without detail | Explicit exceptions listed with justification for each |
+| 10 | **Manifest Entry** | Missing from rule-manifest.json | Incomplete entry (missing fields) | Full entry: id, severity, domains, description, principle |
+
+## Tier Thresholds
+
+| Tier | Score | Interpretation |
+|------|-------|----------------|
+| **S** | 90-100 | Production-grade. Enforceable, scoped, and documented with automation. |
+| **A** | 75-89 | Strong. Clear rule with examples; minor gaps in automation or exceptions. |
+| **B** | 60-74 | Functional. Rule is understandable but lacks enforcement path or scope precision. |
+| **C** | 40-59 | Draft. Statement exists but missing examples or justification. |
+| **D** | 0-39 | Stub or broken. Not enforceable or understandable. |
+
+## How to use this rubric
+
+1. Open the rule file and its corresponding entry in `rule-manifest.json`.
+2. Score each dimension independently (0, 5, or 10).
+3. Sum all 10 scores for a total out of 100.
+4. Map the total to a tier using the thresholds above.
+5. Rules below B-tier should not be added to the active manifest -- prioritize adding WRONG/RIGHT examples and an automation path.

package/skills/aw-adk/references/rubric-skill.md

@@ -0,0 +1,36 @@
+# Rubric: Skill Quality (10 dimensions, /100)
+
+Evaluates the quality of an AW skill file (SKILL.md + references/).
+
+## Scoring Table
+
+| # | Dimension | 0 (Missing) | 5 (Partial) | 10 (Complete) |
+|---|-----------|-------------|-------------|---------------|
+| 1 | **Frontmatter** | Missing | `name` + `description` present | `name` + `description` + `trigger` with "use when" clause |
+| 2 | **Purpose Statement** | Missing | 1 vague sentence | 2-3 specific sentences naming domain, scope, and outcomes |
+| 3 | **When to Use** | Missing | 1 trigger scenario | 3+ trigger scenarios covering distinct use cases |
+| 4 | **Instructions** | Missing or vague | Numbered list without detail | Step-by-step with concrete actions, commands, decision points |
+| 5 | **Code Examples** | No code blocks | 1 generic code block | 3+ domain-specific code blocks with context |
+| 6 | **Checklists** | Missing | Basic bullet list | Items with pass/fail criteria, severity, and fix guidance |
+| 7 | **References** | No references | Internal links only | Links to platform-docs + reference files in references/ |
+| 8 | **Progressive Disclosure** | Everything in SKILL.md or too sparse | SKILL.md + some refs | SKILL.md < 5k words, detailed content in references/ |
+| 9 | **Domain Specificity** | Generic / framework-agnostic | Mentions package names | Actual package names, design tokens, API patterns with versions |
+| 10 | **Output Format** | No output template | Vague description of output | Concrete markdown template with field names and placeholders |
+
+## Tier Thresholds
+
+| Tier | Score | Interpretation |
+|------|-------|----------------|
+| **S** | 90-100 | Production-grade. Ready for cross-team adoption. |
+| **A** | 75-89 | Strong. Minor gaps in examples or references. |
+| **B** | 60-74 | Functional. Usable but missing depth in 2-3 dimensions. |
+| **C** | 40-59 | Draft. Needs significant work before team use. |
+| **D** | 0-39 | Stub or broken. Not usable without rewrite. |
+
+## How to use this rubric
+
+1. Open the skill's `SKILL.md` and its `references/` directory.
+2. Score each dimension independently (0, 5, or 10).
+3. Sum all 10 scores for a total out of 100.
+4. Map the total to a tier using the thresholds above.
+5. Record dimension-level scores to guide targeted improvements -- focus on any dimension scoring 0 or 5 first.