Merge pull request #18 from shakacode/jg/sync-address-review-cmd

Add sync-commands script and shared-command docs for consuming repos

Author: justin808

AGENTS.md

@@ -17,3 +17,11 @@ This repository stores reusable AI workflows and supporting documentation.
 - Treat `prompts/` as the canonical place for workflows meant to be pasted into Codex, GPT, or other tools without Claude slash commands.
 - When the user asks to address PR review comments outside Claude slash commands, follow `prompts/address-review.md`.
 - README is the human discovery surface. Update it whenever you add or rename a reusable asset.
+
+## Canonical Source for Shared Commands
+
+This repo is the single source of truth for shared commands (especially `/address-review`). Other repos copy these commands into their `.claude/commands/` directory.
+
+**For agents working in consuming repos:** If you need to update a shared command like `/address-review`, do NOT edit the local copy. Instead, update the canonical version in this repo and re-sync using `bin/sync-commands`.
+
+**For agents working in this repo:** When updating a shared command, keep it generic — no project-specific logic. Project-specific behavior belongs in the consuming repo's `CLAUDE.md` or `AGENTS.md`.

README.md

@@ -30,7 +30,7 @@ For project-level sharing, copy to your project's `.claude/commands/` or `.claud
 
 | Command | Description |
 |---------|-------------|
-| [`/address-review`](commands/address-review.md) | Fetch GitHub PR review comments and create todos to address them |
+| [`/address-review`](commands/address-review.md) | Fetch GitHub PR review comments, triage them, create todos for must-fix items, reply to comments, and resolve addressed threads |
 | [`/review-all-prs`](commands/review-all-prs.md) | Review all open PRs or a specific PR, post reviews to GitHub |
 | [`/self-review`](commands/self-review.md) | Comprehensive self-review of uncommitted changes before creating a PR |
 | [`/merge-commit-msg`](commands/merge-commit-msg.md) | Generate a structured merge commit message from PR changes |
@@ -79,6 +79,7 @@ Starter templates for new projects:
 
 | Script | Description |
 |--------|-------------|
+| [`bin/sync-commands`](bin/sync-commands) | Sync commands from this repo into a target project's `.claude/commands/` |
 | [`bin/chrome-mcp`](bin/chrome-mcp) | Launch Chrome with a separate profile for MCP browser debugging |
 | `bin/set-review-instructions` | Initialize file-by-file review with instructions and changed file list |
 | `bin/print-git-diff` | Print diff, before/after, and review instructions for a single file |
@@ -95,6 +96,55 @@ Starter templates for new projects:
 | [Claude Code Review](.github/workflows/claude-code-review.yml) | Automatic PR review on open/sync |
 | [Claude Code](.github/workflows/claude.yml) | Respond to `@claude` mentions in issues/PRs |
 
+## Syncing Commands to Your Project
+
+This repo is the canonical source for shared commands like `/address-review`. To keep a project in sync:
+
+### One-Time Setup
+
+```bash
+# From your project root
+BOOSTERS=~/.claude/claude-code-commands-skills-agents
+
+# Clone (or pull if already cloned)
+if [ -d "$BOOSTERS" ]; then
+  git -C "$BOOSTERS" pull --rebase
+else
+  git clone https://github.com/shakacode/claude-code-commands-skills-agents.git "$BOOSTERS"
+fi
+
+# Copy the commands you want into your project
+mkdir -p .claude/commands
+cp "$BOOSTERS/commands/address-review.md" .claude/commands/
+```
+
+### Keeping Up to Date
+
+Run `bin/sync-commands` from this repo to pull the latest commands into a target project:
+
+```bash
+# Sync all commands to a project
+./bin/sync-commands ~/projects/my-app
+
+# Sync a specific command
+./bin/sync-commands ~/projects/my-app address-review
+```
+
+### For AI Agents in Consuming Repos
+
+Add this to your project's `CLAUDE.md` or `AGENTS.md` so agents know where shared commands come from:
+
+```markdown
+## Shared Commands
+
+The `/address-review` command is synced from
+[claude-code-commands-skills-agents](https://github.com/shakacode/claude-code-commands-skills-agents).
+Do not edit `.claude/commands/address-review.md` directly — update the
+canonical copy in the boosters repo and re-sync.
+```
+
+See the [templates/](templates/) directory for starter `CLAUDE.md` and `AGENTS.md` files that include this pattern.
+
 ## Contributing
 
 1. Add new commands to `commands/`

