rk-skills 1.0.0 → 1.1.0

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "rk-skills",
-  "description": "Marketplace for rk-skills: Richard Kuo's personal Claude Code skill collection.",
+  "description": "Marketplace for rk-skills: Claude Code workflow skills for GitHub issues, PR review loops, docs syncing, and releases.",
   "owner": {
     "name": "Richard Kuo"
   },
@@ -8,7 +8,7 @@
     {
       "name": "rk-skills",
       "source": "./",
-      "description": "Richard Kuo's personal Claude Code skills: GitHub issue/PR/release workflow automation and Fable-driven planning."
+      "description": "Claude Code workflow skills: GitHub issue/PR/release automation and Fable-driven planning."
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "rk-skills",
   "displayName": "rk-skills",
-  "version": "1.0.0",
-  "description": "Richard Kuo's personal Claude Code skills: GitHub issue/PR/release workflow automation and Fable-driven planning.",
+  "version": "1.1.0",
+  "description": "Claude Code workflow skills: GitHub issue/PR/release automation and Fable-driven planning.",
   "author": {
     "name": "Richard Kuo"
   },

package/README.md

@@ -1,42 +1,78 @@
 # rk-skills
 
-Richard Kuo's personal [Claude Code](https://claude.com/claude-code) skills — the custom skills, global instructions, and slash command I use across every session.
+Workflow skills for [Claude Code](https://claude.com/claude-code) — automate GitHub issues, PR review loops, docs syncing, and releases.
 
-The real files live in this repo. On my machine they're symlinked into `~/.claude`, so editing in either place is the same file and a `git commit` here captures the change. Third-party / marketplace-installed skills are deliberately excluded — they're reinstallable and not authored by me.
+A "skill" is a reusable instruction file that teaches Claude Code how to do one job well (like filing a GitHub issue or cutting a release). You trigger one by name, and Claude follows its steps.
 
 ## Skills
 
-Most workflow skills come in two forms: a **base** skill that does one step, and a **`-loop`** variant that drives the whole thing autonomously through review to a merged PR.
+Most workflow skills come in two forms: a **base** skill that does one step and stops, and a **`-loop`** variant that keeps going on its own — through code review and re-review — until the pull request (PR) is approved.
 
-- **Issues** — `new-issue`, `validate-issue`, `work-on-issue` (+ `-loop` variants): file a fully-specified, complexity-scored issue; verify its claims against the actual code; implement it end-to-end in an isolated worktree and open a PR.
-- **PR review** — `fix-pr-review` (+ `-loop`): re-validate every review finding against the code, fix the ones that hold, push, and re-trigger review until approved.
-- **Docs & release** — `sync-docs`, `sync-docs-release`, `create-release`: refresh `CLAUDE.md`/`README`/`SKILL.md` from recent commits, and cut versioned GitHub releases.
-- **Fable-driven** — `fableplan`, `fable-validate`, `fable-new-issue` (+ `-loop` variants): delegate planning / validation / issue-drafting to a Fable 5 subagent, then build with your main-session model.
+```mermaid
+flowchart LR
+    A([validate-issue]) --> B([work-on-issue])
+    B --> C([PR + review])
+    C -- findings --> D([fix-pr-review])
+    D --> C
+    C -- LGTM --> E([issue complete])
+```
 
-Also included:
+Several skills mention a **complexity score** (`C0`–`C100`): a rough 0–100 rating of how hard an issue is to implement, put right in the issue title. "Fable" skills hand part of the work to a subagent running on the Fable 5 model — a second Claude instance that plans, validates, or drafts while your main session does the building.
 
-- `CLAUDE.md` — my global instructions for all Claude Code sessions (linked to `~/.claude/CLAUDE.md`). Many skills above are tuned to the conventions defined here (attribution footers, complexity scores, the branch+PR workflow).
-- `commands/commit.md` — the `/commit` slash command (linked to `~/.claude/commands/commit.md`).
+### Issue skills
 
-## Install (as a plugin)
+| Skill | What it does |
+|-------|--------------|
+| `new-issue` | Turns a bug, idea, or conversation into a complete GitHub issue. Checks the claims against the actual code first, adds a complexity score, and never files a half-empty stub. |
+| `new-issue-loop` | Runs `new-issue`, then automatically validates the new issue, implements it, and drives the PR through review — one command from idea to reviewed PR. Stops early if it finds a duplicate issue. |
+| `validate-issue` | Fact-checks an existing issue: verifies every claim against the real code (with file and line references), and checks that the proposed approach is feasible and self-consistent. |
+| `validate-issue-loop` | Runs `validate-issue`, applies any fixes the verdict calls for to the issue itself, then hands off to `work-on-issue-loop`. Stops instead if the issue is too large, infeasible, or already fixed elsewhere. |
+| `work-on-issue` | Implements an issue end-to-end: builds the fix in an isolated git worktree (a separate working copy, so your main checkout stays untouched), verifies it, and opens a PR that closes the issue. |
+| `work-on-issue-loop` | Runs `work-on-issue`, requests a code review, then keeps fixing whatever the review finds until the PR gets an approval ("LGTM" — looks good to me). |
 
-This repo is a Claude Code plugin marketplace. In any Claude Code session:
+### PR review skills
 
-```
-/plugin marketplace add richkuo/rk-skills
-/plugin install rk-skills@rk-skills
-```
+| Skill | What it does |
+|-------|--------------|
+| `fix-pr-review` | Reads all unaddressed feedback on a PR, re-checks each point against the actual code (never blindly applies a suggestion), fixes what holds up, pushes, replies point-by-point, and requests a fresh review. |
+| `fix-pr-review-loop` | Repeats `fix-pr-review` after every new review until the PR is approved. After 5 review rounds it accepts the first approval even if minor, non-blocking notes remain. |
 
-Claude Code auto-discovers everything under `skills/` (and the `/commit` command). `CLAUDE.md` is my personal global config and is **not** installed by the plugin — treat it as a reference. Restart Claude Code (or start a new session), then trigger any skill by name, e.g. `/fableplan <task>`.
+### Docs & release skills
 
-Prefer to install a single skill? Each is just a directory with a `SKILL.md`, so you can copy one in directly:
+| Skill | What it does |
+|-------|--------------|
+| `sync-docs` | Updates `CLAUDE.md`, `AGENTS.md`, `SKILL.md`, and `README.md` to match what recent commits actually changed. |
+| `create-release` | Cuts a version tag and publishes a GitHub release with generated notes, bumping the package version first so publish workflows fire correctly. |
+| `sync-docs-release` | The two above in sequence: sync docs, commit, then cut the release. |
+
+### Fable-driven skills
+
+| Skill | What it does |
+|-------|--------------|
+| `fableplan` | Has a Fable 5 subagent write an implementation plan before you build; posts the plan to the related issue if there is one. |
+| `fable-new-issue` | Like `new-issue`, but a read-only Fable 5 subagent researches and drafts the issue; your main session spot-checks and files it. |
+| `fable-new-issue-loop` | Runs `fable-new-issue`, then drives the new issue all the way to a reviewed PR automatically. |
+| `fable-validate` | Like `validate-issue`, but the fact-checking runs on a Fable 5 subagent; your main session presents the verdict and acts on it. |
+| `fable-validate-loop` | Runs `fable-validate`, applies issue fixes, gets a Fable plan (only for issues scored C50+ or touching safety-critical code), then drives to a reviewed PR. |
+| `validate-issue-fableplan-loop` | The hybrid: validates on your session's own model, but still brings in Fable for planning when the issue is C50+ or safety-flagged, then drives to a reviewed PR. |
+
+### Review bot prerequisite
+
+The PR-review skills (`fix-pr-review`, all `-loop` variants) depend on an automated reviewer that responds to `@claude review` comments and answers in a specific format (an `LGTM` / `Needs Updates` verdict plus structured findings). This repo ships a ready-made GitHub Actions workflow for that: copy [`templates/claude-review.yml`](./templates/claude-review.yml) into your repo's `.github/workflows/`, add an `ANTHROPIC_API_KEY` secret, and the bot and skills speak the same format out of the box. Without a review bot, the loop skills detect its absence and stop instead of waiting for a review that never arrives.
+
+Grab the workflow directly into a repo:
 
 ```sh
-mkdir -p ~/.claude/skills/work-on-issue && \
-  curl -fsSL https://raw.githubusercontent.com/richkuo/rk-skills/main/skills/work-on-issue/SKILL.md \
-  -o ~/.claude/skills/work-on-issue/SKILL.md
+mkdir -p .github/workflows && \
+  curl -fsSL https://raw.githubusercontent.com/richkuo/rk-skills/main/templates/claude-review.yml \
+  -o .github/workflows/claude.yml
 ```
 
+Also included:
+
+- `CLAUDE.md` — an example set of global instructions these skills are tuned for (attribution footers, complexity scores, the branch+PR workflow). Use it as a reference for your own `~/.claude/CLAUDE.md`.
+- `commands/commit.md` — a `/commit` slash command for creating well-formed git commits.
+
 ## Install (with npx)
 
 Copy every skill into your personal `~/.claude/skills/` with one command — no marketplace, no clone:
@@ -45,15 +81,25 @@ Copy every skill into your personal `~/.claude/skills/` with one command — no
 npx rk-skills
 ```
 
-Add `--project` to install into the current repo's `.claude/skills/` instead. This path is copy-based — re-run it to update — whereas the plugin above auto-updates. It installs the **skills only**; not `CLAUDE.md` (my personal global config) or the `/commit` command.
+Add `--project` to install into the current repo's `.claude/skills/` instead. This path is copy-based — re-run it to update — whereas the plugin below auto-updates. It installs the **skills and their subagent files** (a few skills delegate their work to helper agents in `agents/`, which land in `~/.claude/agents/`); it does not install `CLAUDE.md` (the example global config) or the `/commit` command.
 
-## Restore on a new machine (my setup)
+## Install (as a plugin)
 
-Clone this repo, then run `./install.sh`. It symlinks every tracked item into `~/.claude`, backing up any existing real file to `<name>.bak` first. It only ever replaces symlinks — it never deletes your data.
+This repo is a Claude Code plugin marketplace. In any Claude Code session:
 
-```bash
-git clone git@github.com:richkuo/rk-skills.git ~/Work/rk-skills
-cd ~/Work/rk-skills && ./install.sh
+```
+/plugin marketplace add richkuo/rk-skills
+/plugin install rk-skills@rk-skills
+```
+
+Claude Code auto-discovers everything under `skills/` (and the `/commit` command). `CLAUDE.md` is **not** installed by the plugin — treat it as a reference. Restart Claude Code (or start a new session), then trigger any skill by name, e.g. `/fableplan <task>`.
+
+Prefer to install a single skill? Each is just a directory with a `SKILL.md`, so you can copy one in directly:
+
+```sh
+mkdir -p ~/.claude/skills/work-on-issue && \
+  curl -fsSL https://raw.githubusercontent.com/richkuo/rk-skills/main/skills/work-on-issue/SKILL.md \
+  -o ~/.claude/skills/work-on-issue/SKILL.md
 ```
 
 ## License

package/agents/create-release-runner.md

@@ -0,0 +1,96 @@
+---
+name: create-release-runner
+description: Runs the create-release workflow. Use whenever the user asks to create a release, cut a release, tag a version, publish release notes, or ship a new versioned GitHub release for the current repo.
+---
+
+# create-release
+
+Cut an annotated semver tag and publish a GitHub release with auto-generated notes.
+
+## Preconditions — verify ALL before doing anything
+
+```bash
+git status              # must be clean — stop if dirty, surface the diff
+git branch --show-current   # must be on default branch (main/master)
+git fetch origin && git status  # must be up to date with origin
+gh auth status          # must succeed
+```
+
+If any check fails: **stop and tell the user**. Do not proceed.
+
+## Steps
+
+1. **Inspect actual tags** — never rely on memory or CHANGELOG:
+   ```bash
+   git tag --sort=-v:refname | head -10
+   ```
+
+2. **Review commits since last tag:**
+   ```bash
+   git log <last-tag>..HEAD --oneline
+   ```
+
+3. **Determine semver bump and state rationale** — breaking = major, new feature = minor, fixes/polish = patch. Proceed immediately. Only pause to ask the user if the bump type is genuinely ambiguous (e.g. unclear whether commits are breaking).
+
+4. **Bump the repo's declared version — MANDATORY whenever a version field exists.** This is the package/manifest version, not just a "user-facing app" version: a library, CLI, or installer package (e.g. one with a `package.json` `"version"`) counts and **must** be bumped. Do not skip this because the repo "isn't an app." Grep the repo for version fields and update every match to `X.Y.Z` so the tag points at a commit carrying the correct version. Common locations (check all, update every match):
+
+   | File | Field |
+   |------|-------|
+   | `package.json` | `"version"` |
+   | `.claude-plugin/plugin.json` | `"version"` |
+   | `app.json` / `app.config.js` / `app.config.ts` | `expo.version` |
+   | `pubspec.yaml` | `version` |
+   | `Cargo.toml` | `[package] version` |
+   | `pyproject.toml` | `[project] version` or `[tool.poetry] version` |
+   | iOS `*.xcodeproj/project.pbxproj` | `MARKETING_VERSION` |
+   | Android `build.gradle` | `versionName` |
+
+   - Leave native build numbers (`buildNumber`, `versionCode`, `CURRENT_PROJECT_VERSION`) alone unless the user asks.
+   - If — and only if — no version field exists anywhere, skip silently and proceed to step 5.
+   - **Publish-on-release check (do this every time):** inspect `.github/workflows/` for a job that runs on `release: published` (e.g. `npm publish`). These jobs are almost always idempotency-guarded on the manifest version — if `package.json` still holds the previous version, the guard sees it already published and **silently skips**, so the release ships to GitHub but never reaches the registry. If such a workflow exists, bumping the manifest version in this step is what makes the publish actually fire; a mismatch between the tag and the manifest version is a bug.
+   - If a version field exists, edit it, then commit and push **before tagging**:
+     ```bash
+     git commit -am "chore(release): bump version to X.Y.Z"
+     git push origin <default-branch>
+     ```
+   - The tag must point at this bump commit — create the tag only after the commit and push succeed.
+
+5. **Create annotated tag** (not lightweight):
+   ```bash
+   git tag -a vX.Y.Z -m "vX.Y.Z"
+   ```
+
+6. **Push tag:**
+   ```bash
+   git push origin vX.Y.Z
+   ```
+
+7. **Create release with auto-generated notes:**
+   ```bash
+   gh release create vX.Y.Z --generate-notes --title "vX.Y.Z"
+   ```
+   Print the URL from `gh`'s output.
+
+8. **Project-local hook:** if the repo has a `MEMORY.md` or `CHANGELOG.md` with a Releases section, append:
+   `**vX.Y.Z** — YYYY-MM-DD: <one-line summary>`
+   Skip silently if neither exists.
+
+## Red Flags — STOP
+
+| Situation | Action |
+|-----------|--------|
+| Tag already exists | Do NOT force-overwrite. Ask user. |
+| `git status` dirty | Stop. Surface the diff. |
+| Not on default branch | Stop. Ask user to confirm intent. |
+| Breaking changes + patch bump proposed | Require major bump. |
+| Manifest version (`package.json` etc.) still at previous version | Bump it (step 4) before tagging — a stale version silently no-ops any publish-on-release workflow. |
+
+## Common Mistakes
+
+- **Trusting memory for latest version** — always run `git tag`, tags and notes diverge.
+- **Hand-writing release notes** — always use `--generate-notes`; GitHub builds them from merged PRs automatically.
+- **Stalling for unnecessary confirmation** — if preconditions pass and bump type is clear, tag and release immediately.
+- **Lightweight tag** — `git tag vX.Y.Z` without `-a` creates a lightweight tag; use `-a` always.
+- **Letting `gh release create` implicitly create the tag** — create and push the tag explicitly first so it's traceable.
+- **Tagging before the version bump commit** — if the repo has a declared version, bump and commit it first, then tag that commit. A tag pointing at a commit with the old version is wrong.
+- **Treating a library/installer's `package.json` version as "not an app version" and skipping the bump** — any manifest `version` field must be bumped (step 4). Skipping it strands the release on GitHub and silently skips the npm publish, because the publish workflow keys off `package.json`'s version.

package/agents/sync-docs-runner.md

@@ -0,0 +1,174 @@
+---
+name: sync-docs-runner
+description: Runs the sync-docs workflow. Use whenever the user asks to sync, update, or refresh CLAUDE.md, AGENTS.md, SKILL.md, or README.md to reflect recent commits or PRs.
+---
+
+# sync-docs
+
+Keep CLAUDE.md, AGENTS.md, SKILL.md, and README.md accurate after new commits land. Finds the last docs-sync point, classifies every commit since then, and writes targeted updates — no rewrite, no drift. Syncing is bidirectional: as well as adding what's new, **remove or correct anything the current codebase now contradicts** — stale paths, renamed symbols, removed fields, dead defaults. A doc that lies is worse than one that's merely incomplete.
+
+Adapt to the repo you're in. The doc set below is the common shape, not a requirement — a repo may have only a README, or add its own docs. Edit the files that exist; never create a new top-level doc (AGENTS.md, CHANGELOG.md, SKILL.md) as part of a sync — if one seems warranted, surface it to the user instead.
+
+Audience split:
+- **CLAUDE.md** — agent-facing dense reference (architecture, symbol/file names, `file:line` cues). Describes **current behavior**; not a history log.
+- **AGENTS.md** *(only if the repo already has one — check `ls AGENTS.md` first)* — the counterpart agent doc for other tools (e.g. Codex). Same body content (architecture, commands, conventions); only the intro line stays tool-specific. When present, mirror every CLAUDE.md body edit into it so the two stay in lockstep — see step 5.
+- **SKILL.md** *(only if the repo has one)* — operator-facing imperative guide (config knobs, setup prompts, CLI flows).
+- **README.md** — public/newcomer-facing (setup, supported features, headline config). Lowest churn — update only when public surface changes.
+- **CHANGELOG.md** *(only if the repo already has one — check `ls CHANGELOG.md` first)* — per-issue/PR history, rationale, and migration archaeology. When present it is the home for the "why" and resolved-migration detail, so CLAUDE.md stays lean. Never create one as part of a sync.
+
+## Preconditions
+
+```bash
+git log --oneline -5        # confirm you're on the right branch
+git status                  # must be clean before editing docs
+```
+
+## Steps
+
+### 1. Find the last sync baseline
+
+```bash
+git log --oneline | grep -m1 "docs:.*sync\|docs:.*CLAUDE\|docs:.*SKILL\|sync docs"
+```
+
+Note the SHA. If none found, ask the user for the last-known-good tag or SHA (or fall back to the initial commit for a first sync).
+
+### 2. Get commits since last sync
+
+```bash
+git log <last-sync-sha>..HEAD --oneline
+```
+
+Exclude pure CI / workflow / chore commits (`.github/`, `scripts/`, version bumps) unless they affect agent- or operator-facing behavior.
+
+### 3. Classify each commit
+
+| Category | Docs target | Action |
+|----------|-------------|--------|
+| New config field / flag / setting | CLAUDE.md config reference; SKILL.md settings table (if present); README.md **only if** it's a top-level/public-facing knob | Add field description + notes |
+| Changed default behavior | CLAUDE.md patterns section; SKILL.md (if present); README.md **only if** a documented default/example now contradicts the code | Update description; note old vs new |
+| New pluggable unit (plugin, command, integration, platform, strategy, theme, provider…) | CLAUDE.md structure + SKILL.md catalog (if present) + README.md feature list | Add entry to each doc that enumerates the set |
+| Bug fix (behavior change) | CLAUDE.md patterns (if pattern-level) | Update the relevant bullet |
+| New CLI command / flag | SKILL.md commands (if present); README.md Getting Started **only if** it's part of the setup/operator flow | Add usage |
+| Setup / install flow change | README.md Getting Started + SKILL.md (if operator-facing) | Update the relevant block |
+| Internal refactor / test | Skip (no docs change needed) | — |
+| New release milestone | Project memory/notes file **if one exists** (see step 9) | Append version entry |
+| Per-issue/PR history, rationale, or migration archaeology (*if CHANGELOG.md exists*) | CHANGELOG.md | Add a keyed entry there, not into CLAUDE.md; CLAUDE.md gets only the terse current-state invariant |
+| Existing doc claim contradicted by current code (stale path, renamed symbol, removed field, changed default) | Whichever doc carries the claim | Correct or delete the stale statement |
+
+### 4. Audit existing docs against the codebase and prune outdated content
+
+Commit-driven updates catch what changed; they miss docs that silently went stale. Before writing new content, spot-check the existing docs against the actual code:
+
+- For each doc section in the area of an in-scope commit, verify the surrounding claims still hold — file paths exist, symbol names match, defaults and version numbers are current, CLI flags still accept the documented args.
+- Delete or correct any statement the codebase contradicts: removed fields, renamed symbols, dead file paths, stale defaults, deprecated flows, examples that no longer run.
+- Removing wrong content is as important as adding new content — treat a prune as a first-class edit, not an afterthought.
+- Stay scoped: audit the areas related to the in-scope commits, not the entire doc. If the docs look broadly drifted beyond that scope, flag it to the user rather than silently doing a full rewrite.
+- When unsure whether something is outdated, grep the code to confirm before deleting — never remove a claim you haven't verified is wrong.
+- **Cross-check "current/live/active/default" claims against the deciding variable, not the doc's own prior text.** Any doc that names which version/mode/config is currently in effect (a build script's target, a feature-flag default, an active-environment pointer) can go stale silently — the doc reads as self-consistent even after the underlying switch moved. Find the actual switch (grep for the assignment — `MAIN=`, `ACTIVE_*`, a default-branch config key, etc.) and confirm it still matches what the doc claims.
+- **Diff enumerable generated listings against the filesystem.** When an in-scope commit touches a directory holding a versioned or pluggable set of items (plugins, commands, integrations, themes, providers), list the actual directory entries (`ls`, `find`) and compare against every place that's supposed to enumerate them (index/chooser pages, catalog tables, README lists). A missing or orphaned entry is a silent drift the commit diff alone won't surface, because the commit that broke it may be several syncs back.
+- **Check promotion/demotion parity.** If the codebase has a "promote item to active, retire the previous one" pattern (a new default version, a new production config, a newly-active integration), verify that state encoding "this is the active one" — self-referencing URLs, indexing/discoverability directives, feature flags, config defaults — was flipped on BOTH the newly-promoted item and the newly-demoted item. A promotion is a two-sided edit; half-applied swaps (new item correct, old item still claiming to be active) are a common source of live bugs, not just doc drift, and won't show up in a diff of the promoting commit alone. If you find this pattern is real but undocumented as an explicit invariant, add a short rule for it to the project's own docs (e.g. CLAUDE.md patterns) so future promotions don't repeat the same half-applied swap.
+
+### 5. Edit CLAUDE.md
+
+- Stay surgical: edit only the sections that changed.
+- Add new fields to the appropriate config or patterns section.
+- Keep bullets concise — CLAUDE.md is dense reference, not narrative.
+- Update any config/schema version constant the project maintains if a migration bumped it.
+- If a new opt-in field was added and the repo has a SKILL.md, add it to the relevant operator table there (see step 6).
+- **Mirror into AGENTS.md if it exists.** Run `ls AGENTS.md`; if present, apply every body edit you just made to CLAUDE.md to AGENTS.md verbatim (architecture, commands, conventions, schema — same content). The only thing that differs is the intro/header line, which stays tool-specific — do not overwrite it with CLAUDE.md's Claude-facing line. Also audit AGENTS.md for the same staleness patterns as step 4: it drifts silently because commit-driven edits target CLAUDE.md by name. If AGENTS.md doesn't exist, skip it — never create one during a sync.
+
+### 6. Edit SKILL.md (only if the repo has one)
+
+Keep SKILL.md operator-facing and imperative; avoid code internals. Common targets, depending on what the repo's SKILL.md documents:
+- **Settings / configuration table** — add new global or per-unit keys.
+- **Post-update / upgrade reference** — add the change as a default, opt-in, or auto-migration row so operators get prompted on upgrade.
+- **Commands / reconfiguration section** — if a CLI surface or reload scope changed.
+- **Operator safety controls** — if guard/circuit-breaker/limit behavior changed.
+
+### 7. Edit README.md (only if public surface changed)
+
+README is the entry point for newcomers and the public face of the project. Default to **no edit** — only touch when one of these is true:
+
+- **New supported feature/platform/integration** → add to the relevant feature or catalog section.
+- **New public-facing unit** (plugin, command, provider, theme) → add to the list that enumerates them, one line each, matching the existing format.
+- **New top-level CLI subcommand** that users run by hand → add to the appropriate Getting Started block or a dedicated section.
+- **Setup / install / build flow change** → update the relevant setup block.
+- **Public-facing config knob change** that contradicts a documented example → update the affected config sub-block only.
+
+Skip README for: bug fixes, internal refactors, parameter tweaks, symbol renames, schema migrations (those go in SKILL.md if present), and cosmetic changes.
+
+When editing:
+- Keep the tone tutorial-clean — no `file:line` cues, no code internals, no PR numbers in body text (PR numbers only in changelog-style sections that already use them).
+- Don't grow lists into prose — each item gets one line / one bullet matching the existing format.
+- If a section already has version/PR references, follow the same convention; otherwise omit them.
+
+### 8. Check CLAUDE.md size and condense if oversized
+
+Claude Code warns when CLAUDE.md exceeds 40k chars ("Large CLAUDE.md will impact performance"). Run after step 5:
+
+```bash
+wc -c CLAUDE.md
+```
+
+If the byte count exceeds **40000**, condense in-place before finishing the sync. Target: bring the file back under 38000 chars (leaves headroom for the next sync). Do NOT split into multiple files — agents only auto-load the root CLAUDE.md.
+
+**If a CHANGELOG.md exists, relocate rather than delete.** Before dropping completed-migration prose, resolved-incident narrative, or per-issue "why" detail (passes 2 and 5 below), move it into CHANGELOG.md keyed by issue/PR instead of discarding it — the history stays available without loading into agent context every turn. Only outright-delete history when the repo has no CHANGELOG.md to receive it. Never create a CHANGELOG.md solely to offload bytes during a sync; if CLAUDE.md is oversized and no CHANGELOG.md exists, surface that to the user as an option rather than introducing the file unilaterally.
+
+**Condensation rules — preserve agent-critical signal, drop narrative:**
+
+| Keep | Trim / drop |
+|------|-------------|
+| Symbol / file names and `file:line` cues | Prose explaining *why* a pattern exists when the rule alone is actionable |
+| Field-name lists, enum values, default values, version numbers (thresholds, timeouts, schema versions) | Historical migration notes once the migration has shipped and stabilized (>2 versions old) |
+| Non-obvious gotchas, race conditions, lock order, ordering constraints | Restated information that's already in another bullet |
+| Active "new X requires Y" instructions | Examples that duplicate a rule already stated tersely |
+| Currently-live behavior | Deprecated behavior, legacy field aliases that no caller uses |
+
+**Mechanical passes — apply in order, stop when under target:**
+
+1. **Collapse duplicated phrasing** — same fact stated twice in different bullets → merge into one bullet.
+2. **Drop completed-migration prose** — if a migration is ≥2 versions behind the current schema/config version AND the legacy field is no longer read, delete the migration narrative; keep the field rename only if code still references the old name.
+3. **Compress example-laden bullets** — `e.g.` lists with 3+ items → keep the first 1–2 + `…` if the pattern is obvious.
+4. **Inline single-line sub-bullets** — `- foo:\n  - bar` where bar is one short clause → `- foo: bar`.
+5. **Remove resolved-incident narrative** — "fixed because X happened in prod" becomes "X — see <symbol>" or is dropped if the rule stands on its own.
+6. **Shorten reference-table cells** — multi-clause descriptions → one clause + symbol name; agents resolve details from code.
+
+**Forbidden — never trim these even if oversized:**
+- The `## Environment`, `## Setup`, `## Build & Deploy`, `## Testing` blocks (operator-load-bearing).
+- Lookup tables — lists of IDs, type names, prefixes, file paths (losing one row corrupts dispatch).
+- Concurrency-hazard rules (state-locking, lock-order, skip-reason/live-exec guards).
+- Any PR/commit footer or format convention the repo's own CLAUDE.md defines.
+
+After condensing, re-run `wc -c CLAUDE.md` and report old → new byte counts. If still over 40k after all six passes, surface to the user with a list of the largest sections and ask which to cut further — don't unilaterally remove load-bearing content.
+
+### 9. Update the project memory/notes file if one exists
+
+Some repos keep a running notes or memory file (e.g. `MEMORY.md`, `NOTES.md`, `docs/CHANGELOG`-style log) with a Releases section. If one exists **and** the in-scope commits include a version tag or release PR, append:
+
+```
+- **vX.Y.Z** — YYYY-MM-DD: <one-line summary> (PRs #N, #M)
+```
+
+Only append if such a file already exists — never create one during a sync.
+
+## Red Flags — STOP
+
+| Situation | Action |
+|-----------|--------|
+| `git status` is dirty before you start | Stash or commit pending work first |
+| Commit touches multiple unrelated areas | Split classification carefully; don't conflate |
+| A field was *removed* | Delete the row/bullet — don't leave stale docs |
+| Behavior reversal (bug was fixed back to original) | Note the revert explicitly, don't just silently restore |
+| A sync seems to warrant a brand-new top-level doc (AGENTS.md, CHANGELOG.md, SKILL.md) | Surface it to the user — never create one as part of a sync |
+
+## Common Mistakes
+
+- **Over-documenting internals** — CLAUDE.md is for agent-relevant patterns; SKILL.md is for operators. Symbol/field names belong in CLAUDE.md, not SKILL.md operator tables.
+- **Under-documenting opt-in fields** — when the repo has a SKILL.md, every new opt-in field needs a row in its settings table and its upgrade reference so operators get prompted on upgrade.
+- **Copying PR descriptions verbatim** — translate to concise imperative phrases the reader can act on.
+- **Bundling multiple unrelated changes into one bullet** — one bullet per behavioral change.
+- **Treating README like CLAUDE.md** — don't dump code internals, symbol names, or PR-by-PR changelog entries into README. If a change doesn't affect what a newcomer needs to install/run/configure, it doesn't belong there.
+- **Forgetting README on new public units** — new features/plugins/integrations are the highest-signal README updates and the easiest to miss because CLAUDE.md and SKILL.md updates feel "complete." Always check the enumerated lists.
+- **Trusting a doc's own history instead of re-deriving current state from code** — a "currently active" claim is only correct as of when it was written. Always re-check it against the actual deciding switch (config default, build-script variable, feature flag) rather than assuming a prior sync got it right.
+- **Creating a new top-level doc during a sync** — AGENTS.md, CHANGELOG.md, and SKILL.md are only edited when they already exist; introducing one is a user decision, not a sync side effect.

package/bin/install.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 
 const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const skillsSrc = join(pkgRoot, 'skills');
+const agentsSrc = join(pkgRoot, 'agents');
 
 if (!existsSync(skillsSrc)) {
 	console.error('rk-skills: could not find the skills/ directory in the package.');
@@ -25,17 +26,35 @@ if (skills.length === 0) {
 }
 
 const project = process.argv.includes('--project');
-const skillsDir = project
-	? join(process.cwd(), '.claude', 'skills')
-	: join(homedir(), '.claude', 'skills');
+const claudeDir = project
+	? join(process.cwd(), '.claude')
+	: join(homedir(), '.claude');
+const skillsDir = join(claudeDir, 'skills');
+const agentsDir = join(claudeDir, 'agents');
 
 mkdirSync(skillsDir, { recursive: true });
 for (const name of skills) {
 	cpSync(join(skillsSrc, name), join(skillsDir, name), { recursive: true });
 }
 
+// Some skills are dispatch shims that invoke subagents; install their agent files too.
+const agents = existsSync(agentsSrc)
+	? readdirSync(agentsSrc).filter((name) => name.endsWith('.md')).sort()
+	: [];
+if (agents.length > 0) {
+	mkdirSync(agentsDir, { recursive: true });
+	for (const name of agents) {
+		cpSync(join(agentsSrc, name), join(agentsDir, name));
+	}
+}
+
 const scope = project ? 'this project' : 'your personal skills';
 console.log(`rk-skills installed ${skills.length} skills into ${scope}:`);
 console.log(`  ${skillsDir}`);
 console.log(`  ${skills.join(', ')}`);
+if (agents.length > 0) {
+	console.log(`\nAlso installed ${agents.length} subagents into:`);
+	console.log(`  ${agentsDir}`);
+	console.log(`  ${agents.map((n) => n.replace(/\.md$/, '')).join(', ')}`);
+}
 console.log('\nRestart Claude Code (or start a new session), then invoke any skill by name, e.g.\n  /fableplan <task to plan>');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rk-skills",
-  "version": "1.0.0",
-  "description": "Installer for Richard Kuo's personal Claude Code skills — GitHub issue/PR/release workflow automation and Fable-driven planning.",
+  "version": "1.1.0",
+  "description": "Installer for Claude Code workflow skills — GitHub issue/PR/release automation and Fable-driven planning.",
   "type": "module",
   "bin": {
     "rk-skills": "bin/install.mjs"
@@ -9,6 +9,7 @@
   "files": [
     "bin",
     "skills",
+    "agents",
     ".claude-plugin",
     "README.md",
     "LICENSE"

package/skills/fable-new-issue/SKILL.md

@@ -22,8 +22,9 @@ Locate the `new-issue` SKILL.md the subagent must follow — prefer the project-
 
 1. `<repo>/.claude/skills/new-issue/SKILL.md` (if it exists)
 2. `~/.claude/skills/new-issue/SKILL.md`
+3. Any other install location — search by name, e.g. `ls ~/.claude/plugins/*/skills/new-issue/SKILL.md` (plugin-marketplace installs live under a plugin directory, not `~/.claude/skills/`).
 
-Record the absolute path. If neither exists, stop and tell the user.
+Record the absolute path. If none of these resolves, stop and tell the user.
 
 If the input is conversation-derived, write the scratchpad summary now (see Input). Do NOT pre-research or pre-draft the issue yourself — the subagent owns steps 1–6 of the procedure up to (but not including) the `gh issue create` call.
 
@@ -68,5 +69,6 @@ Terse: issue URL, number, one-line summary, complexity score, any unfiled follow
 ## Notes
 
 - The drafting subagent runs on Fable 5 regardless of the main agent's model — `model: fable` forces it.
+- **If the `fable` model is unavailable in this harness** (the Agent call errors on the model id), fall back to the most capable model available and proceed — the isolation pattern (read-only subagent drafts, main agent files) is what matters. Name the model that actually ran in the footer and report, never "Fable 5".
 - One subagent, one draft: don't fan out or re-run for a second opinion unless the user asks.
 - Never file a placeholder or thin body — if the subagent's draft isn't complete, it doesn't get filed; that rule outranks finishing the run.

package/skills/fable-validate/SKILL.md

@@ -23,8 +23,9 @@ Locate the `validate-issue` SKILL.md the subagent must follow — prefer the pro
 
 1. `<repo>/.claude/skills/validate-issue/SKILL.md` (if it exists)
 2. `~/.claude/skills/validate-issue/SKILL.md`
+3. Any other install location — search by name, e.g. `ls ~/.claude/plugins/*/skills/validate-issue/SKILL.md` (plugin-marketplace installs live under a plugin directory, not `~/.claude/skills/`).
 
-Record the absolute path. If neither exists, stop and tell the user.
+Record the absolute path. If none of these resolves, stop and tell the user.
 
 If the user referenced an issue, note the number/repo but do NOT fetch or pre-validate it yourself — the subagent owns steps 0–7 of the procedure, including fetching. If no issue was referenced, the subagent resolves the latest open issue itself per the procedure.
 
@@ -69,5 +70,6 @@ Handle the user's reply per the validate-issue procedure — these are main-agen
 ## Notes
 
 - The validation subagent runs on Fable 5 regardless of the main agent's model — `model: fable` on the Agent call forces it.
+- **If the `fable` model is unavailable in this harness** (the Agent call errors on the model id), fall back to the most capable model available and proceed — the isolation pattern (read-only subagent validates, main agent acts) is what matters. Name the model that actually ran in the footer and report, never "Fable 5".
 - One subagent, one verdict: don't fan out or re-run for a second opinion unless the user asks.
 - If the user's reference turns out not to be fetchable (wrong number, no auth), the subagent will report that per the procedure — relay it; never validate against a paraphrase.

package/skills/fable-validate-loop/SKILL.md

@@ -60,7 +60,7 @@ Keep the vetted plan's scratchpad file — step 5 passes it through. If fablepla
 
 Invoke the `work-on-issue-loop` skill for the same issue number (Skill tool, `skill: work-on-issue-loop`). Pass the issue number through explicitly — don't let it re-resolve "latest issue" — and instruct it that the implementation must follow the Fable 5 plan: point it at the plan's scratchpad file and the posted issue comment (`## Implementation plan (Fable 5)`), and tell it deviations from the plan are allowed only when the code contradicts the plan, and must be named in the PR body. (If step 4 was skipped by the complexity gate, there is no plan — hand off the issue alone and note the skip.)
 
-It runs its full loop: work-on-issue implements in a worktree, opens the PR, triggers `@claude` review, and fix-pr-review cycles until convergence.
+It runs its full loop: work-on-issue implements in a worktree and opens the PR, the loop triggers `@claude` review, and fix-pr-review cycles until convergence.
 
 ### 6. Report
 

package/skills/fableplan/SKILL.md

@@ -68,7 +68,7 @@ Add `-R owner/repo` when the issue lives in another repo (as in step 1). Use the
 
 ```
 ---
-Created with: Fable 5 | high | Claude Code | fableplan
+Created with LLM: Fable 5 | high | Harness: Claude Code | fableplan
 ```
 
 After posting, give the user the comment URL `gh` returns. Follow the repo's CLAUDE.md conventions for comment formatting if any apply (e.g. avoid `#N` auto-links in list items). If no issue is referenced, skip this step.
@@ -94,4 +94,5 @@ In the worktree from step 6, the main agent builds the task per the plan. Confir
 ## Notes
 
 - The Plan subagent runs on Fable 5 regardless of the main agent's model — `model: fable` on the Agent call forces it.
+- **If the `fable` model is unavailable in this harness** (the Agent call errors on the model id), fall back to the most capable model available and proceed — the isolation pattern (Plan subagent plans, main agent builds) is what matters. Name the model that actually ran in the footer and report, never "Fable 5".
 - If the user did not reference an issue, never invent one or post anywhere — just plan and build.

package/skills/fix-pr-review-loop/SKILL.md

@@ -29,6 +29,8 @@ gh pr view <N|--> --json number,headRefName,headRepositoryOwner,baseRefName,url,
   ```
   Record the trigger timestamp, set `review_count = 1`, and go to step 2 to wait for it.
 
+**Preflight — confirm a review bot exists before waiting on one.** This loop assumes an automated reviewer that answers `@claude review` comments. Before entering the wait, check the repo for one: `gh api repos/{owner}/{repo}/contents/.github/workflows --jq '.[].name'` and look for a workflow that responds to `@claude` (e.g. `claude.yml`), or confirm the Claude GitHub App is installed. If you find none, don't sink 30 minutes into a review that will never come — tell the user no review bot is configured and point them at `templates/claude-review.yml` in this repo (copy it to `.github/workflows/`, add an `ANTHROPIC_API_KEY` secret). Proceed into the wait only if a reviewer is present or the user confirms one is configured elsewhere.
+
 ### 2. Wait for the review to land
 
 Poll the PR for a new review or issue comment posted **after** the last trigger timestamp — reviews can land as a formal PR review or as an issue comment (the `@claude` bot usually posts as an issue comment; see fix-pr-review step 1 for the `gh` calls to check — it also fetches inline diff threads, which matter when a human reviewer weighs in). An until-loop is the right shape here — you want to be notified once the condition is true, not to busy-poll inline:

package/skills/validate-issue/SKILL.md

@@ -280,7 +280,7 @@ Scope: (omit unless the issue is too large per step 6.5)
 
 ### 7.5. When the user replies "work on issue" — hand off to the work-on-issue skill
 
-When the user opts to **work on** the issue (not merely validate or update it), **invoke the `work-on-issue` skill** — that is the default follow-on. It owns the full implementation flow: create and switch into a fresh isolated worktree off the latest default branch, implement the fix to the codebase's conventions, verify, commit and push, open a PR that `Closes #<N>`, and trigger an `@claude` review on it.
+When the user opts to **work on** the issue (not merely validate or update it), **invoke the `work-on-issue` skill** — that is the default follow-on. It owns the full implementation flow: create and switch into a fresh isolated worktree off the latest default branch, implement the fix to the codebase's conventions, verify, commit and push, and open a PR that `Closes #<N>` (it ends with the open PR — requesting review is the caller's job).
 
 Pass the issue number through; the skill is idempotent about the worktree (reuses an existing one for this issue). Don't start editing code or creating a worktree here yourself — delegate so the implement → PR → review chain stays consistent.
 

package/skills/validate-issue-fableplan-loop/SKILL.md

@@ -62,7 +62,7 @@ Keep the vetted plan's scratchpad file — step 5 passes it through. If fablepla
 
 Invoke the `work-on-issue-loop` skill for the same issue number (Skill tool, `skill: work-on-issue-loop`). Pass the issue number through explicitly — don't let it re-resolve "latest issue" — and instruct it that the implementation must follow the Fable 5 plan: point it at the plan's scratchpad file and the posted issue comment (`## Implementation plan (Fable 5)`), and tell it deviations from the plan are allowed only when the code contradicts the plan, and must be named in the PR body. (If step 4 was skipped by the complexity gate, there is no plan — hand off the issue alone and note the skip.)
 
-It runs its full loop: work-on-issue implements in a worktree, opens the PR, triggers `@claude` review, and fix-pr-review cycles until convergence.
+It runs its full loop: work-on-issue implements in a worktree and opens the PR, the loop triggers `@claude` review, and fix-pr-review cycles until convergence.
 
 ### 6. Report
 

package/skills/work-on-issue/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: work-on-issue
-description: Use when the user says "work on issue", "work on this issue", "implement issue", "/work-on-issue", or otherwise asks to implement a GitHub issue end-to-end (not merely validate it). Takes a GitHub issue URL or number (defaults to the just-validated issue). Implements the fix in an isolated worktree, verifies it, commits and pushes, opens a PR that closes the issue, and triggers an @claude review on the PR. This is the default follow-on when validate-issue offers "work on issue".
+description: Use when the user says "work on issue", "work on this issue", "implement issue", "/work-on-issue", or otherwise asks to implement a GitHub issue end-to-end (not merely validate it). Takes a GitHub issue URL or number (defaults to the just-validated issue). Implements the fix in an isolated worktree, verifies it, commits and pushes, and opens a PR that closes the issue. This is the default follow-on when validate-issue offers "work on issue".
 ---
 
 # work-on-issue
 
-Take a GitHub issue from "validated" to "PR under review", autonomously and end-to-end: isolate the work in a fresh worktree, implement the fix to the codebase's conventions, verify it really works, commit and push, open a pull request that closes the issue, then request an `@claude` review. Don't stop to ask the user between steps — do the work and report at the end.
+Take a GitHub issue from "validated" to "PR open", autonomously and end-to-end: isolate the work in a fresh worktree, implement the fix to the codebase's conventions, verify it really works, commit and push, then open a pull request that closes the issue. The skill ends with the open PR — requesting review is the caller's job (work-on-issue-loop does it; standalone, the user decides). Don't stop to ask the user between steps — do the work and report at the end.
 
 **This is the natural follow-on to validate-issue.** When validate-issue ends with `→ Reply "work on issue"`, the user replying "work on issue" lands here. The skill is also valid standalone — invoke it when the user asks to implement an issue without a prior validation pass.
 
@@ -118,29 +118,11 @@ gh pr create --base "$(gh repo view --json defaultBranchRef -q .defaultBranchRef
 
 Capture the PR number/URL from the command output.
 
-### 7. Check CI, then trigger the @claude review
+### 7. Report to the user
 
-Local verification isn't CI — environment differences and matrix jobs can fail on a tree that passed locally. Check the PR's checks before requesting review; a review of a red PR is wasted:
+The skill ends here — do **not** trigger an `@claude` review or wait on CI; requesting review belongs to the caller (work-on-issue-loop posts the trigger itself; standalone, the user decides whether and when to request one).
 
-```bash
-gh pr checks <PR-number>
-```
-
-- **Failing** → fix the failure, push, and re-check before triggering. **Bound the loop:** if CI is still red after two or three fix-push-recheck rounds, stop and report the PR's true state (open, CI red, what was tried) — an honestly-reported red PR beats an endless loop or a false success.
-- **Pending** → don't block the flow waiting; trigger the review and state the pending CI status in the final report.
-- **Empty output is not "no checks".** Immediately after the PR opens, CI may not have registered its runs yet. If the repo defines workflows (`ls .github/workflows/`), wait briefly and re-run `gh pr checks` before classifying; conclude "none configured" only when the repo has no CI workflows at all — then proceed and note it in the report.
-
-Then post a **separate, one-line** comment so the bot triggers cleanly on its own:
-
-```bash
-gh pr comment <PR-number> --body "@claude review"
-```
-
-(If the repo uses a different review trigger phrase, match it — check recent PR comments.) A trigger mention is not authored content — no footer.
-
-### 8. Report to the user
-
-Terse summary: the worktree/branch, what you implemented (one or two lines), the verification result, the CI-checks status (passing / pending / none — or red-after-bounded-attempts when step 7's exit fired), the commit SHA, the PR URL, that it closes #<N>, and that an `@claude` review was requested. The work is done and under review — not waiting on the user.
+Terse summary: the worktree/branch, what you implemented (one or two lines), the verification result, the commit SHA, the PR URL, and that it closes #<N>. The work is done and the PR is open — not waiting on the user.
 
 **Follow-on work named in the deliverables must not silently drop.** If the PR body, commit message, or any doc the diff adds names follow-on work ("own issue", "future work", "not yet wired"), state it in the report as **unfiled** — under work-on-issue-loop, its step 4.5 files these once review converges; standalone, tell the user the issues still need filing.
 
@@ -164,7 +146,5 @@ Terse summary: the worktree/branch, what you implemented (one or two lines), the
 | Tests/build/lint fail locally | Fix or surface it — never commit, push, or claim success on a failing tree |
 | `git status` shows files unrelated to the change | Don't `git add -A` — stage the intended files by name |
 | Writing the PR body | Include `Closes #<N>` (without it the merge doesn't resolve the issue) and end with the repo's footer convention — **Created** verb, no `Co-authored-by` |
-| `gh pr checks` output is empty right after the PR opens | Not the same as "no CI" — check for workflows and re-poll before classifying |
-| CI checks failing after the PR opens | Fix and push before triggering review; if still red after a few rounds, stop and report the true state — never claim success on a red PR |
-| Bundling `@claude review` into the PR body or first comment | Keep it a separate one-line comment so the bot fires reliably |
-| Tempted to pause and ask the user mid-flow | Don't — implement, verify, commit, push, open the PR, request review, then report |
+| Tempted to trigger an `@claude` review or wait on CI after opening the PR | Don't — the skill ends with the open PR; review requests are the caller's job |
+| Tempted to pause and ask the user mid-flow | Don't — implement, verify, commit, push, open the PR, then report |

package/skills/work-on-issue-loop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: work-on-issue-loop
-description: Use when the user asks to implement a GitHub issue and drive it through review to completion autonomously — "work on issue and loop until approved", "work-on-issue-loop", or as the automatic follow-on from validate-issue-loop. Runs work-on-issue to implement and open the PR (which already triggers the first @claude review), then waits for each review to land and calls fix-pr-review to resolve it. Stops on a bare LGTM with nothing left to fix; once past 5 review cycles it stops at the first LGTM it sees even if non-blocking findings remain, rather than continuing to chase them.
+description: Use when the user asks to implement a GitHub issue and drive it through review to completion autonomously — "work on issue and loop until approved", "work-on-issue-loop", or as the automatic follow-on from validate-issue-loop. Runs work-on-issue to implement and open the PR, triggers the first @claude review itself, then waits for each review to land and calls fix-pr-review to resolve it. Stops on a bare LGTM with nothing left to fix; once past 5 review cycles it stops at the first LGTM it sees even if non-blocking findings remain, rather than continuing to chase them.
 ---
 
 # work-on-issue-loop
@@ -14,15 +14,22 @@ Drive an issue from "validated" to "PR reviewed to convergence" without stopping
 
 ## Steps
 
-### 1. Implement and open the PR
+### 1. Implement, open the PR, and trigger the first review
 
-Invoke the `work-on-issue` skill for the issue (Skill tool, `skill: work-on-issue`). It implements the fix in an isolated worktree, verifies it, commits, pushes, opens the PR (`Closes #<N>`), and triggers the first `@claude review`.
+Invoke the `work-on-issue` skill for the issue (Skill tool, `skill: work-on-issue`). It implements the fix in an isolated worktree, verifies it, commits, pushes, and opens the PR (`Closes #<N>`) — it does **not** request review; that's this loop's job.
 
-**Gate on its outcome before looping — work-on-issue can legitimately stop early:**
+**Gate on its outcome before continuing — work-on-issue can legitimately stop early:**
 
 - **Stopped with no PR** (issue already closed, an existing PR already addresses it, wrong repo checked out) → there is nothing to drive; stop and relay its report.
-- **PR opened but review never triggered** (its bounded red-CI exit: CI stayed red after several fix rounds) → don't poll for a review that was never requested, and don't blindly retry what it already tried; stop and report per step 5.
-- **PR opened and review triggered** → capture the PR number/URL, the branch, and the timestamp of the trigger comment. Set `review_count = 1` — that review is #1 in flight.
+- **PR opened** → capture the PR number/URL and the branch, then trigger the first review yourself. Don't wait on CI or poll `gh pr checks` — CI runs in parallel and the reviewer surfaces check failures itself. Post a **separate, one-line** comment so the bot fires cleanly (match the repo's trigger phrase if it differs — check recent PR comments; a trigger mention is not authored content — no footer):
+
+```bash
+gh pr comment <PR-number> --body "@claude review"
+```
+
+**Preflight — confirm a review bot exists before waiting on one.** This loop assumes an automated reviewer that answers `@claude review` comments. Before entering the wait, check the repo for one: `gh api repos/{owner}/{repo}/contents/.github/workflows --jq '.[].name'` and look for a workflow that responds to `@claude` (e.g. `claude.yml`), or confirm the Claude GitHub App is installed. If you find none, don't sink 30 minutes into a review that will never come — tell the user the PR is pushed but no review bot is configured, and point them at `templates/claude-review.yml` in this repo (copy it to `.github/workflows/`, add an `ANTHROPIC_API_KEY` secret). Proceed into the wait only if a reviewer is present or the user confirms one is configured elsewhere.
+
+Record the timestamp of the trigger comment and set `review_count = 1` — that review is #1 in flight.
 
 ### 2. Wait for the review to land
 
@@ -57,7 +64,7 @@ Evaluate in this order:
 
 Invoke the `fix-pr-review` skill for the PR (Skill tool, `skill: fix-pr-review`). It re-validates every finding against the code, fixes what's real, implements the judgment calls and optional improvements to the best-solution standard, commits, pushes, posts the disposition comment, and triggers a fresh `@claude` review itself (routed to Sonnet when it addressed only non-blocking items, otherwise to the repo default, per fix-pr-review step 7).
 
-fix-pr-review also tiers its own working model by the PR's LGTM history (its step 1.5): no LGTM yet → inline on the session model, one LGTM → an Opus subagent, two or more → a Sonnet subagent. It counts LGTMs from the PR itself, so don't pass it a count or override its choice — just record which model each cycle reported running on, for the step 5 report.
+fix-pr-review also picks its own working model dynamically (its step 3.5): it always validates the findings inline on the session model, then tiers implementation by the complexity of the most complex surviving fix — open judgment calls and safety-class findings stay inline, any non-trivial fix routes the set to an Opus subagent, and all-mechanical work goes to a Sonnet subagent. It decides from the validated findings itself, so don't override its choice — just record which model each cycle reported running on, for the step 5 report.
 
 Increment `review_count`, record the new trigger timestamp from that comment, and go back to step 2.
 
@@ -82,11 +89,10 @@ Stop the loop and report the terminal state — don't claim blanket success:
 | `review_count > 5` and an `LGTM` (with non-blocking items remaining) ended the loop | **Done, with leftovers.** PR is approved; note the remaining optional/follow-up items that were left unaddressed once the loop passed 5 cycles. |
 | Bot never responded within the wait window | **Escalate.** Report that the PR is implemented and pushed but review never landed; the user should check the `@claude` GitHub Action / bot status. |
 | work-on-issue stopped with no PR (closed issue / existing PR / wrong repo) | **Nothing to drive.** Relay its report; zero review cycles ran. |
-| work-on-issue opened the PR but its red-CI exit fired (review never triggered) | **Escalate.** Report the PR URL and the red CI state; the user decides whether to keep pushing on CI. |
 
 There is no "stuck on `Needs Updates` past the cap" case to report — per step 3, `Needs Updates` never stops the loop by cycle count alone; it keeps calling fix-pr-review until an LGTM appears (or the bot stops responding, the row above).
 
-In every case, give: PR URL, number of review cycles run, final verdict, which model each fix cycle ran on (per fix-pr-review's LGTM tiering), any follow-on issues filed in step 4.5 (URLs) or deliberately left unfiled, and (if escalating) exactly what's left.
+In every case, give: PR URL, number of review cycles run, final verdict, which model each fix cycle ran on (per fix-pr-review's findings-based selection), any follow-on issues filed in step 4.5 (URLs) or deliberately left unfiled, and (if escalating) exactly what's left.
 
 **Cap the report at 55 words, ELI18** — plain language, no jargon, as if explaining the outcome to a smart 18-year-old with no context on this codebase or its internals.
 
@@ -100,7 +106,7 @@ In every case, give: PR URL, number of review cycles run, final verdict, which m
 | Review bot hasn't responded after ~30 minutes | Stop waiting; report that review didn't land rather than polling forever |
 | Tempted to treat "LGTM with Recommended Optional items" as terminal at `review_count <= 5` | It isn't — below the cap, LGTM-with-findings still goes through fix-pr-review; only past the cap does the first LGTM end it regardless of findings |
 | PR gets closed or merged mid-loop (e.g. by the user) | Stop immediately; don't keep pushing fixes to a closed/merged PR |
-| work-on-issue ended without triggering a review | Don't enter the wait loop — gate on its outcome in step 1 and report per step 5 |
+| work-on-issue stopped with no PR | Don't trigger a review or enter the wait loop — gate on its outcome in step 1 and report per step 5 |
 | About to report "Done" while the PR/README names follow-on work with no issue filed | Stop — run step 4.5 first; a named follow-on with no issue and no "deliberately unfiled" note in the report is a silent drop |
 
 ## Common Mistakes