Merge pull request #17 from Dropelikeit/fix/improve-codex-install-documentation

ci: auto-generate and commit release artifacts before tagging

Author: Dropelikeit

.agents/plugins/marketplace.json

@@ -8,7 +8,7 @@
       "name": "pr-comments-resolver",
       "source": {
         "source": "local",
-        "path": "."
+        "path": "./plugins/codex/pr-comments-resolver"
       },
       "policy": {
         "installation": "AVAILABLE",

.augment-plugin/marketplace.json

@@ -7,7 +7,7 @@
       "name": "pr-comments-resolver",
       "description": "Resolve unresolved PR/MR review comments across GitHub, GitLab, Bitbucket Cloud, and Azure DevOps",
       "version": "1.1.3",
-      "source": ".",
+      "source": "./plugins/augment/pr-comments-resolver",
       "category": "code-review",
       "tags": [
         "pr",

.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   "plugins": [
     {
       "name": "pr-comments-resolver",
-      "source": "./",
+      "source": "./plugins/claude/pr-comments-resolver",
       "description": "Resolve unresolved PR/MR review comments across GitHub, GitLab, Bitbucket Cloud, and Azure DevOps",
       "version": "1.1.3",
       "category": "code-review",

.github/workflows/build-dist-on-pr-merge.yml

@@ -1,49 +1,68 @@
 name: Release
 
+# Single ordered pipeline that runs after a merge to main:
+#   1. determine the next SemVer version (dry-run, no tag pushed yet)
+#   2. sync that version into the plugin manifests
+#   3. regenerate all agent artifacts (skills/, dist/, plugins/) from core/ + adapters/
+#   4. validate + smoke-test the generated artifacts
+#   5. commit the regenerated artifacts back to main (only if something changed)
+#   6. create + push the version tag on that commit
+#
+# The tag therefore always points at the commit that contains the freshly
+# generated artifacts.
+#
+# Loop prevention:
+#   - Commits pushed with the default GITHUB_TOKEN do NOT trigger new workflow
+#     runs (GitHub's built-in recursion guard).
+#   - The artifact commit additionally carries "[skip ci]" as belt-and-suspenders.
+#   - Pushing a tag does not trigger this workflow (it only listens on branch pushes).
+#
+# Permissions / branch protection assumptions:
+#   - github-actions[bot] (via GITHUB_TOKEN with contents: write) must be allowed
+#     to push directly to main. If main is protected with "require pull request",
+#     the bot must be on the bypass list. This is unchanged from the previous
+#     release workflow, which already pushed to main.
+
 on:
   push:
     branches: [main]
 
 jobs:
-  tag:
-    name: SemVer Tag
+  release:
+    name: Build, Commit Artifacts & Tag
     runs-on: ubuntu-latest
     permissions:
       contents: write
-    outputs:
-      new_tag: ${{ steps.tag.outputs.new_tag }}
-      new_version: ${{ steps.tag.outputs.new_version }}
+
     steps:
       - uses: actions/checkout@v6
         with:
+          ref: main
           fetch-depth: 0
 
-      - name: Bump version and push tag
-        id: tag
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      # 1. Resolve the next version WITHOUT creating the tag yet.
+      - name: Determine next version (dry run)
+        id: version
         uses: mathieudutour/github-tag-action@v6.2
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           default_bump: patch
           tag_prefix: v
           release_branches: main
+          dry_run: true
 
-  sync-version:
-    name: Sync Version To Manifests
-    needs: tag
-    if: needs.tag.outputs.new_tag != ''
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: main
-          fetch-depth: 0
-
-      - name: Update manifests
+      # 2. Sync the resolved version into the plugin manifests so the generated
+      #    plugins/ packages embed the correct version. Skipped when there is no
+      #    version bump (e.g. a docs-only commit).
+      - name: Sync version into manifests
+        if: steps.version.outputs.new_version != ''
         env:
-          VERSION: ${{ needs.tag.outputs.new_version }}
+          VERSION: ${{ steps.version.outputs.new_version }}
         run: |
           set -euo pipefail
           tmp="$(mktemp)"
@@ -65,28 +84,60 @@ jobs:
           }
 
           # Claude
-          bump_root         .claude-plugin/plugin.json
+          bump_root          .claude-plugin/plugin.json
           bump_plugins_entry .claude-plugin/marketplace.json
 
           # Augment (root version on both files + plugins[] entry)
-          bump_root         .augment-plugin/plugin.json
-          bump_root         .augment-plugin/marketplace.json
+          bump_root          .augment-plugin/plugin.json
+          bump_root          .augment-plugin/marketplace.json
           bump_plugins_entry .augment-plugin/marketplace.json
 
           # Codex
-          bump_root         .codex-plugin/plugin.json
+          bump_root          .codex-plugin/plugin.json
+
+      # 3. Regenerate all agent artifacts from the sources.
+      - name: Build all agents
+        run: bash scripts/build.sh all
+
+      # 4. Validate + smoke-test the generated artifacts.
+      - name: Validate generated files
+        run: python3 scripts/validate.py
+
+      - name: Smoke test
+        run: bash tests/build_test.sh
 
-      - name: Commit version bump
+      # 5. Commit regenerated artifacts + manifests back to main, only if changed.
+      - name: Commit regenerated artifacts
+        id: commit
         env:
-          TAG: ${{ needs.tag.outputs.new_tag }}
-          VERSION: ${{ needs.tag.outputs.new_version }}
+          TAG: ${{ steps.version.outputs.new_tag }}
         run: |
+          set -euo pipefail
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add .claude-plugin/ .augment-plugin/ .codex-plugin/
+          git add skills/ dist/ plugins/ .claude-plugin/ .augment-plugin/ .codex-plugin/
           if git diff --cached --quiet; then
-            echo "Manifests already at version ${VERSION}; nothing to commit."
+            echo "No generated changes to commit."
+            echo "committed=false" >> "$GITHUB_OUTPUT"
             exit 0
           fi
-          git commit -m "chore: sync manifest version to ${TAG} [skip ci]"
+          msg="chore: rebuild generated artifacts"
+          if [ -n "${TAG:-}" ]; then
+            msg="chore: rebuild generated artifacts and sync version to ${TAG}"
+          fi
+          git commit -m "${msg} [skip ci]"
           git push origin main
+          echo "committed=true" >> "$GITHUB_OUTPUT"
+
+      # 6. Tag the local HEAD of main, which now contains the freshly generated
+      #    artifacts. We tag explicitly with git (rather than re-running the tag
+      #    action) because the action tags GITHUB_SHA — the original triggering
+      #    commit — which would miss the artifact commit pushed in step 5.
+      - name: Create and push release tag
+        if: steps.version.outputs.new_tag != ''
+        env:
+          TAG: ${{ steps.version.outputs.new_tag }}
+        run: |
+          set -euo pipefail
+          git tag -a "$TAG" -m "$TAG"
+          git push origin "$TAG"

.github/workflows/release.yml

@@ -1,9 +1,13 @@
 name: Verify build
 
+# PR sanity check: the sources must build cleanly and pass validation + smoke
+# tests. Generated artifacts (skills/, dist/, plugins/) are produced and
+# committed automatically after merge by release.yml, so contributors are NOT
+# required to build and commit them locally — this workflow therefore does not
+# enforce drift against committed outputs.
+
 on:
   pull_request:
-  push:
-    branches: [main]
 
 jobs:
   verify:
@@ -16,10 +20,6 @@ jobs:
           python-version: "3.11"
       - name: Build all agents
         run: bash scripts/build.sh all
-      - name: Verify no drift in committed outputs
-        run: |
-          git diff --exit-code -- skills/ dist/ \
-            || { echo "Generated files are out of date — run 'bash scripts/build.sh all' and commit."; exit 1; }
       - name: Validate frontmatter and coverage
         run: python3 scripts/validate.py
       - name: Smoke test

.github/workflows/verify-build.yml

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - `persistence-step.md` snippets gain the `Reply/Resolve permission` field (per-adapter naming). Memories without the field trigger the one-time prompt — fully back-compat.
+- Marketplace manifests for Claude, Augment, and Codex now point to generated agent-specific plugin bundles under `plugins/` instead of the repository root, so Git-based marketplace installs resolve an installable plugin directory after clone.
 
 ## [1.0.0] - 2026-05-12
 

CHANGELOG.md

@@ -35,6 +35,7 @@ This repository ships generated outputs for multiple agents. The canonical logic
 .codex-plugin/           Codex plugin manifest
 .agents/plugins/         Codex repo-scoped marketplace manifest
 .augment-plugin/         Augment plugin manifests
+plugins/                 Generated marketplace-ready plugin bundles
 core/                    Canonical workflow and platform modules
 adapters/                Per-agent frontmatter, prelude, and snippets
 skills/resolve-comments/ Claude build output
@@ -79,6 +80,7 @@ bash tests/build_test.sh
 - `.codex-plugin/plugin.json` — Codex plugin identity and skill path
 - `.agents/plugins/marketplace.json` — Codex repo-scoped marketplace listing
 - `.augment-plugin/*.json` — Augment manifests
+- `plugins/<agent>/pr-comments-resolver/` — generated marketplace install bundles
 
 ## Commit Style
 
@@ -101,11 +103,12 @@ Types: `feat`, `fix`, `docs`, `refactor`, `chore`
 
 ## Releasing
 
-Releases and generated artifacts are handled by the GitHub Actions workflows in `.github/workflows/`. `verify-build.yml` enforces no drift in committed outputs, and merged PRs trigger `build-dist-on-pr-merge.yml` to rebuild and commit generated artifacts.
+Releases and generated artifacts are fully automated by the GitHub Actions workflows in `.github/workflows/`. You do **not** need to build or commit generated outputs (`skills/`, `dist/`, `plugins/`) — edit only the sources under `core/` and `adapters/`.
 
-Version metadata is synchronized by `release.yml`.
+- On a pull request, `verify-build.yml` builds the sources and runs validation + smoke tests as a sanity check (it does not enforce drift against committed outputs).
+- After a merge to `main`, `release.yml` runs a single ordered pipeline: it resolves the next version, syncs it into the manifests, rebuilds all artifacts, validates and smoke-tests them, commits the regenerated artifacts back to `main` (only if anything changed), and finally tags that commit. The tag therefore always points at the commit containing the freshly generated artifacts.
 
-If you need a manual local check before opening a PR:
+If you want to sanity-check the build locally before opening a PR:
 
 ```bash
 bash scripts/build.sh all

CONTRIBUTING.md

@@ -38,11 +38,11 @@ For platforms with two paths the skill prompts on first use. The choice is persi
 
 ### Augment
 
-Augment reads the same `.claude-plugin/` manifests as Claude, plus its own `.augment-plugin/`. Install via Augment's plugin/marketplace UI by pointing it at this repository.
+Augment reads the same `.claude-plugin/` manifests as Claude, plus its own `.augment-plugin/`. The repository now ships an agent-specific plugin bundle under `plugins/augment/pr-comments-resolver`, so the marketplace entry points at an installable plugin directory instead of the repo root. Install via Augment's plugin/marketplace UI by pointing it at this repository.
 
 ### Codex
 
-Codex auto-discovers `.codex-plugin/` and the repo-scoped marketplace at `.agents/plugins/marketplace.json`.
+Codex auto-discovers `.codex-plugin/` and the repo-scoped marketplace at `.agents/plugins/marketplace.json`. The marketplace entry points at `plugins/codex/pr-comments-resolver`, which contains a self-contained Codex plugin bundle.
 
 If plugin installation from repo marketplaces is available in your Codex build, use the repository directly:
 

README.md

@@ -0,0 +1,20 @@
+{
+  "name": "pr-comments-resolver",
+  "version": "1.1.2",
+  "description": "Resolve unresolved PR/MR review comments across GitHub, GitLab, Bitbucket Cloud, and Azure DevOps",
+  "author": {
+    "name": "Marcel Strahl @ Dropelikeit",
+    "url": "https://github.com/Dropelikeit"
+  },
+  "keywords": [
+    "pr",
+    "code-review",
+    "github",
+    "gitlab",
+    "bitbucket",
+    "azure-devops",
+    "merge-request",
+    "review"
+  ],
+  "skills": "./skills/"
+}