instructor-release

name	instructor-release
description	Prepare and execute a new InstructorPHP version release. Use when asked to cut a release, prepare release notes, run release QA, create a release epic and tasks in bd, verify changed packages since the last tag, run curated live examples, publish via scripts/release/publish-ver.sh, or prepare the launch announcement.

Instructor Release

This skill is the repo-local release orchestrator for InstructorPHP. A release is never a loose checklist. It is always a deterministic bd workflow with explicit gates, tracked blockers, and a final approval step before publish.

Treat these files as source of truth:

• AGENTS.md for repo rules, bd, and git ownership constraints
• CONTRIBUTING.md for release and package-management workflow
• QUALITY.md for verification lanes
• scripts/release/publish-ver.sh for the actual publish path
• scripts/packages/sync-ver.sh for version synchronization
• .github/workflows/docs.yml for validated Mintlify and GitHub Pages deployment
• .github/workflows/php.yml for compatibility matrix coverage
• .github/workflows/split.yml for post-tag split package publishing
• docs/release-notes/*.mdx for public release-note shape

Read these references as needed:

• references/bd-release-template.md
• references/preflight-checks.md
• references/examples-policy.md
• references/release-notes-template.mdx
• references/post-release.md

When To Use

Use this skill when the user asks to:

• create or ship a new version release
• prepare release notes or package-change summaries
• run release-candidate QA or production-readiness checks
• decide which tests, examples, docs checks, and CI reproductions are required before publish
• publish with scripts/release/publish-ver.sh
• prepare or post the release announcement

Release Rules

• A release always gets a bd epic and child tasks.
• Root quality gates must be green before publish unless the user explicitly accepts a waiver.
• Split-package verification must be green before publish unless the user explicitly accepts a waiver.
• Live examples are expensive. Run the curated live smoke set once per release cycle, then retry only failed examples after fixes.
• Do not publish, tag, push, or post to X without explicit approval in the current conversation.
• Do not hide failing checks. Record them in bd notes and block the release until resolved or explicitly waived.

Default Workflow

1. Determine the target version and latest tag.
2. Create the bd epic and child tasks from references/bd-release-template.md.
3. Inventory changed packages since the last tag, focusing on packages/*/src.
4. Run preflight from references/preflight-checks.md.
5. Run curated live examples from references/examples-policy.md.
6. Produce per-package change summaries from diffs.
7. Consolidate those summaries into a release draft.
8. Write docs/release-notes/vX.Y.Z.mdx using references/release-notes-template.mdx.
9. Run composer qa:docs-sites -- --release X.Y.Z; never stage generated builds/ output.
10. Ask for explicit approval before scripts/release/publish-ver.sh.
11. After publish, verify both docs provenance endpoints, the GitHub release, and split workflow kickoff.
12. Draft the announcement from references/post-release.md; post externally only after explicit approval.

Deterministic bd Execution

A release is always multi-step. Use bd, not ad hoc notes.

1. Create or reuse a scoped release epic.
2. Create child tasks by lane:
   • scope and changed-package inventory
   • root preflight
   • split-package verification
   • live example verification
   • package change summaries
   • docs/API drift audit
   • release notes draft
   • publish gate
   • post-release communication
3. Claim tasks before work: bd update <id> --claim --json.
4. Record exact commands, failures, retries, and blockers in task notes.
5. Create discovered-from follow-up tasks for unrelated debt or tooling defects.
6. Close tasks only when the gate is green or the blocker is explicitly tracked and waived.

Preflight Policy

Default release gates:

• composer validate --strict
• composer test-all
• composer qa
• ./scripts/test/run-all-tests.sh
• composer qa:docs
• composer qa:docs-sites -- --release X.Y.Z
• composer docs drift --tier=public
• act pull_request -W .github/workflows/php.yml -j build --dryrun

Add targeted non-dryrun act cells when:

• dependency constraints changed
• workflow behavior changed
• compatibility surfaces changed
• the current release includes install-time or matrix-sensitive fixes

Example Policy

Use the deterministic example-selection rules in references/examples-policy.md.

Key rules:

• do not run the entire example corpus by default
• run the curated live smoke set once per release cycle
• add conditional live examples only for changed surfaces
• retry only the failed examples after fixes
• use non-live examples as supplementary verification, not as a substitute for live smoke coverage

Package Change Summaries

Summaries must be package-aware and diff-based.

• identify changed packages from packages/*/src since the last tag
• inspect package diffs directly; do not rely solely on generated scripts that require external CLIs
• focus on developer-facing changes, public API shifts, fixes, behavior changes, and upgrade impact
• keep one summary per changed package, then consolidate into the release draft

Release Notes

Write the public note to docs/release-notes/vX.Y.Z.mdx.

Requirements:

• match the existing repo release-note style
• include user-visible highlights, upgrade notes, and breaking changes if any
• reflect the package summaries, not just a raw changelog
• call out docs, compatibility, telemetry, runtime, agent, or provider changes only when they matter to users

Use references/release-notes-template.mdx as the starting shape.

Publish And Communication Gates

Before publish:

• summarize the exact green gates
• summarize any waived or unresolved risk
• ask for explicit approval to run scripts/release/publish-ver.sh <version>

After publish:

• verify the main GitHub release exists
• verify both public documentation sites expose the release and final source SHA
• verify the split workflow started
• prepare announcement material

For announcement work:

• use references/post-release.md to draft the short release announcement
• post externally only if the user explicitly asks and approves it in the current conversation

Reporting Standard

The final release summary must include:

• target version and base tag
• changed packages
• commands actually run
• pass/fail status by release gate
• live examples run and retried
• blockers, waivers, and follow-up bd tasks
• release-note file path
• whether publish happened
• whether announcement drafting/posting happened