# Maintainer release process

This repo publishes two kinds of npm packages:

- Root bundle: `@barlevalon/skills`
- Individual skill packages: `@barlevalon/<skill>-skill`

Versions are **independent**. Do not bump every package just because one skill changed.

## Versioning

Use SemVer per package:

- Patch: wording fixes, safety clarifications, docs updates
- Minor: new skill behavior, new workflow sections, or materially better analysis behavior
- Major: incompatible skill behavior or package layout changes

Examples:

- Change only `tdd`: bump `skills/engineering/tdd/package.json` only.
- Change only release docs: bump root `package.json` only if the bundled package should be republished.
- Add a new skill: publish that skill at `0.1.0` or `1.0.0` as appropriate; bump the root bundle because its contents changed.
- Change shared repo tooling only: no npm release unless package contents or publish behavior changed.

## Pre-release validation

```bash
npm ci
npm run ci
```

`npm run ci` validates package manifests, skill frontmatter, required docs,
the root bundle package, and each individual skill package.

## First npm publish bootstrap

npm Trusted Publisher setup currently requires each package to already exist.
For the first publish of a new package only, publish it manually from a clean checkout:

```bash
npm login
npm whoami
npm run ci
npm publish ./skills/<category>/<skill> --access public
```

After the package exists on npm, configure Trusted Publisher for it:

- Publisher: GitHub Actions
- Repository owner/name: `barlevalon/skills`
- Workflow: `publish.yml`
- Environment: none, unless npm requires one for the package settings

The GitHub workflow has `id-token: write`, avoids `actions/setup-node` `registry-url` token config so npm can use OIDC, upgrades to a current npm, and publishes with provenance:

```bash
node scripts/publish-packages.mjs
```

No `NPM_TOKEN` repository secret is required after Trusted Publisher is configured.
The publish script checks whether each package version already exists on npm and skips already-published versions, so independent package versions are safe.

## Release steps

1. Decide which package(s) need a release.
2. Bump only those package manifests.
3. Update `CHANGELOG.md` for repo-visible changes. For detailed skill-only notes, prefer the skill README or a future per-skill changelog.
4. Commit with a specific subject, for example:

   ```text
   release: tdd-skill v0.2.1
   release: bundle v0.2.1
   ```

5. Push to `main` and verify CI is green.
6. Create and push a tag:

   ```bash
   git tag tdd-skill-v0.2.1
   git push origin main tdd-skill-v0.2.1
   ```

   For a coordinated bundle release, `vX.Y.Z` is fine.

7. Create a GitHub Release for the tag.
8. The `Publish npm packages` workflow publishes only package versions that do not already exist on npm.

## Manual dry run

```bash
node scripts/publish-packages.mjs --dry-run
```

Do not publish manually except for first-package bootstrap or when GitHub Actions is unavailable and the release has been approved.