rsc-universal 0.1.1

package/skills/cost-tracking/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: cost-tracking
+
+should_trigger:
+  - prompt: "Wrap our OpenAI calls so we record token cost per request."
+    why: Core capture — per-request token + cost capture around an SDK call is the skill's first step.
+  - prompt: "Set a $500/month cap on the Claude API that hard-stops when we hit it."
+    why: Budget plus a hard cap that refuses — the guard layer this skill owns.
+  - prompt: "Our bill is 3x what we estimated — reconcile the billed usage against what we computed."
+    why: Non-obvious — reconciliation of provider-billed vs ledgered usage is a direct tell for this skill, not generic debugging.
+  - prompt: "Attribute our LLM spend per tenant so we know which customer is expensive."
+    why: Ledger attribution — per-tenant cost rollup is exactly the attribution-key design here.
+  - prompt: "Pon un tope de gasto a la API y avísame al 80%."
+    why: Spanish — budget plus a soft alert threshold (80%), the alert/cap branch of the skill.
+  - prompt: "Is prompt caching actually cheaper for our agent, and where's the break-even?"
+    why: The levers section — caching break-even math is owned here, not asserted.
+  - prompt: "A runaway agent loop burned through our token budget overnight with no guardrail."
+    why: The surprise-bill scenario the hard cap exists to prevent; routes straight to budgets+caps.
+
+should_not_trigger:
+  - prompt: "What's our cash runway at this burn rate?"
+    route_to: finance-ops
+    why: Company-level cash, not the AI/cloud line item; cost-tracking is just one input feeding it.
+  - prompt: "Compute the gross margin per subscription."
+    route_to: unit-economics
+    why: Margin math — cost-tracking only produces the cost numerator, it does not divide by units.
+  - prompt: "Record this AWS invoice as an expense in the books."
+    route_to: bookkeeping
+    why: The accounting record, not the operational real-time meter.
+  - prompt: "Decide what to charge customers for the pro plan."
+    route_to: pricing
+    why: Willingness-to-pay / what to charge, not controlling what we spend.
+  - prompt: "Chart our monthly active users and retention curve."
+    route_to: analytics
+    why: Product/behavior telemetry, a different meter; the dollar capture is here but user-behavior charting is not.
+
+capability:
+  - scenario: "We have a Next.js app calling Claude + OpenAI with no cost visibility and a scary bill. Give us a metering + budget-cap design."
+    must_include:
+      - reads cost from the response `usage` object, not pre-send estimates (estimates only for the pre-flight cap check)
+      - versioned pricing table where each model row carries effective_date + source, loaded as data not literals
+      - loud failure on a model absent from the pricing table (never default to $0)
+      - append-only ledger with an idempotency/request key and at least one attribution key (user/tenant/feature)
+      - budget with BOTH a soft threshold (alert/degrade) and a hard threshold (refuse with a typed error)
+      - the three levers (prompt caching with ~1-hit break-even, batch API 50% stacking with caching, model downshift)
+      - notes cloud billing alerts (AWS CAD ~24h delay, GCP Pub/Sub) are a delayed backstop, not the real-time guard

package/skills/cost-tracking/references/cloud-caps.md

@@ -0,0 +1,52 @@
+# Cloud spend caps — recipes (accessed 2026-06-02)
+
+App-level metering is the real-time guard. Everything here is the **slow backstop** — useful for catching what the app meter missed, never the thing standing between you and a runaway loop. The recurring caveat: cloud billing data lags, so by the time the cloud notices, the money is already spent.
+
+## AWS
+
+### Cost Anomaly Detection (ML-based)
+- ML model, runs roughly **3x/day**, with **up to 24h data delay**.
+- Emits to **SNS** → fan out to a **Lambda** that posts into your alert pipe (or revokes a key / disables a feature flag).
+- Source: aws.amazon.com/aws-cost-management/aws-cost-anomaly-detection; docs.aws.amazon.com/cost-management/.../manage-ad.html. Accessed 2026-06-02.
+
+### Budgets (threshold)
+- Set 50/80/100% threshold alerts on a monthly budget → SNS → same Lambda.
+- Pairs with CAD: Budgets catch the *expected* threshold; CAD catches the *unexpected* spike.
+
+```text
+AWS Budgets / Cost Anomaly Detection
+        │ (SNS, up to ~24h delay)
+        ▼
+     Lambda  ──►  shared alert pipe (Slack/PagerDuty/webhook)
+              └─► optional: disable feature flag / rotate-revoke API key
+```
+
+## GCP
+
+- Budgets are **threshold-only** for alerting, but the budget can publish to **Pub/Sub**.
+- Pub/Sub → **Cloud Function** is the one path that can actually **pause or throttle a workload** programmatically (e.g. scale a service to zero, disable a billing account binding).
+- Source: costimizer.ai gcp guide. Accessed 2026-06-02.
+
+```text
+GCP Budget ──► Pub/Sub ──► Cloud Function
+                            ├─► shared alert pipe
+                            └─► throttle / pause workload (real control)
+```
+
+## Azure
+
+- Threshold-only budgets with action groups. Same shape as GCP minus the clean Pub/Sub→pause path; wire the action group into the shared alert pipe.
+
+## Alert-routing pattern (all providers)
+
+Route **every** cloud alert into the **same pipe** as your in-app budget alerts, so there is one place to look and one severity ladder. Tag each alert with its source (`aws-cad`, `gcp-budget`, `app-meter`) so reconciliation can tell which guard fired.
+
+## The delay caveat, stated plainly
+
+| Guard | Latency | Can it stop spend? |
+|---|---|---|
+| App-level cap (this skill) | real-time | yes — refuse the request now |
+| AWS CAD / Budgets | up to ~24h | no — alert only (Lambda can revoke after the fact) |
+| GCP budget → Pub/Sub → Function | minutes-to-hours | partial — can pause a workload, but on lagged data |
+
+Design accordingly: the cloud cap is insurance against what your app meter failed to count; it is not the meter.

