AGENT SKILL

release

Automate AK5 version bump and release workflows for PyPI. Use when releasing a new version of AK5 (patch, minor, or major), running pre-flight linting and test suites, compiling embedded Web UI assets, synchronizing lockfiles, and pushing release git tags for automated CI/CD deployment.

License 许可
Apache-2.0
所属仓库
fritzprix/ak5
最近更新
2026-11-08
Stars
★ 1
Forks
0

01 前言 Front Matter

name
release
description
Automate AK5 version bump and release workflows for PyPI. Use when releasing a new version of AK5 (patch, minor, or major), running pre-flight linting and test suites, compiling embedded Web UI assets, synchronizing lockfiles, and pushing release git tags for automated CI/CD deployment.

03 SKILL.md 正文

AK5 Release Automation Skill

Use this skill when preparing and publishing a new release of AK5 (Python package on PyPI, embedded Web UI, and TypeScript SDK).


1. Release Types & Semantic Versioning

Choose the appropriate release bump based on SemVer 2.0 (MAJOR.MINOR.PATCH):

Release Type Command When to Use Example
patch python3 scripts/release.py patch --push Bug fixes, documentation revisions, minor styling or security patches 1.0.3 → 1.0.4
minor python3 scripts/release.py minor --push New CLI commands, backwards-compatible API features, new MCP tools 1.0.3 → 1.1.0
major python3 scripts/release.py major --push Breaking API/schema changes, major architectural redesigns 1.0.3 → 2.0.0

2. One-Command Automated Release

AK5 includes an automated release script that executes the complete quality and publishing pipeline:

# Preview version calculation without modifying files
python3 scripts/release.py patch --dry-run
python3 scripts/release.py minor --dry-run
python3 scripts/release.py major --dry-run

# Run full pipeline: test -> compile web UI -> bump versions -> lock -> build -> commit & push
python3 scripts/release.py patch --push

What the automation script executes:

  1. Pre-flight Quality Check: Runs uv run ruff check backend and uv run pytest backend/tests.
  2. Web UI Compilation: Executes scripts/build_web_ui.sh to compile Next.js static assets into backend/src/ak5/web_ui/.
  3. Monorepo Version Sync: Synchronizes version numbers in:
    • backend/pyproject.toml
    • frontend/package.json
    • packages/sdk/package.json
  4. Lockfile Synchronization: Executes uv lock to update uv.lock.
  5. Distribution Build: Runs uv build backend --out-dir dist.
  6. Isolated wheel smoke (hard gate): Runs scripts/smoke_uvx_wheel.sh — installs the wheel alone (like uvx), asserts greenlet/asyncio import, ak5.main:app, embedded UI, and CLI help. Release must not tag/push if this fails.
  7. Git Tag & Push: Commits changes, tags v<version>, and pushes both master and the tag to GitHub origin.

3. Manual Step-by-Step Procedure

If you prefer to perform each step manually or need granular debugging:

Step 1: Quality Checks

uv run ruff check backend
uv run pytest backend/tests

Step 2: Build Embedded Static Web Assets

chmod +x scripts/build_web_ui.sh
./scripts/build_web_ui.sh

Step 3: Bump Versions

Update the version string in the following files:

  • backend/pyproject.toml (version = "X.Y.Z")
  • frontend/package.json ("version": "X.Y.Z")
  • packages/sdk/package.json ("version": "X.Y.Z")

Step 4: Update Lockfile & Test Wheel Build

uv lock
rm -rf dist
uv build backend --out-dir dist
unzip -l dist/*.whl | grep web_ui  # Verify web UI is bundled

Step 5: Commit, Tag, and Push

VERSION="1.0.4"
git add backend/pyproject.toml frontend/package.json packages/sdk/package.json uv.lock
git commit -m "release: v${VERSION} — bump version to ${VERSION}"
git tag -a "v${VERSION}" -m "v${VERSION} release"
git push origin master
git push origin "v${VERSION}"

4. Post-Release Verification

After pushing the git tag, GitHub Actions automatically builds and publishes the package to PyPI:

Step 1: Monitor GitHub Actions Run

gh run list --workflow=release.yml -L 1

Step 2: Check PyPI Propagation

# Check latest registered version on PyPI
curl -s https://pypi.org/pypi/ak5/json | jq -r '.info.version'

Step 3: Zero-Install Smoke Test

# Verify the published version executes via uvx
uvx --refresh ak5@latest --version

# Verify the server extra (API + embedded dashboard) resolves
uvx --refresh --from 'ak5[server]@latest' ak5 serve --help

04 同仓库更多 Skills

fritzprix
fritzprix/ak5

ak5

Work as a triage, worker, or gatekeeper agent on an AK5 board through the `ak5` CLI (pull model), in an adversarial loop where each role verifies the previous one and a human gives final approval. Use when you need to find claimable work (`ak5 next`), claim a ticket, submit a deliverable, review or approve another agent's work, route inbox requests to boards, block on a human question, or register a hook that wakes your harness when work becomes available.

★ 1
fritzprix
fritzprix/ak5

ak5

Work as a triage, worker, or gatekeeper agent on an AK5 board through the `ak5` CLI (pull model), in an adversarial loop where each role verifies the previous one and a human gives final approval. Use when you need to find claimable work (`ak5 next`), claim a ticket, submit a deliverable, review or approve another agent's work, route inbox requests to boards, block on a human question, or register a hook that wakes your harness when work becomes available.

★ 1
fritzprix
fritzprix/ak5

release

Automate AK5 version bump and release workflows for PyPI. Use when releasing a new version of AK5 (patch, minor, or major), running pre-flight linting and test suites, compiling embedded Web UI assets, synchronizing lockfiles, and pushing release git tags for automated CI/CD deployment.

★ 1
fritzprix
fritzprix/ak5

cursor-delegate

Delegate code reviews, refactoring, bug fixes, or implementation tasks to the Cursor Agent CLI (`cursor agent` / `agent`). Use when running Cursor as an AK5 worker (claim → run → submit), executing headless/non-interactive code reviews or refactoring, waking Cursor from AK5 WORK_AVAILABLE events, or syncing Cursor output back to AK5 tickets.

★ 1
fritzprix
fritzprix/ak5

create-pr

Create a GitHub pull request from the current feature branch into the latest ``dev/MAJOR.MINOR.x`` integration branch. Use when the user asks to open/create a PR, ``/create-pr``, or merge feature work into ``dev/z.y.x``.

★ 1
fritzprix
fritzprix/ak5

audit-local

Audit uncommitted local working-tree changes for bugs, security issues, regressions, and missing tests. Use when the user asks to audit/review local changes, dirty tree, uncommitted diff, ``/audit-local``, or wants a hands-on review instead of only launching Bugbot.

★ 1