bin/sync-commands

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+#
+# Sync commands from this repo into a target project's .claude/commands/ directory.
+#
+# Usage:
+#   ./bin/sync-commands <target-project-path> [command-name]
+#
+# Examples:
+#   ./bin/sync-commands ~/projects/my-app              # Sync all commands
+#   ./bin/sync-commands ~/projects/my-app address-review  # Sync one command
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+COMMANDS_DIR="$REPO_ROOT/commands"
+
+if [ $# -lt 1 ]; then
+  echo "Usage: $(basename "$0") <target-project-path> [command-name]"
+  echo ""
+  echo "Syncs commands from claude-code-commands-skills-agents into a project."
+  echo ""
+  echo "Examples:"
+  echo "  $(basename "$0") ~/projects/my-app"
+  echo "  $(basename "$0") ~/projects/my-app address-review"
+  exit 1
+fi
+
+TARGET="$1"
+COMMAND="${2:-}"
+
+if [ ! -d "$TARGET" ]; then
+  echo "Error: target directory does not exist: $TARGET"
+  exit 1
+fi
+
+TARGET_DIR="$TARGET/.claude/commands"
+mkdir -p "$TARGET_DIR"
+
+if [ -n "$COMMAND" ]; then
+  COMMAND="${COMMAND%.md}"   # strip accidental .md suffix
+  SOURCE="$COMMANDS_DIR/${COMMAND}.md"
+  if [ ! -f "$SOURCE" ]; then
+    echo "Error: command not found: $SOURCE"
+    echo "Available commands:"
+    ls "$COMMANDS_DIR"/*.md | xargs -I{} basename {} .md | sed 's/^/  /'
+    exit 1
+  fi
+  cp "$SOURCE" "$TARGET_DIR/"
+  echo "Synced $COMMAND -> $TARGET_DIR/${COMMAND}.md"
+else
+  for f in "$COMMANDS_DIR"/*.md; do
+    cp "$f" "$TARGET_DIR/"
+    echo "Synced $(basename "$f" .md) -> $TARGET_DIR/$(basename "$f")"
+  done
+fi
+
+echo ""
+echo "Done. Commands are now in $TARGET_DIR/"

templates/AGENTS.md

@@ -68,6 +68,23 @@ test/
 - Use parameterized queries for database access
 - Never log sensitive data (passwords, tokens, PII)
 
+## Review Workflow
+
+When addressing PR review comments (using `/address-review` or equivalent):
+
+- Wait for the first full review pass to finish before pushing follow-up commits
+- Batch review fixes into one follow-up push when practical -- do not create a new commit for each minor comment
+- Treat as blocking only: correctness bugs, failing tests, regressions, and clear inconsistencies with adjacent code
+- Verify reviewer claims locally before changing code in response to review comments
+- Deduplicate repeated bot comments before acting on them -- fix the underlying issue once, then resolve the duplicates
+
+## Shared Commands
+
+The `/address-review` command and other shared commands are synced from
+[claude-code-commands-skills-agents](https://github.com/shakacode/claude-code-commands-skills-agents).
+Do not edit `.claude/commands/address-review.md` directly in this project.
+Update the canonical copy in the boosters repo and re-sync.
+
 ## Common Mistakes to Avoid
 
 - [Things that AI agents frequently get wrong in this project]

templates/CLAUDE.md

@@ -66,6 +66,16 @@ Always lint changed files before committing.
 - [e.g., "Use factories from test/factories/, not inline data"]
 - [e.g., "When changing source files, run corresponding test files"]
 
+## Shared Commands
+
+The following commands are synced from
+[claude-code-commands-skills-agents](https://github.com/shakacode/claude-code-commands-skills-agents):
+
+- `/address-review` -- Fetch PR review comments, triage, create todos, reply, and resolve threads
+
+Do not edit `.claude/commands/address-review.md` directly. Update the canonical
+copy in the boosters repo and re-sync with `bin/sync-commands`.
+
 ## Common Gotchas
 
 - [Things that trip up new developers or AI assistants]