package/skills/cost-tracking/references/pricing-tables.md

@@ -0,0 +1,51 @@
+# Pricing tables — PERISHABLE snapshot (dated 2026-06-02)
+
+These rates move month to month. **Treat this file as data with an expiry, not a constant.** Every number below carries a source; re-fetch before trusting. The whole point of the skill is that prices live in a dated table, never as literals in logic.
+
+## Anthropic (Claude) — per 1M tokens
+
+| Model | Input | Output | Cache read | Source |
+|---|---|---|---|---|
+| Haiku 4.5 | $1.00 | $5.00 | $0.10 | cloudzero.com/blog/claude-api-pricing |
+| Sonnet 4.6 | $3.00 | $15.00 | $0.30 | cloudzero.com/blog/claude-api-pricing |
+| Opus 4.7 | $5.00 | $25.00 | $0.50 | evolink.ai/blog/claude-api-pricing-guide-2026 |
+
+Cache writes: 5-minute = 1.25x base input; 1-hour = 2x base input. Cache reads = 0.1x base input. Break-even on a 5-min cache entry: after ~1 hit (platform.claude.com prompt-caching; finout.io anthropic-api-pricing). All accessed 2026-06-02.
+
+## OpenAI — per 1M tokens
+
+| Model | Input | Cached input | Source |
+|---|---|---|---|
+| GPT-5.5 | $5.00 | $0.50 | openai.com/api/pricing |
+| GPT-5.4 | $2.50 | $0.25 | devtk.ai/en/blog/openai-api-pricing-guide-2026 |
+
+Cached input = **90% off** standard input across the line. Output rates vary by model — read them off the source, do not assume. Model names and exact rates drift fast; this is precisely why the rate table is data and never a literal. Accessed 2026-06-02.
+
+## Bedrock note
+
+AWS Bedrock re-prices the same underlying models (often with its own regional/commitment rates) and bills on its own line. Do not assume Bedrock matches first-party Anthropic/OpenAI rates — pull the Bedrock model rate separately and tag the table row `source: bedrock`. Cloud-side caps for Bedrock spend belong in `cloud-caps.md`.
+
+## Batch API discount
+
+50% off on both OpenAI and Anthropic, returned async within 24h, and **stacks with prompt caching** (combined up to ~95% off). Source: finout.io anthropic-api-pricing, accessed 2026-06-02. Use for non-realtime work (evals, backfills, nightly jobs).
+
+## The `usage` object — field map per provider
+
+Bill against these, not pre-send estimates.
+
+| Concept | Anthropic | OpenAI |
+|---|---|---|
+| Input tokens | `usage.input_tokens` | `usage.prompt_tokens` |
+| Output tokens | `usage.output_tokens` | `usage.completion_tokens` |
+| Cached (read) | `usage.cache_read_input_tokens` | `usage.prompt_tokens_details.cached_tokens` |
+| Cache write | `usage.cache_creation_input_tokens` | n/a (no explicit write line) |
+| Reasoning | included in output | `usage.completion_tokens_details.reasoning_tokens` |
+
+Pre-flight estimate tools (estimates only): Anthropic `client.messages.count_tokens()` returns input tokens, is free, separate rate limit, **not** tiktoken-compatible; OpenAI/most use `tiktoken` locally. Sources: platform.claude.com token-counting; langfuse.com token-and-cost-tracking. Accessed 2026-06-02.
+
+## How to refresh this file
+
+1. Pull each provider's current pricing page (sources above).
+2. Update the rate and set `effective_date` to today on every changed row.
+3. Add any new model name as a new row — never leave a model out, or the lookup will hit the "unknown model" loud-fail path (which is correct behavior).
+4. Re-run `scripts/verify.sh` against your `pricing.yaml` to confirm every row still carries `effective_date` + `source`.

