agent-devex 0.15.0__tar.gz

agent_devex-0.15.0/.flake8

@@ -0,0 +1,8 @@
+[flake8]
+# Match pyproject.toml's [tool.black] line-length (100) and skip E203
+# ("whitespace before ':'") because black's preferred slice style conflicts
+# with PEP 8 on that one rule. The combination is the documented "black +
+# flake8" compatibility settings per black's own docs.
+max-line-length = 100
+extend-ignore =
+    E203,

agent_devex-0.15.0/.github/workflows/docs.yml

@@ -0,0 +1,146 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/agent_experience/commands/**/SKILL.md"
+      - "src/agent_experience/core/skill_loader.py"
+      - "scripts/sync_skill_md.py"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "src/agent_experience/commands/**/SKILL.md"
+      - "src/agent_experience/core/skill_loader.py"
+      - "scripts/sync_skill_md.py"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  deployments: write
+  pull-requests: write  # for posting the preview URL comment on PRs
+
+jobs:
+  build-and-deploy:
+    # Pull requests from forks cannot see the Cloudflare secrets (GitHub
+    # masks them for security), so the deploy step would fail. Skip the
+    # whole job for fork PRs and let reviewers rely on local `bundle exec
+    # jekyll serve`. This repo is single-owner today, so in practice
+    # every PR comes from a branch within agentculture/agex-cli and hits the
+    # fast path.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      # Refresh docs/commands/*.md from the ground-truth SKILL.md files so
+      # the deployed site cannot drift from what the CLI actually ships.
+      - uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.11"
+      # Match the install pattern used by .github/workflows/build.yml -- the
+      # repo does not commit a uv.lock, so `uv venv` + `uv pip install -e .`
+      # is the reproducible shape across every workflow.
+      - run: uv venv
+      - run: uv pip install -e "."
+      - run: uv run python scripts/sync_skill_md.py
+
+      # Jekyll build.
+      - uses: ruby/setup-ruby@7372622e62b60b3cb750dcd2b9e32c247ffec26a  # v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true
+          working-directory: docs
+      - run: bundle exec jekyll build
+        working-directory: docs
+
+      # Compute the Cloudflare Pages branch name from the PR's head ref.
+      # CF Pages uses the branch name as a subdomain component, so only
+      # `[a-zA-Z0-9-]` are safe: `/`, `.`, whitespace, and other chars
+      # produce a failing branch-alias URL. Replace unsafe chars with `-`,
+      # collapse consecutive dashes, and strip leading/trailing dashes.
+      # Only used on pull_request events -- push and workflow_dispatch
+      # always deploy `--branch=main` (the production branch).
+      - name: Compute preview branch
+        id: branch
+        if: github.event_name == 'pull_request'
+        env:
+          # `github.head_ref` is attacker-controllable (branch name on a PR
+          # from a fork). Pass it through an env var rather than expanding
+          # it inline into the `run:` script -- env values are not re-parsed
+          # by the shell, so the sed sanitiser can no longer be bypassed by
+          # crafted branch names containing shell metacharacters.
+          HEAD_REF: ${{ github.head_ref }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          safe=$(printf '%s' "$HEAD_REF" | sed 's/[^a-zA-Z0-9-]/-/g; s/--*/-/g; s/^-//; s/-$//')
+          # Defence-in-depth: a head_ref of "---" (or other input that is
+          # fully stripped by the sanitiser) would yield an empty `safe`,
+          # and the deploy step's `... && steps.branch.outputs.name ||
+          # 'main'` fallback would then resolve to `'main'` -- publishing
+          # PR content to the production alias. Substitute a deterministic
+          # per-PR name instead.
+          if [ -z "$safe" ]; then
+            safe="pr-${PR_NUMBER}"
+          fi
+          echo "name=$safe" >> "$GITHUB_OUTPUT"
+
+      # Deploy to Cloudflare Pages.
+      # - push / workflow_dispatch -> `--branch=main` = production
+      # - pull_request              -> `--branch=<sanitized-head-ref>` = preview
+      # The project `agex` is a Direct Upload project, so CF won't auto-
+      # build on its own; this step IS the build+deploy pipeline.
+      - name: Deploy to Cloudflare Pages
+        id: deploy
+        uses: cloudflare/wrangler-action@9acf94ace14e7dc412b076f2c5c20b8ce93c79cd  # v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy docs/_site --project-name=agex --branch=${{ github.event_name == 'pull_request' && steps.branch.outputs.name || 'main' }}
+
+      # Post the preview URL back on the PR so reviewers can click through
+      # without digging into the workflow logs. Uses a marker
+      # (`<!-- agex-docs-preview -->`) to update the existing comment on
+      # subsequent pushes instead of spamming the PR thread with a new
+      # comment per workflow run. `gh` is preinstalled on GitHub runners
+      # so no extra SHA-pinned action is needed. Runs only on PR events.
+      - name: Post (or update) preview URL comment
+        if: github.event_name == 'pull_request' && steps.deploy.outputs.deployment-url != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          DEPLOY_URL: ${{ steps.deploy.outputs.deployment-url }}
+          BRANCH: ${{ steps.branch.outputs.name }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -e
+          MARKER='<!-- agex-docs-preview -->'
+          ALIAS_URL="https://${BRANCH}.agex.pages.dev"
+          # Two URLs intentionally:
+          #  * deploy URL (hash)    -- immutable pin for THIS deploy, ideal for
+          #                            review bookmarks that should not drift.
+          #  * branch-alias URL     -- stays the same as you push new commits;
+          #                            always reflects the latest preview.
+          BODY="$MARKER"$'\n'"📘 **docs preview** for this PR:"$'\n\n'"- **Latest deploy:** $DEPLOY_URL  _(immutable — this specific commit)_"$'\n'"- **Branch alias:** $ALIAS_URL  _(always latest — updates on each push)_"
+          # `gh api --paginate` streams one JSON array per page; `jq -s`
+          # ("slurp") collects them into `[[page1], [page2], ...]`, `add`
+          # flattens to a single array, then the filter picks our marker.
+          # `gh api --slurp --jq` itself is mutually exclusive (see
+          # https://github.com/cli/cli/issues/8615), so the slurp has to
+          # happen inside jq. Without the pagination + slurp, PRs with
+          # more than 30 comments would miss the marker and post
+          # duplicate comments on each run.
+          EXISTING=$(gh api --paginate "repos/$REPO/issues/$PR_NUMBER/comments" \
+            | jq -rs "add | [.[] | select(.body | contains(\"$MARKER\")) | .id] | first // empty")
+          if [ -n "$EXISTING" ]; then
+            gh api --method PATCH "repos/$REPO/issues/comments/$EXISTING" \
+              -f body="$BODY" > /dev/null
+            echo "Updated existing preview comment #$EXISTING"
+          else
+            gh pr comment "$PR_NUMBER" --body "$BODY"
+            echo "Created new preview comment"
+          fi

agent_devex-0.15.0/.github/workflows/publish.yml

@@ -0,0 +1,449 @@
+name: publish
+
+# Publishes sdist + wheel with the shape:
+#
+#   - PR              → TestPyPI  (dev version -- per-PR installable preview)
+#   - Push to main    → TestPyPI  (stable version, canary)
+#                    ↓ if v<version> tag doesn't exist yet
+#                    → autotag    (creates + pushes the tag)
+#                    ↓
+#                    → PyPI       (real release, only when autotag succeeded)
+#                    ↓
+#                    → GitHub Release with the matching CHANGELOG section
+#
+# Manual tagging is NOT required -- the `autotag` job turns the version field
+# in `pyproject.toml` into the release signal. Forgetting to bump is caught
+# on the PR by the `version-check` job in test.yml, which fails with a sticky
+# comment pointing at `/version-bump`.
+#
+# The `v*` tag trigger is deliberately absent: tags are created by this
+# workflow (via GITHUB_TOKEN, which by design does not retrigger workflows
+# to prevent loops), and PyPI publish runs inline in the same workflow run.
+# A tag pushed manually from a laptop would therefore not fire a publish --
+# if you ever need that, use `gh workflow run` on this file's main branch
+# or add a `workflow_dispatch:` trigger.
+#
+# Trusted Publishing (OIDC) is used in every publish job -- no API tokens.
+# One-time setup on pypi.org / test.pypi.org and in the repo's Environments
+# (`pypi`, `testpypi`) is documented in the original header below:
+#
+#   - PyPI project `agex-cli` → Publishing → Add a GitHub pending publisher
+#       Owner: OriNachum  Repo: agex
+#       Workflow: publish.yml  Environment: pypi
+#
+#   - TestPyPI project `agex-cli` → same shape, Environment: testpypi
+#
+#   - GitHub repo → Settings → Environments → create `pypi` and `testpypi`
+#     (any required reviewers / wait timers live there)
+#
+# The PR job rewrites `version = "X.Y.Z"` to `"X.Y.Z.devN"` where N is
+# the workflow run number. PEP 440's dev segment is a single integer
+# (internal dots aren't allowed), so run_attempt is NOT encoded in the
+# version -- instead `skip-existing: true` on the TestPyPI upload makes
+# reruns idempotent. PEP 440 orders `.devN` strictly below the real
+# release, so dev wheels never overshadow stable ones on TestPyPI. The
+# PR job comments the exact install command back on the PR (sticky:
+# edits the comment in place on reruns).
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths:
+      - "pyproject.toml"
+      - "src/**"
+      - ".github/workflows/publish.yml"
+
+# Permissions are declared per-job (least privilege). There is no
+# workflow-level `permissions:` block -- a job-level block fully replaces
+# any workflow-level default anyway, so declaring at job level keeps the
+# scope each job actually needs visible in one place.
+
+jobs:
+  # --------------------------------------------------------------------------
+  # Shared build job for the main-push path. Produces one `dist-<dist_name>`
+  # artifact per matrix entry, consumed by publish-testpypi (canary) and
+  # publish-pypi (real release, inline after autotag). Skipped on
+  # pull_request -- the PR path has its own build inside `publish-pr-testpypi`
+  # because it needs to rewrite the version before building.
+  #
+  # The matrix exists so we can publish the same code under two PyPI
+  # distribution names: `agex-cli` (canonical) and `agent-devex` (alias).
+  # Each leg rewrites `[project].name` in pyproject.toml before building so
+  # each wheel is uploaded under its own Trusted Publishing project.
+  # --------------------------------------------------------------------------
+  build:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        dist_name: [agex-cli, agent-devex]
+    permissions:
+      contents: read   # actions/checkout
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.11"
+
+      - run: uv venv
+      - run: uv pip install build
+
+      # Rewrite `[project].name` to the matrix dist name. For `agex-cli`
+      # (the canonical dist) the regex still has to match so we re-emit
+      # the line; for `agent-devex` it produces an alias dist with
+      # identical contents. The post-rewrite re-parse is a fail-closed
+      # check: if a future formatting change breaks the regex match (or
+      # `[project].name` ends up wrong for any reason), the job aborts
+      # before uploading mis-named artifacts.
+      - name: Set dist name
+        env:
+          DIST_NAME: ${{ matrix.dist_name }}
+        run: |
+          set -e
+          uv run python -c "
+          import os, re, tomllib
+          dist = os.environ['DIST_NAME']
+          assert re.fullmatch(r'[a-z][a-z0-9-]*', dist), dist
+          data = open('pyproject.toml').read()
+          parsed = tomllib.loads(data)['project']
+          out, n = re.subn(r'(?m)^name = .+', f'name = \"{dist}\"', data, count=1)
+          assert n == 1, f'expected one [project].name match, got {n}'
+          rewritten = tomllib.loads(out)['project']['name']
+          assert rewritten == dist, f'rewrite produced name={rewritten!r}, expected {dist!r}'
+          open('pyproject.toml', 'w').write(out)
+          print(f'Building dist {dist} version {parsed[\"version\"]}')
+          "
+
+      # Build sdist + wheel via PEP 517. `build` is the canonical frontend;
+      # we avoid pulling in full dev extras here since the build backend
+      # (hatchling) reads everything it needs from pyproject.toml.
+      - run: uv run python -m build
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: dist-${{ matrix.dist_name }}
+          path: dist/
+
+  # --------------------------------------------------------------------------
+  # Per-PR dev-version publish to TestPyPI. Rewrites pyproject.toml to a
+  # `.devN` version before building so each PR gets its own unique TestPyPI
+  # release, then posts (or updates) a sticky PR comment with the install
+  # command for reviewers.
+  # --------------------------------------------------------------------------
+  publish-pr-testpypi:
+    # Fork-PR guard: GitHub masks secrets + denies OIDC to workflow runs
+    # from forks, so the deploy would fail anyway -- and more importantly,
+    # letting an untrusted fork run a privileged publish step is a real
+    # supply-chain hazard (exfiltrating TestPyPI credentials, pushing a
+    # malicious preview under the agex-cli name, etc.). Skip cleanly for
+    # forks; internal PRs take the fast path.
+    #
+    # Matrixed across both distribution names so each PR gets a per-package
+    # TestPyPI preview (and a per-package sticky install-command comment).
+    if: >-
+      github.event_name == 'pull_request'
+      && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        dist_name: [agex-cli, agent-devex]
+    environment: testpypi
+    permissions:
+      id-token: write        # OIDC -- Trusted Publishing
+      contents: read         # actions/checkout
+      pull-requests: write   # sticky comment with the install command
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.11"
+      - run: uv venv
+      - run: uv pip install build
+
+      # Rewrite `[project].name` to the matrix dist name. Same fail-closed
+      # check as the build job: re-parse the result and confirm
+      # `[project].name` matches DIST_NAME before continuing.
+      - name: Set dist name
+        env:
+          DIST_NAME: ${{ matrix.dist_name }}
+        run: |
+          set -e
+          uv run python -c "
+          import os, re, tomllib
+          dist = os.environ['DIST_NAME']
+          assert re.fullmatch(r'[a-z][a-z0-9-]*', dist), dist
+          data = open('pyproject.toml').read()
+          out, n = re.subn(r'(?m)^name = .+', f'name = \"{dist}\"', data, count=1)
+          assert n == 1, f'expected one [project].name match, got {n}'
+          rewritten = tomllib.loads(out)['project']['name']
+          assert rewritten == dist, f'rewrite produced name={rewritten!r}, expected {dist!r}'
+          open('pyproject.toml', 'w').write(out)
+          print(f'Dist name set to {dist}')
+          "
+
+      # Rewrite `[project].version` from `X.Y.Z` to `X.Y.Z.devN` where
+      # N = github.run_number (monotonic across the workflow's lifetime).
+      # run_attempt is intentionally NOT encoded: PEP 440's dev segment is
+      # a single integer with no internal dots allowed, so concatenating
+      # would be ambiguous (`dev71` could mean run_number=7 + attempt=1 OR
+      # run_number=71). `skip-existing: true` on the TestPyPI upload below
+      # handles rerun idempotency instead. Parsing via tomllib + re-emitting
+      # only the `[project]` table's `version` key is more robust than
+      # `sed` -- if a future `[tool.*]` section ever introduces its own
+      # `version` key the regex approach would silently rewrite the wrong
+      # one.
+      - name: Set dev version
+        id: devver
+        run: |
+          set -e
+          DEV_VERSION=$(uv run python -c "
+          import re, tomllib
+          data = open('pyproject.toml').read()
+          base = tomllib.loads(data)['project']['version']
+          dev = f'{base}.dev${{ github.run_number }}'
+          # Fail-closed: bound the final version to PEP 440's safe shape
+          # before substituting into pyproject.toml (defense in depth against
+          # a hostile value sneaking into the [project].version field).
+          assert re.fullmatch(r'[0-9]+(\.[0-9]+)*(\.dev[0-9]+)?', dev), dev
+          out = re.sub(r'(?m)^version = .+', f'version = \"{dev}\"', data, count=1)
+          open('pyproject.toml', 'w').write(out)
+          print(dev)
+          ")
+          echo "dev_version=${DEV_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Publishing ${{ matrix.dist_name }} ${DEV_VERSION} to TestPyPI"
+
+      - run: uv run python -m build
+
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          # Belt-and-braces -- the dev-version scheme above already produces
+          # a unique version per run_id+run_attempt, so collisions shouldn't
+          # happen. If they ever do (e.g. a retry after a partial upload),
+          # skip-existing makes the workflow idempotent instead of failing.
+          skip-existing: true
+
+      # Sticky PR comment with the install command. Uses an
+      # `<!-- agex-pypi-preview-<dist_name> -->` marker (one sticky per
+      # matrix leg) to edit the existing comment on reruns. The
+      # per-dist marker means the two matrix legs don't race on a shared
+      # comment -- each leg is self-contained. `--paginate --slurp`
+      # ensures the marker is found even on PRs with >30 comments
+      # (default gh api page size); otherwise the workflow would post a
+      # duplicate comment on late-stage PRs.
+      - name: Post (or update) install-command comment
+        if: success()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          DEV_VERSION: ${{ steps.devver.outputs.dev_version }}
+          DIST_NAME: ${{ matrix.dist_name }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -e
+          MARKER="<!-- agex-pypi-preview-${DIST_NAME} -->"
+          INSTALL="pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ ${DIST_NAME}==${DEV_VERSION}"
+          BODY="$MARKER"$'\n'"📦 **TestPyPI preview:** \`${DIST_NAME}==${DEV_VERSION}\`"$'\n\n'"Install this PR's wheel to try it locally:"$'\n\n'"\`\`\`bash"$'\n'"$INSTALL"$'\n'"\`\`\`"
+          # `gh api --paginate` streams one JSON array per page; `jq -s`
+          # ("slurp") collects them into `[[page1], [page2], ...]`, `add`
+          # flattens to a single array of all comments, then the filter
+          # picks our marker. `gh api --slurp --jq` itself is mutually
+          # exclusive (see https://github.com/cli/cli/issues/8615), so
+          # the slurp has to happen inside jq.
+          EXISTING=$(gh api --paginate "repos/$REPO/issues/$PR_NUMBER/comments" \
+            | jq -rs "add | [.[] | select(.body | contains(\"$MARKER\")) | .id] | first // empty")
+          if [ -n "$EXISTING" ]; then
+            gh api --method PATCH "repos/$REPO/issues/comments/$EXISTING" \
+              -f body="$BODY" > /dev/null
+            echo "Updated existing preview comment #$EXISTING"
+          else
+            gh pr comment "$PR_NUMBER" --body "$BODY"
+            echo "Created new preview comment"
+          fi
+
+  publish-testpypi:
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        dist_name: [agex-cli, agent-devex]
+    environment: testpypi
+    permissions:
+      id-token: write   # OIDC; no API token needed
+      contents: read    # actions/download-artifact needs this
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: dist-${{ matrix.dist_name }}
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          # See header comment -- idempotent on repeat pushes of the same version.
+          skip-existing: true
+
+  # --------------------------------------------------------------------------
+  # Ensures an annotated `v<version>` tag exists on origin so the PyPI
+  # release and the GitHub Release have a matching git anchor. Runs AFTER
+  # the TestPyPI canary so we don't tag a version that failed to build.
+  #
+  # Output semantics: `tag_present = true` when the tag exists on origin
+  # AFTER this job finishes, regardless of whether we had to create it or
+  # it was already there. Downstream jobs gate on that, not on "did this
+  # specific run push the tag", so reruns after a transient PyPI or
+  # Release failure can complete the publish instead of getting stuck in
+  # a "tag exists but release didn't complete" dead-end. Idempotency for
+  # the actual publish/release steps is handled in those jobs (skip-existing
+  # on PyPI, `gh release view` probe before `gh release create`).
+  #
+  # Tag existence is checked against origin via `git ls-remote`, not the
+  # local ref store -- actions/checkout's default tag-fetching behavior
+  # varies with fetch-depth / options, and a false negative here would
+  # cause `git push origin v$VERSION` to fail on an already-pushed tag.
+  #
+  # GITHUB_TOKEN-pushed tags do not retrigger workflows (documented GitHub
+  # loop-prevention). That's fine -- publish-pypi runs inline in the same
+  # workflow run, keyed off `tag_present`.
+  # --------------------------------------------------------------------------
+  autotag:
+    needs: publish-testpypi
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # git push tag
+    outputs:
+      version:     ${{ steps.version.outputs.version }}
+      tag_present: ${{ steps.tag.outputs.tag_present }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.11"
+      - name: Read version from pyproject.toml
+        id: version
+        run: |
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Detected version: $VERSION"
+      - name: Ensure tag exists on origin
+        id: tag
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          set -e
+          if git ls-remote --exit-code --tags origin "refs/tags/v$VERSION" >/dev/null 2>&1; then
+            echo "Tag v$VERSION already present on origin — downstream jobs will run idempotently."
+          else
+            git config user.name  "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git tag -a "v$VERSION" -m "Release v$VERSION"
+            git push origin "v$VERSION"
+            echo "Created and pushed tag v$VERSION"
+          fi
+          echo "tag_present=true" >> "$GITHUB_OUTPUT"
+
+  # --------------------------------------------------------------------------
+  # Real PyPI publish. Runs inline on main after `autotag` -- the dist
+  # artifact produced by `build` is the same wheel we already canaried on
+  # TestPyPI, so there's no rebuild.
+  #
+  # `skip-existing: true` is set so reruns after a transient failure (or
+  # after a partial-success run where the tag got pushed but a later step
+  # failed) converge cleanly instead of failing on "file already exists".
+  # Combined with the `autotag` gate, the normal case is a real upload;
+  # the abnormal case is a clear no-op log line.
+  # --------------------------------------------------------------------------
+  publish-pypi:
+    needs: [build, autotag]
+    if: >-
+      github.event_name == 'push'
+      && github.ref == 'refs/heads/main'
+      && needs.autotag.outputs.tag_present == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        dist_name: [agex-cli, agent-devex]
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC; no API token needed
+      contents: read    # actions/download-artifact needs this
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: dist-${{ matrix.dist_name }}
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # release/v1
+        with:
+          skip-existing: true
+
+  # --------------------------------------------------------------------------
+  # Creates a GitHub Release at the tag `autotag` ensured exists, with
+  # body pulled from the matching `## [X.Y.Z]` section of CHANGELOG.md.
+  # If the section is empty (or missing), falls back to a stub rather than
+  # failing the workflow -- the release anchor is more important than
+  # perfect notes.
+  #
+  # Idempotent: if a Release for this tag already exists (e.g. a rerun
+  # after a partial failure), `gh release view` succeeds and we skip
+  # creation. Otherwise we create it. No "release already exists" error
+  # blocks reruns.
+  # --------------------------------------------------------------------------
+  github-release:
+    needs: [autotag, publish-pypi]
+    if: needs.autotag.outputs.tag_present == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # gh release create
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          ref: v${{ needs.autotag.outputs.version }}
+          fetch-depth: 1
+      - name: Extract CHANGELOG section
+        env:
+          VERSION: ${{ needs.autotag.outputs.version }}
+        run: |
+          set -e
+          # Pull the section from `## [X.Y.Z]` up to (but not including)
+          # the next `## [` header. The em-dash variant in existing entries
+          # (`— 2026-04-19`) means we match on the bracketed version only,
+          # not the full header line.
+          awk -v ver="$VERSION" '
+            /^## \[/ {
+              if (capturing) exit
+              if ($0 ~ "^## \\[" ver "\\]") { capturing=1; next }
+            }
+            capturing { print }
+          ' CHANGELOG.md > release-notes.md
+          # Strip leading/trailing blank lines for tidy rendering. `\s` is
+          # not portable in sed (GNU/BSD differ); use the POSIX class.
+          sed -i -e '/./,$!d' -e :a -e '/^[[:space:]]*$/{$d;N;ba' -e '}' release-notes.md || true
+          if [ ! -s release-notes.md ]; then
+            echo "See CHANGELOG.md for details." > release-notes.md
+          fi
+          echo "--- release-notes.md ---"
+          cat release-notes.md
+          echo "------------------------"
+      - name: Create GitHub Release (or skip if it already exists)
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.autotag.outputs.version }}
+        run: |
+          set -e
+          if gh release view "v$VERSION" >/dev/null 2>&1; then
+            echo "Release v$VERSION already exists — skipping creation."
+          else
+            gh release create "v$VERSION" \
+              --title "v$VERSION" \
+              --notes-file release-notes.md
+          fi