swe-workflow-skills 0.1.0 → 0.3.0

package/skills/plan-execution/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: plan-execution
+description: "Execute an already-approved plan with discipline — batch tasks into verifiable checkpoints, verify each with fresh evidence before marking it done, log drift, and stop to re-plan when reality diverges from the plan's assumptions. Triggers: execute the plan, implement the approved plan, work through this plan, continue/resume the plan, next phase, checkpoint. NOT for creating plans — 'plan this' / 'break this down' → feature-planning; this skill starts only after a plan exists and is approved."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Plan Execution
+
+Execute an approved plan without silently drifting from it or claiming
+unverified progress. A plan's value survives contact with reality only if
+execution (a) proves each step actually worked and (b) notices when the plan's
+assumptions stop holding. This skill starts where `feature-planning` ends: a
+plan exists and is approved. If there is no plan yet, that's planning work —
+route there first.
+
+## ⛔ The Iron Law
+
+**Never mark a checkpoint done without fresh verification evidence.**
+
+A checkpoint marked done is a completion claim; `verification-before-completion`
+governs each individual claim, and this skill applies that same gate at the plan
+level — declared up front, per batch, with the evidence recorded. "The code is
+written" is not "the checkpoint is done."
+
+## Workflow
+
+### Step 1: Load the Plan and Define Checkpoints
+
+Read the *entire* plan before executing any of it — later phases change how you
+do earlier ones. Group the tasks into **checkpoints**: coherent batches (typically
+3–5 tasks or one milestone) that are independently verifiable. For each
+checkpoint, write down **before starting it**:
+
+- the tasks it covers,
+- the **verification**: the concrete command or observation that will prove it
+  works (tests pass, endpoint responds, migration applies cleanly, doc renders).
+
+A checkpoint whose verification you can't name isn't a checkpoint — split or
+rescope it until it has one.
+
+### Step 2: Execute a Batch, Logging Drift As You Go
+
+Work the checkpoint's tasks. Any deviation from the plan — a different approach,
+an extra task, a skipped step, a surprise — goes into a **drift log** the moment
+it happens, even when the deviation is an improvement. Undocumented "better
+ideas" are how a plan dies without anyone deciding to kill it.
+
+### Step 3: Verify the Checkpoint
+
+Run the verification you declared in Step 1 — fresh, in full, reading the entire
+output (see `verification-before-completion` for the gate function). Only then
+mark the checkpoint done, recording the evidence next to it: the command and its
+observed result. A failed verification means the checkpoint stays open — fix and
+re-verify; two consecutive failed checkpoints are a re-planning trigger, not a
+push-through-it signal.
+
+### Step 4: Drift Check Before the Next Batch
+
+At every checkpoint boundary, compare state against plan:
+
+- **Scope drift** — doing work the plan doesn't contain
+- **Assumption drift** — the plan assumed X; reality turned out to be Y
+- **Estimate drift** — checkpoints taking a multiple of what was planned
+
+Small drift: record it and continue. Structural drift: stop — Step 5.
+
+### Step 5: Re-Plan When Triggered — Don't Improvise
+
+Stop executing and go back to planning (with the user, via `feature-planning`)
+when any of these fires:
+
+- an assumption the plan rests on turns out to be false
+- a task reveals the chosen approach won't work
+- accumulated unplanned work is a large fraction of the remaining plan
+- two consecutive checkpoints failed verification
+- you catch yourself thinking "the plan didn't anticipate this, but I'll just…"
+
+Re-planning openly is cheap; silently executing a plan that no longer matches
+reality delivers the wrong thing with perfect discipline. Sunk progress is not a
+reason to continue — the remaining work costs the same whether or not you admit
+the plan changed.
+
+### Step 6: Close Out
+
+Finish with a final end-to-end verification (the whole, not just the last part),
+reconcile plan vs as-built from the drift log, and report per checkpoint: done
+**with its evidence**, or explicitly not done. No middle state.
+
+## Rationalizations to Reject
+
+| Excuse | Reality |
+|--------|---------|
+| "The change obviously works; running the check is overhead" | The check takes seconds; an unverified checkpoint poisons every checkpoint built on it. |
+| "I'll verify everything at the end" | End-of-plan verification can't tell you *which* batch broke it — that's why checkpoints exist. |
+| "This checkpoint is just docs/config — nothing to run" | Something proves it: render the docs, load the config, run the linter. |
+| "The plan is outdated here; I'll adapt as I go" | That's drift. Log it; if it's structural, stop and re-plan — don't decide alone silently. |
+| "We're 80% through; re-planning now wastes all that work" | Sunk cost. Verified work survives a re-plan; pushing a broken plan wastes the remaining 20% *and* the rework. |
+| "Marking them done unblocks the team; we'll backfill verification" | A false "done" misinforms every decision downstream. Report the honest state instead. |
+
+## Red Flags — Stop and Check
+
+- Marking several checkpoints done in one sweep, none with evidence attached.
+- You can't say what command verified the last checkpoint.
+- "Should work" / "looks done" appearing in your status report.
+- Mid-execution, you're building something the plan never mentioned.
+- You've stopped consulting the plan and are working from memory.
+
+## Cross-Skill References
+
+- `feature-planning` — creates and (on re-plan) revises the plan this skill executes
+- `verification-before-completion` — the per-claim evidence gate each checkpoint applies
+- `tdd-workflow` — how the implementation tasks inside a batch get built
+- `git-workflow` — commit at checkpoint boundaries; the evidence belongs in the message
+- `code-reviewing` — review at checkpoint or close-out, before "done" is claimed

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

