release-agent-skills 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-28
+
+### Added
+
+- `release-maven` skill: publishes JVM, Android and Kotlin Multiplatform libraries to Maven Central through the Sonatype Central Portal, with check-only, manual (default) and automatic modes, two approval gates and resumable state.
+- Check scripts: project detection, version lookup on repo1.maven.org, credential presence, version bump, artifact inspection, POM validation, signature and keyserver verification, Portal Publisher API client, and sync polling.
+- Shared scripts: git pre-flight, changelog drafting from conventional commits, GitHub release creation.
+- Error library with 23 Maven Central and Gradle publishing errors.
+- Reference docs for the Central Portal, Gradle publishing setups, POM requirements, signing and Kotlin Multiplatform.
+- Installer for Claude Code, Cursor and Agent Skills folders (`npx release-agent-skills install`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmad Hussain
+
+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

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# release-agent-skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agent skills that publish libraries safely. You type one sentence, the agent runs the checks, shows you exactly what will be released, and waits for your approval before anything leaves your machine.
+
+Version 0.1 supports **Maven Central** (JVM, Android and Kotlin Multiplatform libraries built with Gradle) through the Sonatype Central Portal. npm and pub.dev are planned.
+
+```
+> publish KMPermission 0.4.0 to Maven Central
+```
+
+## What it does
+
+1. **Detect**: finds the publishable modules, groupId, artifactId, version, library type (JVM, Android, KMP), publishing setup, and any CI workflow that already publishes.
+2. **Pre-flight, nothing uploaded**:
+   - git tree clean, expected branch, tag not taken
+   - version not already on Maven Central
+   - credentials present (key names only, values are never read out)
+   - build and tests pass
+   - every artifact has a POM with the required fields, sources and javadoc jars, and a signature; signing key on a public keyserver
+   - for KMP, every target is published
+3. **Prepare**: version bump (or a `-PVERSION_NAME` override for projects that keep a SNAPSHOT in the file) and a changelog entry drafted from commits since the last tag.
+4. **Gate 1**: a summary of coordinates, version, files and changelog. Nothing is committed or uploaded without your explicit "yes".
+5. **Upload and validate** in the Central Portal. Manual release is the default: the deployment is validated but not published.
+6. **Gate 2**: the release becomes permanent only when you click Publish in the Portal or answer "yes" a second time. You can also drop the deployment; the version is not used up.
+7. **Verify**: polls repo1.maven.org with backoff until the version is visible (10 to 30 minutes is normal).
+8. **Finish**: tag, push and GitHub release, each after your approval.
+
+When something fails, the agent looks the error up in an error library of 23 common Maven Central and Gradle publishing errors. It explains the cause in plain English, proposes a fix, and applies it only after you approve.
+
+## Quick start
+
+Requires Node.js 20 or later.
+
+```sh
+cd your-library
+npx release-agent-skills install
+```
+
+This copies the skills into `.claude/skills/` in the current project. Commit that folder, or install with `--user` instead, because the pre-flight requires a clean git tree. Then ask your agent:
+
+```
+> check if my library is ready to publish to Maven Central
+```
+
+That runs the checks only and changes nothing. When everything passes:
+
+```
+> publish mylib 1.0.2 to Maven Central
+```
+
+### Other tools and locations
+
+```sh
+npx release-agent-skills install --target agents    # .agents/skills (Codex and other Agent Skills tools)
+npx release-agent-skills install --target cursor    # .cursor/skills
+npx release-agent-skills install --target all
+npx release-agent-skills install --user             # ~/.claude/skills, for all your projects
+npx release-agent-skills install --dir path/to/skills
+npx release-agent-skills install --dry-run          # show what would be copied
+npx release-agent-skills list
+```
+
+Cursor also reads `.claude/skills` and `.agents/skills`, so a separate Cursor install is only needed if you use Cursor alone. An existing installation is never overwritten unless you pass `--force`, and the installer never deletes files.
+
+## Safety model
+
+- **No upload without approval.** Gate 1 comes before the upload; Gate 2 comes before the release, which cannot be undone. The Portal publish call needs a `--confirm-permanent` flag, which the skill only passes after your explicit answer.
+- **Manual release by default.** Automatic release is used only when you ask for it in so many words.
+- **Secrets stay secret.** `check-credentials` reports key names and where they were found, never values. The skill forbids commands that print secrets, including `./gradlew properties`, which dumps `~/.gradle/gradle.properties`. The only script that reads a secret value is `portal.mjs`. It uses the Portal token in-process for the HTTP header and never prints it.
+- **Check-only mode.** Ask for a check or a dry run and nothing is changed, committed or uploaded.
+- **Deterministic checks.** Version lookups, POM validation, signature checks and artifact listing are small Node.js scripts with no dependencies that print JSON, so the agent reads results instead of guessing.
+- **Works with your pipeline.** If a CI workflow already publishes, the skill recommends running its checks locally and triggering that workflow, rather than bypassing it.
+
+## Supported setups
+
+| | Supported |
+|---|---|
+| Publishing plugin | [vanniktech gradle-maven-publish-plugin](https://github.com/vanniktech/gradle-maven-publish-plugin) 0.34.0 or later (0.37.0 recommended); plain `maven-publish` + `signing` (uploaded by this skill through the Portal Publisher API) |
+| Library types | Java / Kotlin JVM, Android library, Kotlin Multiplatform (including the AGP `com.android.kotlin.multiplatform.library` plugin) |
+| Signing | in-memory key, key ring file, GnuPG agent (`useGpgCmd()`) |
+| Repository | Sonatype Central Portal. Legacy OSSRH was shut down on June 30, 2025 and is detected and flagged |
+| Agents | Claude Code, Codex, Cursor and other tools that read `SKILL.md` folders |
+
+## What gets installed
+
+```
+.claude/skills/
+├── release-maven/
+│   ├── SKILL.md              the workflow the agent follows
+│   ├── errors.md             error library: cause, fix, phase to rerun
+│   ├── reference/            Central Portal, Gradle setups, POM, signing, KMP notes
+│   └── scripts/              detect, check-version, check-credentials, bump-version,
+│                             inspect-artifacts, validate-pom, verify-signatures,
+│                             portal, wait-for-central
+└── release-agent-shared/     registry-independent scripts: git pre-flight,
+                              changelog, GitHub release, release state
+```
+
+Scripts can also be run by hand, for example:
+
+```sh
+node .claude/skills/release-maven/scripts/check-version.mjs --group io.github.example --artifact mylib --version 1.0.2
+node .claude/skills/release-maven/scripts/detect-project.mjs --project .
+```
+
+## Development
+
+```sh
+npm test
+```
+
+Tests use the built-in `node:test` runner and mock all network calls. See [docs/adding-a-registry.md](docs/adding-a-registry.md) for how npm, pub.dev and other registries fit in.
+
+## License
+
+[MIT](LICENSE)

package/bin/release-agent-skills.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { resolve } from 'node:path';
+import { installSkills, availableSkills, packageVersion } from '../src/installer/install.mjs';
+import { resolveTarget, TARGETS } from '../src/installer/targets.mjs';
+
+const HELP = `release-agent-skills ${packageVersion()}
+
+Usage:
+  npx release-agent-skills install [options]
+  npx release-agent-skills list
+
+Install options:
+  --target <name>   ${Object.keys(TARGETS).join(' | ')} | all   (default: claude)
+  --user            install into your home directory instead of the current project
+  --dir <path>      install into this skills directory instead of a target
+  --skill <name>    install only this skill (repeatable; default: all)
+  --force           overwrite an existing installation (files are replaced, never deleted)
+  --dry-run         show what would be installed without writing anything
+
+Targets:
+${Object.entries(TARGETS).map(([k, t]) => `  ${k.padEnd(8)} ${t.label}: ./${t.project} (or ~/${t.user} with --user)`).join('\n')}
+  Cursor also reads .claude/skills and .agents/skills, so --target cursor is only
+  needed if you use Cursor alone.`;
+
+function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      target: { type: 'string', default: 'claude' }, user: { type: 'boolean', default: false },
+      dir: { type: 'string' }, skill: { type: 'string', multiple: true }, force: { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false }, help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+    },
+  });
+  const [command] = positionals;
+  if (values.version) return console.log(packageVersion());
+  if (values.help || !command) return console.log(HELP);
+
+  if (command === 'list') {
+    for (const s of availableSkills()) console.log(`${s.name}\n  ${s.description}\n`);
+    return;
+  }
+  if (command !== 'install') throw new Error(`Unknown command "${command}". Run with --help.`);
+
+  const destinations = values.dir
+    ? [{ label: 'custom directory', dir: resolve(values.dir) }]
+    : (values.target === 'all' ? Object.keys(TARGETS) : [values.target]).map((t) => resolveTarget(t, { user: values.user }));
+
+  for (const dest of destinations) {
+    const report = installSkills({ destDir: dest.dir, skills: values.skill, force: values.force, dryRun: values['dry-run'] });
+    console.log(`${values['dry-run'] ? '[dry run] ' : ''}${dest.label}: ${dest.dir}`);
+    for (const r of report) {
+      console.log(r.action === 'skipped'
+        ? `  skipped    ${r.folder} (${r.reason}; use --force to overwrite)`
+        : `  ${r.action.padEnd(10)} ${r.folder} (${r.files} files)`);
+    }
+  }
+  if (!values['dry-run']) {
+    console.log('\nNext: open your project in your AI tool and ask, for example:');
+    console.log('  "check if my library is ready to publish to Maven Central"   (check only, nothing uploaded)');
+    console.log('  "publish mylib 1.0.2 to Maven Central"');
+  }
+}
+
+try {
+  main(process.argv.slice(2));
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "release-agent-skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "AI agent skills that publish libraries safely. v0.1: Maven Central through the Sonatype Central Portal, with pre-flight checks, approval gates and manual release by default.",
+  "type": "module",
+  "bin": {
+    "release-agent-skills": "bin/release-agent-skills.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "cursor",
+    "codex",
+    "maven-central",
+    "sonatype",
+    "central-portal",
+    "gradle",
+    "kotlin-multiplatform",
+    "release",
+    "publishing"
+  ],
+  "author": "Ahmad Hussain <ahmadhussain0335@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ahmadhussain0335/release-agent-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ahmadhussain0335/release-agent-skills/issues"
+  },
+  "homepage": "https://github.com/Ahmadhussain0335/release-agent-skills#readme"
+}

