githits-release

name	githits-release
description	Use when preparing, reviewing, or executing a GitHits CLI release. Covers release-version consistency, plugin manifests, user-visible changelog notes, MCP instruction quality, MCP registry publishing/versioning, and the special lifecycle for published Agent Skills.
compatibility	Project-local skill for GitHits maintainers; not packaged for end users.
metadata	{"internal":true}

Use this skill for GitHits release work, version-bump PRs, release-readiness reviews, and release notes.

Release Checklist

• Root githits and @githits/mcp have separate release flows. Bump both only when both surfaces changed.
• For root githits releases, bump package.json, server.json, .plugin/plugin.json, .claude-plugin/plugin.json, plugins/claude/.claude-plugin/plugin.json, .claude-plugin/marketplace.json, and gemini-extension.json together.
• For @githits/mcp releases, bump packages/mcp/package.json only when MCP package API, tool behavior, instructions, schemas, MCP auth/error behavior, or remote-server-facing public types changed.
• For coordinated CLI and MCP releases, keep the MCP minor aligned with the CLI minor for discoverability. Start the first MCP release for a CLI minor at X.Y.0, then bump MCP patch for later MCP-package-visible changes in that CLI minor. Do not bump MCP for CLI-only changes.
• After merge, the root release workflow and MCP release workflow both run from the successful Main workflow on main. The MCP workflow publishes only when @githits/mcp@<version> is not already on npm; use its manual workflow_dispatch path only for recovery or explicit dry runs.
• The root release workflow also publishes server.json to the official MCP registry as com.githits/githits after npm publishes githits@<version>. Treat the MCP registry entry as part of the root githits release, not the @githits/mcp package release.
• Keep server.json.version, the npm package entry version in server.json, and root package.json.version aligned. The release workflow rewrites a temporary registry manifest from package.json, but the committed server.json should still reflect the intended next root release for review and local validation.
• Keep root package.json#mcpName equal to com.githits/githits; npm registry ownership validation depends on the published package manifest matching server.json.name.
• Run or rely on package-scoped version checks to verify root plugin versions stay aligned and MCP versions are intentionally independent.
• Collect a changelog of user-visible changes before release. Include CLI behavior, MCP tool behavior, Agent Skills, auth/error UX, output format changes, and agent-facing instruction changes.
• Review public skills before signoff whenever user-facing CLI/MCP behavior changed. After the behavior is released or included in the same release branch, update skills/githits-code/SKILL.md, skills/githits-package/SKILL.md, and their references so skills.sh users get instructions that match the released surface.
• Keep PR titles and labels release-note friendly; GitHub release notes are generated from merged PRs and .github/release.yml categories.
• Run bun run build before release-readiness signoff. Run targeted smoke/eval commands when MCP tools, CLI commands, shared formatters, auth/error envelopes, Agent Skills, or agent-facing instructions changed.

MCP Registry

• Registry name: com.githits/githits.
• Registry server.json should list both supported transports when available: hosted remote MCP at https://mcp.githits.com and npm stdio via the root githits package with packageArguments equivalent to githits mcp start.
• Do not encode npx githits@latest literally in server.json. The registry package entry uses runtimeHint: "npx", identifier: "githits", the exact release version, and package arguments. This represents the pinned release artifact, while docs can continue to show npx githits@latest mcp start for manual setup.
• Publish to the MCP registry only after githits@<version> is published to npm, because registry validation checks the npm package metadata.
• MCP registry publishing uses GitHub Actions OIDC, the production environment, and the Azure Key Vault-backed signer. Do not add an Azure client secret, Key Vault secret, exported signing key, npm token, or raw registry private key.
• Required GitHub production environment secrets are identifiers used for masking and OIDC wiring: AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID, AZURE_CLIENT_ID, MCP_REGISTRY_KEY_VAULT_NAME, and MCP_REGISTRY_SIGNING_KEY_NAME. Do not print them, dump environment variables, or enable shell tracing.
• Before releasing a registry update, verify mcp-publisher validate server.json locally with the pinned publisher version when practical.
• Before the first registry publish, verify the domain proof is deployed at https://githits.com/.well-known/mcp-registry-auth.
• For remote MCP auth, do not add static Authorization header metadata to server.json. The official registry remote transport schema supports URL, optional user-provided headers, and URL variables; OAuth is discovered from the remote MCP server through its WWW-Authenticate response and /.well-known/oauth-protected-resource metadata. Validate https://mcp.githits.com/.well-known/oauth-protected-resource returns 200 and unauthenticated remote MCP requests return the expected 401 with resource_metadata.

Agent Skills Lifecycle

• User-facing skills under skills/ are picked up by skills.sh from main, not from npm release artifacts.
• Do not update skills/ to describe unreleased CLI/MCP behavior. A merge to main can expose those skill instructions immediately.
• After the backing CLI/MCP behavior is released or part of the release being prepared, update skills/ so skill descriptions, decision flows, examples, detailed references, and command-to-MCP mappings match the released surface.
• When MCP instructions, tool descriptions, or guardrails change, review skills/githits-code/SKILL.md, skills/githits-package/SKILL.md, and their references for parity. Keep MCP instructions as the quality baseline; they are currently strong and should not be weakened casually.
• If a skill update is intentionally delayed until after release, note that in the release/change plan so it is not forgotten.

Changelog Collection

• Use git log and merged PRs since the previous tag to identify user-visible changes.
• Exclude purely internal refactors unless they affect users, agent behavior, performance, or reliability.
• Call out changes that require users or agents to adjust commands, flags, config, auth setup, environment variables, MCP setup, or skill usage.
• Mention known limitations or intentionally deferred skill updates when they affect current users.

Guardrails

• Do not expose credentials while verifying release/auth flows.
• Do not force-push, amend, or rewrite release history unless explicitly requested.
• If root package and plugin manifests disagree, stop and fix them before a root githits release.
• If @githits/mcp changed but its package version did not, stop and either bump it or document why the change is not MCP-package-visible.