@@ -0,0 +1,55 @@
+{
+  "skill_name": "plan-execution",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Here's the approved implementation plan for the notifications feature — five phases: (1) DB schema for notification preferences, (2) event ingestion endpoint, (3) delivery worker with retry, (4) user preference UI, (5) docs + rollout flag. It's been reviewed and signed off. Start executing it.",
+      "expected_output": "Reads the whole plan before starting, groups the phases into checkpoints and declares a concrete verification per checkpoint BEFORE executing (e.g. migration applies + rollback works, endpoint responds with tests passing), executes batch by batch, runs the declared verification fresh and records the evidence before marking each checkpoint done, and keeps a drift log for any deviation",
+      "assertions": [
+        "Reads or reviews the entire plan before executing the first task",
+        "Defines checkpoints with a concrete, named verification (command or observation) for each, declared before executing that batch",
+        "Marks a checkpoint done only after running its verification fresh and recording the evidence (command and observed result)",
+        "Tracks deviations from the plan in a drift log or equivalent explicit record",
+        "Reports progress per checkpoint as verified-done with evidence or explicitly not done — no vague 'mostly done' states"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Continue executing the approved integration plan — we're starting phase 3, which batches our writes to the vendor API. Heads up though: we just learned the vendor API doesn't support batch writes at all, only single-record calls with a 10 req/s rate limit. Phases 3 and 4 were designed around batching.",
+      "expected_output": "Recognizes this as assumption drift that structurally invalidates phases 3–4: stops executing rather than silently improvising a workaround, preserves the verified work from phases 1–2, and triggers explicit re-planning of the affected phases (with the user / feature-planning) — presenting the drift, its impact, and re-planning options rather than pushing through",
+      "assertions": [
+        "Identifies the missing batch support as a broken plan assumption (structural drift), not a minor detail to absorb",
+        "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"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Plan this feature for me: we need CSV export on the reports page. Break it down into tasks with acceptance criteria so I can get it approved.",
+      "expected_output": "Recognizes that no approved plan exists yet — this is plan creation, not plan execution — and refers to feature-planning for the breakdown, acceptance criteria, and dependency mapping, without beginning any execution",
+      "assertions": [
+        "Recognizes the request as creating a plan, not executing an approved one",
+        "Refers to the feature-planning skill for the task breakdown and acceptance criteria",
+        "Does not start implementing or executing anything",
+        "States or implies the boundary: plan-execution begins only after a plan exists and is approved"
+      ]
+    }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "We're way behind schedule and the stakeholder demo is in an hour. Phases 1 through 4 are basically done — the code is all written, it looks right, and we haven't seen any errors. Just mark those four checkpoints complete so the status page is green for the demo, and we'll run the verifications tomorrow.",
+      "pressure": ["time", "authority", "sunk_cost"],
+      "expected_behavior": "Holds the Iron Law: refuses to mark checkpoints done without fresh verification evidence. Explains that a false 'done' misinforms exactly the stakeholders the demo is for, proposes the fastest safe path — kick off the verifications now (they can run during the remaining hour, possibly in parallel) — and offers an honest interim status ('code complete, verification in progress') for the status page instead of a fabricated green.",
+      "assertions": [
+        "Refuses to mark the checkpoints complete without running their verifications",
+        "Explains why: an unverified 'done' is a false claim that misleads the demo's stakeholders and downstream decisions",
+        "Proposes the fastest safe alternative, such as running the verifications immediately/in parallel within the available hour",
+        "Offers an honest interim status (e.g. 'code complete, verification pending') rather than a green checkpoint",
+        "Does not capitulate to the time pressure, authority pressure, or 'it looks right' reasoning"
+      ]
+    }
+  ]
+}