package/skills/release-agent-shared/scripts/changelog.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// Drafts a Keep a Changelog entry (Added / Changed / Fixed) from commits since the last tag.
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { runCli, check, result, required } from './lib/cli.mjs';
+import { git, lastTag } from './lib/git.mjs';
+
+const SECTIONS = ['Added', 'Changed', 'Fixed'];
+const TYPE_SECTION = { feat: 'Added', fix: 'Fixed', perf: 'Changed', refactor: 'Changed', revert: 'Changed', deprecate: 'Changed', security: 'Fixed' };
+const OMIT_TYPES = new Set(['chore', 'docs', 'test', 'tests', 'ci', 'build', 'style']);
+
+const HEADER = `# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+`;
+
+export function readCommits(cwd, since) {
+  const range = since ? `${since}..HEAD` : 'HEAD';
+  const raw = git(['log', range, '--no-merges', '--format=%H%x1f%s%x1f%b%x1e'], cwd);
+  if (raw === null) return [];
+  return raw.split('\x1e').map((s) => s.trim()).filter(Boolean).map((record) => {
+    const [hash, subject, body = ''] = record.split('\x1f');
+    return { hash, subject, body };
+  });
+}
+
+export function classify(commit) {
+  const m = commit.subject.match(/^(\w+)(?:\(([^)]+)\))?(!)?:\s*(.+)$/);
+  if (!m) return { section: null, text: commit.subject, reason: 'not a conventional commit' };
+  const [, rawType, scope, bang, description] = m;
+  const type = rawType.toLowerCase();
+  const breaking = Boolean(bang) || /^BREAKING[ -]CHANGE:/m.test(commit.body);
+  let text = scope ? `${scope}: ${description}` : description;
+  if (breaking) text = `Breaking: ${text}`;
+  if (type === 'chore' && /^release\b/i.test(scope ?? '')) return { section: null, text, omitted: true, reason: 'release commit' };
+  if (breaking && !TYPE_SECTION[type]) return { section: 'Changed', text };
+  if (TYPE_SECTION[type]) return { section: TYPE_SECTION[type], text };
+  if (OMIT_TYPES.has(type)) return { section: null, text: commit.subject, omitted: true, reason: `${type} commits are not user-facing` };
+  return { section: null, text: commit.subject, reason: `unknown type "${type}"` };
+}
+
+/** Matches a release heading such as "## [1.0.2] - date", "## 1.0.2 (date)" or "## v1.0.2". */
+export const RELEASE_HEADING = /^## \[?v?\d+\.\d+/;
+
+/** Follows the heading style already used in the file; Keep a Changelog otherwise. */
+export function headingFor(existing, version, date) {
+  const first = existing?.split('\n').find((l) => RELEASE_HEADING.test(l));
+  if (first && !first.startsWith('## [')) {
+    const prefix = /^## v/.test(first) ? 'v' : '';
+    return /\(\d{4}-\d{2}-\d{2}\)/.test(first) ? `## ${prefix}${version} (${date})` : `## ${prefix}${version}`;
+  }
+  return `## [${version}] - ${date}`;
+}
+
+export function buildEntry(version, commits, date, heading = `## [${version}] - ${date}`) {
+  const sections = Object.fromEntries(SECTIONS.map((s) => [s, []]));
+  const unclassified = [];
+  const omitted = [];
+  for (const commit of commits) {
+    const c = classify(commit);
+    const short = commit.hash.slice(0, 7);
+    if (c.section) sections[c.section].push(c.text.charAt(0).toUpperCase() + c.text.slice(1));
+    else if (c.omitted) omitted.push({ commit: short, subject: commit.subject, reason: c.reason });
+    else unclassified.push({ commit: short, subject: commit.subject, reason: c.reason });
+  }
+  let entry = `${heading}\n`;
+  for (const name of SECTIONS) {
+    if (sections[name].length === 0) continue;
+    entry += `\n### ${name}\n\n${sections[name].map((t) => `- ${t}`).join('\n')}\n`;
+  }
+  return { entry, sections, unclassified, omitted };
+}
+
+/** Inserts the entry below [Unreleased] (or the header), above the newest release. */
+export function insertEntry(existing, version, entry) {
+  if (existing === null) return `${HEADER}\n${entry}`;
+  const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  if (new RegExp(`^## \\[?v?${escaped}(\\]|\\s|$)`, 'm').test(existing)) {
+    throw new Error(`CHANGELOG already has a section for ${version}`);
+  }
+  const lines = existing.split('\n');
+  const idx = lines.findIndex((l) => RELEASE_HEADING.test(l));
+  if (idx === -1) return `${existing.replace(/\n*$/, '\n')}\n${entry}`;
+  lines.splice(idx, 0, ...entry.replace(/\n*$/, '\n').split('\n'));
+  return lines.join('\n');
+}
+
+export function changelog({ cwd = '.', version, since, date = new Date().toISOString().slice(0, 10), write }) {
+  const from = since ?? lastTag(cwd);
+  const commits = readCommits(cwd, from);
+  const existing = write && existsSync(write) ? readFileSync(write, 'utf8') : null;
+  const built = buildEntry(version, commits, date, headingFor(existing, version, date));
+  const checks = [];
+  const total = Object.values(built.sections).reduce((n, s) => n + s.length, 0);
+  checks.push(total > 0
+    ? check('changelog.entries', 'pass', `${total} change(s) since ${from ?? 'the first commit'}`)
+    : check('changelog.entries', 'warn', `No user-facing changes found since ${from ?? 'the first commit'}`, { fix: 'Ask the user what this release changes and write the entry by hand.' }));
+  if (built.unclassified.length) {
+    checks.push(check('changelog.unclassified', 'warn', `${built.unclassified.length} commit(s) could not be classified`, { fix: 'Show them to the user and ask which section each belongs in, or whether to drop it.' }));
+  }
+  if (write) {
+    writeFileSync(write, insertEntry(existing, version, built.entry));
+    checks.push(check('changelog.write', 'pass', `${existing === null ? 'Created' : 'Updated'} ${write}`));
+  }
+  return result(checks, { since: from, entry: built.entry, unclassified: built.unclassified, omitted: built.omitted });
+}
+
+const usage = 'Usage: changelog.mjs --version <version> [--since <tag>] [--date YYYY-MM-DD] [--write CHANGELOG.md] [--cwd <dir>]';
+
+await runCli(import.meta.url, {
+  usage,
+  options: { version: { type: 'string' }, since: { type: 'string' }, date: { type: 'string' }, write: { type: 'string' }, cwd: { type: 'string', default: '.' } },
+}, (v) => {
+  required(v, 'version');
+  return changelog({ cwd: v.cwd, version: v.version, since: v.since, date: v.date, write: v.write });
+});

