Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions .claude/skills/breaking-changes/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
name: breaking-changes
description: Decide whether a change is breaking and label it. Use when labelling a PR, when a change touches public API or observable behaviour, or when the user mentions breaking changes, semver, or 1.0.
---

# Breaking changes

Every PR carries exactly one release label (the `pr-labels` check enforces it). release-drafter turns the labels into
the next version.

## Is it breaking?

Label it `breaking` when a consumer who upgrades must change something or gets different behaviour:

- a public type, member, parameter or overload is removed, renamed or changes signature;
- a default, an output format, an exit code or a thrown exception changes;
- a target framework is dropped, or a minimum dependency version rises enough to force consumers to upgrade.

These are not breaking: adding API, internal changes, fixing behaviour that contradicted the documentation (label
that `bug` and say so in the PR body).

If package validation (`EnablePackageValidation`) fails on `mise run pack`, the change is breaking at the binary
level, whatever it looks like.

## What the label does

| Repo version | `breaking` | `feature` / `enhancement` | everything else |
|---|---|---|---|
| 0.x | minor | minor | patch |
| 1.x and later | major | minor | patch |

0.x never gets a major bump from a label. **Going to 1.0 is always the maintainer's manual decision**: they set the
draft's tag to `1.0.0` when publishing. Do not propose it, and do not edit the resolver on your own.

When the maintainer has released 1.0.0, add a major resolver to `.github/release-drafter.yml` (and nothing else) in
its own PR:

```yaml
version-resolver:
major:
labels: [breaking]
minor:
labels: [feature, enhancement]
default: patch
```

## In the PR body

A `breaking` PR states what a consumer must change, in a **Breaking** line (see the pr skill).
95 changes: 95 additions & 0 deletions .claude/skills/commit/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
---
name: commit
description: Stage relevant files and create a well-formed git commit. Use this when the user asks to commit changes, save work, or create a commit.
---

# Commit Skill

Read [`.claude/skills/writing-style.md`](../writing-style.md) before writing the commit message.

Creates a clean, well-formed commit following this project's conventions.

## Steps

### 1. Check for project hooks

If the repo has a hook runner, ensure it is installed before committing. Common patterns:

```bash
# Husky.Net (dotnet)
if [ -f .husky/task-runner.json ] && [ ! -f .husky/_/husky.sh ]; then
dotnet tool restore && dotnet husky install
fi

# Husky (Node)
# hooks install automatically via npm ci / npm install

# lefthook
if [ -f lefthook.yml ] || [ -f .lefthook.yml ]; then
lefthook install
fi
```

Do not use `--no-verify`.

### 2. Understand what changed

```bash
git status
git diff
git diff --staged
git log --oneline -5
```

### 3. Stage files

Stage specific files by name — never `git add -A` or `git add .` blindly. Exclude:
- `.env` files or anything with secrets/credentials
- Large binaries not already tracked
- Unrelated changes to the task at hand

### 4. Write the commit message

- **First line**: Imperative mood, ≤72 chars, no trailing period. Front-load the outcome — a reader scanning `git log` sees this line only.
- **Body** (optional): One short paragraph explaining *why*, not what. Skip if the title is self-explanatory. Follow the sentence mechanics in `writing-style.md`.
- **Trailer**: Add a `Co-Authored-By:` line that identifies the model that helped write this commit. Use whatever attribution feels accurate — the model name you know yourself to be running as, or simply `Claude` if you are uncertain. The address is always `[email protected]`. The point is honest attribution, not a precise version string.

Always pass the message via HEREDOC to avoid shell escaping issues:

```bash
git commit -m "$(cat <<'EOF'
Title here

Optional body explaining why.

Co-Authored-By: Claude <[email protected]>
EOF
)"
```

### 5. Handle hook failures

If a git hook fails:
1. Read the error output carefully
2. Fix the underlying issue (formatting, linting, type errors — whatever the hook checks)
3. Re-stage the affected files
4. Create a **new commit** — never `git commit --amend` for a failed commit, and never use `--no-verify`

### 6. Verify success

```bash
git status
```

Confirm a clean working tree.

### 7. Refresh the PR description if one exists

```bash
gh pr view --json number,url,isDraft,baseRefName --jq '{number,url,isDraft,baseRefName}' 2>/dev/null
```