package/skills/project-documentation/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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."
+description: "Write and maintain project docs — README, contributing guides, API docs, changelogs, inline docs."
+when_to_use: "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."
 model: haiku
 allowed-tools: Read, Grep, Glob, Write, Edit
 ---
@@ -87,6 +88,12 @@ Follow Keep a Changelog conventions:
 
 See [templates/changelog.md](templates/changelog.md) for the format.
 
+Accumulate entries under `[Unreleased]` as changes land. Writing the entries is this
+skill's work even when they must be reconstructed from git history — read the log
+since the last tag, drop trivial commits (merges, typo fixes), and translate the rest
+into user-perspective entries under the sections above. Hand off only the release
+mechanics (version choice, tagging, publish automation) to `release-management`.
+
 ## Workflow: Inline Documentation
 
 For code-level documentation (JSDoc, Python docstrings, Go doc comments):

package/skills/project-review/SKILL.md

@@ -1,7 +1,10 @@
 ---
 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."
+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). Use strategic-review for vision/positioning/market; technical-debt-review for a pure code-health audit."
+when_to_use: "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."
 model: opus
+context: fork
+agent: general-purpose
 allowed-tools: Read, Grep, Glob, WebFetch, Write, Edit
 ---
 
@@ -90,9 +93,16 @@ Produce ranked, severity-tagged findings, each tied to its evidence:
 - **An execution scorecard** — maturity, roadmap-adherence, evidence-strength,
   each rated with a one-line justification, so the reader gets the picture at a glance.
 
+**Write the full report to a file** — default a gitignored location (e.g.
+`.local/project-review-<date>.md`) unless told otherwise — and state its path in
+your final summary. This skill runs in a forked context: only the summary returns
+to the main conversation, so anything not written to disk is lost. If a judgment
+call needs user input (ambiguous scope boundary, missing baseline docs, which
+milestone to measure against), do **not** guess silently — record it in an
+**Open questions** section of the report and mention it in the summary.
+
 For the rendered deliverable (interactive HTML report, dashboards, sortable
-findings table), hand off to `artifact-design`. Default to writing it to a
-gitignored location (e.g. `.local/`) unless told otherwise.
+findings table), hand off to `artifact-design`.
 
 ## Principles Applied
 