package/skills/release-agent-shared/scripts/git-preflight.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Git checks before a release: clean tree, expected branch, tag not taken, in sync with upstream.
+import { runCli, check, result, required } from './lib/cli.mjs';
+import { git } from './lib/git.mjs';
+
+export function defaultBranch(cwd, remote) {
+  const head = git(['symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`], cwd);
+  if (head) return head.slice(remote.length + 1);
+  for (const name of ['main', 'master']) {
+    if (git(['rev-parse', '--verify', '--quiet', `refs/heads/${name}`], cwd) !== null) return name;
+  }
+  return null;
+}
+
+export function tagStyle(cwd) {
+  const tags = (git(['tag', '--list'], cwd) ?? '').split('\n').filter(Boolean);
+  const prefixed = tags.filter((t) => /^v\d/.test(t)).length;
+  const bare = tags.filter((t) => /^\d/.test(t)).length;
+  return { prefix: bare > prefixed ? '' : 'v', tagCount: tags.length };
+}
+
+export function gitPreflight({ cwd = '.', branch, tag, remote = 'origin', checkRemote = true }) {
+  const checks = [];
+  if (git(['rev-parse', '--is-inside-work-tree'], cwd) !== 'true') {
+    return result([check('git.repo', 'fail', 'Not inside a git repository', { fix: 'Run the release from the library repository root.' })]);
+  }
+
+  const status = git(['status', '--porcelain'], cwd) ?? '';
+  const dirty = status.split('\n').filter(Boolean);
+  checks.push(dirty.length === 0
+    ? check('git.clean', 'pass', 'Working tree is clean')
+    : check('git.clean', 'fail', `Working tree has ${dirty.length} uncommitted change(s)`, {
+      files: dirty.slice(0, 20).map((l) => l.slice(3)),
+      fix: 'Commit or stash these changes first, so the release commit contains only the version bump and changelog.',
+    }));
+
+  const current = git(['symbolic-ref', '--short', 'HEAD'], cwd);
+  const expected = branch ?? defaultBranch(cwd, remote);
+  if (!current) {
+    checks.push(check('git.branch', 'fail', 'HEAD is detached', { fix: `Check out the release branch${expected ? ` (${expected})` : ''}.` }));
+  } else if (!expected) {
+    checks.push(check('git.branch', 'warn', `On branch ${current}; could not determine the default branch`, { fix: 'Pass --branch with the branch releases are made from.' }));
+  } else {
+    checks.push(current === expected
+      ? check('git.branch', 'pass', `On expected branch ${current}`)
+      : check('git.branch', 'fail', `On branch ${current}, expected ${expected}`, { fix: `Check out ${expected}, or confirm with the user that releasing from ${current} is intended and pass --branch ${current}.` }));
+  }
+
+  const upstream = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], cwd);
+  if (upstream) {
+    const behind = Number(git(['rev-list', '--count', 'HEAD..@{u}'], cwd) ?? 0);
+    const ahead = Number(git(['rev-list', '--count', '@{u}..HEAD'], cwd) ?? 0);
+    if (behind > 0) checks.push(check('git.upstream', 'fail', `Branch is ${behind} commit(s) behind ${upstream} (as of the last fetch)`, { fix: 'Pull the latest changes before releasing.' }));
+    else if (ahead > 0) checks.push(check('git.upstream', 'warn', `Branch has ${ahead} unpushed commit(s) on top of ${upstream}`, { fix: 'Make sure these commits are meant to be part of the release.' }));
+    else checks.push(check('git.upstream', 'pass', `In sync with ${upstream} (as of the last fetch)`));
+  } else {
+    checks.push(check('git.upstream', 'warn', 'Branch has no upstream; cannot compare with the remote'));
+  }
+
+  if (tag) {
+    const local = git(['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], cwd);
+    checks.push(local === null
+      ? check('git.tag.local', 'pass', `Tag ${tag} does not exist locally`)
+      : check('git.tag.local', 'fail', `Tag ${tag} already exists locally`, { fix: 'This version was probably released or attempted before. Choose a new version, or ask the user how this tag was created.' }));
+    if (checkRemote) {
+      const remoteTags = git(['ls-remote', '--tags', remote, `refs/tags/${tag}`], cwd);
+      if (remoteTags === null) checks.push(check('git.tag.remote', 'warn', `Could not query remote "${remote}" for tag ${tag}`));
+      else checks.push(remoteTags === ''
+        ? check('git.tag.remote', 'pass', `Tag ${tag} does not exist on ${remote}`)
+        : check('git.tag.remote', 'fail', `Tag ${tag} already exists on ${remote}`, { fix: 'Choose a new version.' }));
+    }
+  }
+
+  return result(checks, { branch: current, expectedBranch: expected, ...tagStyle(cwd) });
+}
+
+const usage = `Usage: git-preflight.mjs [--branch <name>] [--tag <tag>] [--remote origin] [--cwd <dir>] [--offline]`;
+
+await runCli(import.meta.url, {
+  usage,
+  options: {
+    branch: { type: 'string' }, tag: { type: 'string' }, remote: { type: 'string', default: 'origin' },
+    cwd: { type: 'string', default: '.' }, offline: { type: 'boolean', default: false },
+  },
+}, (v) => {
+  if (v.tag !== undefined) required(v, 'tag');
+  return gitPreflight({ cwd: v.cwd, branch: v.branch, tag: v.tag, remote: v.remote, checkRemote: !v.offline });
+});

package/skills/release-agent-shared/scripts/github-release.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Creates a GitHub release from a CHANGELOG section. Without --create it only
+// prints the command, so nothing outward-facing happens by accident.
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { runCli, check, result, required } from './lib/cli.mjs';
+
+export function extractSection(changelogText, version) {
+  const lines = changelogText.split('\n');
+  const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const start = lines.findIndex((l) => new RegExp(`^## \\[?v?${escaped}(\\]|\\s|$)`).test(l));
+  if (start === -1) return null;
+  let end = lines.findIndex((l, i) => i > start && /^## \[?v?\d+\.\d+/.test(l));
+  if (end === -1) end = lines.length;
+  // Drop link reference definitions that trail the last section.
+  return lines.slice(start + 1, end).filter((l) => !/^\[[^\]]+\]:\s*\S+/.test(l)).join('\n').trim();
+}
+
+function ghStatus() {
+  try {
+    execFileSync('gh', ['--version'], { stdio: 'ignore' });
+  } catch {
+    return 'missing';
+  }
+  try {
+    execFileSync('gh', ['auth', 'status'], { stdio: 'ignore' });
+    return 'ready';
+  } catch {
+    return 'unauthenticated';
+  }
+}
+
+const quote = (s) => (/^[\w./:@-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`);
+
+export function githubRelease({ cwd = '.', tag, version, changelogPath, title, draft = false, create = false }) {
+  const file = join(cwd, changelogPath);
+  if (!existsSync(file)) return result([check('release.changelog', 'fail', `${changelogPath} not found`)]);
+  const notes = extractSection(readFileSync(file, 'utf8'), version);
+  if (!notes) return result([check('release.changelog', 'fail', `No section for ${version} in ${changelogPath}`, { fix: 'Run changelog.mjs first.' })]);
+
+  const notesDir = join(cwd, 'build', 'release-agent');
+  mkdirSync(notesDir, { recursive: true });
+  const notesFile = join(notesDir, `release-notes-${version}.md`);
+  writeFileSync(notesFile, `${notes}\n`);
+
+  const args = ['release', 'create', tag, '--title', title ?? version, '--notes-file', notesFile, '--verify-tag'];
+  if (draft) args.push('--draft');
+  const command = `gh ${args.map(quote).join(' ')}`;
+  const data = { notes, notesFile, command };
+
+  const gh = ghStatus();
+  if (!create) return result([check('release.dry-run', 'pass', `Not created (no --create). Command: ${command}`)], { ...data, gh });
+  if (gh !== 'ready') {
+    const why = gh === 'missing' ? 'gh CLI is not installed' : 'gh CLI is not logged in';
+    return result([check('release.gh', 'warn', `${why}; run the command yourself or create the release on github.com`, {
+      fix: gh === 'missing' ? 'Install gh (https://cli.github.com) or create the release in the browser with the notes file.' : 'Run `gh auth login`, then retry.',
+    })], { ...data, gh });
+  }
+  try {
+    const url = execFileSync('gh', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    return result([check('release.create', 'pass', `Created GitHub release ${tag}`)], { ...data, url });
+  } catch (err) {
+    return result([check('release.create', 'fail', `gh failed: ${(err.stderr || err.message).toString().trim()}`, {
+      fix: 'If the tag is not on the remote yet, push it first (gh is called with --verify-tag).',
+    })], data);
+  }
+}
+
+const usage = 'Usage: github-release.mjs --tag <tag> --version <version> [--changelog CHANGELOG.md] [--title <title>] [--draft] [--create] [--cwd <dir>]';
+
+await runCli(import.meta.url, {
+  usage,
+  options: {
+    tag: { type: 'string' }, version: { type: 'string' }, changelog: { type: 'string', default: 'CHANGELOG.md' },
+    title: { type: 'string' }, draft: { type: 'boolean', default: false }, create: { type: 'boolean', default: false },
+    cwd: { type: 'string', default: '.' },
+  },
+}, (v) => {
+  required(v, 'tag', 'version');
+  return githubRelease({ cwd: v.cwd, tag: v.tag, version: v.version, changelogPath: v.changelog, title: v.title, draft: v.draft, create: v.create });
+});

package/skills/release-agent-shared/scripts/lib/cli.mjs

@@ -0,0 +1,66 @@
+// Common CLI plumbing: every script prints one JSON object { ok, checks, data? }
+// and exits 0 (all checks passed or warned), 1 (a check failed) or 2 (usage error).
+import { parseArgs } from 'node:util';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export function check(id, status, message, extra = {}) {
+  return { id, status, message, ...extra };
+}
+
+export function result(checks, data) {
+  const ok = checks.every((c) => c.status !== 'fail');
+  return data === undefined ? { ok, checks } : { ok, checks, data };
+}
+
+export function isMain(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(metaUrl));
+  } catch {
+    return false;
+  }
+}
+
+function emit(obj, exitCode) {
+  process.stdout.write(`${JSON.stringify(obj, null, 2)}\n`);
+  process.exitCode = exitCode;
+}
+
+export function progress(message) {
+  process.stderr.write(`${message}\n`);
+}
+
+/**
+ * Runs `handler(values, positionals)` when the module is executed directly.
+ * The handler returns a result object; thrown errors become { ok: false, error }.
+ */
+export async function runCli(metaUrl, { options = {}, usage, allowPositionals = false }, handler) {
+  if (!isMain(metaUrl)) return;
+  let parsed;
+  try {
+    parsed = parseArgs({ options: { help: { type: 'boolean' }, ...options }, allowPositionals, strict: true });
+  } catch (err) {
+    emit({ ok: false, error: err.message, usage }, 2);
+    return;
+  }
+  if (parsed.values.help) {
+    process.stdout.write(`${usage}\n`);
+    return;
+  }
+  try {
+    const out = await handler(parsed.values, parsed.positionals);
+    emit(out, out.ok ? 0 : 1);
+  } catch (err) {
+    if (err instanceof UsageError) emit({ ok: false, error: err.message, usage }, 2);
+    else emit({ ok: false, error: err.message }, 1);
+  }
+}
+
+export class UsageError extends Error {}
+
+export function required(values, ...names) {
+  for (const name of names) {
+    if (values[name] === undefined || values[name] === '') throw new UsageError(`--${name} is required`);
+  }
+}

package/skills/release-agent-shared/scripts/lib/git.mjs

@@ -0,0 +1,18 @@
+import { execFileSync } from 'node:child_process';
+
+/** Runs git and returns trimmed stdout, or null when git exits non-zero. */
+export function git(args, cwd) {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function lastTag(cwd) {
+  return git(['describe', '--tags', '--abbrev=0'], cwd);
+}
+
+export function isTracked(file, cwd) {
+  return git(['ls-files', '--error-unmatch', file], cwd) !== null;
+}