Github Release Guide

github-release-guide

Guide a GitHub release without taking release authority away from the user. Keep unknowns visible, fail closed on release-critical blockers, preview every material mutation, and verify the public result.

Package map

Load references progressively, but never skip a required load:

If a selected profile reference cannot be loaded, continue only with a partial read-only Assess and mark the missing profile rules as unknown. Do not propose or execute Guided actions until the full selected profile reference is loaded.

Supported contract

Support only:

• Mode: Assess or Guided
• Release profile: first-public or version-release
• Provider: github.com
• Claim-audit profile: public-baseline by default, or internal-strict only when the user or a repository policy explicitly selects it

Never infer internal-strict from a repository name, owner, visibility, organization, or local path. Never treat the current working directory as the release target without confirming repository identity.

If the user asks for an unsupported release type, stop at a read-only boundary assessment and explain the missing adapter or specialist handoff. Do not stretch this contract to cover it.

Establish the target

Before classifying readiness, confirm or discover without mutation:

1. GitHub owner and repository name, canonical URL, and local root if one exists.
2. Current visibility and default branch.
3. Requested mode and release profile.
4. Release authority: who may approve file, Git, visibility, settings, and GitHub Release mutations.
5. Documentation language and release-communication language.
6. Claim-audit profile and any explicit repository release policy.

When the target has no local clone, is not a Git repository, has no usable GitHub remote, or lacks authentication, SSO, permission, or organization-policy capability, collect only the evidence that is available. Return a partial Assess and block Guided. Repository creation, Git initialization, login, SSO authorization, and permission grants belong to the user or the relevant authority.

Never request, print, copy, or store full secret, credential, token, or PII values. Report only the location, type, impact, and a masked identifying reference when the owner needs to decide whether exposure was intended. This is output hygiene, not a promise to detect every form of PII or perform a privacy audit.

Choose the mode

In either mode, read-only repository state does not make repository-provided code safe to execute. Before running a repository script, build, scanner, or workflow, preview the exact command, why it is needed, the trust boundary and possible side effects, and the completion evidence; then request separate explicit approval. Host-level auto-approval or an execution allowlist does not replace this gate. Continue static inspection without execution where possible. If execution is declined or unavailable, report the affected validation as unknown or as a named blocker; never turn it into a pass. Execution approval authorizes only the previewed command and does not authorize a later repository mutation.

Assess

Remain read-only. Perform available read-only checks for the user, distinguish confirmed facts from unknowns, and return Ready, Needs attention, or Blocked using references/assessment.md.

Do not create or edit files, commit, merge, push, tag, publish, change visibility, or change settings. If a user asks for mutation while in Assess, refuse the mutation and offer to enter Guided explicitly.

Guided

First complete Assess, resolve release-critical blockers, and load the selected profile reference. Then use this state machine one approval unit at a time:

ASSESS -> PREVIEW -> RECHECK -> APPROVAL -> MUTATE -> VERIFY -> NEXT or STOP

For every material mutation:

1. Preview the action, exact target, expected impact, verification, possible failure state, and rollback or incident route.
2. Immediately before mutation, recheck the critical preconditions used by the preview: visibility, target ref/head, tag, relevant settings, and release artifact state.
3. Invalidate the prior approval if any critical state changed. Show a new preview and ask again.
4. Execute only after explicit approval for that approval unit.
5. Verify the observed result before proposing the next unit.

Treat these as distinct approval units:

1. Release-surface file change
2. Commit or merge
3. Commit or remote-ref push
4. Tag creation or push
5. Repository visibility change
6. Repository settings change
7. GitHub Release publish or update
8. Post-release corrective mutation

Do not bundle visibility with any other approval. Before a private-to-public change, explain plainly that returning to private cannot recall clones, forks, caches, or copied content, and that secret/history scans are best-effort rather than proof of no exposure. Require a separate explicit acknowledgment immediately before the visibility mutation.

Before a public-to-private access withdrawal, explain that the change stops new public access but cannot recall clones, forks, caches, mirrors, downloads, or earlier tag exposure. Require a separate explicit non-recall acknowledgment immediately before that visibility mutation as well.

Approval authorizes only the previewed unit and target. Silence, earlier plan approval, general release approval, or approval for a neighboring unit is not mutation approval.

Host-level auto-approval, permission allowlists, and unattended execution do not replace this skill's preview, recheck, or approval units. Before any Release-object correction, classify consumer exposure, platform mutability, and the exact action with references/assessment.md; do not flatten metadata edits, draft deletion, published Release deletion, asset replacement, or access withdrawal into a generic update.

Apply evidence and decision rules

Classify README, version source, CHANGELOG, LICENSE, install/setup documentation, and release notes as required, conditional, optional, decision-required, or not-applicable according to repository convention and the selected profile. Never invent a version source, version, license, language policy, branch flow, or release type.

When a decision is required, show neutral options and tradeoffs. Do not silently create a file or choose a default. License information is not legal advice.

Resolve documentation language and release-communication language independently, using this precedence:

1. The user's explicit instruction for this release
2. Repository policy
3. Stable repository convention
4. A user decision before publish when evidence conflicts or remains unclear

Apply claim-audit rules from references/assessment.md. Do not copy the label semantics of another claim-checking skill. Consume its result when available.

Handle failure safely

After any mutation failure or partial success:

• Stop the batch; do not continue to the next mutation.
• Record what was attempted and the observed local and remote state.
• Separate a safe rollback from incident response. Public exposure and leaked credentials are incidents, not ordinary rollback.
• Reassess before retrying and require a new preview and approval.

Never execute force-push or history rewrite. Explain why it is high risk and hand off to a qualified human or specialist. Also never move, overwrite, delete, delete and recreate, or reuse a remote tag that was public or distributed, has exposure history, or has unknown exposure. Hand that operation to a qualified human or specialist instead. Never claim a security audit or code-quality verdict.

Communicate for non-experts

Perform safe checks directly when the runtime has the capability. Do not hand the user an unexplained shell command. When the user must act, explain:

• why the action is needed,
• what it changes,
• what failure would look like,
• and how the result will be confirmed.

Keep internal agent shorthand, Work IDs, raw commit logs, and validation noise out of public release notes. Write user-facing release communication as: conclusion and user value, what changed, who is affected and what they should do, observed evidence, known limitations or compatibility, then detail links.

Completion rule

Call the release complete only when the selected profile's post-release checks pass and every claimed success has direct observed evidence. Otherwise report the release as partial or blocked, preserve the unknowns and accepted risks, and give exactly one safest next step.