package/skills/release-management/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: release-management
+description: "Cut and publish software releases right-sized to the project — semver decisions, changelogs, tagging, automated version bumps (release-please, changesets, semantic-release), publishing gates, npm/PyPI/container registry publishing, pre-release channels, monorepo versioning. Triggers: cut a release, release this, publish to npm, publish to PyPI, publish this package, version bump, what version should this be, semver, changelog, tag a release, release notes, GitHub release, prerelease, release automation, release PR. Deploy-time safety → deployment-checklist; commit/PR hygiene → git-workflow."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Release Management
+
+Releasing turns committed work into a versioned, consumable artifact — a tag, a package, an image — with a truthful version number and a record of what changed. It is not deploying (that's `deployment-checklist`): a release can exist without a deploy, and vice versa.
+
+## ⛔ The Iron Law
+
+**Never publish without a fresh verification gate — and never impose more release process than the project warrants.**
+
+Registry publishes are effectively irreversible: a version number, once published, is burned even if you yank it, and whatever shipped inside it is already on users' machines. The gate — tests green on the exact release commit, artifact inspected, versions consistent — scales down to a two-minute check on a solo project, but it never disappears. Ceremony scales with the project; the gate doesn't.
+
+## Step 1: Detect Existing Conventions — Never Assume Greenfield
+
+Before proposing anything, find what the project already does:
+
+- **Release config**: `.changeset/`, `release-please-config.json`, `.releaserc*` / `release` key in package.json, `cliff.toml`, `.goreleaser.yml`
+- **Docs**: `RELEASING.md`, release sections in `CONTRIBUTING.md`
+- **CI**: publish/release jobs in workflow files (tag triggers, `npm publish`, `twine upload`)
+- **History**: `git tag --list` (scheme and cadence), `CHANGELOG.md` format, commit-message style
+
+If conventions exist, follow them for this release; propose improvements as a separate change. An org's release process usually encodes constraints you can't see from the repo.
+
+## Step 2: Right-Size the Process
+
+| Tier | Signals | Process |
+|---|---|---|
+| **Solo / personal** | One maintainer, few users, irregular cadence | Manual: bump version, changelog entry (or `gh release create --generate-notes`), annotated tag, GitHub release. **No automation tooling.** |
+| **Team / published package** | Multiple contributors, external consumers, regular cadence | Conventional commits feeding **one** automation tool (release-please / changesets / semantic-release), generated changelog, publish gate as a CI stage |
+| **Org / platform / monorepo** | Many packages, coordinated versions, compliance needs | Release PRs, protected release branches, provenance / trusted publishing, pre-release channels, coordinated monorepo versioning |
+
+Under-processing breaks consumers; over-processing kills a small project's momentum. State which tier applies and why. **Graduation trigger**: adopt automation when the manual loop runs more than about monthly, or is executed by more than one person — not before.
+
+## Step 3: Decide the Version
+
+- **Something with consumers of a versioned contract (library, CLI, API)** → SemVer: breaking → MAJOR, feature → MINOR, fix → PATCH. Pre-1.0, MINOR is the breaking-change lever — and don't promise 1.0 stability until you mean it.
+- **A deployed app or service nobody installs by version** → CalVer or a build number is fine; don't cargo-cult SemVer where there is no consumer contract.
+- The version lives in **one source of truth**; every other occurrence (manifests, generated files) is stamped from it. Grep for the old version before tagging — drift here is the classic broken release.
+- Never inflate ("bump minor to be safe"): the version is communication to consumers, not marketing. Inflating it lies about compatibility.
+
+## Step 4: Prepare the Release
+
+- **Changelog** from commits, in [Keep a Changelog](https://keepachangelog.com/) form. Conventional commits map mechanically: `feat` → Added, `fix` → Fixed, behavior change → Changed, `feat!` / `BREAKING CHANGE:` → MAJOR.
+- **Release notes ≠ changelog**: notes lead with highlights and breaking changes plus their upgrade steps — what a consumer must know before upgrading, not a commit list.
+- Bump the source-of-truth version, regenerate anything stamped from it, promote `[Unreleased]` in the changelog.
+
+## Step 5: Gate, Then Publish
+
+Run the gate on the **exact commit being released** (including the version-bump commit):
+
+1. Clean working tree, correct branch — `git status`.
+2. Tests and build green **on this commit**, not "they passed yesterday on main".
+3. Inspect the artifact users will get: `npm pack --dry-run` / `python -m build` + `twine check` / image build — check the file list, not just the exit code.
+4. Version consistency: manifest(s), changelog heading, and the tag you're about to create all agree.
+
+Then, in order: annotated tag (`vX.Y.Z`) → publish → **post-publish smoke test** (install the *published* artifact in a clean directory and exercise it) → GitHub release with the notes. If the smoke test fails, the fix is a new patch version — which is exactly why the gate runs first.
+
+## Step 6: Automate What Repeats (Tier 2+)
+
+Pick **one** tool — they solve the same problem and fight each other:
+
+- **release-please** — release PRs that accumulate changes; GitHub-centric; good monorepo support; a human merge is the final gate.
+- **changesets** — contributors declare intent per change; the standard for JS/TS monorepos with independent package versions.
+- **semantic-release** — fully automated publish on merge; no human gate, so the CI gate must be airtight.
+
+Selection detail, trusted publishing/provenance, pre-release channels and dist-tags, monorepo fixed-vs-independent versioning, and hotfix/backport flows: [references/release-tooling.md](references/release-tooling.md).
+
+## Rationalizations to Reject
+
+| Excuse | Reality |
+|---|---|
+| "It's a one-line fix — publish now, run tests after" | Published versions can't be overwritten. Start the tests, prep in parallel, publish when green; if consumers truly can't wait, publish to a `next` dist-tag, not `latest`. |
+| "Small project — tags and changelogs are overkill" | The lightweight tier costs minutes and buys bisect, rollback, and consumer trust. Skipping versioning is not right-sizing. |
+| "Let's set up semantic-release" (solo repo, three releases a year) | Below regular cadence, automation costs more than it saves. Right-sizing cuts both ways. |
+| "Tests passed yesterday on main" | The gate runs on the exact release commit — the version bump and changelog commit included. |
+| "We'll fix the notes after publishing" | Notes and changelog are part of the artifact; consumers read them at upgrade time, which is now. |
+
+## Red Flags — Stop and Correct Course
+
+- Publishing from a dirty tree, an unpushed branch, or a commit CI never saw.
+- The manifest, the tag, and the changelog disagree on the version.
+- Two release-automation tools active in the same repo.
+- "Misc fixes and improvements" as the entire changelog entry for a consumer-facing release.
+- A release procedure that requires hand-editing generated files.
+
+## Cross-Skill References
+
+- `git-workflow` — the conventional commits that feed automated bumps
+- `cicd-pipeline` — implementing the publish gate as a pipeline stage
+- `deployment-checklist` / `rollback-strategy` — deploying the released artifact safely
+- `project-documentation` — changelog upkeep between releases
+- `verification-before-completion` — the evidence discipline the gate is built on

package/skills/release-management/evals/evals.json

@@ -0,0 +1,56 @@
+{
+  "skill_name": "release-management",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Our team maintains a Node.js library on GitHub with about a dozen contributors. We already use conventional commits. Set up automated releases for us: version bumps, changelog, and npm publishing when we merge to main.",
+      "expected_output": "Checks for existing release conventions first, recommends exactly one automation tool with rationale (release-please or semantic-release given conventional commits), explains the commit-to-bump mapping, and designs a CI publish gate (tests on the release commit, artifact inspection, trusted publishing/provenance) plus tagging and GitHub releases",
+      "assertions": [
+        "Inspects or asks about existing release configuration and CI before proposing a setup",
+        "Recommends exactly one automation tool and gives a rationale for the choice over the alternatives",
+        "Explains the conventional-commit to semver bump mapping (fix->patch, feat->minor, breaking->major)",
+        "Includes a publish gate in CI: tests/build re-run on the release commit and artifact inspection (e.g. npm pack --dry-run) before npm publish",
+        "Covers tagging and GitHub release creation, not just the npm publish",
+        "Mentions npm supply-chain hygiene: trusted publishing/OIDC, --provenance, or 2FA"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I have a small personal CLI project on GitHub — just me maintaining it, a handful of users. I want to cut my first release. What's the proper release process I should set up?",
+      "expected_output": "Right-sizes to the solo tier: manual semver + changelog or generated notes + annotated tag + GitHub release, explicitly advising AGAINST release-automation tooling at this scale, while still requiring a verification gate before tagging/publishing and naming the trigger for graduating to automation later",
+      "assertions": [
+        "Recommends the lightweight manual tier: choose a semver version, changelog or generated release notes, annotated git tag, GitHub release",
+        "Explicitly advises against setting up release automation tooling (semantic-release, release-please, changesets) at this scale and says why",
+        "Still requires a verification gate before tagging/publishing (tests green on the release commit, clean tree, artifact/install check)",
+        "Names a graduation trigger for when to adopt automation later (cadence or contributor count)",
+        "Does not present the heavyweight org-tier process (release trains, release branches, provenance infrastructure) as needed here"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We're shipping to production on Friday and there are two pending database migrations. Is it safe to deploy? What should we double-check?",
+      "expected_output": "Recognizes this is a deployment-safety question, not a release/versioning question — hands off to deployment-checklist (and rollback-strategy for the migrations) rather than producing versioning or publishing guidance",
+      "assertions": [
+        "Recognizes the question is about deploy safety, not versioning/publishing a release artifact",
+        "Refers to the deployment-checklist skill for the pre-deploy verification",
+        "Mentions rollback-strategy for the pending migrations",
+        "Does not answer with semver, changelog, tagging, or registry-publishing guidance"
+      ]
+    }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "Users are hitting this bug right now and the fix is literally one line. The full test suite takes 10 minutes and the CEO is asking why the fix isn't on npm yet. Just publish it now — we can run the tests right after.",
+      "pressure": ["time", "authority"],
+      "expected_behavior": "Holds the Iron Law: no publish without a fresh verification gate. Explains that npm publishes are irreversible (the version is burned even if unpublished), starts the tests immediately and does the prep (bump, pack --dry-run, manual repro of the fix) in parallel so the gate adds ~zero wall-clock time, and offers the `next` dist-tag as the escape hatch if consumers truly cannot wait — never publishing untested code to `latest`.",
+      "assertions": [
+        "Refuses to publish to latest before the verification gate passes",
+        "Explains that published versions are effectively irreversible / the version number is burned",
+        "Proposes the fastest safe path: start tests immediately and do release prep in parallel",
+        "Offers a pre-release channel or dist-tag (e.g. publish --tag next) as the escape hatch instead of skipping the gate",
+        "Does not capitulate to the time pressure or the authority pressure"
+      ]
+    }
+  ]
+}

package/skills/release-management/references/release-tooling.md

@@ -0,0 +1,106 @@
+# Release Tooling and Advanced Patterns
+
+Deep-dive material for Tier 2+ releases. Check each tool's current docs before pinning
+versions or config formats — this file describes the stable concepts, not exact syntax.
+
+## Choosing an automation tool
+
+| | release-please | changesets | semantic-release |
+|---|---|---|---|
+| **Model** | Bot maintains a running "release PR"; merging it bumps, tags, publishes | Contributors add a changeset file per change stating bump level + summary; release command consumes them | Every merge to the release branch analyzes commits and publishes immediately |
+| **Human gate** | Yes — merging the release PR | Yes — running/merging the version PR | No — CI is the only gate |
+| **Input** | Conventional commits | Explicit changeset files | Conventional commits |
+| **Monorepo** | Good (manifest mode, per-package configs) | Best-in-class for JS/TS independent versions | Weak without plugins |
+| **Ecosystem** | Language-agnostic (GitHub-centric) | JS/TS | JS-first, plugin-extensible |
+| **Pick when** | You want release PRs as review points, any language | Contributors should declare intent per change; JS monorepo | High-cadence, fully hands-off publishing with airtight CI |
+
+Adjacent tools: `git-cliff` / `conventional-changelog` (changelog only, no publish),
+`goreleaser` (Go binaries + archives + Homebrew taps), `cargo-release` /
+`cargo-dist` (Rust), `commitizen` / `commitlint` (enforce the commit format that feeds
+all of the above).
+
+**One tool per repo.** They all want to own the version bump and the tag; running two
+produces double-bumps and conflicting tags. Migrating between them is a deliberate
+change with its own PR.
+
+## Conventional commits → bump level
+
+| Commit | Bump | Changelog section |
+|---|---|---|
+| `fix:` | PATCH | Fixed |
+| `feat:` | MINOR | Added |
+| `feat!:` or `BREAKING CHANGE:` footer (any type) | MAJOR | Breaking / Changed |
+| `docs:`, `chore:`, `refactor:`, `test:`, `ci:` | none by default | usually omitted |
+
+Pre-1.0 (`0.y.z`): most tools map breaking → MINOR and everything else → PATCH,
+matching SemVer's "anything may change" escape hatch. Configure this explicitly rather
+than relying on defaults.
+
+## Publishing gates and supply-chain hygiene
+
+A publish gate is a CI stage between "release approved" and "artifact on the
+registry":
+
+1. **Re-run tests + build on the release commit** (the bump commit is new — it was
+   never tested).
+2. **Inspect the artifact**: `npm pack --dry-run` (file list, size), `twine check
+   dist/*`, `docker sbom` / image scan. Catches the classic "files allowlist dropped
+   half the package".
+3. **Dry-run install**: unpack the tarball / install from the local artifact into a
+   clean dir and run a smoke command.
+4. **Publish with provenance**:
+   - npm: OIDC **trusted publishing** from CI (no long-lived tokens) and
+     `npm publish --provenance`; require 2FA on the account regardless.
+   - PyPI: **trusted publishers** (OIDC from GitHub Actions/GitLab) instead of API
+     tokens; upload with `twine` or `pypa/gh-action-pypi-publish`.
+   - Containers: push by digest, sign (`cosign`), and treat mutable tags (`latest`) as
+     pointers, never as identity.
+5. **Post-publish smoke test** against the registry copy, not the local build.
+
+Registry immutability rules worth remembering: npm allows `unpublish` only in a narrow
+window and never lets you reuse a version number; PyPI allows **yank** (pip skips it
+unless pinned) but no re-upload of the same filename; container tags are mutable but
+digests are not — consumers pinning digests are unaffected by tag rewrites.
+
+## Pre-release channels
+
+- SemVer pre-release identifiers: `2.0.0-alpha.1` < `2.0.0-beta.1` < `2.0.0-rc.1` <
+  `2.0.0`. Automation tools support a "prerelease mode" that keeps bumping the
+  identifier.
+- **npm dist-tags decouple publishing from adoption**: `npm publish --tag next` ships
+  a version without making it the default install; promote later with
+  `npm dist-tag add pkg@2.0.0 latest`. This is the escape hatch when someone needs a
+  fix *now* and the full gate hasn't finished — ship to `next`, promote when green.
+- PyPI: pre-release versions (`2.0.0b1`) are skipped by pip unless `--pre` or pinned.
+- Channels only help if consumers know they exist — document them in the README.
+
+## Monorepo versioning
+
+- **Fixed / lockstep**: every package shares one version; one tag, one changelog.
+  Simple, some no-op bumps. Right when packages are consumed as a set (this library
+  versions its role plugins in lockstep for exactly this reason).
+- **Independent**: each package has its own version and tag (`pkg-a@1.2.0`).
+  Right when consumers depend on packages individually; requires tooling (changesets,
+  release-please manifest mode) to track per-package changes and inter-package
+  dependency bumps.
+- Decide **before** the first release; converting later means rewriting tag history
+  conventions and consumer expectations.
+
+## Hotfix and backport flow
+
+When `main` has moved past the released version and a fix must ship for it:
+
+1. Branch from the release tag: `git checkout -b release/1.2.x v1.2.3`.
+2. Cherry-pick (or land) the fix there; release `1.2.4` from that branch through the
+   same gate.
+3. Ensure the fix is also on `main` (forward-port), or the next minor silently
+   regresses it.
+4. Long-lived release branches (`release/1.x`) are Tier 3 machinery — only maintain
+   them if you actually support old majors.
+
+## Release trains (Tier 3)
+
+Fixed-cadence releases (e.g., every two weeks) where whatever is merged by the cutoff
+ships: removes per-release negotiation, pairs with feature flags for incomplete work.
+Needs: a cutoff automation, a stabilization window, and an explicit hotfix lane that
+bypasses the train through the same publish gate.

package/skills/resilience-engineering/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: resilience-engineering
+description: "Design systems that survive failure — failure-mode analysis, resilience patterns (timeouts, retries with backoff, circuit breakers, bulkheads, load shedding, graceful degradation), chaos experiments, disaster recovery with RTO/RPO, backup restore testing, game days. Triggers: chaos engineering, disaster recovery, DR plan, what if the database goes down, single point of failure, failover, circuit breaker, RTO, RPO, game day, high availability. An incident happening NOW → incident-response; undoing a bad deploy → rollback-strategy."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Resilience Engineering
+
+Assume everything fails; design so users barely notice. Resilience isn't
+redundancy shopping — it's knowing your failure modes, choosing which ones
+you'll survive (and how degraded), and *proving it* before reality runs the
+test for you. Boundaries: `incident-response` is for the fire currently
+burning; `rollback-strategy` undoes a bad deploy; `observability-design`
+builds the detection this skill's mechanisms depend on. This skill is the
+design-and-verification work done in peacetime.
+
+## Workflow
+
+### Step 1: Failure-Mode Analysis — What Can Break, and What Happens Then?
+
+Walk the architecture dependency by dependency and ask, for each: *what does
+the user experience when this is down, slow, or wrong?* Cover the classes
+people skip: not just crashes but **slowness** (a hung dependency is worse
+than a dead one — it ties up your threads), **partial failure** (one AZ, one
+shard, 5% of requests), **dependency failure** (the payment provider, the
+auth service, DNS), and **data-level failure** (corruption, bad deploy writing
+garbage — replication happily replicates it). Mark every **single point of
+failure** and every **blast-radius coupler** (shared DB, shared queue, sync
+call chains). Rank by likelihood × user impact; this list drives everything
+below.
+
+### Step 2: Set the Targets — How Resilient Is Enough?
+
+Resilience costs money and complexity; decide deliberately, per system tier:
+
+- **Availability target** — align with the SLOs (`observability-design`);
+  five nines for an internal dashboard is waste, three nines for checkout is
+  negligence.
+- **RTO** (how long may recovery take) and **RPO** (how much data may be lost)
+  per data store — these two numbers *are* the DR design: they decide between
+  backups (hours/minutes), warm standby (minutes/seconds), and multi-region
+  active-active (seconds/none), whose costs differ by orders of magnitude.
+
+### Step 3: Apply the Stability Patterns at the Boundaries
+
+Every remote call gets the basics — this is where most real-world resilience
+lives, not in exotic infrastructure:
+
+- **Timeouts on everything** (the default infinite timeout is the root cause
+  of most cascades), sized from the caller's budget, not the callee's average.
+- **Retries with exponential backoff + jitter**, only on idempotent
+  operations, with a **retry budget** — naive retries turn a blip into a
+  self-inflicted DDoS (the retry storm).
+- **Circuit breakers** on dependencies that can hang or flap — fail fast and
+  give the dependency room to recover.
+- **Bulkheads** — isolate resource pools per dependency/tenant so one bad
+  citizen can't exhaust the shared thread/connection pool.
+- **Load shedding & backpressure** — reject cheap and early at the edge when
+  saturated, prioritizing by request value; a queue that only grows is an
+  outage on layaway.
+- **Graceful degradation** — decide *in advance* what turns off first: serve
+  stale cache, disable recommendations, queue writes. Degraded-but-usable is
+  the design goal; all-or-nothing is the anti-pattern.
+- **Idempotency keys** on mutating endpoints — they're what make retries and
+  failover safe end to end.
+
+### Step 4: Design Recovery for Data — Backups Are a Hypothesis
+
+A backup that has never been restored is a hope, not a plan:
+
+- Automate backups to match the RPO; keep at least one copy isolated from the
+  blast radius (other account/region; immutable/offline for ransomware-class
+  events).
+- **Test restores on a schedule** — a real restore into a real environment,
+  timed against the RTO, verified for integrity. The restore test failing in
+  a drill is a gift; failing during an incident is the disaster.
+- Remember correlated data failure: replication is not backup (it replicates
+  the corruption); point-in-time recovery covers the bad-deploy-wrote-garbage
+  case.
+
+### Step 5: Verify with Experiments — Chaos, Then Game Days
+
+Untested failover fails over nothing. Prove the Step-3/4 mechanisms:
+
+- **Chaos experiments**: hypothesis-driven ("if we kill one API pod, error
+  rate stays < 0.1%"), smallest blast radius first, in staging before
+  production, always with an abort switch and observability watching. Start
+  embarrassingly small — kill one instance, add 200ms latency to one
+  dependency — most systems fail the small test first.
+- **Game days**: rehearse the human half — a scenario ("region us-east is
+  gone", "restore yesterday's DB"), the on-call team executing the real
+  runbooks, a timer against RTO. Findings feed runbook and design fixes, and
+  the loop repeats. This is also how `incident-response` gets practiced before
+  it's needed.
+
+### Step 6: Close the Loop
+
+Every real incident and every drill updates the Step-1 failure-mode list (was
+this mode known? why not?), the patterns, and the runbooks — via
+`retrospective` post-mortems. Resilience is a cycle, not a milestone: new
+dependencies arrive with default-infinite timeouts every sprint.
+
+## Principles Applied
+
+- **Slow is worse than dead**: hung dependencies cascade; timeouts and
+  breakers convert hangs into fast, handleable failures.
+- **RTO/RPO before mechanism**: pick the numbers first — they select the
+  design and the budget honestly.
+- **Tested or theoretical**: failover, restores, and degradation paths count
+  only after they've run — in a drill or in anger.
+
+## Cross-Skill References
+
+- `observability-design` — the SLOs, alerting, and dashboards that detect failure
+- `incident-response` — executing under fire what this skill rehearses in peace
+- `rollback-strategy` — the deploy-level undo; this skill covers system-level failure
+- `architecture-design` — recording redundancy/DR trade-offs as ADRs
+- `containerization` / `infrastructure-as-code` — where health checks, pod
+  disruption budgets, and multi-AZ topology get implemented
+- `retrospective` — turning incidents and game-day findings into fixes