chore: auto-bump plugin versions and update marketplace

Author: nsheaps

.claude-plugin/marketplace.json

@@ -454,7 +454,7 @@
     {
       "name": "scm-utils",
       "description": "Source control management utilities for improving interactions with branches and PRs, both locally and in CI environments",
-      "version": "0.1.14",
+      "version": "0.2.0",
       "author": {
         "name": "Nathan Heaps"
       },

docs/review-system-analysis.md

@@ -16,18 +16,18 @@ The ai-mktpl review system is a multi-layered automated PR review pipeline built
 
 ### Components
 
-| Component | Location | Purpose |
-|-----------|----------|---------|
-| **CI Workflow** | `.github/workflows/claude-code-review.yaml` | GitHub Actions workflow triggered on PR events |
-| **Review Prompt** | `.github/prompts/claude-code-review.md` | Detailed prompt template for CI review bot |
-| **Shared Self-Review Skill** | `shared/skills/self-review/SKILL.md` | Multi-agent review procedure (scoring, dimensions, format) |
-| **Shared Parallel-Review Skill** | `shared/skills/parallel-review/SKILL.md` | Agent Teams fan-out review orchestration |
-| **Plugin Code-Review Skill** | `plugins/scm-utils/skills/code-review/SKILL.md` | Entry point: triggers CI or falls back to self-review |
-| **Plugin Template** | `plugins/scm-utils/skills/code-review/references/prompt-template.md` | Prompt template for other repos |
-| **Workflow Template** | `plugins/scm-utils/skills/code-review/references/workflow-template.yaml` | Workflow template for other repos |
-| **Interpolation Action** | `.github/actions/interpolate-prompt/action.yml` | `envsubst`-based template interpolation |
-| **Agent Trigger** | `.github/workflows/claude-agent-trigger.yaml` | Detects @claude mentions, dispatches to agent |
-| **Agent Workflow** | `.github/workflows/claude-agent.yaml` | Handles repository_dispatch from @claude mentions |
+| Component                        | Location                                                                 | Purpose                                                    |
+| -------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| **CI Workflow**                  | `.github/workflows/claude-code-review.yaml`                              | GitHub Actions workflow triggered on PR events             |
+| **Review Prompt**                | `.github/prompts/claude-code-review.md`                                  | Detailed prompt template for CI review bot                 |
+| **Shared Self-Review Skill**     | `shared/skills/self-review/SKILL.md`                                     | Multi-agent review procedure (scoring, dimensions, format) |
+| **Shared Parallel-Review Skill** | `shared/skills/parallel-review/SKILL.md`                                 | Agent Teams fan-out review orchestration                   |
+| **Plugin Code-Review Skill**     | `plugins/scm-utils/skills/code-review/SKILL.md`                          | Entry point: triggers CI or falls back to self-review      |
+| **Plugin Template**              | `plugins/scm-utils/skills/code-review/references/prompt-template.md`     | Prompt template for other repos                            |
+| **Workflow Template**            | `plugins/scm-utils/skills/code-review/references/workflow-template.yaml` | Workflow template for other repos                          |
+| **Interpolation Action**         | `.github/actions/interpolate-prompt/action.yml`                          | `envsubst`-based template interpolation                    |
+| **Agent Trigger**                | `.github/workflows/claude-agent-trigger.yaml`                            | Detects @claude mentions, dispatches to agent              |
+| **Agent Workflow**               | `.github/workflows/claude-agent.yaml`                                    | Handles repository_dispatch from @claude mentions          |
 
 ### Flow: CI-Triggered Review
 
@@ -98,81 +98,100 @@ User invokes /parallel-review (requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)
 ## 2. Strengths
 
 ### 2.1 Structured Review Process
+
 The 11-step review process in the CI prompt is well-thought-out. It enforces:
+
 - Local doc tracking (compensates for context window volatility)
 - Previous review management (minimize, resolve, update)
 - Post-review verification
 - Clear verdict criteria
 
 ### 2.2 GitHub Integration Depth
+
 The system leverages GitHub's full review API surface:
+
 - Pending reviews with inline comments (not just PR comments)
 - GraphQL for minimizing comments and resolving threads
 - `gh-pr-review` extension for better review comment access
 - Proper bot identity management (`bot_id`, `bot_name`, `allowed_bots`)
 
 ### 2.3 Concurrency Safety
+
 The workflow uses `cancel-in-progress: false` with PR-scoped concurrency groups, preventing review waste while avoiding stale reviews from racing.
 
 ### 2.4 Flexible Trigger System
+
 Supports multiple trigger patterns:
+
 - Automatic on non-draft PR open/sync
 - Manual via `request-review` label (auto-removed)
 - Persistent via `always-review` label for drafts
 
 ### 2.5 Security Consciousness
+
 - Git push denied in CI context
 - CI status checks denied (prevents self-referential loop)
 - GitHub App auth (not PAT) for proper identity
 - Separate secrets for review vs general CI
 
 ### 2.6 Distributable via Plugin
+
 The scm-utils plugin packages the review system for reuse across repos with templates, setup guide, and clear secret requirements.
 
 ---
 
 ## 3. Weaknesses
 
 ### 3.1 Review Logic Split (Improved in v2)
+
 Previously, review instructions existed in three divergent places. In v2, the architecture was restructured:
 
-| Location | Purpose | Status |
-|----------|---------|--------|
-| `.github/prompts/claude-code-review.md` | Active CI prompt (comprehensive) | Updated with fixes |
-| `plugins/scm-utils/.../prompt-template.md` | Template for other repos | Updated with fixes |
-| `shared/skills/self-review/SKILL.md` | Shared review procedure | **NEW** — extracted from project skill |
-| `shared/skills/parallel-review/SKILL.md` | Agent Teams fan-out | **NEW** |
-| `.claude/skills/code-review/SKILL.md` | (Removed) | **REMOVED** — replaced by shared skills |
+| Location                                   | Purpose                          | Status                                  |
+| ------------------------------------------ | -------------------------------- | --------------------------------------- |
+| `.github/prompts/claude-code-review.md`    | Active CI prompt (comprehensive) | Updated with fixes                      |
+| `plugins/scm-utils/.../prompt-template.md` | Template for other repos         | Updated with fixes                      |
+| `shared/skills/self-review/SKILL.md`       | Shared review procedure          | **NEW** — extracted from project skill  |
+| `shared/skills/parallel-review/SKILL.md`   | Agent Teams fan-out              | **NEW**                                 |
+| `.claude/skills/code-review/SKILL.md`      | (Removed)                        | **REMOVED** — replaced by shared skills |
 
 The CI prompt and plugin template still need to be kept in sync manually. A future improvement could generate both from a single source.
 
 ### 3.2 Single-Agent CI Review Bottleneck
+
 The CI workflow runs a single Claude session. For large PRs, this means:
+
 - Long review times (often 10-20+ minutes)
 - Risk of context window exhaustion on complex changes
 - No parallelism for independent review concerns (security vs. quality vs. patterns)
 
 The project-level SKILL.md already describes a multi-agent approach, but this architecture hasn't been brought to the CI workflow.
 
 ### 3.3 No Structured Output Validation
+
 The review output format (badges, details/summary, footnotes) relies entirely on prompt instructions. There's no post-processing to validate that the output is well-formed markdown before posting. This has led to issues like CDATA wrappers appearing in posted reviews.
 
 ### 3.4 COMMENT Verdict Overuse
+
 The original guidance made it too easy to use `COMMENT` (non-blocking) when `REQUEST_CHANGES` would be more appropriate. The threshold was "won't break if merged" rather than "would the code be better if this were addressed." This resulted in reviews that identified real improvements but didn't enforce them.
 
 ### 3.5 Template Synchronization Problem
+
 The `interpolate-prompt` action uses `envsubst`, which means the prompt template is a flat markdown file with `${VAR}` placeholders. There's no mechanism to:
+
 - Share common sections between the CI prompt and scm-utils template
 - Version the prompt independently from the workflow
 - Test prompt changes before deploying
 
 ### 3.6 Missing Review State Persistence
+
 The CI review runs in a fresh environment every time. While the prompt instructs the agent to review previous reviews, there's no persistent memory of past review decisions. Each review re-evaluates from scratch, which can lead to:
+
 - Score inconsistency across reviews
 - Re-raising issues that were already discussed and resolved
 - Missing context from conversations that happened between reviews
 
 ### 3.7 No Inline Comment Deduplication
+
 The prompt says "future reviews don't need to re-post in-line comments" but there's no mechanism to enforce this. The agent must discover its previous inline comments via API calls during the review, adding complexity and unreliability.
 
 ---
@@ -181,13 +200,13 @@ The prompt says "future reviews don't need to re-post in-line comments" but ther
 
 ### scm-utils (Plugin) vs. ai-mktpl (Project)
 
-| Aspect | scm-utils Plugin | ai-mktpl Project |
-|--------|-----------------|------------------|
-| **Purpose** | Distributable review setup for any repo | This repo's specific review instance |
-| **Skill** | `code-review` — triggers CI or falls back to local review | `code-review` — multi-agent local review |
-| **Prompt** | Template for new repos | Active CI prompt |
-| **Workflow** | Template for new repos | Active CI workflow |
-| **Audience** | Plugin consumers (other repos) | ai-mktpl itself |
+| Aspect       | scm-utils Plugin                                          | ai-mktpl Project                         |
+| ------------ | --------------------------------------------------------- | ---------------------------------------- |
+| **Purpose**  | Distributable review setup for any repo                   | This repo's specific review instance     |
+| **Skill**    | `code-review` — triggers CI or falls back to local review | `code-review` — multi-agent local review |
+| **Prompt**   | Template for new repos                                    | Active CI prompt                         |
+| **Workflow** | Template for new repos                                    | Active CI workflow                       |
+| **Audience** | Plugin consumers (other repos)                            | ai-mktpl itself                          |
 
 The scm-utils plugin is the **distribution mechanism**. It contains templates and a skill that knows how to trigger the CI bot (via label) or fall back to local review. The ai-mktpl project has its own instantiated copies that have evolved beyond the templates.
 
@@ -203,32 +222,42 @@ The scm-utils plugin is the **distribution mechanism**. It contains templates an
 ## 5. Suggested Improvements
 
 ### 5.1 Unify Prompt Templates (High Priority)
+
 Extract the shared review logic into a single source of truth. The scm-utils template should be the canonical version, with the ai-mktpl prompt generated from it (or symlinked).
 
 ### 5.2 Multi-Agent CI Review (High Priority)
+
 Bring the parallel agent architecture from the project SKILL.md into the CI workflow. Use Claude Code's Agent Teams or sub-agent fan-out to parallelize review by category. See the migration guide for details.
 
 ### 5.3 Output Validation Gate
+
 Add a post-processing step (or hook) that validates the review markdown before posting:
+
 - Strip any CDATA wrappers
 - Verify `<details>/<summary>` structure
 - Validate shields.io badge URLs return 200
 - Check footnote references are complete
 
 ### 5.4 Review State Persistence
+
 Store review decisions in a structured format (e.g., `.claude/pr-reviews/<pr>/<timestamp>/decision.json`) that subsequent reviews can reference. This enables:
+
 - Consistent scoring across iterations
 - Awareness of which issues were previously raised and addressed
 - Faster subsequent reviews (skip validated categories)
 
 ### 5.5 Prompt Versioning
+
 Version the review prompt independently from the workflow. Tag prompt versions and include the version in the review footnotes so authors know which review criteria were applied.
 
 ### 5.6 Strengthen Non-Blocking Criteria
+
 The non-blocking feedback fix applied in this changeset raises the bar for `COMMENT` verdicts. Monitor subsequent reviews to confirm the model respects the new criteria and adjusts to REQUEST_CHANGES for actionable improvements.
 
 ### 5.7 Review Metrics Dashboard
+
 Instrument reviews to track:
+
 - Review duration
 - Verdict distribution (APPROVE/COMMENT/REQUEST_CHANGES)
 - Score distributions by category

docs/review-system-v2-migration-guide.md

@@ -25,6 +25,7 @@ v2 of the review system introduces:
 **What changed:** The project-level `.claude/skills/code-review/SKILL.md` has been removed. Its content has been refactored into the shared `self-review` skill.
 
 **Action required:**
+
 ```bash
 # If you have a project-level code-review skill, remove it
 rm -rf .claude/skills/code-review/
@@ -35,10 +36,12 @@ rm -rf .claude/skills/code-review/
 ### Step 2: Update scm-utils Plugin
 
 **What changed:** scm-utils v0.2.0 adds two new shared skills:
+
 - `self-review` — the multi-agent review procedure (was the project-level `code-review` skill)
 - `parallel-review` — Agent Teams-based fan-out review
 
 **Action required:**
+
 - Update scm-utils to v0.2.0 or later
 - The `code-review` skill continues to work as before (triggers CI review or falls back to local review)
 - The new `self-review` skill is used as the fallback when CI is unavailable
@@ -66,6 +69,7 @@ CRITICAL: NEVER wrap any part of your review output in `<![CDATA[...]]>` tags.
 ...
 
 Your footnotes MUST NOT include:
+
 - Links to your previous reviews
 - Links to individual comments you made in the review
 ```
@@ -74,6 +78,7 @@ And the verdict section:
 
 ```markdown
 Use **"COMMENT"** only when ALL of these are true:
+
 - The code won't break if merged as-is
 - The suggestions are genuinely optional improvements
 - There is a clear, specific reason why each suggestion should NOT be addressed in this PR
@@ -84,15 +89,19 @@ Use **"COMMENT"** only when ALL of these are true:
 **What changed:** Non-blocking follow-up items now MUST include a reason.
 
 **Before (v1):**
+
 ```markdown
 **Recommended follow-ups** (non-blocking):
+
 - Consider adding unit tests for the new helper function
 - The error message could be more descriptive
 ```
 
 **After (v2):**
+
 ```markdown
 **Recommended follow-ups** (non-blocking — each item MUST explain why it shouldn't be addressed in this PR):
+
 - Consider adding unit tests — out of scope for this bugfix PR, tracked in #456
 - The error message could be more descriptive — requires UX discussion on error messaging standards
 ```
@@ -104,6 +113,7 @@ Use **"COMMENT"** only when ALL of these are true:
 **To enable:**
 
 1. Enable Agent Teams:
+
    ```json
    // .claude/settings.json or ~/.claude/settings.json
    {
@@ -114,6 +124,7 @@ Use **"COMMENT"** only when ALL of these are true:
    ```
 
 2. Use tmux mode for visual monitoring:
+
    ```bash
    claude --teammate-mode tmux
    ```
@@ -141,6 +152,7 @@ plugins/scm-utils/.../prompt-template.md      ← Plugin (prompt template)
 ```
 
 Problems:
+
 - Review logic duplicated between project and plugin
 - Project skill not shareable
 - Prompt templates diverge over time
@@ -158,6 +170,7 @@ plugins/scm-utils/.../prompt-template.md      ← Plugin (prompt template, updat
 ```
 
 Benefits:
+
 - Single source of truth for review logic (shared skills)
 - Plugin distributes via symlinks (no duplication)
 - CI prompt and template kept in sync
@@ -167,11 +180,11 @@ Benefits:
 
 ## Skill Responsibility Matrix
 
-| Skill | Purpose | Where It Lives | Used By |
-|-------|---------|----------------|---------|
-| `self-review` | Multi-agent review procedure (scoring, dimensions, output format) | `shared/skills/self-review/` | CI workflow, local fallback, any plugin |
-| `parallel-review` | Agent Teams fan-out orchestration | `shared/skills/parallel-review/` | Interactive use with agent teams enabled |
-| `code-review` | Trigger CI review or fall back to local review | `plugins/scm-utils/skills/code-review/` | User-facing entry point |
+| Skill             | Purpose                                                           | Where It Lives                          | Used By                                  |
+| ----------------- | ----------------------------------------------------------------- | --------------------------------------- | ---------------------------------------- |
+| `self-review`     | Multi-agent review procedure (scoring, dimensions, output format) | `shared/skills/self-review/`            | CI workflow, local fallback, any plugin  |
+| `parallel-review` | Agent Teams fan-out orchestration                                 | `shared/skills/parallel-review/`        | Interactive use with agent teams enabled |
+| `code-review`     | Trigger CI review or fall back to local review                    | `plugins/scm-utils/skills/code-review/` | User-facing entry point                  |
 
 ### How They Interact
 
@@ -208,7 +221,7 @@ Currently, the CI workflow runs a single Claude session. A future v3 could adopt
 - name: Run Claude Code Review
   uses: anthropics/claude-code-action@v1
   env:
-    CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1'
+    CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"
   with:
     prompt: ${{ steps.prompt.outputs.prompt }}
     settings: |
@@ -221,6 +234,7 @@ Currently, the CI workflow runs a single Claude session. A future v3 could adopt
 This would enable true parallel review in CI, reducing review time for large PRs from 15-20 minutes to 5-8 minutes.
 
 **Blockers for CI agent teams:**
+
 - `claude-code-action` needs to support `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` environment variable
 - In-process teammate mode must work in GitHub Actions runners
 - Token cost needs to be justified by review quality improvement
@@ -229,11 +243,11 @@ This would enable true parallel review in CI, reducing review time for large PRs
 
 ## Breaking Changes
 
-| Change | Impact | Migration |
-|--------|--------|-----------|
-| Project-level `code-review` skill removed | Local `/review` commands may not trigger | Use scm-utils `code-review` or `self-review` skill instead |
-| Non-blocking feedback requires justification | Reviews will have fewer COMMENT verdicts | Update prompt templates per Step 3 |
-| Footnote structure changed | Existing prompt templates won't match new format | Replace prompt template per Step 3 |
+| Change                                       | Impact                                           | Migration                                                  |
+| -------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------- |
+| Project-level `code-review` skill removed    | Local `/review` commands may not trigger         | Use scm-utils `code-review` or `self-review` skill instead |
+| Non-blocking feedback requires justification | Reviews will have fewer COMMENT verdicts         | Update prompt templates per Step 3                         |
+| Footnote structure changed                   | Existing prompt templates won't match new format | Replace prompt template per Step 3                         |
 
 ---