feat: add prepare-pr / address-pr-review skills and relocate hooks - #269
Merged
Conversation
Bundle the /prepare-pr skill: workflow doc, extract_signals.py helper (trunk resolution, WIP preflight, phase-2 base, signal detection, ARCHITECTURE.md staleness check), and a per-repo .claude/prepare-pr.toml that keeps the script portable across repos.
State-aware Copilot server-side PR review handler: detects review state, triggers Copilot, polls, resolves threads, and drives to a clean state. pr_review.py exposes state/trigger/wait/resolve subcommands so /prepare-pr Phase 4.5 can orchestrate iterations without ad-hoc gh api mutations.
review_brief.py: switch shebang to 'uv run --frozen python'; look up CLAUDE.md at .claude/CLAUDE.md before the root fallback; replace the Path.rglob-based file probe with a pruned walker that skips SKIP_DIRS (vendored trees like .venv/node_modules) up-front instead of filtering matches after the fact. SKILL.md: unwrap long paragraphs; use 'uv run --frozen python' in the example commands. REVIEW-BRIEF.md: describe the gremlins hook's actual policy - relaxed in markup (.md/.html/.htm allows EM DASH, NBSP, ellipsis, middle dot), ASCII elsewhere - and reference the new hooks/gremlins.py path.
Relocate the three custom pre-commit hook scripts (align_tables, gremlins, validate_docs_words) from src/hooks/ to hooks/, and upgrade two of them: - gremlins: give markup files (.md/.html/.htm) a relaxed pass that allows EM DASH, NBSP, HORIZONTAL ELLIPSIS, and MIDDLE DOT, while still auto-fixing smart quotes and most invisibles; report unfixable bidi controls as errors. - align_tables: preserve '|' inside Obsidian wikilinks ([[a|b]]) and escaped '\|' when splitting table rows, so display-text wikilinks in cells are no longer chopped in half. Retarget the prek entries (python3 -m src.hooks.X -> python3 -m hooks.X) and rescope ruff to ^hooks/ so the scripts stay under linter coverage (they would have dropped out of the old ^(src|tests)/ scope).
There was a problem hiding this comment.
Pull request overview
This PR adds two new Claude Code skills (/prepare-pr, /address-pr-review) to standardize branch consolidation and PR-review handling, while relocating and enhancing the repo’s custom pre-commit hooks (notably gremlins and align_tables) and updating related tooling/docs to match the new layout and policies.
Changes:
- Introduce
/prepare-pr(withextract_signals.py+.claude/prepare-pr.toml) and/address-pr-review(withpr_review.py) for repeatable PR prep + review-state automation. - Move custom hooks from
src/hooks/tohooks/, expandinggremlins(relaxed policy for markup + bidi detection) and improvingalign_tables(wikilink + escaped pipe handling). - Update pre-commit/ruff configuration, Makefile
PREK_RUNstaging strategy, CI uv setup, and repo docs to reflect the new conventions and hook behavior.
Reviewed changes
Copilot reviewed 20 out of 22 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
uv.lock |
Bumps prek lock entries to the new resolved version. |
src/hooks/gremlins.py |
Removes old hook implementation from the previous location. |
src/hooks/align_tables.py |
Removes old table-align hook from the previous location. |
Makefile |
Changes PREK_RUN to use a scratch index via GIT_INDEX_FILE and updates prek invocation. |
hooks/validate_docs_words.py |
Updates project-root resolution after hook relocation. |
hooks/gremlins.py |
New enhanced gremlins hook (auto-fix + relaxed markup rules + bidi reporting). |
hooks/align_tables.py |
New enhanced table aligner (separator detection, indent preservation, wikilink/escaped pipe safety). |
design/lessons.md |
Adds new operational lessons for directory moves and hook-policy/doc sync. |
ARCHITECTURE.md |
Updates repo layout, hook inventory, skills catalog, and adds module versioning guidance + section ID contract. |
AGENTS.md |
Adds/upgrades contributor guidance around module versioning and gremlins policy. |
.pre-commit-config.yaml |
Repoints custom hooks to hooks.*, updates ruff rev, and scopes ruff to ^hooks/. |
.markdownlint.yml |
Disables MD013 line-length rule. |
.gitignore |
Ignores local editor/agent configuration artifacts. |
.github/workflows/repo_checks.yml |
Stops pinning setup-uv’s uv version; otherwise keeps workflow structure. |
.claude/skills/second-opinion/SKILL.md |
Updates docs/commands to use uv run --frozen python and other clarifications. |
.claude/skills/second-opinion/scripts/review_brief.py |
Prunes repo discovery traversal and adjusts CLAUDE.md lookup + check exit semantics. |
.claude/skills/second-opinion/REVIEW-BRIEF.md |
Updates gremlins policy notes to match the new hook behavior. |
.claude/skills/prepare-pr/SKILL.md |
Adds the new prepare-pr skill definition and full workflow. |
.claude/skills/prepare-pr/scripts/extract_signals.py |
Adds helper CLI supporting prepare-pr (trunk sync, base resolution, signals, architecture staleness, etc.). |
.claude/skills/address-pr-review/SKILL.md |
Adds the new address-pr-review skill definition and workflow. |
.claude/skills/address-pr-review/scripts/pr_review.py |
Adds the PR review state machine + trigger/wait/resolve tooling via gh + GraphQL. |
.claude/prepare-pr.toml |
Adds per-repo configuration for prepare-pr portability (architecture section mapping + paths). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Rework the Makefile PREK_RUN macro to stage into a throwaway GIT_INDEX_FILE (<git-dir>/index.prek) instead of backing up and restoring the real index. prek now runs over the whole working tree without ever mutating the user's staging state; auto-fixes still land in the working tree for review. Drops the now-unneeded --extra devel.
Turn off MD013 entirely (was 120 with code-block/table exemptions). Prose line length is no longer gated; long paragraphs and links no longer need manual wrapping.
Add settings.local.json, /.claude/settings.json, /.claude/rules/openwolf.md, /.wolf, and /CLAUDE.md to .gitignore - per-developer local config that should not be tracked.
Bump ruff-pre-commit to v0.15.21, refresh uv.lock (prek and transitive deps), and drop the pinned version input on astral-sh/setup-uv@v7 in CI so the uv CLI floats to the action default.
AGENTS.md + ARCHITECTURE.md: add the per-module versioning contract (each modules/<name>/ bumps its own ModuleVersion in a module-only commit, <prefix>: <name> vX.Y.Z), plus the section-name contract the /prepare-pr staleness checker keys off. Refresh the hook, skills, and tooling sections for the hooks/ move, ^hooks/ ruff scope, disabled MD013, the PREK_RUN scratch-index staging, and the bundled skill scripts. design/lessons.md: add L-002 (audit string references when relocating a directory) and L-003 (sync human-facing docs when a hook's policy changes).
Comment on lines
167
to
+169
| `mkdocs-build` (`mkdocs build --strict`), `ruff-check`, `ruff-format` (both scoped to | ||
| `src/`+`tests/`), `check-executables-have-shebangs`, `check-shebang-scripts-are-executable`, | ||
| `end-of-file-fixer`, `mixed-line-ending`, `trailing-whitespace`, `markdownlint-cli2` (all | ||
| `.md`), and `cspell` (docs + commit messages). | ||
| `^hooks/` - the only Python source dir left in-tree), `check-executables-have-shebangs`, | ||
| `check-shebang-scripts-are-executable`, `end-of-file-fixer`, `mixed-line-ending`, |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/prepare-prskill: end-of-branch consolidation (survey → optional second-opinion review → learnings extraction → ARCHITECTURE staleness check → soft-reset + per-prefix recommit → lint → push → PR → optional PR-review address), bundledextract_signals.pyhelper, and a per-repo.claude/prepare-pr.tomlthat keeps the script portable./address-pr-reviewskill: state-aware Copilot server-side PR-review handler (pr_review.pywith state/trigger/wait/resolve subcommands).second-opinion:uv run --frozen pythonshebang/commands,.claude/CLAUDE.mdlookup, a pruned discovery walker that skips vendored trees, and aREVIEW-BRIEF.mdthat matches the gremlins hook's actual (relaxed-in-markup) policy.src/hooks/to top-levelhooks/, and enrich two:gremlinsnow gives markup files a relaxed pass (EM DASH / NBSP / ellipsis / middle dot) while flagging bidi controls;align_tablespreserves|inside wikilinks and escaped\|. Ruff rescoped to^hooks/so the moved scripts stay linted.PREK_RUNto stage into a disposable scratch index (never touches the user's real staging); disable markdownlint MD013; ignore local editor/wolf/settings artifacts; bump ruff to v0.15.21, refreshuv.lock, and float thesetup-uvversion in CI.<prefix>: <name> vX.Y.Z, module-only commits) inAGENTS.md+ARCHITECTURE.md, add the section-name contract the staleness checker keys off, and record two operational lessons (L-002 directory-move reference audit, L-003 hook-policy doc sync).Test plan
make lint-diff- all pre-commit hooks green/second-opinion(gpt-5.3-codex) - 3 findings, all fixed and verified clean on rerunmake lintstill runs the custom hooks from their newhooks/location on a fresh clonealign_tablesagainst a markdown table containing a[[a|b]]wikilinkhooks/*.py(edit one to introduce a lint error, runmake lint HOOK=ruff-check)🤖 Generated with Claude Code