package/skills/cost-tracking/scripts/verify.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+#
+# verify.sh - lint a candidate cost-tracking config/ledger artifact.
+#
+# Usage:
+#   cd <dir containing the config>
+#   ./verify.sh [path-to-config]      # yaml | yml | json | ts | js
+#
+# Read-only: never mutates anything. Checks the artifact for:
+#   1. every pricing entry carries effective_date AND source
+#   2. no model referenced in logic is absent from the pricing table
+#   3. the ledger schema has an idempotency/request key + >=1 attribution key
+#   4. the budget declares BOTH a soft and a hard threshold
+#   5. cost is derived from a usage/response field, not a len()/char estimate
+#
+# Emits [ ok ]/[fail] per check, then PASS or FAIL.
+# Exits 0 on a clean config AND on no config found (no false failure).
+# Exits 1 with the missing pieces on any violation.
+#
+# Portable: stock macOS bash 3.2 + grep + awk. No associative arrays, no mapfile.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+
+failed=0
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+
+# --- locate the config -------------------------------------------------------
+file="${1:-}"
+if [ -z "$file" ]; then
+  for cand in cost-tracking.yaml cost-tracking.yml pricing.yaml pricing.yml \
+              cost-config.yaml cost-config.yml cost-tracking.json cost-tracking.ts; do
+    if [ -f "$cand" ]; then file="$cand"; break; fi
+  done
+fi
+
+if [ -z "$file" ] || [ ! -f "$file" ]; then
+  printf '%s[skip]%s no cost-tracking config found (cost-tracking.{yaml,json,ts} / pricing.yaml) - nothing to verify.\n' "$YELLOW" "$RESET"
+  exit 0
+fi
+
+printf -- '----- linting %s\n' "$file"
+
+# case-insensitive fixed-ish grep helper
+has() { grep -Eiq "$1" "$file"; }
+
+# --- 1. pricing entries carry effective_date AND source ----------------------
+mentions_pricing=0
+if has 'pric|input_per_mtok|in_per_mtok|rate_in|cost_per'; then mentions_pricing=1; fi
+if [ "$mentions_pricing" -eq 1 ]; then
+  miss=""
+  has 'effective_date|effective-date|effectiveDate' || miss="$miss effective_date"
+  has 'source' || miss="$miss source"
+  if [ -z "$miss" ]; then
+    ok "pricing entries carry effective_date + source"
+  else
+    fail "pricing table missing:$miss (each model row must be dated and sourced)"
+  fi
+else
+  printf '%s[skip]%s no pricing table in this file (check 1)\n' "$YELLOW" "$RESET"
+fi
+
+# --- 2. no model referenced in logic absent from the table -------------------
+# Heuristic: collect model-ish identifiers (claude-*/gpt-*/sonnet/opus/haiku/o-series)
+# that appear OUTSIDE a "model:" / "- model:" declaration line, and warn if the
+# file declares no model rows at all while still naming models.
+declared=$(grep -Eio '(^|[^a-z])model[[:space:]]*[:=]' "$file" | wc -l | tr -d ' ')
+named=$(grep -Eio '(claude-[a-z0-9.]+|gpt-[a-z0-9.]+|sonnet|opus|haiku|gemini-[a-z0-9.]+)' "$file" \
+        | sort -u | wc -l | tr -d ' ')
+if [ "$named" -gt 0 ]; then
+  if [ "$declared" -eq 0 ]; then
+    fail "models are named but no 'model:' table rows declared - unknown models would price as \$0"
+  else
+    ok "models named ($named) are declared in 'model:' rows ($declared) - lookup can fail-loud on unknowns"
+  fi
+else
+  printf '%s[skip]%s no model identifiers found (check 2)\n' "$YELLOW" "$RESET"
+fi
+
+# --- 3. ledger: idempotency key + >=1 attribution key ------------------------
+mentions_ledger=0
+if has 'ledger|usage|input_tokens|output_tokens|cost_usd'; then mentions_ledger=1; fi
+if [ "$mentions_ledger" -eq 1 ]; then
+  miss=""
+  has 'request_id|idempotency|request-id|requestId|dedup' || miss="$miss idempotency/request key"
+  has 'user_id|tenant_id|tenant|feature|user-id|tenantId|userId' || miss="$miss attribution-key(user/tenant/feature)"
+  if [ -z "$miss" ]; then
+    ok "ledger has an idempotency key + at least one attribution key"
+  else
+    fail "ledger missing:$miss"
+  fi
+else
+  printf '%s[skip]%s no ledger schema in this file (check 3)\n' "$YELLOW" "$RESET"
+fi
+
+# --- 4. budget: both a soft and a hard threshold -----------------------------
+mentions_budget=0
+if has 'budget|threshold|cap|alert'; then mentions_budget=1; fi
+if [ "$mentions_budget" -eq 1 ]; then
+  miss=""
+  has 'soft|alert|warn|degrade|downshift' || miss="$miss soft(alert/degrade)"
+  has 'hard|refuse|hard_cap|hard-cap|block|reject' || miss="$miss hard(refuse)"
+  if [ -z "$miss" ]; then
+    ok "budget declares both a soft and a hard threshold"
+  else
+    fail "budget missing:$miss threshold"
+  fi
+else
+  printf '%s[skip]%s no budget config in this file (check 4)\n' "$YELLOW" "$RESET"
+fi
+
+# --- 5. cost derived from usage, not a len()/char estimate -------------------
+if has 'usage|input_tokens|output_tokens|cached_tokens|prompt_tokens'; then
+  if grep -Eiq 'len\(|\.length|char_count|charcount|//[[:space:]]*4|/[[:space:]]*4' "$file" \
+     && ! has 'estimate|pre-?flight|preflight'; then
+    fail "cost may be derived from a len()/char estimate - bill against the response usage object"
+  else
+    ok "cost derived from a usage/response field, not a char estimate"
+  fi
+else
+  printf '%s[skip]%s no usage-based cost field found (check 5)\n' "$YELLOW" "$RESET"
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s cost-tracking config is missing required pieces (see [fail] lines above).\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s cost-tracking config carries the required guardrails.\n' "$GREEN" "$RESET"