- **No PR** → done. Say nothing.
- **PR exists** → compare the current body against the current diff versus the PR's base branch. A PR description always describes the current diff against the base branch. It is never a log of the commits on the branch and never records the direction the work took. If any section (`## What`, `## Verify`, or the lead paragraph) no longer describes that diff, the description is stale.
- **Stale description** → read and follow [pr](../pr/SKILL.md)'s update path (step 7). Do not hand-edit the body inline from the commit skill. State plainly what was refreshed.
- **Still accurate** → state that the description is still accurate. No edit needed.
162 changes: 162 additions & 0 deletions .claude/skills/pr/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
---
name: pr
description: Create a GitHub pull request with a focused why/what body. Use when the user asks to open a PR, create a pull request, or ship a branch.
---

# PR Skill

Read [`.claude/skills/writing-style.md`](../writing-style.md) before writing anything.

Creates a GitHub PR body that a newcomer can orient from in under a minute: front-loaded outcome, grounded Why, behaviour-led What, verifiable by the reviewer.

## Steps

### 1. Understand the branch

```bash
git status
git log main..HEAD --oneline
git diff main...HEAD --stat
```

### 2. Commit uncommitted work if needed

If the working tree has changes that belong in this PR, read and follow [commit](../commit/SKILL.md) first. Do not commit inline. Do not skip hooks.

### 3. Push (if needed)

```bash
git push -u origin HEAD
```

### 4. Write the PR title

- ≤70 characters, imperative mood, no trailing period
- States what changed at a human level — not a file list, not a symbol name
- No `[bug]` / `[feature]` / `[chore]` prefixes — the label carries the type

### 5. Write the PR body

Required structure:

```
<One or two sentences, no heading. What this changes and the effect.
A newcomer reads only this and knows whether the PR concerns them.>

**Prompt summary:** <One paragraph, two to three sentences. What the author was asked
to do in their own framing — the goal behind the branch, not the diff. Present tense,
active voice. This is the ask; ## Why is the problem in the code. They are not
interchangeable and neither restates the other. Omit only when the branch has no
originating ask.>

## Why
<Two to four sentences. The concrete failure or gap. Active voice, present tense
for current behaviour. Do not open with the history of a prior PR.>

## What

#### <Conceptual label — not a filename>
<Prose paragraph. Group by what changed conceptually, not by which files moved.
Lead with behaviour. Name a symbol only when the reviewer needs it to find the code.
Two to four sentences. Three to five sections total.>

## Verify
<How a reviewer confirms this locally. Use real commands they would run.
If there is no clear local verification step, omit this section entirely.
Do not list CI checks or scripts an agent would run to prove their own work —
those are not reviewer steps.>
```

Conditional add-ons — each is one or two sentences with a bold lead-in, no heading:

- **Breaking** — what a consumer must change and when it bites them.
- **Out of scope** — a gap this PR deliberately leaves, so a reviewer does not raise it as a finding.
- **Risk** — shared or production state this touches. Required when the change reaches infrastructure, credentials, or shared data stores.
- **Stack** — position and links when this is one of several stacked PRs: `3 of 5, on top of [#42](https://github.com/org/repo/pull/42)`. A bare `Stack: 3/5` with no links is not enough.

**Do not** include bullet lists of changed files. Do not summarize what the diff already states plainly.

### 6. Apply exactly one release label

The `pr-labels` check fails a PR without exactly one of these, and release-drafter turns them into the next version:

| Label | Use when | Version |
|---|---|---|
| `breaking` | A consumer must change something after upgrading (see [breaking-changes](../breaking-changes/SKILL.md)) | 0.x: minor, 1.x+: major |
| `feature` | A new capability | minor |
| `enhancement` | An existing capability improved | minor |
| `bug` / `fix` | A defect in existing behaviour is fixed | patch |
| `documentation` | Docs only | patch |
| `chore` | Cleanup, refactor, internal restructure; no user-visible change | patch |
| `dependencies` | Dependency version bumps | patch |
| `ci` | Build and automation | patch |
| `changelog:skip` | Should not appear in the release notes | patch |

### 7. Check whether a PR already exists

```bash
gh pr view --json number,url,baseRefName --jq '{number,url,baseRefName}' 2>/dev/null
```

**If a PR exists — update it.**

Rebuild the body from the cumulative diff against the PR's own base branch (not a hardcoded `main`):

```bash
git diff origin/<baseRefName>...HEAD --stat
git diff origin/<baseRefName>...HEAD
```

Write the description of **the current diff against the base** — never a log of the commits on the branch and never an "update" or "addendum" appended to the old body. Any section of the old body that no longer matches the diff is wrong, not history. Replace it.

