refactor: slim CLAUDE.md, port pr-review-toolkit agents, sync .opencode parity by Aureliolo · Pull Request #1833 · Aureliolo/synthorg

Aureliolo · 2026-05-09T08:23:39Z

Summary

Slim Claude Code's session context baseline. Empty /context was reading 53.5k tokens; this PR brings it to ~37–39k by:

CLAUDE.md: 238 → 107 lines (~12.8k → ~3.5k tokens). 11 MANDATORY paragraphs collapse to one-liners + reference links. The 30-script gate inventory moves to a new docs/reference/convention-gates.md.
Plugin port: 6 agents migrated verbatim from the pr-review-toolkit plugin into .claude/agents/ (descriptions slimmed to project style, bodies preserved). The /pre-pr-review skill drops the pr-review-toolkit: qualifier on 18 subagent_type references; the .opencode/ mirror does the same.
OpenCode parity: 5 MAJOR drift findings from tool-parity-checker fixed in-PR. New .opencode/agents/code-simplifier.md (SynthOrg-tuned standalone) plugs the parity gap.
AGENTS.md: tier listings updated (22 → 26 review agents).

The actual agent slim work (descriptions tightened from 451–731 tokens each to ~120 tokens) was tracked under #1826 and closed as part of this PR.

Files

Edited:

CLAUDE.md (slim)
.claude/skills/pre-pr-review/SKILL.md (qualifier strip)
.opencode/commands/pre-pr-review.md (qualifier strip + code-simplifier mapping)
.opencode/commands/aurelio-review-pr.md (qualifier strip)
AGENTS.md (tier listings)

Created:

docs/reference/convention-gates.md (35 enforcement gates + meta-gate; replaces inline inventory in CLAUDE.md)
.claude/agents/code-reviewer.md, code-simplifier.md, comment-analyzer.md, pr-test-analyzer.md, silent-failure-hunter.md, type-design-analyzer.md (ported)
.opencode/agents/code-simplifier.md (parity)

Test plan

Pre-commit + pre-push hooks pass (em-dashes, gate inventory, secrets, etc.)
scripts/check_convention_gate_inventory.py passes (every MANDATORY one-liner detected via inline-bold regex match against scripts/convention_gate_map.yaml)
Manual /context baseline check in a fresh Claude Code session: confirm drop from ~53.5k to ~37–39k.
End-to-end /pre-pr-review quick against a topic branch: confirm at least the ported code-reviewer agent fires (note: the harness may need a session restart for the new .claude/agents/ to appear in the subagent registry).

Review coverage

