- GitHub stars
- 15
Install
/plugin install workflow@sjungling-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add sjungling/sjungling-claude-plugins.
Contents
Discovered from sourceCommands 10
Create a GitHub issue using the best available content from the current session.
Parse $ARGUMENTS for an optional file path override.
Step 1: Discover Content
Run the discovery script to find the best content source. The script is located relative to this command file:
SCRIPT_DIR="$(cd "$(dirname "$0")/../scripts" 2>/dev/null && pwd || echo "")"
If $SCRIPT_DIR is empty or the script does not exist, compute the path from the plugin root. The script lives at plugins/workflow/scripts/discover-issue-content.sh relative to the marketplace root. As a fallback, use ${CLAUDE_PLUGIN_ROOT}/scripts/discover-issue-content.sh if that variable is available.
Run the script, passing $ARGUMENTS if non-empty:
DISCOVERY=$(bash "$SCRIPT_DIR/discover-issue-content.sh" $ARGUMENTS 2>&1)
If the script exits non-zero, check stderr for {"error": "..."} and report the error to the user. Common errors:
gh CLI not installed— tell user to install GitHub CLIjq not installed— tell user to install jqnot in a git repository— abortfile not found: <path>— abort with the missing file path
Parse the JSON output:
SOURCE=$(echo "$DISCOVERY" | jq -r '.source')
PRIMARY=$(echo "$DISCOVERY" | jq -r '.primary')
SECONDARY=$(echo "$DISCOVERY" | jq -r '.secondary')
LABEL=$(echo "$DISCOVERY" | jq -r '.label')
REPO=$(echo "$DISCOVERY" | jq -r '.repo')
SPECS=$(echo "$DISCOVERY" | jq -r '.candidates.specs[]' 2>/dev/null)
PLANS=$(echo "$DISCOVERY" | jq -r '.candidates.plans[]' 2>/dev/null)
Step 2: Resolve Content
Based on the SOURCE value:
explicit or claude-plan
PRIMARY already points to the file. Use it directly as $BODY_FILE.
superpowers
If PRIMARY is non-empty, use it as $BODY_FILE.
If PRIMARY is empty, there are multiple candidates that need disambiguation. Use AskUserQuestion to present the candidates from SPECS and/or PLANS and ask which file to use as the issue body. Set $BODY_FILE to the chosen file.
If SECONDARY is non-empty, it will be posted as a comment after issue creation.
summary
No content files were found. Write a markdown summary of the current conversation covering:
- Problem statement — what prompted the session
- Approach discussed — key technical decisions and alternatives considered
- Current status — what was accomplished, what remains
- Open questions — anything unresolved
Write the summary to a temp file:
BODY_FILE=$(mktemp /tmp/gh-issue-body-XXXXXX.md)
Step 3: Validate Content Size
Check the byte count of $BODY_FILE:
wc -c < "$BODY_FILE"
If it exceeds 60000 bytes:
- Read the file and find the last markdown heading (
##or###) boundary before the 60000 byte mark - Truncate at that boundary
- Append:
\n\n---\n_Content truncated due to GitHub size limits. Full document: \`_` - Write the truncated version to a new temp file and use that instead
Apply the same size check to $SECONDARY if it is non-empty.
Step 4: Suggest and Confirm Title
Extract a title suggestion from $BODY_FILE:
- Look for the first
#(H1) heading in the file - If no H1, use the first non-empty, non-frontmatter line
- Strip any markdown formatting from the title
Use AskUserQuestion to present:
- Which content source was detected (
SOURCEvalue) - The file path being used
- The suggested title
- Ask the user to confirm the title or provide a different one
Step 5: Create the Issue
Build the label flag from the discovery output:
- If
LABELis non-empty, use--label "$LABEL" - Otherwise, omit
--label
gh issue create --title "<confirmed-title>" --body-file "$BODY_FILE" --label "$LABEL"
Capture the output — gh prints the issue URL on success.
Step 6: Post Secondary Content
If SECONDARY is non-empty:
- Extract the issue number from the URL:
echo "$ISSUE_URL" | grep -o '[0-9]*$' - Post the secondary content as a comment:
gh issue comment "$ISSUE_NUMBER" --body-file "$SECONDARY"
Step 7: Cleanup and Report
Remove any temp files that were created (do NOT remove the original source files).
Report to the user:
- The issue URL (as a clickable link)
- Which content source was used (
SOURCE) - Which label was applied (if any)
- Whether secondary content was added as a comment
Enrich a GitHub issue with codebase analysis: write narrative prose that traces the problem through the code with inline identifier hyperlinks, and optionally include a Mermaid sequence diagram that is render-validated before posting.
Step 1: Resolve Issue Number
Parse $ARGUMENTS for the issue number. If it is empty, use AskUserQuestion to ask the user for the issue number before proceeding.
ISSUE_NUMBER="$ARGUMENTS"
if [ -z "$ISSUE_NUMBER" ]; then
# Use AskUserQuestion to collect the issue number, then set ISSUE_NUMBER
exit 0
fi
Step 2: Fetch Issue and Permalink Base
Fetch the full issue details:
gh issue view "$ISSUE_NUMBER" --json number,title,body,labels,comments,url
If gh issue view returns a 404, tell the user the issue was not found in the current repository. Suggest they verify the issue number or pass --repo owner/repo to gh issue view manually and retry.
Resolve the permalink base pinned to origin/main HEAD:
REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
SHA=$(git rev-parse origin/main 2>/dev/null || git rev-parse HEAD)
PERMALINK_BASE="https://github.com/$REPO/blob/$SHA"
If git rev-parse origin/main fails (no remote), use HEAD and note the fallback at the end of the triage prose.
Step 3: Dispatch Research Subagent
Dispatch a fresh Agent to search the codebase. Fill in <number>, <title>, <body>, <repo>, <sha>, and <permalink_base> before dispatching.
Agent prompt:
You are analyzing GitHub issue #<number>: "<title>"
Issue body:
<body>
Repository: <repo>
Permalink base (pinned to origin/main HEAD <sha>): <permalink_base>
Map this issue to the codebase. Do NOT prescribe solutions. Do not use language like "should", "fix by", "change X to Y", or "the solution is".
## 1. TRIAGE THE CODEBASE
- Search for relevant symbols, error messages, config keys, or API paths from the issue using Grep, Glob, and Read
- Trace the execution path or data flow from entry point to failure
- Note blast radius: other areas affected even if not the root cause
Write triage prose — 3-6 sentences of narrative that traces the call chain from where the problem enters to where it manifests. Every code identifier you name (class name, method name, field name) must be a markdown hyperlink whose link text IS the identifier itself, not the file path. Build each permalink as:
<permalink_base>/<file>#L<start>-L<end>
Format: [`ClassName.methodName`](permalink) or [`fieldName`](permalink)
Render references as inline code permalinks, not as raw-path link text or a separate table.
Verify every file exists with `test -f <path>` before building its permalink. Skip any file that does not exist.
Example (not real — illustrative only):
The issue originates in [`TokenRefreshFilter.doFilter`](https://github.com/org/repo/blob/SHA/path/Filter.java#L42-L67) where the session is re-issued without copying the expiry timestamp. The new token object is assembled in [`SessionFactory.build`](permalink) and written by [`SessionStore.persist`](permalink), which receives no expiry argument.
## 2. CODE REFS (for verification only — not displayed directly)
Return a separate machine-readable list of the code locations embedded in the prose above. These are used for post-hoc verification only and are NOT rendered in the output.
[
{ "file": "relative/path/from/repo/root.java", "start": 42, "end": 67 }
]
## 3. ASSESS DIAGRAM VALUE
Decide whether a Mermaid sequenceDiagram would materially help a reader understand WHERE the issue occurs:
- Include if: the issue involves interactions across multiple components or services
- Omit if: it is contained within a single function or class
If including, use real component names verified to exist in the code. Show ONLY the actual current flow. Use a `Note` annotation to mark the failure point. Do NOT show a corrected or desired flow.
Critical Mermaid syntax rules — violations will cause the diagram to fail rendering:
- Participant aliases: short identifiers only, NO spaces, parentheses, or special characters
Good: `participant W as WorkerService` Bad: `participant WorkerService (recipe-worker)`
- Message labels (arrows): NO semicolons. Semicolons are statement terminators in Mermaid — use a dash or comma instead
Good: `W->>R: readUpgradesAndMigrations - returns empty` Bad: `W->>R: reads CSV; returns empty`
- Note text: single line, under 80 characters, no colons or semicolons
- Do not use activate/deactivate blocks
## RETURN
{
"triage_prose": "narrative with inline [`Identifier`](permalink) links...",
"code_refs": [{ "file": "...", "start": N, "end": N }],
"diagram": "sequenceDiagram\n ..." or null,
"diagram_rationale": "one sentence"
}
Capture the result as $RESEARCH.
Step 4: Build Enrichment Body
Write the enrichment to a temp file:
ENRICHMENT_FILE=$(mktemp /tmp/gh-enrich-XXXXXX.md)
Write triage_prose as the entire body under a heading:
## Issue Triage
<triage_prose>
If diagram is non-null, append a ### Flow Diagram heading followed by a fenced mermaid block. Use 4-space indentation here to avoid nested-fence ambiguity when writing the command file itself — when writing the actual enrichment file, use literal triple-backtick fences:
### Flow Diagram
```mermaid
<diagram content>
```
Step 5: Render-validate the Mermaid Diagram
If a diagram was included, validate it renders before posting. A diagram that fails to parse is worse than no diagram.
# Extract the mermaid block content from the enrichment file
MMD_FILE=$(mktemp /tmp/gh-diagram-XXXXXX.mmd)
sed -n '/^```mermaid$/,/^```$/{ /^```/d; p }' "$ENRICHMENT_FILE" > "$MMD_FILE"
# Create puppeteer config pointing at system Chrome (default puppeteer Chrome not installed)
PUPPETEER_CFG=$(mktemp /tmp/puppeteer-XXXXXX.json)
cat > "$PUPPETEER_CFG" <<'JSON'
{
"args": ["--no-sandbox"],
"executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}
JSON
# Resolve mmdc
if command -v mmdc &>/dev/null; then
MMDC_CMD="mmdc"
else
MMDC_CMD="npx --yes @mermaid-js/mermaid-cli"
fi
OUT_PNG=$(mktemp /tmp/gh-diagram-XXXXXX.png)
MMDC_OUTPUT=$($MMDC_CMD -i "$MMD_FILE" -o "$OUT_PNG" --puppeteerConfigFile "$PUPPETEER_CFG" 2>&1)
MMDC_EXIT=$?
rm -f "$OUT_PNG" "$PUPPETEER_CFG"
If $MMDC_EXIT is non-zero:
- Show
$MMDC_OUTPUTto the user - Pass the error and the failing diagram back to a fresh
Agentwith this prompt:
This Mermaid sequenceDiagram failed to render. Fix ONLY the syntax — do not change the diagram's meaning.
Error from mmdc:
<MMDC_OUTPUT>
Failing diagram:
<MMD content>
Rules:
- No semicolons anywhere in message labels or Note text — they are statement terminators in Mermaid
- Participant aliases must be short identifiers with no spaces or parentheses
- Note text must be a single line under 80 characters with no colons or semicolons
- Return only the corrected diagram content (no fences, no explanation)
Replace the diagram block in $ENRICHMENT_FILE with the corrected diagram and re-run the mmdc validation. Repeat until the diagram renders cleanly or the agent cannot fix it (in which case, remove the diagram from the enrichment and note the failure to the user).
Clean up $MMD_FILE.
Step 6: Dispatch Review Subagent
Dispatch a fresh Agent to review the enrichment. Fill in <number>, <title>, <body>, and the contents of $ENRICHMENT_FILE.
Agent prompt:
Review this GitHub issue enrichment before it is posted. Use Bash, Grep, Glob, and Read to verify — do not guess.
Issue #<number>: "<title>"
Body: <body>
Enrichment:
<enrichment_body>
Checks:
1. FILE EXISTENCE: For every permalink in the enrichment, extract the file path and run:
test -f <path> && echo "OK" || echo "MISSING: <path>"
Fail any reference pointing to a nonexistent file.
2. LINE RANGE VALIDITY: For each file, confirm referenced lines are within the file:
wc -l < <path>
3. LINK STYLE: Every code identifier link must use the identifier as link text — never a raw file path.
Good: [`ClassName.methodName`](url) Bad: [`path/to/File.java:42-58`](url)
Flag any link where the visible text is a file path rather than an identifier name.
4. NO SOLUTIONS: Flag any language like "should", "fix by", "change X to Y", or "the solution is".
5. TRIAGE SPECIFICITY: Does the prose name real identifiers from the codebase, not generic descriptions?
6. DIAGRAM: The diagram has already been validated by mmdc. Confirm that each participant alias
and component name in the diagram grep-matches to an actual name in the codebase.
Return JSON:
{
"approved": true or false,
"issues": ["specific problems"],
"missed_areas": ["relevant symbols or paths absent from the enrichment"]
}
If approved is false or missed_areas is non-empty:
- Address flagged issues in
$ENRICHMENT_FILE - For missed areas, search and incorporate additional inline references in the prose
- Re-run this step if significant changes were made
Step 7: Choose Update Method
Use AskUserQuestion to ask how to apply the enrichment:
- Post as a comment — preserves the original description, adds context below
- Append to description — adds the enrichment as a new section at the bottom
Step 8: Post Enrichment
If comment:
gh issue comment "$ISSUE_NUMBER" --body-file "$ENRICHMENT_FILE"
If append to description:
Re-fetch the current body to avoid overwriting any edits made during this workflow:
BODY_FILE=$(mktemp /tmp/gh-body-XXXXXX.md)
gh issue view "$ISSUE_NUMBER" --json body -q '.body' > "$BODY_FILE"
printf '\n\n---\n\n' >> "$BODY_FILE"
cat "$ENRICHMENT_FILE" >> "$BODY_FILE"
gh issue edit "$ISSUE_NUMBER" --body-file "$BODY_FILE"
rm -f "$BODY_FILE"
Clean up $ENRICHMENT_FILE and report the issue URL to the user.
Step 9: Optional Title and Description Refinement
Use AskUserQuestion to ask:
Based on the codebase research, would you like me to suggest a more precise title or description for this issue?
If yes:
- Propose a revised title that names the actual component and observed behavior
- Propose an optional one-paragraph clarification that references the triaged identifiers
Ask for explicit confirmation before applying:
gh issue edit "$ISSUE_NUMBER" --title "<revised_title>"
Notes
- Never prescribe solutions — describe what exists, not what should change
- All permalinks use the
origin/mainHEAD SHA, never the branch name - If the issue spans multiple repositories, name all of them in the triage prose and focus research on the current repo
- Clean up all temp files whether the command succeeds or is cancelled
Move an issue to a column on project board 8 (https://github.com/orgs/moderneinc/projects/8).
Project 8 spans several repos (moderne-saas, codegenomeproject, …), so an issue number is not unique on the board — the same number exists in multiple repos. Resolve by repository, never by number alone.
Parse $ARGUMENTS:
- First token = issue number (required).
- A token containing
/(e.g.moderneinc/codegenomeproject) = repository (optional). A bare repo without an owner is assumed undermoderneinc. - Remaining tokens = target column name (optional, default
In Progress). Match case-insensitively against the known columns below.
Known IDs (stable)
These are fixed for moderneinc project 8 — no need to re-resolve them:
PROJECT_ID=PVT_kwDOBBZwVM0q6gFIELD_ID(Status) =PVTSSF_lADOBBZwVM0q6s4AATqk- Status option IDs:
- Icebox =
6f4ce84a - Refine =
e2a82074 - Backlog =
f75ad846 - In Progress =
47fc9ee4 - Ready to Communicate =
98236657 - Done =
04d30f6f
- Icebox =
If the requested column is not in this list, list the valid columns and stop.
Run
Resolve the per-issue item ID scoped to its repository, then set the Status
field. Replace <ISSUE> with the issue number, <OPTION_ID> with the option ID
for the requested column, and <REPO> with owner/repo (empty if the caller
gave none):
ISSUE=<ISSUE>
OPTION_ID=<OPTION_ID>
REPO=<REPO> # e.g. moderneinc/codegenomeproject; empty if not specified
ITEMS=$(gh project item-list 8 --owner moderneinc --format json --limit 10000)
if [ -n "$REPO" ]; then
# .content.repository is "owner/repo" — the reliable disambiguator.
# Here-strings (<<<), not `echo "$ITEMS" | …`: zsh's echo mangles the \n/\t
# escapes inside issue titles and corrupts the JSON.
ITEM_ID=$(jq -r --arg n "$ISSUE" --arg r "$REPO" \
'.items[] | select(.content.number == ($n|tonumber) and .content.repository == $r) | .id' <<<"$ITEMS")
else
MATCHES=$(jq --arg n "$ISSUE" \
'[.items[] | select(.content.number == ($n|tonumber))]' <<<"$ITEMS")
if [ "$(jq 'length' <<<"$MATCHES")" -gt 1 ]; then
echo "Issue #$ISSUE is ambiguous — it exists in multiple repos on project 8:"
jq -r '.[] | " \(.content.repository) — \(.content.title)"' <<<"$MATCHES"
echo "Re-run with the repo, e.g.: /workflow:issue-status $ISSUE <column> moderneinc/<repo>"
exit 1
fi
ITEM_ID=$(jq -r '.[0].id // empty' <<<"$MATCHES")
fi
if [ -z "$ITEM_ID" ]; then
TARGET="${REPO:-moderneinc/<repo>}"
echo "Issue #$ISSUE${REPO:+ in $REPO} is not on project 8. Add it first with:"
echo " gh project item-add 8 --owner moderneinc --url https://github.com/$TARGET/issues/$ISSUE"
exit 1
fi
gh project item-edit \
--id "$ITEM_ID" \
--project-id "PVT_kwDOBBZwVM0q6g" \
--field-id "PVTSSF_lADOBBZwVM0q6s4AATqk" \
--single-select-option-id "$OPTION_ID"
Notes
gh projectcommands require theprojectscope. If you hit an auth error, tell the user to rungh auth refresh -s project.- Numbers collide across repos on project 8: without a repo, an ambiguous number
lists its candidates and stops rather than editing the wrong (or every) item.
Pass
owner/repoto resolve it directly. - If the issue isn't on the board, surface the
gh project item-addcommand (with the resolved repo) rather than failing silently. - Report the final column the issue landed in.
Monitor all open pull requests in the current repository. Designed for recurring use with /loop or as a one-shot check.
This command orchestrates PR monitoring. Expensive review work is delegated to specialized skills and agents that use their own models.
Setup
Determine the repository owner and name:
REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
Fetch all open PRs authored by the current user:
gh pr list --author "@me" --state open --json number,title,headRefName,updatedAt,mergeable
If no open PRs are found, report that to the user and stop.
Step 1: Identify PRs Needing Review
Track review state using a timestamp file at /tmp/monitor-prs-last-run-{repo-slug}.txt. If the file exists, read the ISO 8601 timestamp from it. If it does not exist, treat all PRs as needing review.
Filter to PRs whose updatedAt is newer than the last-run timestamp (or all PRs on the first run). Skip unchanged PRs for review, but still include them in conflict and comment checks (Steps 4-5).
Step 2: Review New or Updated PRs
For each PR that needs review, invoke the /pr-review-toolkit:review-pr skill using the Skill tool:
Skill: "pr-review-toolkit:review-pr"
Args: "{number}"
This delegates the full code review (diff analysis, finding issues, confidence scoring, validation) to the specialized review toolkit, which uses its own model and agent pipeline.
Wait for the review to complete before proceeding. The skill will produce validated review findings.
Step 3: Post Review Comments
If the review from Step 2 produced any findings, use the /workflow:post-pr-comments skill to post them on the PR:
Skill: "workflow:post-pr-comments"
Invoke the skill once per PR that has findings. The skill handles formatting comments, resolving line numbers, and posting via the GitHub API.
If no findings were produced, skip to Step 4.
Step 4: Check for Merge Conflicts
For each open PR, check the mergeable field from the PR list query:
MERGEABLE— no action neededCONFLICTING— resolve the conflictUNKNOWN— re-fetch:gh pr view {number} --json mergeable -q '.mergeable'
For each PR with merge conflicts, dispatch a teammate agent in a worktree to resolve them:
Use the Agent tool with isolation: "worktree" to:
- Check out the PR branch
- Attempt to rebase onto the base branch (usually
main) - Resolve any conflicts
- Push the resolved branch to update the PR
Agent prompt: "Check out branch '{headRefName}', rebase it onto 'main', resolve any merge conflicts, and push the result. The repo is {REPO}. PR #{number}: {title}"
If conflict resolution fails, note it for the summary but do not block the rest of the workflow.
Step 5: Surface New Review Comments
For each open PR, fetch review comments posted since the last monitoring cycle:
gh api repos/{REPO}/pulls/{number}/comments --jq '[.[] | select(.created_at > "{last_run_timestamp}")] | length'
If there are new comments, fetch their details:
gh api repos/{REPO}/pulls/{number}/comments --jq '[.[] | select(.created_at > "{last_run_timestamp}")] | .[] | {user: .user.login, path: .path, line: .line, body: .body}'
Also check for PR review comments (top-level review bodies):
gh api repos/{REPO}/pulls/{number}/reviews --jq '[.[] | select(.submitted_at > "{last_run_timestamp}" and .state != "PENDING")] | .[] | {user: .user.login, state: .state, body: .body}'
Summarize any new comments for the user, grouped by PR.
Finalize
Update the last-run timestamp file:
date -u +"%Y-%m-%dT%H:%M:%SZ" > /tmp/monitor-prs-last-run-{repo-slug}.txt
Report a summary to the user:
- PRs reviewed: count and PR numbers
- Comments posted: count per PR
- Conflicts resolved: which PRs, success/failure
- New reviewer feedback: summary of comments per PR
- No changes: if nothing required attention, say so briefly
Post inline code review comments on the GitHub PR associated with the current branch.
Step 1: Gather Findings
Collect all code review findings, issues, or suggestions from the current conversation. For each finding, determine:
- File path — relative to the repo root
- Line number(s) — the specific line or line range in the current version of the file
- Comment body — a clear, actionable description of the issue in markdown
If there are no review findings in the conversation, tell the user and stop.
Step 2: Resolve Line Numbers
For each finding, verify the line numbers are accurate:
- Read the file to confirm the code at the referenced line matches what was discussed
- If the line has shifted (e.g., due to edits since the review), find the correct current line
- For issues spanning multiple lines, use
start_lineandlineto define the range
Step 3: Write Comments JSON
Write a JSON file containing the comments array:
COMMENTS_FILE=$(mktemp /tmp/pr-review-comments-XXXXXX.json)
Each comment object must have:
path(string) — file path relative to repo rootline(number) — the line number (or end line for ranges)side(string) — always"RIGHT"body(string) — markdown comment body
For multi-line ranges, also include:
start_line(number) — first line of the rangestart_side(string) — always"RIGHT"
Required footer
Append an attribution footer to the end of every comment body, so reviewers know the finding was machine-generated and at what rigor. Format:
\n\n---\n<sub>🤖 Analysis: <MODEL> · <REASONING> reasoning effort<EXTRA></sub>
<MODEL>— the model that produced the analysis, e.g.Claude Opus 4.8.<REASONING>— the reasoning/thinking level used, e.g.high.<EXTRA>— optional· <note>suffix for extra provenance that genuinely applies, e.g.· red-teamed before postingwhen findings were adversarially verified. Omit entirely if nothing extra applies — do not fabricate it.
Example footer: \n\n---\n<sub>🤖 Analysis: Claude Opus 4.8 · high reasoning effort · red-teamed before posting</sub>
Example:
[
{
"path": "src/foo.swift",
"line": 42,
"side": "RIGHT",
"body": "**Raw spacing literal**\n\nUse `CortinaSpacing.lg` instead of `12`.\n\n---\n<sub>🤖 Analysis: Claude Opus 4.8 · high reasoning effort</sub>"
},
{
"path": "src/bar.swift",
"start_line": 10,
"start_side": "RIGHT",
"line": 15,
"side": "RIGHT",
"body": "This block should use the shared helper.\n\n---\n<sub>🤖 Analysis: Claude Opus 4.8 · high reasoning effort</sub>"
}
]
Write the array to $COMMENTS_FILE.
Step 4: Post the Review
Run the posting script. The script is located relative to this command file:
SCRIPT_DIR="$(cd "$(dirname "$0")/../scripts" 2>/dev/null && pwd || echo "")"
If $SCRIPT_DIR is empty or the script does not exist, use ${CLAUDE_PLUGIN_ROOT}/scripts/post-pr-comments.sh as a fallback.
RESULT=$(bash "$SCRIPT_DIR/post-pr-comments.sh" "$COMMENTS_FILE" 2>&1)
Step 5: Cleanup and Report
Remove the comments temp file:
rm -f "$COMMENTS_FILE"
Parse $RESULT as JSON:
- If it contains
review_url: report the URL and comment count to the user - If it contains
error: report the error message to the user
Rebase the current branch against main. Follow this workflow exactly:
Step 1: Detect Environment
Run these commands to determine context:
!git rev-parse --show-toplevel
!git worktree list
!git branch --show-current
!git status --porcelain
From these results, determine:
- Current branch name (from
git branch --show-current) - Is this a worktree? — If
git worktree listshows more than one entry AND the current working directory is NOT the first (main) worktree listed, then we are in a linked worktree - Has uncommitted changes? — If
git status --porcelainproduces output - Main worktree path — The first entry in
git worktree list(the bare/main worktree)
Step 2: Stash if needed
If there are uncommitted changes (staged or unstaged):
- Run
git stash push -m "rebase-main: auto-stash before rebase" - Remember that we stashed so we can pop later
Step 3: Rebase based on context
Case A: In a worktree
Fetch the latest main from origin and rebase against it. Do NOT try to update the local main ref — git refuses to update a branch that is checked out in another worktree.
- Run
git fetch origin main - Run
git rebase origin/main
Case B: Not in a worktree, ON main branch
We're on main itself — rebase against origin:
- Run
git fetch origin main - Run
git rebase origin/main
Case C: Not in a worktree, on a NON-main branch
Rebase against the local main branch:
- Run
git rebase main
Step 4: Handle rebase conflicts
If the rebase fails due to conflicts:
- Report the conflicting files to the user
- Ask the user how they want to proceed: resolve conflicts, or abort with
git rebase --abort - Do NOT automatically resolve conflicts — wait for user guidance
Step 5: Restore stash
If we stashed changes in Step 2:
- Run
git stash pop - If the stash pop has conflicts, report them to the user
Step 6: Report results
Summarize what happened:
- Which rebase case was used (worktree/main/branch)
- Whether changes were stashed and restored
- Current branch status after rebase
Run a review-and-fix cycle on a pull request. The PR must already exist. If a PR number is provided as an argument, use it; otherwise use the PR associated with the current branch.
Step 1: Resolve PR Context
Determine which PR to work on:
# If $ARGUMENTS is set, use it as the PR number; otherwise resolve from current branch
PR_NUMBER="${ARGUMENTS:-}"
if [ -z "$PR_NUMBER" ]; then
PR_NUMBER=$(gh pr view --json number -q '.number' 2>/dev/null || echo "")
fi
If no PR can be resolved, tell the user and stop. Do not try to open a PR — this command is fix-only.
Fetch PR metadata to confirm the target:
gh pr view "$PR_NUMBER" --json number,title,headRefName,baseRefName,state,mergeable
Confirm the PR is open. If it is merged or closed, stop and report.
Check that the current working tree matches the PR's headRefName. If not, tell the user and stop — do not switch branches automatically, since the user may have unsaved work or be in a specific worktree. Tell them the command required branch and let them switch.
Step 2: Dispatch Review Subagent
Use the Agent tool to run a code review in a subagent. This keeps the raw diff output out of the main context and isolates the review findings.
Agent prompt template:
Review PR #<number> in the current repository. The head branch is <headRefName>
and the base is <baseRefName>.
1. Get the diff with: gh pr diff <number>
2. Analyze every changed hunk for:
- Bugs and logic errors
- Missing error handling on system-boundary calls
- Style violations against project conventions (read CLAUDE.md if present)
- Missing tests for new behavior
- Performance regressions on hot paths
- Accessibility issues in view code (if the project has accessibility rules)
3. For each finding, return a JSON object:
{
"path": "relative/path.ext",
"line": 42,
"confidence": 0-100,
"category": "bug|style|test|perf|a11y|other",
"description": "What is wrong",
"suggested_fix": "Concrete change to make (code snippet or instruction)"
}
4. Return a JSON array of findings. If nothing is wrong, return [].
Be strict about confidence scoring. Only score >= 80 for issues you are certain
are real bugs or clear policy violations. Score 60-79 for likely-but-not-certain
issues. Score below 60 for subjective preferences — these will be discarded.
Capture the agent's returned JSON array as $FINDINGS.
Step 3: Filter and Report
Parse $FINDINGS and split into three buckets:
- Auto-fix: confidence >= 80 — will be fixed in Step 4
- Ask user: confidence 60-79 — report to user for a decision, do not auto-fix
- Discard: confidence < 60 — ignore silently
If the auto-fix bucket is empty:
- If the ask-user bucket is also empty, report "No actionable findings" and stop.
- Otherwise, report the ask-user findings and stop — wait for the user to tell you which to address.
Step 4: Apply Fixes
For each auto-fix finding, apply the suggested change using Edit or Write. After each fix:
- Re-read the file to confirm the edit landed correctly
- Keep a running list of
(path, description)pairs for the commit message
Apply one finding at a time so failures are isolated.
Step 5: Build Verification
Before committing, run the project's build. This step is mandatory — do not skip it even if the changes seem trivial.
Find the build command:
- Read
CLAUDE.mdin the project root, if present, for a documented build command - If not documented, check for common build systems in this order:
Package.swift→swift build*.xcodeproj→xcodebuild -scheme $(ls -1 *.xcodeproj | head -1 | sed 's/.xcodeproj$//') -quiet buildpackage.jsonwith abuildscript →npm run buildCargo.toml→cargo buildMakefilewith abuildtarget →make build
- If none match, ask the user for the build command
Run the build. If it fails:
- Show the error output to the user
- Don't fix the build failure automatically — the fix may require reverting a finding
- Stop and wait for user guidance
If the build passes, continue.
Step 6: Confirmation Checkpoint
Before committing and pushing, show the user:
- The PR number and title
- The list of fixes applied (path + description for each)
- The build verification result (passed)
- The pending commit message draft
Ask the user to confirm before proceeding. Do NOT commit or push without explicit confirmation. If the user declines, leave the working tree as-is (fixes applied but uncommitted) so they can adjust.
Step 7: Commit and Push
On confirmation:
git add -A
git commit -m "$(cat <<'EOF'
review: address findings from /review-and-fix
<bulleted list of fixes, one per line>
EOF
)"
git push
Do not use --no-verify. If a pre-commit hook fails, stop and report — do not bypass.
Step 8: Report Summary
Report to the user:
- PR:
#<number> <title> - Fixes applied: count and bullet list
- Ask-user findings: count and bullet list (if any were surfaced in Step 3)
- Build: passed
- Commit: SHA and push status
- Next step: suggest running
/monitor-prsor viewing the PR to confirm CI is green
Launch the review-unstaged agent to review unstaged changes with context isolation.
Pass the following context to the agent:
- Working directory: the current project root
When the agent completes, report its findings to the user.
Spotlight testing: merge worktree changes into the main worktree without committing, so you can test in the main worktree's environment (build artifacts, node_modules, databases, etc.).
Parse $ARGUMENTS for the mode: on (default if empty), off, refresh, or status.
Step 1: Detect Environment
Run these commands:
!git rev-parse --show-toplevel
!git worktree list
!git branch --show-current
!git status --porcelain
Determine:
- Current worktree path and main worktree path (first entry in
git worktree list) - Is this a linked worktree? — current directory is NOT the main worktree
- Current branch name
- Has uncommitted changes?
If NOT in a linked worktree, abort with:
"Spotlight requires a linked worktree. Run this from a Claude Code worktree, not the main repo."
Step 2: Execute Mode
Mode: on (default)
-
Check main worktree state:
- Run
git -C <main-worktree-path> status --porcelain - If dirty, abort: "Main worktree has uncommitted changes. Commit or stash them first."
- Check for active merge: look for MERGE_HEAD in the main worktree's git directory.
For a standard (non-bare) main worktree, check
<main-worktree-path>/.git/MERGE_HEAD. If an active merge exists, abort: "Main worktree already has an active merge. Run/spotlight offfirst."
- Run
-
Checkpoint uncommitted changes (if any):
- If
git status --porcelainshows changes:git add -Agit commit -m "spotlight: checkpoint"- Remember we created a checkpoint commit (report this to user)
- If no changes, skip this step
- If
-
Merge into main worktree:
- Get current branch name:
<branch> git -C <main-worktree-path> merge --no-commit --no-ff <branch>- The
--no-ffensures we get a proper staging even if fast-forward is possible
- Get current branch name:
-
Handle result:
- Success: Report that changes are now staged in main worktree. Remind user:
- Test in main worktree at
<main-worktree-path> - Run
/spotlight offwhen done to clean up
- Test in main worktree at
- Conflicts: Report conflicting files. User can resolve in main worktree or
run
/spotlight offto abort
- Success: Report that changes are now staged in main worktree. Remind user:
Mode: refresh
Re-spotlight the current branch's latest state into the main worktree. Useful after making new commits on the feature branch — avoids the off + on dance.
-
Clear any existing spotlight in main:
- If main worktree has an active merge (MERGE_HEAD exists):
git -C <main-worktree-path> merge --abort - Otherwise continue.
- If main worktree has an active merge (MERGE_HEAD exists):
-
Undo a prior checkpoint commit (if any):
- If current worktree HEAD subject is
spotlight: checkpoint:git reset --soft HEAD~1.
- If current worktree HEAD subject is
-
Re-run the
onflow: checkpoint any uncommitted changes, thengit -C <main-worktree-path> merge --no-commit --no-ff <branch>. -
Report the refreshed state (branch, main worktree path, whether a new checkpoint was created).
Mode: off
-
Abort merge in main worktree:
- Check if main worktree has an active merge (check for MERGE_HEAD as described above)
- If yes:
git -C <main-worktree-path> merge --abort - If no active merge: inform user "No active spotlight session found in main worktree"
-
Undo checkpoint commit (if applicable):
- Check if HEAD commit message is "spotlight: checkpoint"
via
git log -1 --format=%s - If yes:
git reset --soft HEAD~1to restore working state - If no: skip (user may have made additional commits)
- Check if HEAD commit message is "spotlight: checkpoint"
via
-
Report: Confirm cleanup is complete
Mode: status
- Check main worktree for active merge (MERGE_HEAD)
- Check if current worktree HEAD is a spotlight checkpoint
- Report:
- Whether spotlight is active
- Which branch is spotlighted
- Main worktree path
- Whether a checkpoint commit exists
Teleport this Claude conversation into a tmux window so the user can close the terminal they accidentally started Claude in without losing the session.
macOS cannot move a live process's controlling terminal (no working reptyr),
so this does NOT move the running process. Instead it arms a new tmux window to
resume the current conversation from disk (claude --resume <session-id>)
the moment the old process exits. The conversation transcript is persisted per
turn, so everything committed transfers; only truly in-flight work is lost.
All the real work lives in ${CLAUDE_PLUGIN_ROOT}/scripts/teleport-tmux.sh.
This command just runs it in two phases and relays the result.
IMPORTANT — run every bash block in this command with the sandbox DISABLED (
dangerouslyDisableSandbox: true). tmux talks to its server over a Unix socket (e.g./private/tmp/tmux-501/default) that lives outside the default sandbox's writable allowlist. Under the sandbox,tmux list-sessions,new-window, andsend-keysall fail witherror connecting to … (Operation not permitted). The script surfaces this asERROR_LISTING_SESSIONSinstead of silently hiding sessions — but it still cannot create the window unless the sandbox is off. Thecommand -v tmuxcheck passes either way (the binary exists), so the failure is easy to miss. Disable the sandbox up front.
Follow this workflow exactly.
Step 1: Discover state
Run this (sandbox disabled) and read its output:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/teleport-tmux.sh" --discover
Capture from the output:
RESUME_SCRIPT— path passed to--armin Step 3.AUTO—yesif the oldclaudePID was detected,nootherwise.INSIDE_TMUX—yesif we're already inside tmux.- The session list under
--- existing tmux sessions ---.
If you see ERROR_LISTING_SESSIONS, the sandbox is still on (or the tmux socket
is otherwise blocked). Re-run the command with the sandbox disabled before
continuing — do NOT treat it as "no sessions."
Step 2: Resolve the target session
- If the user passed an argument (
$ARGUMENTS), use it as the target session name. - Otherwise, look at the existing sessions from Step 1:
- If there are existing sessions, use AskUserQuestion to let the user pick
one, or choose "Create a new session". Offer a sensible default name for a
new session based on the current directory:
claude-<basename of CWD>. - If
<none>, default to creatingclaude-<basename of CWD>(still confirm the name with AskUserQuestion if the user gave no argument).
- If there are existing sessions, use AskUserQuestion to let the user pick
one, or choose "Create a new session". Offer a sensible default name for a
new session based on the current directory:
Set TARGET to the chosen session name.
Step 3: Create the window and arm the resume
Run this (sandbox disabled), substituting __TARGET__ (chosen session),
__SCRIPT__ (the RESUME_SCRIPT path from Step 1), and __AUTO__ (yes/no
from Step 1):
bash "${CLAUDE_PLUGIN_ROOT}/scripts/teleport-tmux.sh" --arm \
--target '__TARGET__' --script '__SCRIPT__' --auto '__AUTO__'
The script prints ARMED_AUTO_WAIT (auto mode) or ARMED_MANUAL (PID not
detected). If it dies with a "tmux socket is blocked" message, the sandbox is
still on — re-run with it disabled.
Step 4: Tell the user what to do
Based on the output:
-
If auto-wait was armed (
ARMED_AUTO_WAIT):- If
INSIDE_TMUXwasyes:tmux switch-client -t <TARGET>Otherwise, from any terminal:tmux attach -t <TARGET> - The new window shows "Waiting for the original Claude session to exit…".
- Close / exit the original terminal (or
Ctrl-Cthen exit the old Claude). The new window will automatically launchclaude --resumeand pick the conversation back up.
- If
-
If manual was armed (
ARMED_MANUAL— PID not detected):- Attach/switch to
<TARGET>as above. - The resume command is pre-typed but not running.
- First close the original terminal, then press Enter in the new window to start the resumed session (this ordering avoids transcript corruption from two processes writing at once).
- Attach/switch to
Keep the final message concise: the attach/switch command, and the reminder to close the old terminal.
Agents 1
Review the unstaged changes in this repository. The dispatching command will provide the working directory context.
Step 1: Get the Diff
Run git diff to capture the current unstaged changes.
If the diff is empty, report "No unstaged changes to review" and stop.
Step 2: Analyze Changes
Read full context of modified files as needed to understand the changes.
Analyze the diff for:
- Code quality issues
- Style inconsistencies
- Potential bugs or logic errors
- Missing error handling
- Opportunities for simplification
Step 3: Output
Provide feedback organized by:
- Issues: Problems that should be fixed before committing
- Suggestions: Improvements that would be nice to have
- Simplifications: Code that could be cleaner or more concise
Reference specific line numbers and file paths when possible. Keep the review concise and actionable.
Hooks 1
Sponsors
Details
- Marketplace
- sjungling/sjungling-claude-plugins
- Source
- plugins/workflow
- Category
- Community
