swe-workflow-skills 0.9.0 → 0.10.0

package/README.md

@@ -6,76 +6,29 @@
 [![license: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
 
 A curated library of **66 Claude Code Agent Skills** that walk Claude through the
-software lifecycle the way a disciplined senior engineer would — planning, design,
+software lifecycle the way a disciplined senior engineer would: planning, design,
 TDD, review, security, deployment, incidents, and the project-management work around
 them.
 
-Each skill encodes a *method* (DRY, YAGNI, KISS, clean architecture, evidence-before-done),
-not just a task. They compose into end-to-end workflows and are kept honest by an
-LLM-as-judge eval harness.
+Each skill encodes a *method* (DRY, YAGNI, KISS, clean architecture, evidence before
+"done"), not just a task. An orchestrator skill, **`skill-router`**, matches your intent
+to the right skills and chains them across phases. Every skill is kept honest by an
+**LLM-as-judge evaluation harness** that compares the model with and without the skill.
 
 ![skill-router routing a live session](docs/demo/routing.gif)
 
-## Why this library
-
-Not just a pile of skills — a routing layer over Claude Code's native skill
-activation, an eval discipline, and full-SDLC breadth that popular collections
-don't cover:
-
-- **An orchestrator, not auto-trigger roulette.** A `skill-router` skill maps your
-  intent to the right skill(s) and chains them across phases. Community measurements put
-  Claude's own description-based auto-triggering at roughly a coin flip to ~84%; here
-  activation is *routed and deterministic* instead, and the routing eval harness measures
-  it (top-1 accuracy 65/65 and one boundary misroute in 65 on the committed k=3 baseline,
-  regression-gated in CI) — see the [routing benchmark](docs/ROUTING-BENCHMARK.md). This is the one thing the
-  platform still doesn't do for you.
-- **Every skill stays reachable, no pre-picking.** Claude Code injects skill descriptions
-  only up to ~1% of context, so large libraries silently stop auto-triggering past ~20–40
-  skills. The fix is Claude Code's own **`name-only`** state (its docs recommend it for
-  low-priority skills); this library just applies it wholesale — keeping the router +
-  safety skills "loud" and listing the rest name-only — so the router can still invoke
-  every skill by name, with no cropping and without making you pre-pick a subset
-  ([how it works](docs/ROLES.md)).
-- **Tested like code, not prose.** Every skill ships 3 evals; two LLM-as-judge
-  harnesses (content quality and routing accuracy) replay them with skill loaded vs
-  absent and gate regressions in CI. Across all 66 skills — 234 cases, 1315 assertions,
-  every row measured at k>=3 — the same model passes **64.1%** of assertions without the
-  skill's content and **97.9%** with the skill loaded, and **no skill scores below the
-  no-content baseline on any case**
-  ([results](docs/EVALS.md#results-content-evals-full-catalog)). Safety-critical skills
-  (deploys, releases, tests, incidents, security) are **hardened**: an Iron Law, a
-  rationalization table distilled from real baseline failures, and pressure tests that
-  try to talk the agent out of it.
-- **Curated, not a mega-catalog.** First-party skills, versioned and eval-gated in the
-  repo — no arbitrary third-party skills pulled from a hub, and nothing that executes on
-  its own (the content is instructions and templates; the only code is the open Node
-  installer). In an ecosystem where researchers have flagged hundreds of malicious
-  community skills, curated-and-reviewed is itself a feature — see [SECURITY.md](SECURITY.md).
-- **Full-SDLC breadth.** Planning, architecture/ADRs, API and data design, TDD, review,
-  security, releases, deploys, GitOps, observability, incidents, MLOps, LLM apps
-  and AI evaluation, data pipelines and data quality, and the PM/strategy work
-  around them — a wider slice of the lifecycle than the community collections we
-  know of aim for (they tend to go deep on the coding inner loop; see
-  [Acknowledgements](#acknowledgements)).
-- **Role-scoped.** `/role backend` (or `frontend`, `devops`, `ml`, `ai`, `data`,
-  `data-scientist`, `security`, `architect`, `em`, `pm`, `strategy`, `qa`, `mobile`,
-  `designer`) promotes a working set to auto-trigger; the rest stay one route away.
-- **Cross-platform install.** The installer and SessionStart hook are **pure Node** — the
-  one runtime Claude Code already requires — so they run identically on Linux, macOS, and
-  Windows (no bash, Python, or `sed`).
-
 ## Quick Start
 
-**Most people — install the per-role plugin for your hat** (works on CLI, Claude Code
-web, claude.ai chat, and Cowork):
+**Most people: install the per-role plugin for your hat.** It works on the CLI, Claude
+Code web, claude.ai chat, and Cowork:
 
 ```text
 /plugin marketplace add SWEStash/swe-workflow-skills
 /plugin install swe-workflow-pm@swe-workflow
 ```
 
-**Want the whole library with the orchestrator** (CLI) — no clone needed. This is a
-**two-step** setup:
+**Want the whole library with the orchestrator?** On the CLI, with no clone needed, it
+is a **two-step** setup:
 
 ```bash
 # 1. Install all 66 skills + router + /role + the hook script, and apply the baseline
@@ -84,16 +37,16 @@ npx swe-workflow-skills install --global
 
 ```jsonc
 // 2. Wire the hook: merge the snippet the installer prints into your settings.json
-//    (the installer never edits settings.json for you — it just prints the block).
+//    (the installer never edits settings.json for you; it just prints the block).
 //    Then start a new session; /doctor should show the hook registered.
 { "hooks": { "SessionStart": [ /* ...the printed block... */ ] } }
 ```
 
 > ⚠️ **Don't skip step 2.** Step 1 alone installs the skills and prevents cropping, but
-> the hook is what nudges Claude to consult `skill-router` first — **without it, skills
-> won't auto-route** (the whole point of the library) and the baseline isn't re-asserted
+> the hook is what nudges Claude to consult `skill-router` first. **Without it, skills
+> won't auto-route** (the whole point of the library), and the baseline isn't re-asserted
 > after `/compact`. If you deliberately want no hook, pass `--no-hook`; auto-routing stays
-> off until a hook is wired. The **per-role plugin** path above needs no hook — it's
+> off until a hook is wired. The **per-role plugin** path above needs no hook: it is
 > self-contained.
 
 Or from a clone: `node install.mjs --global`.
@@ -119,20 +72,20 @@ npx swe-workflow-skills uninstall --dry-run   # preview removal; --global/--dir
 
 From a clone, the same commands are `node install.mjs …` / `node uninstall.mjs …`.
 
-The installer never edits `settings.json` — it prints the SessionStart hook snippet for
+The installer never edits `settings.json`: it prints the SessionStart hook snippet for
 you to merge. Re-running is idempotent. See **[INSTALL-MATRIX.md](docs/INSTALL-MATRIX.md)**
 for every method × surface, and **[ROLES.md](docs/ROLES.md)** for the activation model.
 
 ## Usage
 
-On any non-trivial task, Claude consults **`skill-router`** first; it reads the full
+On any non-trivial task, Claude consults **`skill-router`** first. It reads the full
 catalog and invokes the matching skill(s) by name, re-routing as the work changes phase.
-The default SessionStart hook nudges Claude to do this automatically; you can also route
-explicitly ("use the security-audit skill") or switch the promoted set with `/role`. Don't
-want a particular skill routed at all? `npx swe-workflow-skills disable <skill>` opts it out
-durably — see [disable a skill from routing](docs/ROLES.md#advanced-disable-a-skill-from-routing).
+The default SessionStart hook nudges Claude to do this automatically. You can also route
+explicitly ("use the security-audit skill") or switch the promoted set with `/role`.
+Don't want a particular skill routed at all? `npx swe-workflow-skills disable <skill>`
+opts it out durably; see [disable a skill from routing](docs/ROLES.md#advanced-disable-a-skill-from-routing).
 
-**A routed chain, by phase** — e.g. *"add OAuth login"*:
+**A routed chain, by phase**, e.g. *"add OAuth login"*:
 
 ```
 feature-planning      →  scope tasks, acceptance criteria, risks
@@ -146,16 +99,37 @@ verification-before-completion
 deployment-checklist  →  pre-deploy safety + rollback readiness
 ```
 
-The router invokes each skill as you reach its phase rather than all at once. A single
-request often fans out to several skills — *"review this for accessibility and UX"* pulls
-in both `accessibility-design` and `ui-ux-design`. See a full session play out in
-**[what routing looks like](docs/ROLES.md#what-routing-looks-like-in-a-session)**; the
-pre-built chains (new feature · bug/incident · continuous improvement · pre-public
-review) live in the `skill-router` skill and **[ROLES.md](docs/ROLES.md)**.
+The router invokes each skill as you reach its phase rather than all at once, and one
+request can fan out to several skills. See a full session in
+**[what routing looks like](docs/ROLES.md#what-routing-looks-like-in-a-session)**.
+
+## Why this library
+
+- **An orchestrator, not auto-trigger roulette.** Description-based auto-triggering is
+  probabilistic. Here `skill-router` routes intent to skills by name, and a routing
+  harness measures it: 65/65 top-1 and 64/65 on boundary cases on the committed k=3
+  baseline ([routing benchmark](docs/ROUTING-BENCHMARK.md)).
+- **Every skill stays reachable.** Claude Code lists skill descriptions only up to about
+  1% of context, so large libraries stop auto-triggering past 20 to 40 skills. This
+  library keeps the router and safety skills fully listed and the rest **`name-only`**
+  (Claude Code's own setting for low-priority skills), so every skill is one route away
+  with no pre-picking ([how it works](docs/ROLES.md)).
+- **Tested like code, not prose.** Across 234 eval cases and 1323 assertions, the same
+  model passes **63.6%** of assertions without the skill's content and **97.9%** with
+  it, and **no case scores lower with the skill** ([results](docs/EVALS.md#results-content-evals-full-catalog)).
+  Safety-critical skills are **hardened** with an Iron Law, a rationalization table, and
+  pressure tests.
+- **Curated, not a mega-catalog.** First-party and reviewed. Nothing executes on its own
+  except the open Node installer ([SECURITY.md](SECURITY.md)).
+- **Full-SDLC breadth, role-scoped.** From planning to incidents, plus MLOps, LLM apps,
+  data, and PM work. `/role backend` (or any of 15 roles) promotes a working set to
+  auto-trigger.
+- **Cross-platform.** The installer and hook are pure Node, so they run the same on
+  Linux, macOS, and Windows.
 
 ## What's included
 
-66 skills — **[full catalog → SKILLS.md](docs/SKILLS.md)**:
+66 skills, listed in the **[full catalog → SKILLS.md](docs/SKILLS.md)**:
 
 | Area | Count | Examples |
 |------|-------|----------|
@@ -171,31 +145,29 @@ review) live in the `skill-router` skill and **[ROLES.md](docs/ROLES.md)**.
 | Evaluation & Monitoring | 2 | observability-design, test-data-strategy |
 | Meta | 2 | skill-router, writing-skills |
 
-## Documentation
+## Evaluation
 
-- **[ROLES.md](docs/ROLES.md)** — the activation model (name-only baseline, roles, the orchestrator) and the CLI vs web/plugin paths.
-- **[INSTALL-MATRIX.md](docs/INSTALL-MATRIX.md)** — every install method × surface, side by side.
-- **[SKILLS.md](docs/SKILLS.md)** — the full skill catalog by area.
-- **[EVALS.md](docs/EVALS.md)** — how the skills are tested (RED/GREEN, pressure tests, CI gate).
-- **[ROUTING-BENCHMARK.md](docs/ROUTING-BENCHMARK.md)** — the routing reliability numbers, methodology, and how to reproduce them.
-- **[AUTHORING.md](docs/AUTHORING.md)** — write or modify a skill (descriptions, budget, progressive disclosure, evals).
-- **[RELEASING.md](docs/RELEASING.md)** — versioning policy and how to cut a release. Changes are tracked in **[CHANGELOG.md](CHANGELOG.md)**.
-- **[SECURITY.md](SECURITY.md)** — the security model: trust boundaries, what runs automatically, supply-chain guarantees, and how to report a vulnerability.
+Every skill ships 3 evals (happy path, edge case, scope boundary), and safety skills add
+pressure tests. Each case is replayed with the skill loaded (GREEN) and without it (RED),
+and a skeptical LLM-as-judge grades every assertion. Evals run in-session through
+`evals/workflow-runner.mjs`, with no API key, and the results are committed to
+`evals/baseline.json`. Merging a re-run reports any assertion that regressed. Full guide
+in **[EVALS.md](docs/EVALS.md)**.
 
-## Evaluation
+## Documentation
 
-Each skill carries an `evals/` directory; safety/discipline skills add a `pressure_tests`
-block. Two runners replay scenarios through Claude (skill loaded = GREEN, absent = RED)
-and judge each assertion with a skeptical LLM-as-judge: `evals/workflow-runner.mjs`
-(in-session, no API key) and `evals/run.py` (CI regression gate, wired into
-`.github/workflows/skill-evals.yml`). The GREEN arm reads the skill *and* the
-`references/`/`templates/` files it links to, so improving a reference file moves the
-score. The first runner writes `evals/baseline.json`; the second gates against it.
-Full guide in **[EVALS.md](docs/EVALS.md)**.
+- **[ROLES.md](docs/ROLES.md)**: the activation model (name-only baseline, roles, the orchestrator) and the CLI vs web/plugin paths.
+- **[INSTALL-MATRIX.md](docs/INSTALL-MATRIX.md)**: every install method × surface, side by side.
+- **[SKILLS.md](docs/SKILLS.md)**: the full skill catalog by area.
+- **[EVALS.md](docs/EVALS.md)**: how the skills are tested (RED/GREEN, pressure tests, the regression baseline).
+- **[ROUTING-BENCHMARK.md](docs/ROUTING-BENCHMARK.md)**: the routing reliability numbers, methodology, and how to reproduce them.
+- **[AUTHORING.md](docs/AUTHORING.md)**: write or modify a skill (descriptions, budget, progressive disclosure, evals).
+- **[RELEASING.md](docs/RELEASING.md)**: versioning policy and how to cut a release. Changes are tracked in **[CHANGELOG.md](CHANGELOG.md)**.
+- **[SECURITY.md](SECURITY.md)**: the security model, what runs automatically, supply-chain guarantees, and how to report a vulnerability.
 
 ## Contributing
 
-New or improved skills are welcome — start with **[AUTHORING.md](docs/AUTHORING.md)** (or
+New or improved skills are welcome. Start with **[AUTHORING.md](docs/AUTHORING.md)** (or
 install the `writing-skills` skill). The short version: descriptions are everything, keep
 SKILL.md concise with detail in `references/`, and ship exactly 3 evals.
 
@@ -203,23 +175,23 @@ SKILL.md concise with detail in `references/`, and ship exactly 3 evals.
 
 This library stands on ideas from projects we found genuinely useful:
 
-- **[obra/superpowers](https://github.com/obra/superpowers)** — the guardrail pattern
+- **[obra/superpowers](https://github.com/obra/superpowers)**: the guardrail pattern
   our hardened safety skills adopt (an Iron Law, a rationalization table distilled from
   real failures, and pressure tests that try to talk the agent out of it) comes from
   Jesse Vincent's work here, as does the idea of a Socratic brainstorming skill as the
   entry point to a feature. Superpowers goes deeper on the coding inner loop than we do;
   if that's what you want, use it.
-- **[anthropics/skills](https://github.com/anthropics/skills)** — Anthropic's official
+- **[anthropics/skills](https://github.com/anthropics/skills)**: Anthropic's official
   skills (and `skill-creator` in particular) are the authoring practice we benchmark
   ours against; the eval-first loop in [AUTHORING.md](docs/AUTHORING.md) follows the
   same instinct.
 - **The [Agent Skills docs](https://code.claude.com/docs/en/skills) and Anthropic's
-  engineering posts** — progressive disclosure, the listing budget, and the
+  engineering posts**: progressive disclosure, the listing budget, and the
   `name-only` + `skillOverrides` activation surface this library's routing model is
   built on.
-- **The awesome-claude-skills community lists** — the ecosystem survey that shaped our
+- **The awesome-claude-skills community lists**: the ecosystem survey that shaped our
   gap analysis of what a full-SDLC library should cover.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT, see [LICENSE](LICENSE).

package/VERSION

@@ -1 +1 @@
-0.9.0
+0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A curated library of Claude Code Agent Skills covering the full software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
   "type": "module",
   "bin": {

package/skills/ai-evaluation/evals/evals.json

@@ -10,7 +10,8 @@
         "Covers the RAG triad or equivalent — faithfulness/groundedness, answer relevance, and retrieval/context quality — and distinguishes retrieval metrics from generation metrics",
         "Recommends a concrete evaluation tool (ragas, deepeval, or promptfoo) and explains its role",
         "Addresses LLM-as-judge reliability with at least one concrete measure: rubric design, position/self-preference bias, majority voting, or calibrating the judge against human spot-checks",
-        "Proposes running the evals as a repeatable regression gate (in CI or before each prompt/pipeline change), not only as a one-off pre-launch check"
+        "Proposes running the evals as a repeatable regression gate (in CI or before each prompt/pipeline change), not only as a one-off pre-launch check",
+        "Specifies the judge rubric as a separate score per quality criterion on a binary or 3-point scale, rather than one overall score such as 1–10"
       ]
     },
     {

package/skills/configuration-strategy/evals/evals.json

@@ -11,7 +11,8 @@
         "Suggests percentage-based rollout for the feature flag",
         "Warns against committing any credential to version control",
         "Recommends startup validation to fail fast if secrets are missing",
-        "Notes different values needed for dev/staging/production"
+        "Notes different values needed for dev/staging/production",
+        "Before adding the new keys, establishes what configuration already exists (existing keys or values, .env.example, config conventions), or says it cannot inspect the project and names what it would check"
       ]
     },
     {

package/skills/data-modeling/evals/evals.json

@@ -12,7 +12,8 @@
         "Includes indexes for common access patterns (order lookup by user, product search)",
         "Foreign keys have explicit ON DELETE behavior",
         "Includes created_at/updated_at timestamps",
-        "Validates schema against likely access patterns"
+        "Validates schema against likely access patterns",
+        "Before proposing tables, establishes what schema already exists, or says it is treating the project as greenfield or cannot inspect it and names what it would check"
       ]
     },
     {

package/skills/performance-optimization/evals/evals.json

@@ -13,7 +13,8 @@
         "Suggests computing averageRating in the database query, not in application code",
         "Does NOT start with micro-optimizations (variable names, array methods)",
         "Provides concrete refactored code",
-        "Suggests adding an index on reviews.productId if not present"
+        "Suggests adding an index on reviews.productId if not present",
+        "Orders the fixes explicitly by impact relative to effort, putting the highest payoff for the least work first"
       ]
     },
     {
@@ -38,9 +39,10 @@
         "Identifies the algorithmic complexity (O(n²) from nested loops, O(n) from includes)",
         "Explains WHY this is slow for large arrays",
         "Refactors to a single O(n) pass using hashed lookups — a Map or object counting occurrences, or a Set of emails already seen",
-        "Uses a Set for the duplicates result (not includes() on an array)",
+        "Removes the includes() scan over the result list: collects duplicates in a Set, or reads them off a Map of counts",
         "Notes the repeated toLowerCase() calls as a secondary optimization",
-        "Provides working refactored code"
+        "Provides working refactored code",
+        "Says to confirm before shipping that the rewrite returns the same results as the original (its tests, or a side-by-side comparison on realistic input), not only that it is faster"
       ]
     }
   ]

package/skills/plan-execution/evals/evals.json

@@ -22,7 +22,8 @@
         "Stops executing the affected phases instead of silently improvising a different approach under the old plan",
         "Explicitly triggers re-planning for the affected phases, involving the user or the feature-planning workflow",
         "Preserves and does not discard the completed, verified work from earlier phases",
-        "Communicates the drift, its impact on the remaining plan, and the options — rather than quietly continuing"
+        "Communicates the drift, its impact on the remaining plan, and the options — rather than quietly continuing",
+        "Routes the structural question the plan did not answer (such as where queued, in-flight or failed writes are stored) to data-modeling or architecture-design rather than settling it inline"
       ]
     },
     {

package/skills/subagent-orchestration/evals/evals.json

@@ -22,7 +22,8 @@
         "Recommends fixing the shared contract/conventions first, before any fan-out, rather than gluing independently-designed pieces afterward",
         "Explains the failure mode: parallel agents without a shared contract produce incompatible outputs and costly reconciliation",
         "Offers a legitimate parallel structure instead — e.g. per-resource spec drafting against the fixed contract, or a multi-perspective review/judge panel of a single draft",
-        "Does not simply execute the 6-way split as requested"
+        "Does not simply execute the 6-way split as requested",
+        "Notes that subagents cannot ask clarifying questions mid-flight, so open questions must be resolved before any fan-out"
       ]
     },
     {

package/skills/verification-before-completion/evals/evals.json

@@ -19,7 +19,8 @@
       "assertions": [
         "Treats the prior CI run as stale, not as fresh evidence",
         "Does not rubber-stamp the merge on the 'only a comment' rationalization",
-        "Bases the go/no-go on the fresh output"
+        "Bases the go/no-go on the fresh output",
+        "Counts the static gates the repo configures (type checker, linter) as part of the fresh check, not the test suite alone"
       ]
     },
     {

package/skills/writing-skills/SKILL.md

@@ -320,5 +320,5 @@ Full policy: docs/AUTHORING.md § Obsolescence review.
 
 - docs/AUTHORING.md — the canonical rules and common mistakes.
 - [references/pressure-testing.md](references/pressure-testing.md) — running baseline scenarios and the pressure levers.
-- `docs/EVALS.md` — the automated RED/GREEN harness that replays evals through subagents and gates regressions in CI.
+- `docs/EVALS.md` — the automated RED/GREEN harness that replays evals through subagents and checks regressions against a committed baseline.
 - `verification-before-completion` — the discipline that proves a skill change works (run the eval, read the result).