swe-workflow-skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SWEStash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# SWE Workflow Skills for Claude Code
+
+[![roles-check](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml/badge.svg)](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml)
+![skills](https://img.shields.io/badge/skills-44-blue)
+[![license](https://img.shields.io/github/license/SWEStash/swe-workflow-skills)](LICENSE)
+
+A curated library of **44 Claude Code Agent Skills** that walk Claude through the
+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.
+
+![skill-router routing a live session](docs/demo/routing.gif)
+
+## Why this library
+
+- **An orchestrator, not a pile of skills.** A `skill-router` skill maps your intent to
+  the right skill(s) and chains them across phases. Activation is *routed and
+  deterministic*, not left to fuzzy auto-triggering.
+- **Scales past Claude's skill-listing budget.** Claude Code only injects skill
+  descriptions up to ~1% of context, so large libraries silently stop triggering past
+  ~20–40 skills. This library keeps only the router + safety skills "loud" and lists the
+  rest **name-only** — so the router can invoke all 44 by name, with no cropping and
+  without making you pre-pick a subset ([how it works](docs/ROLES.md)).
+- **Role-scoped.** `/role backend` (or `frontend`, `devops`, `ml`, `security`,
+  `architect`, `em`, `pm`, `qa`, `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`).
+- **Tested.** Every skill ships 3 evals; safety/discipline skills add pressure tests.
+
+## Quick Start
+
+**Most people — install the per-role plugin for your hat** (works on 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:
+
+```bash
+npx swe-workflow-skills install --global   # all 44 skills + router + /role + the SessionStart hook
+```
+
+Or from a clone: `node install.mjs --global`.
+
+> **Prerequisite:** Node.js ≥ 18 (already present wherever Claude Code runs).
+
+## Installation
+
+Two supported paths, chosen by what your environment can run:
+
+| Path | What you get | Works on |
+|------|--------------|----------|
+| **Per-role plugin** (above) | your role's crop-safe subset, auto-triggering | CLI · Code web · claude.ai chat · Cowork |
+| **`npx swe-workflow-skills`** | the full library + orchestrator + `/role` + hook | CLI · Cowork |
+
+```bash
+npx swe-workflow-skills install               # all skills -> ./.claude/ (project-local)
+npx swe-workflow-skills install --global      # -> user config dir ($CLAUDE_CONFIG_DIR or ~/.claude)
+npx swe-workflow-skills install --role pm     # a lean hard subset (just the PM skills)
+npx swe-workflow-skills install --no-hook     # skip the SessionStart hook (baseline still applied)
+npx swe-workflow-skills uninstall --dry-run   # preview removal; --global/--dir mirror install
+```
+
+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
+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
+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`.
+
+**A routed chain, by phase** — e.g. *"add OAuth login"*:
+
+```
+feature-planning      →  scope tasks, acceptance criteria, risks
+architecture-design   →  ADR: session vs token, where auth lives
+data-modeling         →  user/session schema + migration
+tdd-workflow          →  red-green-refactor the implementation
+security-audit        →  authn/authz, token handling, OWASP pass
+code-reviewing        →  DRY/KISS/SRP + conventions
+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)**.
+
+## What's included
+
+44 skills — **[full catalog → SKILLS.md](docs/SKILLS.md)**:
+
+| Area | Count | Examples |
+|------|-------|----------|
+| Software Engineering | 23 | feature-planning, architecture-design, tdd-workflow, code-reviewing, security-audit, refactoring, incident-response |
+| Project Management | 6 | prd-writing, effort-estimation, metrics-and-okrs, retrospective, strategic-review |
+| DevOps | 5 | containerization, cicd-pipeline, infrastructure-as-code, gitops-delivery |
+| Design | 3 | ui-ux-design, frontend-architecture, accessibility-design |
+| MLOps | 3 | ml-pipeline-design, ml-experiment-tracking, ml-model-deployment |
+| Evaluation & Monitoring | 2 | observability-design, test-data-strategy |
+| Meta | 2 | skill-router, writing-skills |
+
+## Documentation
+
+- **[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).
+- **[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)**.
+
+## Evaluation
+
+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`). Full guide in **[EVALS.md](docs/EVALS.md)**.
+
+## Contributing
+
+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.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/VERSION

@@ -0,0 +1 @@
+0.1.0

package/bin/cli.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// swe-workflow-skills — npm CLI entry point. Dispatches subcommands to the
+// installer/uninstaller so `npx swe-workflow-skills install` reads naturally.
+// Runs on Linux, macOS, and Windows (the one runtime Claude Code already requires).
+//
+//   npx swe-workflow-skills install [--global|--dir DIR|--role R|--no-hook|...]
+//   npx swe-workflow-skills uninstall [--global|--dir DIR|--dry-run|--yes]
+
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const [sub, ...rest] = process.argv.slice(2);
+
+const HELP = `swe-workflow-skills <command> [options]
+
+Commands:
+  install      Install skills into a Claude config dir (passes flags to install.mjs)
+  uninstall    Remove the library (passes flags to uninstall.mjs)
+
+Examples:
+  npx swe-workflow-skills install --global
+  npx swe-workflow-skills install --role pm
+  npx swe-workflow-skills uninstall --global --dry-run
+
+Run a command with --help to see its full option list.`;
+
+if (sub === "install" || sub === "uninstall") {
+  const script = join(ROOT, sub === "install" ? "install.mjs" : "uninstall.mjs");
+  // stdio inherited so install output and uninstall's confirm prompt pass through.
+  const res = spawnSync(process.execPath, [script, ...rest], { stdio: "inherit" });
+  process.exit(res.status ?? 1);
+} else if (sub === "-v" || sub === "--version" || sub === "version") {
+  process.stdout.write(readFileSync(join(ROOT, "VERSION"), "utf-8"));
+  process.exit(0);
+} else if (!sub || sub === "-h" || sub === "--help" || sub === "help") {
+  process.stdout.write(HELP + "\n");
+  process.exit(sub ? 0 : 1); // bare invocation is a usage error; explicit help is success
+} else {
+  process.stderr.write(`Unknown command: ${sub}\n\n${HELP}\n`);
+  process.exit(1);
+}

package/catalog.json

@@ -0,0 +1,225 @@
+{
+  "version": 1,
+  "skills": [
+    {
+      "name": "accessibility-design",
+      "description": "Design and implement accessible web/mobile apps to WCAG 2.1/2.2 — semantic HTML, ARIA patterns, keyboard navigation, focus management, color contrast, screen readers, accessible forms. Triggers: accessibility, a11y, WCAG, screen reader, keyboard navigation, ARIA, focus management, color contrast, alt text, semantic HTML, tab order, focus trap, skip link, announce. Build it in, don't bolt it on.",
+      "path": "accessibility-design/SKILL.md"
+    },
+    {
+      "name": "api-design",
+      "description": "Design RESTful and GraphQL APIs — endpoint naming, request/response contracts, error handling, pagination, versioning, auth patterns, OpenAPI specs. Triggers: design the API, API contract, REST API, GraphQL schema, error response format, pagination, API versioning, OpenAPI, swagger, endpoints. Use architecture-design for REST-vs-GraphQL or monolith-vs-microservices decisions.",
+      "path": "api-design/SKILL.md"
+    },
+    {
+      "name": "architecture-design",
+      "description": "Guide architectural and structural decisions using Architecture Decision Records (ADRs) — new services, pattern choices, database selection, component boundaries, state management, costly-to-reverse decisions. Triggers: how should I architect, which pattern, design decision, should I use X or Y, system design, ADR, component design, architectural trade-off.",
+      "path": "architecture-design/SKILL.md"
+    },
+    {
+      "name": "architecture-documentation",
+      "description": "Design and maintain architecture documentation with multi-level diagrams (C4) and docs-as-code. Triggers: architecture diagram, document the architecture, C4 diagram, system context, container diagram, component diagram, architecture docs, docs-as-code, PlantUML, Structurizr, D2, Mermaid architecture, infrastructure diagram, runtime flow. Use architecture-design for ADRs.",
+      "path": "architecture-documentation/SKILL.md"
+    },
+    {
+      "name": "bug-investigating",
+      "description": "Systematic debugging and root cause analysis using structured methodology — reproduce, isolate, hypothesize, verify. Triggers: this doesn't work, I'm getting an error, something is broken, bug, debug this, why is this happening, unexpected behavior, regression, root cause, stack trace, error message.",
+      "path": "bug-investigating/SKILL.md"
+    },
+    {
+      "name": "cicd-pipeline",
+      "description": "Design CI/CD pipelines for automated build, test, deploy — GitHub Actions, GitLab CI, quality gates. Triggers: CI/CD, pipeline, GitHub Actions, GitLab CI, workflow, automated deployment, build pipeline, continuous integration, continuous deployment, automate tests on PR, deploy automatically, quality gate.",
+      "path": "cicd-pipeline/SKILL.md"
+    },
+    {
+      "name": "code-reviewing",
+      "description": "Structured code reviews enforcing DRY, KISS, YAGNI, SRP, best practices, and project conventions. Triggers: review this code, code review, check my code, what do you think of this implementation, review this PR, is this code good, feedback on my code, review staged changes before commit.",
+      "path": "code-reviewing/SKILL.md"
+    },
+    {
+      "name": "configuration-strategy",
+      "description": "Design environment configuration, secrets management, and feature-flag hierarchy for a service or feature. Triggers: config strategy, environment variables, .env, secrets management, feature flag, config hierarchy, config precedence, twelve-factor config, environment-specific settings.",
+      "path": "configuration-strategy/SKILL.md"
+    },
+    {
+      "name": "containerization",
+      "description": "Write production-grade Dockerfiles, docker-compose, and Kubernetes manifests following security and reliability best practices. Triggers: Dockerfile, docker-compose, containerize, Docker image, Kubernetes, k8s manifest, container, pod, deployment yaml, multi-stage build, docker build, image size, container security.",
+      "path": "containerization/SKILL.md"
+    },
+    {
+      "name": "data-modeling",
+      "description": "Design database schemas, relationships, indexes, and migration strategies — relational and document stores. Triggers: data model, schema design, ER diagram, database schema, table design, foreign key, index strategy, normalization, denormalization, migration plan, document model, partition key.",
+      "path": "data-modeling/SKILL.md"
+    },
+    {
+      "name": "dependency-impact-analysis",
+      "description": "Map the blast radius of a change before implementing — find dependents, classify breaking vs additive, identify coordination needs, produce a propagation plan. Triggers: what will break if I change this, blast radius, impact analysis, breaking change, who depends on this, downstream impact, safe to rename, shared schema change, dependency graph.",
+      "path": "dependency-impact-analysis/SKILL.md"
+    },
+    {
+      "name": "dependency-management",
+      "description": "Evaluate, audit, and upgrade project dependencies — assess libraries before adoption, audit CVEs, plan major upgrades, resolve conflicts. Triggers: should I use this library, npm audit, upgrade dependencies, dependency vulnerability, outdated packages, evaluate this package, is this library maintained, dependency conflict, lock file, breaking changes in upgrade.",
+      "path": "dependency-management/SKILL.md"
+    },
+    {
+      "name": "deployment-checklist",
+      "description": "Pre-deploy verification and release safety checks — config, migrations, monitoring, rollback readiness, comms. Triggers: deployment checklist, ready to deploy, pre-deploy, release checklist, go-live, ship checklist, deploy safety, is this safe to ship, release readiness.",
+      "path": "deployment-checklist/SKILL.md"
+    },
+    {
+      "name": "deployment-repo",
+      "description": "Design a deployment (GitOps) repo that orchestrates multiple services in a polyrepo — version pinning, environment promotion, compatibility matrices, system config. Triggers: deployment repo, GitOps repo, polyrepo, multi-repo, version pinning, compatibility matrix, environment promotion, multi-service deployment, orchestration repo, which versions work together.",
+      "path": "deployment-repo/SKILL.md"
+    },
+    {
+      "name": "effort-estimation",
+      "description": "Estimate engineering effort with agile techniques — story points, t-shirt sizing, three-point estimation, capacity planning. Triggers: estimate this, how long will this take, story points, t-shirt sizing, effort estimation, capacity planning, sprint planning, budget estimate, forecast, velocity, when will this be done.",
+      "path": "effort-estimation/SKILL.md"
+    },
+    {
+      "name": "feature-planning",
+      "description": "Break features into well-scoped tasks with acceptance criteria, risk assessment, and dependency mapping. Triggers: plan this, break this down, scope this feature, create tasks for, sprint planning, how should I implement this feature, user stories, acceptance criteria, dependency mapping, feature breakdown.",
+      "path": "feature-planning/SKILL.md"
+    },
+    {
+      "name": "frontend-architecture",
+      "description": "Design frontend architecture — React component hierarchy, state management, design tokens, data fetching, routing, error boundaries, code organization. Triggers: component architecture, state management, design system, design tokens, component library, React structure, folder structure, Zustand vs Redux, React Query, code splitting, error boundary, compound component.",
+      "path": "frontend-architecture/SKILL.md"
+    },
+    {
+      "name": "git-workflow",
+      "description": "Write commit messages, PR descriptions, and manage branching strategy following conventional commits. Triggers: write a commit message, commit this, PR description, pull request, branching strategy, git workflow, squash commits, rebase, conventional commits, how should I commit this, review staged changes.",
+      "path": "git-workflow/SKILL.md"
+    },
+    {
+      "name": "gitops-delivery",
+      "description": "Design GitOps continuous delivery with ArgoCD or Flux — declarative reconciliation, cross-repo CI/CD triggers, drift detection, progressive delivery. Triggers: ArgoCD, Flux, FluxCD, GitOps, git-based deployment, declarative delivery, auto-sync, drift detection, cross-repo trigger, reconciliation loop, pull-based deployment, canary GitOps.",
+      "path": "gitops-delivery/SKILL.md"
+    },
+    {
+      "name": "incident-response",
+      "description": "Structured production incident workflow — triage, mitigation, investigation, recovery, comms. Triggers: production is down, site is down, incident, outage, users seeing errors, on-call, alert fired, p0, p1, sev1, sev2, broken in prod, rollback, emergency deploy. For active incidents under time pressure.",
+      "path": "incident-response/SKILL.md"
+    },
+    {
+      "name": "infrastructure-as-code",
+      "description": "Write and review IaC with Terraform, CloudFormation, Pulumi, or CDK — modularity, security, state management. Triggers: Terraform, CloudFormation, Pulumi, infrastructure as code, IaC, provision, cloud resources, terraform module, state management, terraform plan, CDK, drift, remote state.",
+      "path": "infrastructure-as-code/SKILL.md"
+    },
+    {
+      "name": "metrics-and-okrs",
+      "description": "Define OKRs, KPIs, success metrics, and engineering health metrics (DORA). Triggers: OKR, KPI, metrics, success metrics, key results, objectives, measure success, DORA metrics, engineering metrics, velocity, cycle time, deployment frequency, how do we measure, what should we track.",
+      "path": "metrics-and-okrs/SKILL.md"
+    },
+    {
+      "name": "ml-experiment-tracking",
+      "description": "Design reproducible ML experiments — tracking, versioning, run comparison with MLflow, W&B, or DVC. Triggers: experiment tracking, MLflow, wandb, weights and biases, DVC, track experiments, compare models, hyperparameter, reproducibility, model registry, which model is better, experiment results, log metrics.",
+      "path": "ml-experiment-tracking/SKILL.md"
+    },
+    {
+      "name": "ml-model-deployment",
+      "description": "Deploy ML models to production — serving infrastructure, monitoring, drift detection, safe rollouts. Triggers: deploy model, serve model, model API, model monitoring, data drift, concept drift, model degradation, A/B test model, canary model, inference endpoint, prediction API, retrain trigger.",
+      "path": "ml-model-deployment/SKILL.md"
+    },
+    {
+      "name": "ml-pipeline-design",
+      "description": "Design reproducible ML training and data pipelines — ingestion, validation, feature engineering, training, evaluation, continuous training orchestration. Triggers: training pipeline, data pipeline, feature engineering, ETL for ML, continuous training, data validation, feature store, preprocessing, notebook to pipeline, orchestrate training, Airflow, Kubeflow, pipeline DAG.",
+      "path": "ml-pipeline-design/SKILL.md"
+    },
+    {
+      "name": "observability-design",
+      "description": "Design production observability — SLIs, SLOs, SLAs, error budgets, OpenTelemetry traces/metrics/logs, structured logging, alerting, dashboards. Triggers: SLO, SLI, SLA, error budget, observability, monitoring, OpenTelemetry, OTel, tracing, distributed tracing, structured logging, alerting, dashboard, metrics, correlation ID, alert fatigue.",
+      "path": "observability-design/SKILL.md"
+    },
+    {
+      "name": "performance-optimization",
+      "description": "Identify and resolve performance bottlenecks via static analysis — N+1 queries, algorithmic complexity, query optimization, caching, memory leaks, bundle size, connection management. Triggers: this is slow, optimize, performance, N+1, query optimization, caching, bundle size, memory leak, latency, response time, scale, bottleneck.",
+      "path": "performance-optimization/SKILL.md"
+    },
+    {
+      "name": "prd-writing",
+      "description": "Write lightweight agile PRDs and technical RFCs that align stakeholders before implementation. Triggers: PRD, product requirements, RFC, request for comments, technical design doc, design document, tech spec, write requirements, what are we building, spec this out. Produces the WHAT and WHY — feature-planning handles HOW.",
+      "path": "prd-writing/SKILL.md"
+    },
+    {
+      "name": "project-documentation",
+      "description": "Write and maintain project docs — README, contributing guides, API docs, changelogs, inline docs. Triggers: write a README, document this project, create documentation, contributing guide, changelog, API docs, how do I document, this needs docs, onboarding docs, JSDoc, docstrings.",
+      "path": "project-documentation/SKILL.md"
+    },
+    {
+      "name": "project-proposal",
+      "description": "Write lightweight project proposals for budget approval and go/no-go decisions — problem, business case, scope, rough estimates, risks, success criteria. Triggers: project proposal, project brief, business case, budget estimate, should we build this, go/no-go, risk assessment, cost-benefit, ROI, justify this project, stakeholder approval.",
+      "path": "project-proposal/SKILL.md"
+    },
+    {
+      "name": "project-review",
+      "description": "Review a built project's execution health before a milestone — scope alignment, roadmap / execution-plan adherence, implementation maturity (what's production-ready vs stub/deferred), and the evidence it actually works (tests, coverage, validation results, changelog). Triggers: project review, execution review, are we on track, implementation vs roadmap, scope drift, readiness review, what's actually built, validation results review, pre-launch review. Use strategic-review for vision/positioning/market; technical-debt-review for a pure code-health audit.",
+      "path": "project-review/SKILL.md"
+    },
+    {
+      "name": "refactoring",
+      "description": "Systematic code improvement via design principles, smell detection, and safe transformation patterns. Triggers: refactor this, clean this up, simplify this code, reduce complexity, extract this, this code is messy, tech debt, improve this code, code smell, rename, extract function, dead code.",
+      "path": "refactoring/SKILL.md"
+    },
+    {
+      "name": "retrospective",
+      "description": "Facilitate sprint retros, project post-mortems, and incident post-mortems with actionable, owned improvements. Triggers: retrospective, retro, post-mortem, postmortem, lessons learned, what went wrong, what went well, incident review, blameless, action items, sprint review, after action review.",
+      "path": "retrospective/SKILL.md"
+    },
+    {
+      "name": "rollback-strategy",
+      "description": "Design safe rollback plans before deploying — identify irreversible changes, classify rollback complexity, create tested undo procedures. Triggers: rollback plan, rollback strategy, how do I undo this, can we revert, what if the deploy fails, safe to deploy, feature flag rollout, blue-green, database migration rollback, irreversible change.",
+      "path": "rollback-strategy/SKILL.md"
+    },
+    {
+      "name": "security-audit",
+      "description": "Comprehensive security analysis — OWASP Top 10, auth/authz flows, injection vulnerabilities, data exposure, secrets detection, dependency CVEs, hardening recommendations. Triggers: security audit, vulnerability, is this secure, security review, pentest prep, OWASP, harden this, check for vulnerabilities, injection, XSS, CSRF, auth security.",
+      "path": "security-audit/SKILL.md"
+    },
+    {
+      "name": "skill-router",
+      "description": "Orchestrator and entry point for the swe-workflow skills library — consult FIRST when starting any non-trivial software task; most skills load name-only and only activate when invoked here. Triggers: starting a feature, planning, an architecture or design decision, implementing, debugging, reviewing, refactoring, testing, security, deployment, an incident, shipping, or unsure which skill fits. Routes intent to the right skill(s) and invokes them by name; shows the Golden Path chains.",
+      "path": "skill-router/SKILL.md"
+    },
+    {
+      "name": "strategic-review",
+      "description": "Review a project's strategic position before going public, launching, or raising — vision, mission, value proposition, scope positioning, the defensible wedge, and a live competitive / market comparative analysis. Triggers: strategic review, positioning, go public, go-to-market, market analysis, competitive landscape, value proposition, is there a moat, who are our competitors, platform absorption risk, market positioning, comparable products. Use project-review for execution/roadmap/implementation health; delegates deep market scans to deep-research.",
+      "path": "strategic-review/SKILL.md"
+    },
+    {
+      "name": "tdd-workflow",
+      "description": "Guide test-driven development with red-green-refactor. Triggers: use tdd, test first, write the tests, red green refactor, test-driven, what should I test, write tests before code, failing test, implement using TDD. For NEW code via test-first — use test-suite-design for adding tests to existing code.",
+      "path": "tdd-workflow/SKILL.md"
+    },
+    {
+      "name": "technical-debt-review",
+      "description": "Strategic codebase health assessment — identify hotspots, categorize debt, produce remediation roadmap. Triggers: technical debt, tech debt, debt review, codebase health, hotspots, debt assessment, remediation plan, what should we fix first, debt roadmap, code rot, legacy code audit.",
+      "path": "technical-debt-review/SKILL.md"
+    },
+    {
+      "name": "test-data-strategy",
+      "description": "Design and generate test data — factories, synthetic data, property-based testing, boundary analysis, contract testing, load scenarios, GDPR-safe data. Triggers: test data, synthetic data, fake data, factory, seed data, fixtures, property-based testing, fuzz testing, boundary values, contract testing, Pact, load test data, anonymize, GDPR test data.",
+      "path": "test-data-strategy/SKILL.md"
+    },
+    {
+      "name": "test-suite-design",
+      "description": "Design comprehensive test suites for existing code — strategy across unit/integration/e2e, fixtures, factories, helpers. Triggers: add tests, write tests for, increase coverage, test this module, testing strategy, test plan, what tests do I need, test infrastructure, test helpers, this has no tests. Not for TDD — use tdd-workflow.",
+      "path": "test-suite-design/SKILL.md"
+    },
+    {
+      "name": "ui-ux-design",
+      "description": "Design user experiences from an engineer's perspective — user flows, wireframes, interaction patterns, responsive strategy, navigation, loading/error/empty states. Triggers: design the UI, user flow, wireframe, how should this screen look, loading state, error state, empty state, responsive design, navigation, page layout, form design, mockup.",
+      "path": "ui-ux-design/SKILL.md"
+    },
+    {
+      "name": "verification-before-completion",
+      "description": "Evidence gate before claiming work is done, passing, fixed, or deployed. Use before saying 'done', 'it works', or 'tests pass', or before committing, pushing, or opening a PR. Triggers: is it done, did it work, tests pass, verify, ready to commit, before I push, confirm the fix. Run the proving command fresh and read its output first.",
+      "path": "verification-before-completion/SKILL.md"
+    },
+    {
+      "name": "writing-skills",
+      "description": "Use when authoring, editing, or reviewing a skill in this library — a new SKILL.md, one that under-triggers, or hardening an existing one. Covers description and listing-budget rules, frontmatter, progressive disclosure, the 3-eval rule, and pressure-testing against rationalizations. Triggers: write a skill, new skill, edit a skill, skill isn't triggering.",
+      "path": "writing-skills/SKILL.md"
+    }
+  ]
+}

package/commands/role.md

@@ -0,0 +1,34 @@
+---
+name: role
+description: "Switch the active swe-workflow role: promote that role's skills to auto-trigger (on) and send the rest to name-only. Usage: /role <name> to set, /role to show current + list, /role all (or none) to reset to baseline."
+argument-hint: [role]
+allowed-tools: Bash
+disable-model-invocation: true
+---
+
+The user is managing the active swe-workflow skill role. The requested role argument is: `$ARGUMENTS`
+
+Run this script exactly once via Bash, then report the result to the user concisely (the new active role, and that the change hot-reloads so it applies to the next prompt):
+
+```bash
+ROLE="$ARGUMENTS"
+RESOLVE="@@RESOLVE@@"; SKILLS="@@SKILLS@@"; SETTINGS="@@SETTINGS@@"
+ROLES="@@ROLES@@"; ACTIVE="@@ACTIVE_ROLE@@"
+export ROLES_JSON="$ROLES"
+if [ -z "$ROLE" ]; then
+  echo "Active role: $(cat "$ACTIVE" 2>/dev/null || echo 'baseline (none)')"
+  echo "Available roles:"; node "$RESOLVE" roles
+elif [ "$ROLE" = "all" ] || [ "$ROLE" = "none" ]; then
+  node "$RESOLVE" apply "$SETTINGS" "$SKILLS" none && rm -f "$ACTIVE"
+  echo "Reset to baseline — only the pinned skills auto-trigger now."
+elif node "$RESOLVE" label "$ROLE" >/dev/null 2>&1; then
+  node "$RESOLVE" apply "$SETTINGS" "$SKILLS" "$ROLE" && printf '%s\n' "$ROLE" > "$ACTIVE"
+  echo "Active role set to '$ROLE' — its skills now auto-trigger."
+else
+  echo "Unknown role '$ROLE'. Available roles:"; node "$RESOLVE" roles
+fi
+```
+
+Notes:
+- `skillOverrides` and the skill listing hot-reload when `settings.local.json` changes, so the new auto-trigger set takes effect on the next prompt without a restart.
+- This command is for the full (all-skills) CLI install. Hard-subset (`--role`) installs and the per-role marketplace plugins don't need it.

package/hooks/session-start.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// swe-workflow-skills — SessionStart hook (the activation baseline writer).
+//
+// The library uses a "name-only baseline": all skills are installed, but only a
+// pinned critical set (the skill-router orchestrator + safety skills) keeps its
+// description in context and auto-triggers. Everything else is listed name-only
+// (invocable, but not auto-triggered) so the listing never overflows the budget.
+//
+// On every session boundary (startup|resume|clear|compact) this hook:
+//   1. writes that baseline into <claude>/settings.local.json via resolve.mjs
+//      (promoting the active role's skills to "on" if a role is set), and
+//   2. emits reloadSkills:true so it applies to THIS session, plus a short nudge.
+//
+// settings.local.json `skillOverrides` and reloadSkills both hot-reload, so the
+// crop takes effect immediately. The listing is NOT re-injected after /compact,
+// which is why this must run on every boundary.
+//
+// Pure Node (the one runtime Claude Code guarantees on every OS). Register it as
+//   { "type": "command", "command": "node \"<path>/session-start.mjs\"" }
+// so it runs identically on Linux, macOS, and Windows.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = join(SCRIPT_DIR, "..", "skills");
+const SETTINGS = join(SCRIPT_DIR, "..", "settings.local.json");
+const ROLES_FILE = join(SKILLS_DIR, ".roles.json");
+
+const BASE = `This project has the swe-workflow skills library installed with a name-only
+baseline: only a few critical skills (the \`skill-router\` orchestrator plus the
+safety skills) keep their descriptions in context and auto-trigger. Every other
+skill is listed by name only — invocable, but it will NOT auto-trigger on its
+own. Routing through \`skill-router\` is the ONLY way those skills activate.
+
+Consult \`skill-router\` FIRST — as your very first action, before you explore or
+analyze the codebase, spawn subagents, plan, design, or make any Edit/Write — on
+any substantial software work: analysis, planning, a structural or data decision,
+implementing, debugging, reviewing, refactoring, or shipping. It reads the full
+catalog and invokes the right skill by name. Exploring or planning first and
+routing "once you understand the problem" is already too late — route, THEN
+explore under the chosen skill.
+
+Re-route on each new PHASE of work, not just at session start: when you pivot
+from analysis to implementing, to writing tests, to reviewing, or to shipping,
+consult \`skill-router\` again for that phase before you act. The skill for the new
+phase almost certainly isn't loaded yet — routing once at the start does not
+cover work you start an hour later.
+
+Route even when you already believe you know how to proceed — do NOT wait until
+you feel unsure, and do NOT talk yourself out of it because the task "looks like a
+one-liner," touches only one file, or seems obvious. Small structural changes
+(renames, config edits, dependency bumps) and anything that matches a specific
+skill's domain (accessibility, API design, security, data modeling, migrations,
+performance…) are exactly what the skills are for. When in doubt, route.
+
+Skip ONLY for genuinely trivial, conversational, or information-lookup replies,
+or when the user tells you not to use a skill or to "just do X" — the user's
+explicit instructions always take precedence.`;
+
+// Active role, if one was set (by install --role or the /role command).
+let role = "";
+const activeRoleFile = join(SKILLS_DIR, ".active-role");
+if (existsSync(activeRoleFile)) {
+  try {
+    role = readFileSync(activeRoleFile, "utf-8").replace(/\s+/g, "");
+  } catch {
+    role = "";
+  }
+}
+
+// Write the name-only baseline (promote pinned ∪ active-role to "on"). Best-effort:
+// if resolve.mjs / roles.json / skills aren't present, skip silently. resolve.mjs
+// is a sibling once installed; fall back to the repo location for in-tree runs.
+async function loadResolve() {
+  for (const p of [join(SCRIPT_DIR, "resolve.mjs"), join(SCRIPT_DIR, "..", "scripts", "resolve.mjs")]) {
+    if (existsSync(p)) return import(pathToFileURL(p).href);
+  }
+  return null;
+}
+
+function isDir(p) {
+  return existsSync(p) && statSync(p).isDirectory();
+}
+
+try {
+  if (existsSync(ROLES_FILE) && isDir(SKILLS_DIR)) {
+    const resolveMod = await loadResolve();
+    if (resolveMod) {
+      const data = resolveMod.loadRoles(ROLES_FILE);
+      // A stale/removed role in .active-role must NOT abort the hook: applyBaseline
+      // calls process.exit on an unknown role (uncatchable), which would suppress the
+      // nudge below. Fall back to the baseline if the marker no longer names a role.
+      if (role && !(data.roles && role in data.roles)) role = "";
+      resolveMod.applyBaseline(data, SETTINGS, SKILLS_DIR, role || null);
+    }
+  }
+} catch {
+  // best-effort: never block the session if the baseline can't be written
+}
+
+let ctx = BASE;
+if (role) {
+  ctx +=
+    `\n\nActive role: ${role} — its skills are promoted to auto-trigger. ` +
+    "Switch with `/role <name>` (`/role all` resets to baseline).";
+}
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      reloadSkills: true,
+      additionalContext: ctx,
+    },
+  }) + "\n",
+);