Pre-reviewed by 3 agents (docs-consistency, comment-quality-rot, tool-parity-checker). 5 MAJOR findings addressed in-PR; 1 MEDIUM advisory (wrap .opencode/agents/* to @.claude/agents/*) was investigated and rejected as a false positive against the documented standalone-tier architecture in AGENTS.md (the OpenCode prompts are intentionally SynthOrg-tuned with HIGH/MEDIUM/LOW severity vs. the upstream-ported Claude prompts using confidence scoring). Triage table at _audit/pre-pr-review/triage.md (gitignored).

Closes #1826.

github-actions · 2026-05-09T08:23:49Z

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

coderabbitai · 2026-05-09T08:24:39Z

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

This PR adds six new CLAUDE agent prompt/config files and one OPENCODE agent spec, refactors agent routing and adapter mappings to use unprefixed agent identifiers, updates AGENTS.md, condenses CLAUDE.md into mandatory repository rules, introduces docs/reference/convention-gates.md and wires it into pre-commit and the numeric-macro checker, adds a convention_gates runtime stat with fetcher and YAML mapping, and extends unit tests to cover the new stat.

Suggested labels

autorelease: tagged

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 40.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title accurately reflects the main refactoring work: slimming CLAUDE.md, porting agents from pr-review-toolkit, and syncing .opencode parity.
Description check	✅ Passed	The PR description is comprehensive and directly related to the changeset, explaining the context-token reduction strategy and implementation details.
Linked Issues check	✅ Passed	All requirements from `#1826` (slim six agent description fields to project style) are met: agent bodies preserved, descriptions condensed to ~120 tokens, following project style, and verified via /context baseline and /pre-pr-review quick.
Out of Scope Changes check	✅ Passed	All changes are within scope: CLAUDE.md slimming, convention-gates documentation, agent porting/description slimming, qualifier removal, AGENTS.md tier updates, and supporting script/test changes align with stated objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

gemini-code-assist

Code Review

This pull request introduces several new automated review agents for both Claude and OpenCode, updates agent routing in the pre-PR review skill, and significantly refactors CLAUDE.md to be more concise by moving detailed reference material to dedicated documentation files. A new convention-gates.md reference file was also added to document the project's enforcement policy. Feedback was provided regarding the code-simplifier agent definition for Claude, which incorrectly prioritized JavaScript conventions over the project's Python-centric standards, suggesting an update to align it with the Python 3.14 core.

gemini-code-assist · 2026-05-09T08:25:16Z

+description: Refines recently modified code for clarity, consistency, and maintainability while preserving exact functionality. Prefers explicit/readable over compact; never changes behaviour. Applies CLAUDE.md project standards (function over arrow, ES module imports with extensions, explicit return types). Operates on recently touched code unless told otherwise.
+model: opus
+---
+
+You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. Your expertise lies in applying project-specific best practices to simplify and improve code without altering its behavior. You prioritize readable, explicit code over overly compact solutions. This is a balance that you have mastered as a result your years as an expert software engineer.
+
+You will analyze recently modified code and apply refinements that:
+
+1. **Preserve Functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
+
+2. **Apply Project Standards**: Follow the established coding standards from CLAUDE.md including:
+
+   - Use ES modules with proper import sorting and extensions
+   - Prefer `function` keyword over arrow functions
+   - Use explicit return type annotations for top-level functions
+   - Follow proper React component patterns with explicit Props types
+   - Use proper error handling patterns (avoid try/catch when possible)
+   - Maintain consistent naming conventions


The Claude version of the code-simplifier agent appears to be using JS/TS-centric conventions (e.g., "function over arrow", "ES module imports") as its primary examples of project standards. However, the project is primarily Python-centric (Python 3.14+).

In contrast, the OpenCode version (.opencode/agents/code-simplifier.md) is correctly tuned for the project's Python core, referencing model_copy, itertools, and PEP 649. The Claude version should be updated to include these Pythonic standards to ensure it provides relevant suggestions for the backend codebase while still supporting the React dashboard.

Suggested change

description: Refines recently modified code for clarity, consistency, and maintainability while preserving exact functionality. Prefers explicit/readable over compact; never changes behaviour. Applies CLAUDE.md project standards (function over arrow, ES module imports with extensions, explicit return types). Operates on recently touched code unless told otherwise.

model: opus

---

You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. Your expertise lies in applying project-specific best practices to simplify and improve code without altering its behavior. You prioritize readable, explicit code over overly compact solutions. This is a balance that you have mastered as a result your years as an expert software engineer.

You will analyze recently modified code and apply refinements that:

1. **Preserve Functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.

2. **Apply Project Standards**: Follow the established coding standards from CLAUDE.md including:

- Use ES modules with proper import sorting and extensions

- Prefer `function` keyword over arrow functions

- Use explicit return type annotations for top-level functions

- Follow proper React component patterns with explicit Props types

- Use proper error handling patterns (avoid try/catch when possible)

- Maintain consistent naming conventions

description: Refines recently modified code for clarity, consistency, and maintainability while preserving exact functionality. Prefers explicit/readable over compact; never changes behaviour. Applies CLAUDE.md project standards (no __future__ annotations, explicit return types, function over arrow). Operates on recently touched code unless told otherwise.

model: opus

---

You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. Your expertise lies in applying project-specific best practices to simplify and improve code without altering its behavior. You prioritize readable, explicit code over overly compact solutions. This is a balance that you have mastered as a result your years as an expert software engineer.

You will analyze recently modified code and apply refinements that:

1. **Preserve Functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.

2. **Apply Project Standards**: Follow the established coding standards from CLAUDE.md including:

- No `from __future__ import annotations` (Python 3.14+ uses PEP 649)

- Use explicit return type annotations for all public functions

- Prefer `function` keyword over arrow functions in React components

- Use `model_copy(update={...})` for Pydantic model updates

- Maintain consistent naming conventions (British English)

- Use proper error handling patterns (avoid broad try/except or try/catch)

- Use ES modules with proper import sorting and extensions (web only)

coderabbitai

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.claude/agents/code-reviewer.md:
- Around line 29-43: The confidence-band ranges conflict with the reporting
threshold and overlap; update the rubric lines (the "**76-90**" and "**91-100**"
entries and the "Only report issues with confidence ≥ 80" rule) so ranges are
mutually exclusive and align with the threshold — e.g., change the Important
band to "**80-89**" and the Critical band to "**90-100**", remove or repurpose
the "**76-90**"/"**76-79**" text so no scores below 80 are listed as reportable,
and ensure the "Only report issues with confidence ≥ 80" statement matches these
new bands.

In @.claude/agents/code-simplifier.md:
- Around line 13-20: The checklist item "2. **Apply Project Standards**"
currently lists frontend-specific rules (e.g., "Use ES modules with proper
import sorting and extensions", "Prefer `function` keyword over arrow
functions", "Follow proper React component patterns with explicit Props types")
as global standards; update the section in .claude/agents/code-simplifier.md so
these bullets are explicitly scoped to frontend files only (add a qualifying
sentence like "Apply the following frontend-specific standards only to
JavaScript/TypeScript/React frontend files" and leave backend/Python/Go rules
unaffected), and ensure the bullets remain unchanged except for the added scope
note so reviewers working on non-frontend languages are not misdirected.

In @.claude/agents/type-design-analyzer.md:
- Around line 52-79: The fenced example block starting at the "## Type:
[TypeName]" section uses an untyped triple-backtick code fence; update that
fence to include a language tag (e.g., change ``` to ```text) so markdownlint
passes and rendering is consistent across viewers—ensure the opening fence above
the Invariants/Ratings block is modified (leave the closing ``` unchanged).

In @.opencode/agents/code-simplifier.md:
- Around line 23-31: The markdown has lint violations: add a blank line before
each subsection heading (e.g., before "### 1. Unnecessary complexity (HIGH)" and
"### 2. Dead and redundant code (HIGH)" and any similar third-level headings
later in the file) so headings follow markdownlint spacing rules, and update the
fenced example block to include a language tag (e.g., change the fence to
```text) and ensure there is a blank line before and after the fenced block;
locate the fenced block and headings by their exact text in the diff and apply
these spacing and fence-tag fixes consistently (also apply the same changes to
the other occurrences referenced in the comment).

In `@CLAUDE.md`:
- Around line 29-35: Update the quick-command examples that call pytest so they
consistently include the mandatory xdist distribution flag; add
"--dist=loadfile" to each shown command variant (e.g. the commands beginning
with "uv run python -m pytest tests/ -m unit -n 8", "uv run python -m pytest
tests/ -m integration -n 8", "uv run python -m pytest tests/ -m e2e -n 8", the
coverage command with "--cov=synthorg", the benchmarks command, and the
HYPOTHESIS_PROFILE examples) so the docs match the requirement stated elsewhere
and prevent users from copying commands that omit --dist=loadfile.

In `@docs/reference/convention-gates.md`:
- Line 49: Replace the hardcoded numeric claim "(35 enforcement gates plus the
meta-gate below = 36 total `check_*.py` scripts.)" in
docs/reference/convention-gates.md with a runtime-stats marker; use the
appropriate key from data/runtime_stats.yaml (e.g. add or use a key like
CONVENTION_GATES) and insert the marker <!--RS:CONVENTION_GATES--> where the
number currently appears so the docs pull the total at build/runtime instead of
hardcoding it.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: b8d5844d-566f-4c60-8747-c70465fd6e41

📥 Commits

Reviewing files that changed from the base of the PR and between d1faf86 and 23c6108.

📒 Files selected for processing (13)

.claude/agents/code-reviewer.md
.claude/agents/code-simplifier.md
.claude/agents/comment-analyzer.md
.claude/agents/pr-test-analyzer.md
.claude/agents/silent-failure-hunter.md
.claude/agents/type-design-analyzer.md
.claude/skills/pre-pr-review/SKILL.md
.opencode/agents/code-simplifier.md
.opencode/commands/aurelio-review-pr.md
.opencode/commands/pre-pr-review.md
AGENTS.md
CLAUDE.md
docs/reference/convention-gates.md

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

GitHub Check: Build Web Assets (melange)
GitHub Check: Lighthouse Site
GitHub Check: Analyze (python)

🧰 Additional context used

📓 Path-based instructions (4)

.opencode/commands/**/*

📄 CodeRabbit inference engine (AGENTS.md)

PowerShell translation of bash commands happens in OpenCode adapters (.opencode/commands/), not in shared skill content

Files:

.opencode/commands/aurelio-review-pr.md
.opencode/commands/pre-pr-review.md

{README.md,docs/**/*.md}

📄 CodeRabbit inference engine (CLAUDE.md)

Numeric claims in README and public docs must be sourced from data/runtime_stats.yaml via  markers

Files:

docs/reference/convention-gates.md

**/*.{d2,md}

📄 CodeRabbit inference engine (CLAUDE.md)

Use d2 for architecture/nested container diagrams; use mermaid for flowcharts/sequence/pipelines; use Markdown tables for tabular data. D2 theme 200 (Dark Mauve), CI pinned to v0.7.1

Files:

docs/reference/convention-gates.md
AGENTS.md
CLAUDE.md

.claude/skills/**/*

📄 CodeRabbit inference engine (AGENTS.md)

Shared skills in .claude/skills/ should remain shell-neutral or bash-based; use POSIX/bash-compatible commands (ls -la, grep, pipes)

Git commands in shared skills work the same in both shells and do not require translation

Files:

.claude/skills/pre-pr-review/SKILL.md

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:23:56.593Z
Learning: All project conventions, commands, and standards are defined in CLAUDE.md - reference it for project structure, package layout, code conventions, quick commands, Git workflow, testing standards, design specs, logging, resilience, security patterns, convention rollout enforcement, and telemetry

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:23:56.593Z
Learning: Memory directory structure should include MEMORY.md (index), research-log.md (one-liner entries), research/ subdirectory (detailed write-ups), and individual memory files with prefixes (user_*.md, feedback_*.md, project_*.md, reference_*.md)

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: Read `docs/design/` page before implementing; deviations need approval per DESIGN_SPEC.md

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: Present every plan for accept/deny before coding

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: No region/currency/locale should be privileged; use metric units and British English

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: Every convention PR must ship its enforcement gate

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: Test timeout/slow failures indicate source-code regression; never edit `tests/baselines/unit_timing.json`

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: After issue resolution: branch + commit + push (no auto-PR); use `/pre-pr-review` command; after PR merge use `/post-merge-cleanup`; after PR creation use `/aurelio-review-pr` for external feedback. Fix everything valid; never defer.

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: Always run tests with `pytest-xdist -n 8 --dist=loadfile` (loadfile prevents 3.14+Windows ProactorEventLoop leak)

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: Git commits: `<type>: <description>` format (feat/fix/refactor/docs/test/chore/perf/ci); commitizen-enforced. Branches: `<type>/<slug>` from main

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: Signed commits required on protected refs (GPG/SSH or GitHub App via `synthorg-repo-bot`)

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: Pre-commit/pre-push hooks configured via `.pre-commit-config.yaml`; hookify rules in `.claude/hookify.*.md`

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: Squash merge on PRs; PR body becomes squash commit; trailers (`Release-As`, `Closes `#N``) must be in PR body

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: GitHub queries: use `gh issue list` via Bash, NOT MCP `list_issues`

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: CLI is Docker-only (init/start/stop/status); features go in dashboard + REST API. See `cli/CLAUDE.md` (use `go -C cli`, never `cd cli`)

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-05-09T08:24:39.425Z
Learning: Web code: see `web/CLAUDE.md` for React 19 + design system details; use Go binary for CLI

🪛 LanguageTool

.claude/agents/silent-failure-hunter.md

[style] ~61-~61: This phrase is redundant. Consider using “outside”.
Context: ...to a mock, stub, or fake implementation outside of test code? Error Propagation: - Sh...

(OUTSIDE_OF)

[style] ~74-~74: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...oes it provide actionable next steps? - Does it avoid jargon unless the user is a de...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

[grammar] ~113-~113: Use a hyphen to join words.
Context: ...keptical, and uncompromising about error handling quality. You: - Call out every ...

(QB_NEW_EN_HYPHEN)

.claude/agents/code-simplifier.md

[style] ~35-~35: To elevate your writing, try using a synonym here.
Context: ...Create overly clever solutions that are hard to understand - Combine too many con...

(HARD_TO)

.claude/agents/pr-test-analyzer.md

[style] ~29-~29: ‘absolutely essential’ might be wordy. Consider a shorter alternative.
Context: ... - Rate criticality from 1-10 (10 being absolutely essential) - Explain the specific regression o...

(EN_WORDINESS_PREMIUM_ABSOLUTELY_ESSENTIAL)

CLAUDE.md

[grammar] ~89-~89: Ensure spelling is correct
Context: ...d @example(...)). - Flaky: NEVER skip/xfail; fix fundamentally. Use `asyncio.Event()...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.22.1)

.claude/agents/type-design-analyzer.md

[warning] 52-52: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

.opencode/agents/code-simplifier.md

[warning] 23-23: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below