User Story

As a Tech Lead onboarding a new managed project under ApexYard, I want to ship company-specific coding standards as handbooks that Rex (the code-reviewer agent) consults during PR review — alongside the framework's generic rules — so the standards become enforced in CI rather than living as advisory wiki pages nobody reads.

Acceptance Criteria

• New top-level handbooks/ directory in the ApexYard ops fork — framework-level handbooks live here and apply to all managed projects (no per-project handbook scope in v1; revisit if adopters ask)
• Each handbook is a flat markdown file (no structured YAML frontmatter required) — Rex reads them as prose
• Per-handbook discovery rules:
  • Files under handbooks/architecture/*.md always load into Rex's review context (architecture standards apply to every PR)
  • Files under handbooks/language/<lang>/*.md only load when the PR's diff touches files of that language (matched via path-glob inferred from <lang>, e.g. python/ → **/*.py, typescript/ → **/*.{ts,tsx})
  • Files under handbooks/general/*.md always load (small set of cross-cutting rules — e.g. commit-message style, comment density)
• Rex agent definition (.claude/agents/code-reviewer.md) updated:
  • On every PR review, after loading the framework rules, glob the applicable handbook files per the discovery logic above
  • For each handbook, scan the PR diff for handbook violations
  • Emit findings in the review comment, distinguishing advisory vs blocking:
    • Advisory (default for all handbooks) — surfaced as nit: / suggestion: comments
    • Blocking — handbook contains the literal phrase ENFORCEMENT: blocking (or similar marker — bikeshed in design) at the top, AND Rex finds a clear violation. Rex's overall verdict becomes "request changes" and the merge gate (Rex marker absent) blocks the PR
• At least 4 sample handbooks shipped, demonstrating the four shapes:
  • handbooks/architecture/clean-architecture-layers.md — domain has no external deps; application doesn't import infrastructure (mirrors the existing .claude/rules/code-standards.md § DDD section)
  • handbooks/architecture/migration-safety.md — schema migrations must be backwards-compatible for one release (sample blocking handbook)
  • handbooks/language/typescript/strict-mode.md — TS strict mode required, no bare any without inline justification (sample language-specific advisory)
  • handbooks/general/commit-message-quality.md — commit body must explain WHY not WHAT, refs ticket, etc. (cross-cutting advisory)
• handbooks/README.md index — explains the discovery model, how to add new handbooks, the advisory-vs-blocking convention, the trade-off vs framework-wide rules in .claude/rules/
• CLAUDE.md QUICK REFERENCE updated to surface handbooks/ next to .claude/rules/
• Brief mention in .claude/agents/code-reviewer.md describing the new handbook layer (so Rex agent docs are self-documenting)
• Manual smoke test: open a PR touching **/*.ts files in a managed project, confirm Rex's review comment cites both framework rules AND the typescript handbook(s); open a PR touching only **/*.py files, confirm typescript handbook is NOT cited

Design Notes

Why framework-level and not per-project (the answer to my Q1): simplicity for v1. Handbooks travel with the framework fork, applying uniformly across all managed projects. If a future adopter has truly project-specific patterns, file a follow-up to add per-project layering — but the cost of that complexity isn't justified yet.

Why flat markdown (Q3): Rex already reads markdown rules as prose; handbooks are structurally identical. Skipping YAML frontmatter keeps the authoring bar low — anyone can write a handbook in one file. The discovery logic uses path conventions (architecture/ vs language// vs general/) instead of frontmatter to keep the format inspection-free.

Why advisory by default with blocking opt-in (Q5): the framework's existing rules are already a mix of advisory (parallel-work, plan-mode) and blocking (ticket-first, secret-scan). Handbooks should default to the gentler shape — a handbook that breaks every PR on day 1 is operator-hostile. Authors who want blocking enforcement opt in explicitly via the marker phrase.

Sample handbooks chosen to demonstrate all four shapes:

• One always-load architectural advisory (clean-architecture)
• One always-load architectural blocking (migration-safety — material risk if violated)
• One language-specific advisory (TS strict)
• One always-load cross-cutting advisory (commit messages)

These are also the ones I'd actually ship as defaults — they're load-bearing without being controversial.

Rex integration risk: the agent's prompt grows by N handbooks. Mitigations: (a) language-specific handbooks only load on diff match, so a Python-only PR doesn't pay the TS-handbook cost; (b) handbook files should aim for ≤ 50 lines each (one rule cluster per file); (c) follow-up work could add a glob: directive in handbook prose to narrow even further.

Out of Scope

• Per-project handbooks layered over framework handbooks — useful if adopters with multiple managed projects want project-specific patterns. File a follow-up when there's an adopter asking for it.
• Handbook authoring skill (/handbook to scaffold a new handbook interactively) — nice-to-have UX; v1 works with raw vim handbooks/.... File a follow-up if authoring friction shows up.
• Auto-generation of handbook stub when a feature is filed (/feature would prompt to also draft a handbook entry) — your answer docs(#100): positioning rewrite — "where projects get forged" #4 specifically said "just write an example for us, no per-feature scaffold". File a follow-up if this becomes desired later.
• Handbook conflict resolution between framework rules and handbook rules — defer until a real conflict surfaces. Handbooks should be additive, not contradictory; in v1 if they conflict, the framework rule wins (Rex prefers the rule it loaded first, which is always the framework rule).
• Cross-project handbook aggregation / dashboard — out of scope; the audit-history pattern from [Feature] Audit-skill artefact persistence + canonical structure #218 covers this style of cross-cutting visibility separately if needed.
• Handbook versioning — handbooks are flat markdown, version-controlled by git. No schema_version field required.

Effort Estimate

TBD