package/skills/course-builder/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: course-builder
+description: "Use when you must turn a vague \"I want to teach X\" into a defensible course/curriculum skeleton — writing measurable learning outcomes, designing assessment that proves them, sequencing modules, scoping a workshop/bootcamp/cohort/onboarding track, or building an outcome×module×assessment alignment matrix. Triggers: 'structure my course', 'turn these topics into a curriculum', 'write learning outcomes / objectives', 'design the final project and quizzes', 'map my modules to outcomes', 'is my course actually aligned?', 'my course just ends with no real endpoint — what should they be able to DO?', 'estructura el temario de mi curso', 'define los resultados de aprendizaje', 'dissenya el pla docent', 'quina avaluació demostra cada objectiu'. NOT making a concept land emotionally (that is course-storytelling)."
+tags: [course, curriculum, instructional-design, learning-outcomes, assessment]
+recommends: [course-storytelling, presentations, sop-builder]
+origin: risco
+---
+
+# Course Builder — The Course Is a Contract
+
+*Outcomes promise what the learner can DO. Assessment is the proof. Modules are the build order. If the three don't line up, you have a content dump, not a course. You design them backward — outcomes first, assessment second, content last — and you emit a matrix that makes the alignment checkable.*
+
+This skill owns the **skeleton**: the measurable outcomes, the assessment that certifies each one, the module sequence that builds toward them, and the alignment matrix tying it all together. It does not own the *teaching* of any one concept.
+
+## What this skill owns / does NOT own
+
+**Owns:** desired results (outcomes), acceptable evidence (assessment), build order (module sequence), and the outcome×module×assessment matrix that proves nothing is orphaned or unproven.
+
+**Does NOT own:**
+
+- Making a single concept *click and stick* emotionally — epiphany, sticky names, grounded analogies. That is `../course-storytelling/SKILL.md`. Build the skeleton HERE first, then hand each module there to make it land.
+- Auditing a *finished* course for gaps, redundancy, anachronisms with a written report → `../review/SKILL.md`.
+- Turning a designed module into slides/decks → `../presentations/SKILL.md` (+ `../design/SKILL.md` for the visual system).
+- Sales/landing copy and launch emails → `../marketing/SKILL.md`. You design the learning contract, never the pitch.
+- Fact-checking or sourcing the subject matter → `../research-ops/SKILL.md`. You structure what the user already knows.
+- A repeatable internal procedure with steps but no outcomes/assessment → `../sop-builder/SKILL.md`. An SOP tells someone the steps; a course changes what they can DO and proves it.
+
+**The litmus.** If the question is *"what must the learner be able to DO, how do we prove it, and in what order do we build it?"* → here. If it's *"how do I make THIS concept click and stick?"* → `../course-storytelling/SKILL.md`.
+
+## The grounding gate (read first — STOP if unmet)
+
+You cannot design a course backward without knowing the destination. Do not write a single outcome until you have all three. Why: an outcome scoped for a senior engineer in a 90-minute workshop is wrong for a beginner in a 12-week cohort — same topic, different contract.
+
+1. **WHO** — the learner and their *current* level (absolute beginner? practitioner? what can they already do?).
+2. **WHAT transformation** — what must they be able to DO at the end that they cannot do now.
+3. **FORMAT + constraints** — duration, modality (live cohort vs self-paced), group size, prerequisites, certification stakes.
+
+If a `02-DOCS/wiki/teaching/` profile exists (the convention shared with `../course-storytelling/SKILL.md`), read it first and reuse it. Otherwise interview in ONE batch — ask all three at once, do not dribble questions. **Incomplete grounding = STOP and ask.** Depth, the interview script, and scope right-sizing by format → `references/grounding-and-scoping.md`.
+
+## The non-negotiables
+
+Each rule carries its one-line reason. Break one and the skeleton is not defensible.
+
+1. **Design backward: outcomes first, then assessment, then content.** UbD has exactly three stages in order — desired results → acceptable evidence → learning experiences (Wiggins & McTighe, *Understanding by Design*). Content designed first is a dump with no destination.
+2. **Every outcome uses a measurable Bloom verb.** The revised taxonomy (Anderson & Krathwohl, 2001) is six ascending levels of *verbs* — Remember → Understand → Apply → Analyze → Evaluate → Create — each supplying observable action verbs. A verb you can't observe, you can't assess.
+3. **Banlist: never "understand", "know", "learn about", "appreciate", "be aware", "be familiar".** They name a private mental state, not an observable behavior. Replace with what the learner *does*: list, explain, build, debug, evaluate, design.
+4. **Each outcome is ABCD-complete.** Audience + Behavior (verb + object) + Condition (situation/tools) + Degree (success criterion). A bare verb without a condition and a degree is not yet assessable — "write code" vs "given a failing test, write code that makes it pass".
+5. **Every outcome is proven by ≥1 assessment.** No unproven outcomes. An outcome with no evidence is a promise you never keep.
+6. **Every module ties to ≥1 outcome.** No orphan modules. If a module maps to no outcome, it's content the contract never asked for — cut it or write the outcome it serves.
+7. **The verb in the outcome = the verb activated in teaching = the verb verified in assessment** (constructive alignment, Biggs). If the outcome says "design" and the quiz tests "recall", the assessment proves the wrong thing.
+8. **Place BOTH formative and summative assessment.** Formative runs *during* learning (low/no stakes — quizzes, checklists, drafts) to give feedback; summative runs *at the end* (the project, the exam) to certify mastery. A course with only the final exam gives the learner no feedback loop.
+9. **No content-first design.** "I already have these slides, build a course around them" inverts the contract. Outcomes decide what content survives.
+10. **Right-size scope to format.** A 90-minute workshop earns ~1–2 outcomes; a 12-week cohort earns 5–8. Cramming a bootcamp's outcomes into a workshop guarantees none are actually achieved.
+
+## The build workflow (one backward pass)
+
+Run it in order. Do not jump to modules.
+
+```text
+Stage 0  Grounding gate         WHO + WHAT transformation + FORMAT. Incomplete → STOP.
+Stage 1  Outcomes               3–8 course-level outcomes. Measurable Bloom verb + ABCD.
+                                Verb banlist enforced. Right-sized to format.
+Stage 2  Assessment             For EACH outcome, the evidence that proves it.
+                                Verb-match the outcome. Place formative + summative.
+                                Check content validity (covers the breadth of outcomes).
+Stage 3  Modules + sequence     One focus per module, prerequisite order. Each module
+                                maps to >=1 outcome. No orphans, no unproven outcomes.
+Stage 4  Alignment matrix       Emit outcome x module x assessment. The checkable artifact.
+Stage 5  QA gate                Run scripts/verify.sh over the curriculum doc. Fix warnings
+                                or justify them. Then hand modules to course-storytelling.
+```
+
+## Writing measurable outcomes
+
+Pick the verb at the level the learner must actually operate. Recall ≠ build.
+
+```text
+Level         What the learner does          Sample verbs
+Remember      recall facts                   list, define, name, label, recall
+Understand    explain in own words           explain, summarize, classify, compare
+Apply         use in a new situation         apply, use, implement, solve, run
+Analyze       break apart, find relations    analyze, differentiate, debug, diagram
+Evaluate      judge against criteria         evaluate, critique, justify, prioritize, review
+Create        produce something new          design, build, compose, construct, ship
+```
+
+The **ABCD template** for one outcome:
+
+```text
+[Audience]   the learner
+[Behavior]   <Bloom verb> + <object>
+[Condition]  given <situation / tools / inputs>
+[Degree]     <criterion that counts as success>
+```
+
+Bad → Good (the banlist verb is the tell):
+
+```markdown
+Bad:  Students will understand REST APIs.
+Good: Given a spec, the learner builds a REST endpoint that returns the correct
+      status code for 3 named error cases (400, 404, 500).
+
+Bad:  Learners will know SQL joins.
+Good: Given two tables, the learner writes a query joining them that returns the
+      expected rows for 2 of 2 test cases.
+
+Bad:  Participants will appreciate good test design.
+Good: Given a 20-line module, the learner writes 3 tests that cover the happy path
+      and 2 edge cases, all passing.
+```
+
+Full per-level verb tables, the banlist, more worked ABCD examples, and course-level vs module-level granularity → `references/outcomes-and-blooms.md`.
+
+## Designing aligned assessment
+
+Assessment is the proof, not an afterthought. For every outcome, ask: *what would I have to SEE the learner do to believe they achieved it?* — and make that the assessment.
+
+```text
+                 Formative (during)              Summative (at the end)
+Job              feedback, guide improvement     certify mastery / accountability
+Stakes           low / none                      high — the grade, the cert
+Examples         quizzes, skill checklists,      capstone project, final exam,
+                 drafts, peer review, exit        portfolio, graded build
+                 tickets
+Bloom fit        Remember/Understand/Apply        Apply/Analyze/Evaluate/Create
+```
+
+Two hard checks:
+
+- **Verb match.** The assessment must require the *same* verb as the outcome. Outcome "build" → assessment is a build, not a multiple-choice quiz. Outcome "evaluate" → assessment asks for a judgement with justification, not recall.
+- **Content validity.** The set of assessments must cover the *breadth* of the outcomes — every outcome touched, none over-weighted into a vanity exam. Competency-based design maps this via the matrix and certifies demonstrated mastery, not seat time.
+
+The full formative↔summative menu mapped to Bloom levels, the content-validity / blueprint checklist, and the verb-match rule worked end-to-end → `references/assessment-design.md`.
+
+## Sequencing modules + the alignment matrix
+
+Order modules by **prerequisite** (you can't build before you can run), give each **one focus**, and map each to ≥1 outcome. Then emit the matrix — this is the artifact `scripts/verify.sh` checks.
+
+```markdown
+| Outcome                          | Module(s)        | Assessment (F=formative, S=summative) |
+|----------------------------------|------------------|---------------------------------------|
+| O1 build a REST endpoint         | M2, M3           | F: M2 quiz · S: capstone API          |
+| O2 debug a failing request       | M4               | F: M4 debug drill · S: capstone API   |
+| O3 evaluate an API's error model | M5               | F: M5 peer review · S: capstone rubric|
+```
+
+Read the matrix two ways: down a column finds **orphan modules** (a module in no row → cut or justify); across the outcome list finds **unproven outcomes** (an outcome with an empty assessment cell → design evidence). A complete matrix has no empty cells.
+
+## Decision table (branch only where the flow actually splits)
+
+```text
+Situation                         Then
+Live cohort                       Schedule synchronous formative checkpoints; peer
+                                  assessment is cheap and valuable.
+Self-paced                        Formative must be self-graded/auto-graded (quizzes,
+                                  tests that run); no instructor in the loop.
+Short workshop (<= half day)      1-2 outcomes, mostly Apply; one summative artifact, no exam.
+Full course / bootcamp            5-8 outcomes spanning up to Create; staged formative +
+                                  a capstone summative.
+Knowledge outcome                 Assess with explanation/application, not recognition alone.
+Skill outcome                     Assess with a performance/build, never a quiz.
+Attitude/disposition outcome      Assess with reflection + observed behavior; hardest to
+                                  prove — keep few and honest.
+```
+
+## Anti-patterns
+
+| Bad | Why it fails | Do instead |
+|-----|--------------|------------|
+| Content-first: "build a course around my slides" | Inverts the contract; content with no destination | Write outcomes first; let them decide what content survives |
+| Vanity outcome: "students will understand X" | Names a private state, not observable → unassessable | Use a measurable Bloom verb in ABCD form |
+| Orphan module: a module mapped to no outcome | Content the contract never asked for | Cut it, or write the outcome it serves |
+| Unproven outcome: an outcome with no assessment | A promise you never verify | Design evidence that requires the outcome's verb |
+| Verb mismatch: outcome "design", quiz tests "recall" | Proves the wrong thing | Make the assessment require the outcome's verb |
+| Summative-only: just a final exam | No feedback loop during learning | Place formative checkpoints throughout |
+| Scope creep: bootcamp outcomes in a workshop | None are actually achievable in the time | Right-size outcome count to the format |
+
+## Hand-off
+
+The skeleton is the start, not the finish.
+
+- Skeleton + matrix pass QA → hand **each module** to `../course-storytelling/SKILL.md` to make the teaching land (epiphany, named models, grounded analogies). You built *what* and *in what order*; that skill makes it stick.
+- Need decks → `../presentations/SKILL.md` for slides, `../design/SKILL.md` for the visual system.
+- A repeatable team procedure surfaced that isn't a course → `../sop-builder/SKILL.md`.
+
+The boundary is executable: `scripts/verify.sh` checks your curriculum's STRUCTURE and ALIGNMENT (measurable verbs, the matrix, proven outcomes, formative + summative). It does not judge whether the teaching lands — that is `course-storytelling`'s job, and its verify.sh checks narrative, not structure.

package/skills/course-builder/evals/README.md

@@ -0,0 +1,16 @@
+# Eval harness — `course-builder`
+
+This is an **agent-run** eval, not an automated grader. `cases.yaml` has three blocks:
+`should_trigger` (7), `should_not_trigger` (5), and `capability` (1 scenario with a rubric). To run
+it, load **only** `course-builder` into a fresh agent (no sibling skills, so a miss can't be masked),
+paste each `should_trigger` / `should_not_trigger` prompt verbatim over 3–5 trials, and record
+whether the agent invokes the skill — `should_trigger` should fire, `should_not_trigger` should
+stay quiet and ideally route to the named sibling. Aim for ≥90% correct decisions across trials; a
+prompt that misses on a majority of its trials is a real defect — fix the description/triggers in
+`SKILL.md`, don't loosen the case. For the `capability` scenario, run it once and score the output
+against the `must_include` rubric by hand: did it work backward (outcomes first), ban vanity verbs,
+verb-match assessment to outcomes with both formative and summative, sequence modules with no
+orphans/unproven outcomes, emit the alignment matrix, and hand storytelling off rather than doing
+it? Grading is judgement, not grep — `scripts/verify.sh` only checks the greppable structure of a
+finished curriculum doc (banlist verbs, matrix presence, proven outcomes, formative+summative); the
+rubric here is the real bar.

package/skills/course-builder/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: course-builder
+
+should_trigger:
+  - prompt: "I have 30 topics on Kubernetes scattered in a doc — turn them into a structured curriculum with modules and a sensible order."
+    why: "Raw topic pile -> structured curriculum with sequenced modules. Core sequencing/scoping job."
+  - prompt: "Write measurable learning outcomes for my intro Python course; right now I just have 'students will understand functions'."
+    why: "Outcomes + measurability/Bloom, including rewriting a banlist verb ('understand') into an observable one."
+  - prompt: "What should the final project and quizzes be for my data-analytics bootcamp, and do they actually prove what I claim students will be able to do?"
+    why: "Assessment design plus alignment — does the evidence prove the outcomes (constructive alignment)."
+  - prompt: "My course just ends with no real endpoint. What should a learner be able to DO when they finish, and how do I build toward that?"
+    why: "NON-OBVIOUS: no Bloom/curriculum jargon, but it's pure backward design — outcomes-first, build toward the DO."
+  - prompt: "Estructura el temario de mi curso de onboarding y dime qué evaluación demuestra cada objetivo."
+    why: "Spanish: structure the curriculum and map assessment to each objective — outcomes + alignment."
+  - prompt: "Map my existing modules to outcomes — I want to check the course is actually aligned and nothing is orphaned."
+    why: "Alignment matrix / constructive-alignment check; orphan-module and unproven-outcome detection is the emitted artifact."
+  - prompt: "Dissenya el pla docent d'un taller de 2 hores sobre Git per a principiants i quina avaluació demostra cada objectiu."
+    why: "Catalan: design the syllabus for a short workshop and the assessment per objective — grounding + right-sized scope + alignment."
+
+should_not_trigger:
+  - prompt: "This module on indexing is correct but students nod and forget it — make it land with a story and a sticky name."
+    route_to: course-storytelling
+    why: "Narrative landing of a single concept (epiphany, sticky name), not the skeleton/structure."
+  - prompt: "Audit module 14 of my finished course for gaps, redundancy, and outdated references, with a written report."
+    route_to: review
+    why: "Diagnostic content-audit pass over finished material, not design-from-intent."
+  - prompt: "Turn my designed module into a polished slide deck with speaker notes."
+    route_to: presentations
+    why: "Slides/visuals from an already-designed module, not the learning structure."
+  - prompt: "Write the landing-page copy and launch emails to sell my course."
+    route_to: marketing
+    why: "Sales/launch copy, not the learning contract."
+  - prompt: "Document the exact repeatable steps our support team follows to process a refund."
+    route_to: sop-builder
+    why: "A repeatable procedure with steps but no outcomes/assessment — an SOP, not a course."
+
+capability:
+  - scenario: >
+      A user gives a learner profile (junior dev who can write small scripts but has never built a
+      web API) and a goal ("ship a small REST API"), in a 2-week self-paced format, and asks
+      course-builder to design the course.
+    must_include:
+      - "Works backward: defines measurable outcomes (Bloom verbs in ABCD form) BEFORE any module or content."
+      - "Bans vanity verbs — no 'understand'/'know'; outcomes are observable ('build', 'deploy', 'debug')."
+      - "Designs assessment that PROVES each outcome, with BOTH formative checkpoints and a summative artifact."
+      - "Verb-matches: the assessment requires the same verb as the outcome (constructive alignment), not a recall quiz for a 'build' outcome."
+      - "Sequences modules in prerequisite order, each module mapped to >=1 outcome (no orphan modules, no unproven outcomes)."
+      - "Respects self-paced format: formative checks self-grade (auto-graded quiz / a test that runs); right-sizes outcome count to 2 weeks."
+      - "Emits an outcome x module x assessment alignment matrix as the artifact."
+      - "Hands off narrative landing to course-storytelling rather than doing the storytelling here."

package/skills/course-builder/references/assessment-design.md

@@ -0,0 +1,74 @@
+# Assessment design
+
+Assessment is the proof that an outcome was achieved — not a grade-generating afterthought. The
+backward-design question for every outcome is: *what would I have to SEE the learner do to believe
+this outcome is met?* That sight IS the assessment. This file is the formative↔summative menu, the
+content-validity check, and the verb-match rule worked end to end.
+
+## Formative vs summative — different jobs
+
+```text
+                  Formative (DURING learning)        Summative (AT THE END)
+Purpose           feedback; guide improvement        certify mastery; accountability
+Stakes            low / none                         high — the grade, the certificate
+When              throughout each module             after the module / the course
+Owner of action   the learner adjusts                the institution decides
+Examples          quizzes, skill checklists,         capstone project, final exam,
+                  drafts + revision, peer review,     portfolio, graded build, defense
+                  exit tickets, self-checks
+```
+
+A course needs both. Summative-only gives the learner no chance to course-correct; formative-only
+never certifies the contract was met.
+
+## Assessment type mapped to Bloom level
+
+Match the assessment to where the outcome's verb sits. A quiz can't prove "build".
+
+```text
+Outcome level     Formative options              Summative options
+Remember          flashcards, recall quiz        section of a written exam
+Understand        explain-back, concept map      short-answer / explanation exam
+Apply             guided exercise, lab drill     applied problem set, practical task
+Analyze           debug drill, code review        case analysis, diagnostic task
+Evaluate          peer review w/ rubric          critique + justification, defense
+Create            draft + feedback cycles        capstone build / portfolio / project
+```
+
+## The verb-match rule, worked
+
+Constructive alignment (Biggs): the verb in the outcome must be the verb the learner *performs* in
+the assessment. Walk it through:
+
+```markdown
+Outcome:    Given a spec, the learner BUILDS a REST endpoint that returns the correct
+            status code for 3 named error cases.   (verb = build, level = Create)
+
+Wrong assessment:  A 10-question multiple-choice quiz on HTTP status codes.
+Why wrong:         the learner RECALLS (Remember). Recall ≠ build. It proves a different,
+                   lower outcome — the contract is unverified.
+
+Right assessment:  The learner ships a working endpoint; a test run hits all 3 error
+                   cases and asserts the status codes.  (verb performed = build)
+```
+
+If you find yourself assessing with a quiz an outcome that says "design" / "build" / "evaluate",
+that's the mismatch anti-pattern — fix the assessment, not the outcome.
+
+## Content-validity / blueprint check
+
+Competency-based design certifies *demonstrated mastery*, not seat time, and the assessment set must
+have **content validity**: it covers the breadth of the outcomes and aligns with them. Build a
+one-row-per-outcome blueprint and confirm:
+
+```text
+[ ] Every course-level outcome has at least one assessment that requires its verb.
+[ ] No outcome is over-weighted (one vanity exam carrying the whole grade).
+[ ] No outcome is under-assessed (touched once, in passing, never certified).
+[ ] Both formative AND summative evidence exist across the course.
+[ ] The summative assessment(s) together cover all course-level outcomes.
+[ ] Self-paced? Every formative check grades itself (auto-graded / a test that runs).
+```
+
+When the blueprint has no gaps and no over-weighting, the assessment plan is content-valid and the
+outcomes are provable. That blueprint feeds straight into the alignment matrix in SKILL.md.