Skip to content

feat(#232): adopter handbooks consumed by Rex during code review#233

Merged
atlas-apex merged 3 commits into
devfrom
feature/GH-232-adopter-handbooks
May 14, 2026
Merged

feat(#232): adopter handbooks consumed by Rex during code review#233
atlas-apex merged 3 commits into
devfrom
feature/GH-232-adopter-handbooks

Conversation

@atlas-apex

@atlas-apex atlas-apex commented May 14, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • New handbooks/ directory at the ops fork root for adopter-authored coding standards consumed by Rex during PR review, layered on top of the framework's generic rules in .claude/rules/
  • Discovery by path-convention (no YAML frontmatter): handbooks/architecture/*.md + handbooks/general/*.md always-load; handbooks/language/<lang>/*.md loads only when the PR diff includes files matching <lang>'s extensions
  • Enforcement defaults to advisory; opt in to blocking with the literal phrase ENFORCEMENT: blocking at the top of a handbook file
  • Four sample handbooks shipped, demonstrating each shape (always-load advisory architectural / always-load blocking architectural / diff-matched advisory language / always-load advisory cross-cutting)
  • Rex agent definition (.claude/agents/code-reviewer.md) gains § 8 "Adopter Handbooks" with discovery rules, advisory/blocking convention, what-to-surface, and a ### Handbook Findings section in the review output template
  • CLAUDE.md Quick Reference and framework integration table updated to surface handbooks/ next to .claude/rules/

Why this matters

Before this PR, adopter coding standards lived in three places: ad-hoc Slack messages, wiki pages nobody re-reads, and inline PR comments that disappear with the PR. Rex enforced framework-wide rules but had no way to know about your team's patterns ("never use floats for currency", "all DB queries go through the repository layer", "Tailwind utility class order is alphabetised").

This PR closes that gap. Adopters drop a markdown file under handbooks/, Rex picks it up automatically on the next review, and the standard becomes enforced in CI rather than enforced by tribal memory. No code change needed to teach Rex a new rule — adopter authors a handbook, commits, done.

The four shapes (architecture/always-load, architecture/blocking, language/diff-matched, general/always-load) are the four shapes that cover most company coding standards. Per AgDR-0020, the design intentionally trades flexibility (no per-project layering, no YAML frontmatter, no per-feature scaffold) for adopter ergonomics — a one-file-and-done shape that authors can write without learning a schema.

Testing

  • Directory structure created and 4 sample handbooks rendered with realistic content (DDD layering, migration safety with blocking marker, TS strict mode, commit-message quality)
  • Rex agent doc updated with § 8 "Adopter Handbooks" — discovery, advisory/blocking, what-to-surface, output template, new Rules entry feat(#101): /handover auto-append + /idea polish (audit-flagged gaps) #9
  • Section ordering in Rex agent doc verified: 1, 2, 3, 4, 5, 6, 7 (AgDR), 8 (Handbooks), then Process / Output Format / Rules
  • CLAUDE.md updated in two places (framework integration table + Quick Reference) to surface handbooks/
  • AgDR-0020 captures all five locked-in design decisions with options-considered tables
  • Reviewer can spot-check the discovery shape in .claude/agents/code-reviewer.md § 8 — verify the path globs match the conventions described in handbooks/README.md
  • Reviewer can confirm the blocking marker pattern (ENFORCEMENT: blocking at the top of handbooks/architecture/migration-safety.md) is the literal phrase Rex's prompt instructs him to look for
  • Manual smoke test post-merge: open a real PR touching a **/*.ts file in any registered project, confirm Rex's review comment cites both framework rules AND the typescript-strict-mode handbook; open another PR touching only **/*.py files (no Python handbooks shipped yet), confirm Rex skips the typescript handbook

Glossary

Term Definition
Handbook A flat markdown file under handbooks/ containing an adopter-authored coding standard. Consumed by Rex (the code-reviewer agent) during PR review alongside the framework's generic rules in .claude/rules/.
Path-convention discovery Rex finds handbooks by globbing well-known paths — no YAML frontmatter, no applies_to: glob to maintain. The directory IS the targeting metadata. architecture/ and general/ always-load; language/<lang>/ loads on diff match.
ENFORCEMENT: blocking marker Literal phrase placed at the top of a handbook file (typically the first line) that opts the handbook in to blocking enforcement. When Rex finds a violation of a blocking handbook, his verdict becomes REQUEST CHANGES and the merge gate (Rex marker absent) blocks the PR. Default is advisory.
Advisory handbook Default enforcement mode. Rex surfaces violations as nit: / suggestion: comments. Verdict unaffected — APPROVED / COMMENT still valid.
Blocking handbook Opt-in enforcement mode. Surface format ⛔ Handbook (blocking):. Verdict becomes REQUEST CHANGES.
Handbook Findings section New ### Handbook Findings section in Rex's review output, between ### Issues Found and ### Suggestions. Groups violations by handbook, severity (blocking first), then file:line. Omitted when no handbooks loaded.
Diff-matched language handbook A handbook under handbooks/language/<lang>/ that Rex loads only when the PR diff includes files of <lang>'s extensions. Keeps Rex's per-PR token cost bounded — Python-only PRs don't pay the TS handbook cost.
Sample handbooks The four handbooks shipped with the framework demonstrating each shape: clean-architecture-layers (advisory architectural), migration-safety (blocking architectural), strict-mode (advisory language), commit-message-quality (advisory cross-cutting). Adopters can keep, edit, or replace them freely.

🤖 Generated with Claude Code

@me2resh @claude
feat(#232): adopter handbooks consumed by Rex during code review
0ea3bdf 
Introduces a `handbooks/` directory at the ops fork root for
adopter-authored coding standards that Rex consults during PR review,
layered on top of the framework's generic rules in `.claude/rules/`.
Discovery is by path-convention (no YAML frontmatter); enforcement
defaults to advisory with explicit blocking opt-in via the literal
`ENFORCEMENT: blocking` marker phrase at the top of a file.

Components:

- handbooks/README.md — index + discovery rules + advisory/blocking
  convention + authoring guidance + the four sample-handbook table
- handbooks/architecture/clean-architecture-layers.md — DDD layering
  (advisory, always-load)
- handbooks/architecture/migration-safety.md — schema-migration
  backwards-compat rule (BLOCKING, always-load) — demonstrates the
  enforcement opt-in shape
- handbooks/language/typescript/strict-mode.md — TS strict-mode + no
  bare `any` (advisory, loads on **/*.{ts,tsx} diff match)
- handbooks/general/commit-message-quality.md — commit-message WHY-
  not-WHAT discipline (advisory, always-load)
- .claude/agents/code-reviewer.md — new § 8 "Adopter Handbooks":
  discovery (path-convention), enforcement (advisory vs blocking
  marker), what-to-surface, Handbook Findings section in the review
  output template, new Rules entry #9 codifying the layer
- CLAUDE.md — Quick Reference + framework integration table updated
  to surface handbooks/ alongside .claude/rules/

Decision rationale: docs/agdr/AgDR-0020-adopter-handbooks-for-rex.md
captures all five load-bearing decisions (scope, discovery,
format, sample-scaffold-per-feature, enforcement default) with
options-considered tables.

Closes #232

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
atlas-apex
atlas-apex commented May 14, 2026
View reviewed changes

@atlas-apex atlas-apex left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review: PR #233

Commit: 0ea3bdfb308a6a7d2c651dc767485f66791edac1

Summary

Introduces a handbooks/ layer at the ops fork root for adopter-authored coding standards consumed by Rex (the code-reviewer agent), layered on top of the framework's generic .claude/rules/. Discovery is by path-convention (no YAML frontmatter); enforcement defaults to advisory, with explicit opt-in to blocking via the literal phrase ENFORCEMENT: blocking at the top of a handbook file. Ships 4 sample handbooks demonstrating each shape, updates Rex's agent definition with a new § 8, and updates CLAUDE.md in two places.

Checklist Results

  • Architecture & Design: Pass
  • Code Quality: Pass
  • Testing: Pass (docs-only PR; testing is the author's "Reviewer can spot-check…" steps in the PR body)
  • Security: Pass (no executable code paths introduced)
  • Performance: Pass (Rex's per-PR token cost is bounded by diff-match for language/<lang>/)
  • PR Description & Glossary: Pass
  • Technical Decisions (AgDR): Pass — AgDR-0020 linked, covers all 5 load-bearing decisions
  • Adopter Handbooks: N/A (this PR introduces the layer; doesn't apply retroactively)

Verification of asks

  1. AgDR-0020 quality: Pass. All five decisions (A scope, B discovery, C format, D sample-scaffold, E enforcement) are present with ## Options Considered tables and 3 options each. Chosen option called out with bold + rationale paragraph. Consequences section honestly discusses v1 trade-offs (no per-project layering, no /handbook skill, magic-string marker risk, Rex's prompt growth bound).

  2. Path-convention consistency across three sources: Pass. All three describe the same convention — handbooks/architecture/*.md always-load, handbooks/general/*.md always-load, handbooks/language/<lang>/*.md diff-matched by extension. Wording and examples align.

  3. Blocking marker spec consistency: Pass. handbooks/README.md § "Enforcement" specifies ENFORCEMENT: blocking at the top of the file. Rex agent doc § 8 cites the same literal phrase. The blocking sample (handbooks/architecture/migration-safety.md) has ENFORCEMENT: blocking as its actual first line (verified).

  4. Sample handbooks are real, not boilerplate: Pass. Each of the 4 has a concrete "What Rex flags" trigger list (e.g. migration-safety enumerates DROP COLUMN, RENAME COLUMN, narrowing ALTER COLUMN, etc.; strict-mode lists any without justification, @ts-ignore, unsafe as narrowing) AND a "What's NOT a violation" false-positive guard (e.g. type-only cross-layer imports, unknown, additive migrations, revert commits). No platitudes — each entry is actionable in code review.

  5. Rex agent doc structural integrity: Pass. Section ordering verified — ### 1. through ### 7. Technical Decisions (AgDR) then ### 8. Adopter Handbooks. Output Format ordering: ### Issues Found (line 322) → ### Handbook Findings (line 325) → ### Suggestions (line 328) → ### Verdict (line 331). New Rules entry #9 sits after #8 and adds a non-conflicting handbook-layer rule.

  6. CLAUDE.md updated in two places: Pass. Framework integration table at line 188 (peer to Rules row) and Quick Reference at line 271 (peer to Rules (modular, framework-wide)). Both surface handbooks/ as a peer to .claude/rules/.

  7. PR body has Summary, Testing, Glossary: Pass. All three present. Glossary covers handbook, path-convention discovery, ENFORCEMENT: blocking marker, advisory/blocking handbooks, Handbook Findings section, diff-matched language handbook, sample handbooks — 8 entries covering the new vocabulary.

  8. Commit message: Pass. feat(#232): adopter handbooks consumed by Rex during code review matches type(#NN): description. Body explains components and decision artefact. Closes #232 present. Co-Authored-By line present.

Issues Found

None.

Suggestions (non-blocking)

  • handbooks/README.md § "If you need a fourth bucket…" tells adopters to update Rex's discovery logic in the agent file. Since the agent doc § 8 already specifies the unknown-directory fallback ("Default to always-load if you don't recognise the directory; flag in your review that the directory convention is undocumented"), the README sentence under-promises the framework's actual behaviour. Tightening this in a follow-up would let adopters add new buckets without touching agent prose.
  • The CLAUDE.md Rules row was updated to "10 modular rule files" listing "plan mode" as a new entry, but no plan-mode rule file appears in this PR's diff. If this is leftover from a sibling PR, leave it; if accidentally introduced here, it's the only meta-inconsistency I noticed.
  • Consider mentioning in handbooks/README.md that the <other> directory unknown-bucket fallback is documented in the agent file, so adopters know the framework won't silently drop their new directory.

Verdict

APPROVED

The handbooks layer is well-scoped, consistently specified across all three sources, and the four sample handbooks are substantive enough to ship as defaults without embarrassment. The advisory-first / blocking-opt-in default is the right call for adopter onboarding. AgDR-0020 captures the design rationale honestly, including the v1 trade-offs.

I cannot self-approve via --approve (own PR), so this comes through as a --comment review with the APPROVED verdict explicit above. Per the agent spec, I will write the Rex approval marker for the merge gate.

Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: 0ea3bdfb308a6a7d2c651dc767485f66791edac1

me2resh and others added 2 commits May 14, 2026 10:43
@me2resh @claude
fix(#232): correct rule-file count in CLAUDE.md (10 → 11)
cc85e4e 
Rex flagged the count mismatch in his review of #233. There are
actually 11 rule files in .claude/rules/ (the previous list also
omitted leak-protection). One-line fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@me2resh @claude
fix(#232): markdownlint MD028/MD032 in handbook samples
0005960 
Three handbook samples tripped markdownlint:
- migration-safety.md: list-inside-blockquote needs a blank `>` line
  before the list (MD032)
- commit-message-quality.md: two adjacent blockquotes joined with `>`
  instead of a blank line (MD028)
- strict-mode.md: same fix for three adjacent sample-finding blockquotes
  (MD028 x2)

Pure formatting fix. No content change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
atlas-apex
atlas-apex commented May 14, 2026
View reviewed changes

@atlas-apex atlas-apex left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review: PR #233 (follow-up commits)

Commit: 0005960aa789dcb0aec01cb36590a6dfaf1536de

Verification

  • cc85e4e — CLAUDE.md rule count corrected from 10 → 11; alphabetised list now includes leak protection. Addresses my prior non-blocking suggestion. One-line content fix, no scope creep.
  • 0005960 — Pure formatting fix (MD028/MD032) across 3 handbook samples: blank > line inserted between adjacent blockquotes / before list-in-blockquote. Zero content change verified.

CI

All three checks SUCCESS at HEAD: markdownlint-cli2, lychee, Verify Ticket ID.

Verdict

APPROVED — original verdict still applies. None of the load-bearing decisions (handbook scope, discovery, format, samples, enforcement) changed. Approval marker refreshed for new HEAD.

Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: 0005960aa789dcb0aec01cb36590a6dfaf1536de

@atlas-apex atlas-apex merged commit c498fbd into dev May 14, 2026
3 checks passed
@atlas-apex atlas-apex deleted the feature/GH-232-adopter-handbooks branch May 14, 2026 11:53
me2resh added a commit that referenced this pull request Jun 5, 2026
@atlas-apex @me2resh @claude
feat(#232): adopter handbooks consumed by Rex during code review (#233)
5de6c95 
* feat(#232): adopter handbooks consumed by Rex during code review

Introduces a `handbooks/` directory at the ops fork root for
adopter-authored coding standards that Rex consults during PR review,
layered on top of the framework's generic rules in `.claude/rules/`.
Discovery is by path-convention (no YAML frontmatter); enforcement
defaults to advisory with explicit blocking opt-in via the literal
`ENFORCEMENT: blocking` marker phrase at the top of a file.

Components:

- handbooks/README.md — index + discovery rules + advisory/blocking
  convention + authoring guidance + the four sample-handbook table
- handbooks/architecture/clean-architecture-layers.md — DDD layering
  (advisory, always-load)
- handbooks/architecture/migration-safety.md — schema-migration
  backwards-compat rule (BLOCKING, always-load) — demonstrates the
  enforcement opt-in shape
- handbooks/language/typescript/strict-mode.md — TS strict-mode + no
  bare `any` (advisory, loads on **/*.{ts,tsx} diff match)
- handbooks/general/commit-message-quality.md — commit-message WHY-
  not-WHAT discipline (advisory, always-load)
- .claude/agents/code-reviewer.md — new § 8 "Adopter Handbooks":
  discovery (path-convention), enforcement (advisory vs blocking
  marker), what-to-surface, Handbook Findings section in the review
  output template, new Rules entry #9 codifying the layer
- CLAUDE.md — Quick Reference + framework integration table updated
  to surface handbooks/ alongside .claude/rules/

Decision rationale: docs/agdr/AgDR-0020-adopter-handbooks-for-rex.md
captures all five load-bearing decisions (scope, discovery,
format, sample-scaffold-per-feature, enforcement default) with
options-considered tables.

Closes #232

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(#232): correct rule-file count in CLAUDE.md (10 → 11)

Rex flagged the count mismatch in his review of #233. There are
actually 11 rule files in .claude/rules/ (the previous list also
omitted leak-protection). One-line fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(#232): markdownlint MD028/MD032 in handbook samples

Three handbook samples tripped markdownlint:
- migration-safety.md: list-inside-blockquote needs a blank `>` line
  before the list (MD032)
- commit-message-quality.md: two adjacent blockquotes joined with `>`
  instead of a blank line (MD028)
- strict-mode.md: same fix for three adjacent sample-finding blockquotes
  (MD028 x2)

Pure formatting fix. No content change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

github-issue has-ticket

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@atlas-apex @me2resh