- Preserve the original `**Prompt summary:**` verbatim unless the ask itself changed; extend it rather than replace it when scope was added.
- Reassess the label — added commits can shift a `chore` to a `bug`.
- Apply in one call:

```bash
gh pr edit --title "<title>" --body "$(cat <<'EOF'
<new body>
EOF
)"
```

Add or remove the label only if it changed:

```bash
gh pr edit --add-label "<new-label>" --remove-label "<old-label>"
```

**If no PR exists — create it.** Proceed to step 8.

### 8. Create the PR

One call — title, label, and body together. No follow-up `gh pr edit`:

```bash
gh pr create --title "<title>" --label "<label>" --body "$(cat <<'EOF'
<lead sentence(s)>

**Prompt summary:** ...

## Why

...

## What

#### ...

...

## Verify

```bash
<command>
```
EOF
)"
```

### 9. Return the PR URL

Always print the URL so the user can open it directly.
49 changes: 49 additions & 0 deletions .claude/skills/releasing/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
name: releasing
description: Release this repository. Use when the user asks to release, ship a version, publish to NuGet, or check what the next version will be.
---

# Release

Releases are never cut from a pushed tag. release-drafter keeps a **draft release** up to date from the labels of
merged pull requests; **publishing that draft** creates the tag and runs `.github/workflows/ci.yml` on it, whose `release` job builds
any binary assets, packs at the tag's version (MinVer) and pushes to nuget.org with trusted publishing.
In this repository the same run's `publish-npm` job publishes `@nullean/journeys` to npm, also with trusted
publishing, and both jobs run in the `release` environment.

## Steps

1. Look at the draft and the version it resolved:

```bash
mise run release
```

No draft means nothing labelled has merged since the last release, or the release-drafter workflow failed:
`gh run list --workflow release-drafter.yml --limit 3`.

2. Check the version against the rules in [breaking-changes](../breaking-changes/SKILL.md). In 0.x a `breaking` PR
bumps the minor version. **Never** pick 1.0.0 yourself: that is the maintainer's call.

3. Publish only when the user asked for it:

```bash
mise run release publish
```

The maintainer often promotes the draft from the GitHub UI instead; both do the same.

4. Follow the run and report the outcome, packages and assets included:

```bash
gh run watch "$(gh run list --workflow ci.yml --event release --limit 1 --json databaseId --jq '.[0].databaseId')"
gh release view <tag>
```

## When it fails

- Re-run the failed jobs (`gh run rerun <id> --failed`). The push uses `--skip-duplicate` and asset uploads use
`--clobber`, so a re-run is safe.
- `trusted publishing` errors mean nuget.org's policy no longer names this repo's `ci.yml`. Only the maintainer can
fix that on nuget.org.
- Never delete a published tag or release to retry. Fix forward with a patch release.
32 changes: 32 additions & 0 deletions .claude/skills/upgrade-deps/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
name: upgrade-deps
description: Update NuGet packages, .NET tools, the SDK or GitHub Actions. Use when the user asks to bump, upgrade or update dependencies, or to triage dependabot PRs.
---

# Upgrade dependencies

Versions live in one place each:

| What | Where |
|---|---|
| NuGet packages | `Directory.Packages.props` (Central Package Management); never put `Version=` on a `PackageReference` |
| .NET tools | `.config/dotnet-tools.json` |
| .NET SDK | `global.json` only; mise reads it from there |
| other CLI tools | `mise.toml` `[tools]` |
| GitHub Actions | pinned by commit SHA with a `# vX.Y.Z` comment; reusable workflows from `nullean/.github` likewise |

## Steps

1. Branch first. One concern per PR: SDK bumps, package bumps and action bumps go separately when any of them changes
behaviour.
2. Find what is outdated: `dotnet list package --outdated`, plus `dotnet tool list` against nuget.org.
3. Bump, then `mise run ci`. A new SDK also needs `mise install`.
4. Read the release notes of every major bump and say in the PR body what changed for this repo.
5. Label the PR `dependencies` unless the bump forces consumers to change something; then it is `breaking` (see
[breaking-changes](../breaking-changes/SKILL.md)).

For dependabot PRs: check CI, read the changelog for majors, merge groups that pass. Do not rebase a dependabot PR by
hand; comment `@dependabot rebase`.

Pin an action to the commit its release tag points at:
`gh api repos/<owner>/<action>/commits/<tag> --jq .sha`.
Loading
Loading