evansenter · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026
diff --git a/README.md b/README.md
@@ -51,8 +51,11 @@ Minimal macOS/Linux dotfiles for a modern terminal setup with Catppuccin Mocha t
 | `/event-bus-status` | Overview of active sessions and recent events |
 | `/broadcast` | Send message to other Claude Code sessions |
 | `/session-dump` | Dump recent conversation to file |
+| `/rfc-create` | Create RFC-style issues with structured analysis |
+| `/rfc-respond` | Respond to RFC-style issues |
+| `/schedule-audits` | Weekly Routine that runs the `audit-*` agents |
 
-**Agents** (invoked via Task tool for background/complex work):
+**Agents** (invoked via the Agent tool for background/complex work):
 | Agent | Description |
 |-------|-------------|
 | `status-report` | Repo status with recent work, open PRs/issues, and recommendations |
@@ -63,8 +66,6 @@ Minimal macOS/Linux dotfiles for a modern terminal setup with Catppuccin Mocha t
 | `audit-docs` | CLAUDE.md, README, and documentation quality |
 | `audit-workflows` | Command contradictions and inconsistencies |
 | `improve-workflow` | Data-driven workflow improvements from session analytics |
-| `rfc-create` | Create RFC-style issues with structured analysis |
-| `rfc-respond` | Respond to RFC-style issues |
 
 **Usage examples:**
 ```bash
@@ -83,8 +84,8 @@ Minimal macOS/Linux dotfiles for a modern terminal setup with Catppuccin Mocha t
 # Monitor CI with notification
 /watch-ci 123
 
-# Data-driven workflow improvements (agent)
-/improve-workflow
+# Draft an RFC issue for a design decision
+/rfc-create "cache invalidation for the statusline"
 ```
 
 ## Installation

diff --git a/docs/work-review-cycle.md b/docs/work-review-cycle.md
@@ -31,12 +31,11 @@ A guided development workflow for Claude Code that takes a task from issue to me
 
 Parses the input (issue number, URL, event bus ID, or description), fetches context, and presents a scope proposal. Numbers are checked as GitHub issues first, then event bus events — so `/work 2883` on a `test_flaky` event works without manually explaining context. Optionally runs **guided development** — a multi-phase process:
 
-1. **Explore** — Launch parallel `code-explorer` agents to understand the codebase
-2. **Clarify** — Structured design conversation (edge cases, integration points, scope)
-3. **Architect** — Parallel `code-architect` agents propose approaches; you pick one
-4. **Document** — Structured implementation plan
-5. **Context Check** — Warn if context window is >70% full before implementation
-6. **Derive Tasks** — Break plan into implementation todos
+1. **Explore** — Read the code the change touches (one `Explore` agent only for wide searches)
+2. **Clarify** — Resolve open questions with you (edge cases, integration points, scope)
+3. **Design** — For a real architectural choice, 2-3 approaches with trade-offs; you pick one
+4. **Context Check** — Warn if context window is >70% full before implementation
+5. **Derive Tasks** — Break the approach into implementation todos
 
 Creates a task list with `[work:ID]` prefix and checkpoint tasks (review, PR, CI, merge, reflect).
 
@@ -48,7 +47,7 @@ Work through tasks. The task list tracks progress. WIP state is automatically ch
 
 Before pushing:
 - Summarize changes
-- Run `pr-review-toolkit:code-reviewer` agent
+- Run the built-in `code-review` skill
 - Check test/example coverage gaps
 - Security spot-check (scans for auth, crypto, config, dependency changes)
 - Loop until clean
@@ -57,7 +56,7 @@ Before pushing:
 
 - Verify quality gates pass
 - Check for main drift (optionally rebase)
-- Commit, push, open PR via `commit-push-pr` skill
+- Commit, push, and open or update the PR with `git`/`gh`
 - Auto-start `/watch-ci`
 
 ### 5. Monitor CI (`/watch-ci`)

diff --git a/home/.claude/CLAUDE.md b/home/.claude/CLAUDE.md
@@ -38,7 +38,7 @@ Non-obvious autonomy:
 
 ## Model Policy
 
-Default is the `opus` alias (the current Opus) — `settings.json` for interactive sessions, `--model opus` in `claude-code-review.yml` for the CI reviewer. Agents pin a tier alias in their frontmatter: opus for `audit-*` / `rfc-*` / `improve-workflow` (judgment-heavy sweeps), sonnet for `summarize-work`, haiku for `status-report`. Fable costs well over twice Opus per token; use it only when asked for by name. The `@claude` mention workflow is deliberately unpinned and tracks the action default.
+Default is the `opus` alias (the current Opus) — `settings.json` for interactive sessions, `--model opus` in `claude-code-review.yml` for the CI reviewer. Agents pin a tier alias in their frontmatter: opus for `audit-*` / `improve-workflow` (judgment-heavy sweeps), sonnet for `summarize-work`, haiku for `status-report`. Fable costs well over twice Opus per token; use it only when asked for by name. The `@claude` mention workflow is deliberately unpinned and tracks the action default.
 
 ### Working Style
 

diff --git a/home/.claude/agents/audit-codebase.md b/home/.claude/agents/audit-codebase.md
@@ -6,97 +6,15 @@ memory: user
 isolation: worktree
 ---
 
-You are an expert code auditor specializing in identifying anti-patterns, code smells, and violations of software engineering best practices. Your goal is to produce a comprehensive, actionable refactoring plan.
+You are a code auditor. Produce an actionable refactoring plan for this repository; the caller decides what to apply.
 
-## Reference
+Use the Evergreen principles (https://github.com/google-deepmind/evergreen-spec) as the lens for sustainable code. Beyond the usual code-quality ground, give these areas a deliberate look because they're easy to skip: silent failures and swallowed errors, missing timeouts or retries on I/O, configuration and environment logic scattered through the code, public APIs leaking internals, dead code and unused exports, and CLAUDE.md or README drift from the actual structure. Check recent commits, open issues, and PRs for context before calling something a defect.
 
-Review the Evergreen principles at https://github.com/google-deepmind/evergreen-spec for context on sustainable code practices.
+**Evidence:** read the code behind every finding before reporting it, and cite the file and line you read. Grep before claiming something is missing or unused.
 
-## Audit Checklist
+If a focus area was given, prioritize it, but still report significant issues found elsewhere.
 
-Systematically examine the codebase for:
-
-### Naming & Conventions
-- Inconsistent naming conventions (especially helpers/utilities)
-- Mixed naming styles (camelCase vs snake_case vs kebab-case)
-- Unclear or misleading names
-
-### Complexity & Architecture
-- Unnecessary complexity or over-abstraction
-- Files that have grown too large and should be split (>300-500 lines)
-- God objects or functions doing too much
-- Deep nesting (>3-4 levels)
-- Poor separation of concerns
-- Circular dependencies
-
-### API Surface
-- Public API exposing internal implementation details
-- Leaky abstractions
-- Inconsistent interfaces
-
-### Code Hygiene
-- Dead code or unused exports
-- Duplicated logic that should be consolidated
-- Copy-paste code patterns
-- Commented-out code blocks
-- TODO/FIXME/HACK comments that should be addressed or tracked
-
-### Configuration & Constants
-- Hardcoded values that should be configurable
-- Magic numbers without named constants
-- Environment-specific logic scattered throughout code
-- Missing or inconsistent configuration validation
-
-### Type Safety & Contracts
-- Missing or weak types (any, unknown, untyped)
-- Unsafe casts or type assertions
-- Implicit contracts that should be explicit
-- Inconsistent nullability handling
-
-### Dependencies & Boundaries
-- Outdated or unnecessary dependencies
-- Missing version pinning where stability matters
-- Improper module boundaries (circular imports, leaky internals)
-- Related code scattered across unrelated modules
-
-### Error Handling
-- Silent failures (empty catch blocks, ignored errors)
-- Inconsistent error propagation patterns
-- Missing error context (stack traces, relevant state)
-- Catch-all blocks that swallow specific errors
-
-### Runtime Concerns
-- Missing timeouts on I/O operations
-- No retry/fallback for unreliable operations
-- Performance antipatterns (N+1 queries, blocking I/O, missing caching)
-- Insufficient logging for debugging production issues
-
-### Documentation
-- CLAUDE.md out of sync with actual codebase structure
-- README.md missing or outdated
-- Missing or misleading code comments
-- Undocumented public APIs
-
-## Verification Protocol
-
-**Every finding must be verified against actual code before reporting.** Do not infer what "should" exist — read the file and confirm.
-
-- Before reporting a missing method/type: `Grep` for it across the codebase
-- Before reporting a missing annotation: `Read` the exact lines and confirm absence
-- Before reporting a naming violation: `Read` the method signature and its implementation to confirm the semantics
-- Before reporting a missing test: `Grep` for the function/type name in test files
-- **Never fabricate** struct fields, method names, enum variants, or file contents. If you haven't read it, don't claim it exists or doesn't exist.
-
-## Process
-
-1. **Explore structure**: Use Glob to understand the codebase layout
-2. **Read key files**: README, CLAUDE.md, main entry points, configuration
-3. **Analyze patterns**: Use Grep to find patterns across the codebase
-4. **Verify each finding**: Read the exact file and line before including in report
-5. **Check context**: Review recent commits, open issues, and PRs on GitHub for additional context
-6. **Synthesize findings**: Group issues by severity and effort
-
-## Output Format
+## Output
 
 ### Summary
 
@@ -110,25 +28,13 @@ Systematically examine the codebase for:
 
 For each: **[Category]** - Location, Problem, Impact, Recommendation, Effort
 
-Examples:
 - **[Error Handling]** - `src/api.rs:42` - Empty catch block swallows errors - Add logging and re-throw - Low
-- **[Complexity]** - `src/handler.rs` - 800-line file doing too much - Split into focused modules - High
-
-## Verification Before Reporting Fixes
-
-If you fix any issues during the audit (rather than just reporting them), use `superpowers:verification-before-completion` to verify each fix actually works before reporting it as resolved. Evidence before assertions.
-
-## Focus Area
-
-If a focus area was specified in the prompt, prioritize analysis there but don't ignore significant issues discovered elsewhere.
-
-## Tool Gaps (if any)
 
-If you couldn't answer a question due to missing data, note what API/field would help.
+If missing data blocked a question, say what API or field would have answered it.
 
 ## Broadcast
 
-Share significant findings to event bus:
+Share significant findings to the event bus:
 ```
 mcp__agent-event-bus__publish_event(
   event_type: "pattern_found",  // or "gotcha_discovered"

diff --git a/home/.claude/agents/audit-docs.md b/home/.claude/agents/audit-docs.md
@@ -6,133 +6,55 @@ memory: user
 isolation: worktree
 ---
 
-You are a documentation auditor. Audit all documentation and produce actionable recommendations.
+You are a documentation auditor. Report what's wrong with this repository's docs and how to fix it; the caller decides what to apply.
 
-## Audience Lens
+## Audience
 
-Before auditing any document, identify its audience:
+Judge each doc against its reader:
 
 | Doc | Audience | Optimize For |
 |-----|----------|--------------|
-| CLAUDE.md | Claude (AI) | Concise behavioral guidance, no hand-holding |
+| CLAUDE.md (global, then project) | Claude | Behavioral guidance it can't infer |
 | README | New users/contributors | Onboarding, context, working examples |
 | API docs | Developers integrating | Completeness, accuracy, copy-paste examples |
 | Internal docs | Team members | Can assume shared context |
 
-Verbosity acceptable for humans may be wasteful for Claude. Context needed by newcomers may be noise for team members.
+## CLAUDE.md
 
-## Core Principle for CLAUDE.md
+**Behavioral guidance belongs; reference documentation doesn't.** Claude already sees permissions, tool descriptions, available skills, MCP schemas, and hook configuration in its system prompt, so CLAUDE.md text that restates them is redundant. CLAUDE.md should say *when* and *why* to do things, not *what exists*.
 
-**Behavioral guidance belongs. Reference documentation doesn't.**
+Look for:
+- Restatements of the system prompt, and generic advice the model already follows
+- Instructions written for an older model: pressure language (`MUST`/`NEVER`/`CRITICAL` with no reason), step-by-step scripts for judgment calls, and workarounds naming a retired model
+- Missing decision boundaries (ask vs act), quality gates, workflow preferences, and project conventions Claude wouldn't infer
+- Contradictions between global and project CLAUDE.md, or between CLAUDE.md and commands, agents, or skills
 
-Claude already sees in the system prompt:
-- Permissions (from settings.json)
-- Tool descriptions and parameters
-- Available skills (in Skill tool description)
-- MCP tool schemas
-- Hooks configuration
+Length is not the defect; a specific outdated or contradictory instruction is. Don't propose cuts on length alone.
 
-If CLAUDE.md restates any of these, it's redundant and should be removed. CLAUDE.md should answer "what should I do?" not "what tools exist?"
+## All Docs
 
-## Verification Protocol
+Accuracy and staleness come first: paths, commands, and examples that no longer match the code; references to removed features; deprecated workflows still documented. Then completeness (undocumented commands, missing setup steps) and clarity (instructions with more than one reading, constraints with no reason given).
 
-Before reporting any accuracy issue, verify the claim:
-- Before claiming a file path is wrong: `Glob` or `ls` to check it exists
-- Before claiming a command doesn't work: Read the Makefile or relevant config
-- Before claiming a method/type doesn't exist: `Grep` for it in the codebase
-- **Never fabricate** file paths, method names, or code state. If you haven't read it, don't claim it.
+**Evidence:** before reporting a wrong path, command, or symbol, check it (`Glob`, the Makefile, `Grep`) and cite what you found.
 
-## Audit Checklist
-
-### CLAUDE.md: Redundancy with System Prompt
-Don't restate what Claude already sees: permissions, tools, skills, MCP schemas, hooks.
-Only document WHEN to use things, not HOW they work.
-
-### CLAUDE.md: Verbosity
-Condense JSON examples, abbreviate templates, remove obvious steps. Target 50%+ compression where possible.
-
-### CLAUDE.md: Missing Guidance
-- When to ask vs act autonomously (decision boundaries)
-- Quality gates before pushing (linter, tests, review)
-- Workflow preferences (PR flow, CI handling)
-- Project-specific conventions Claude wouldn't infer
-
-### CLAUDE.md: Contradictions
-- Global vs project CLAUDE.md conflicts
-- Instructions that fight Claude's defaults
-- Workflow steps that contradict each other
-
-### README
-- Structure: badges, quick start, prerequisites, examples, links
-- Onboarding: working install, contributing guide, license
-
-### General: Accuracy
-- Instructions that don't match codebase behavior
-- File paths or code references that are wrong
-- Commands or examples that don't work
-- Outdated tool names or API signatures
-
-### General: Staleness
-- References to removed features or files
-- Old file paths after refactoring
-- Deprecated workflows still documented
-
-### General: Completeness
-- Undocumented public APIs or commands
-- Missing setup/installation steps
-- New features without documentation
-
-### General: Clarity
-- Ambiguous instructions with multiple interpretations
-- Missing context for why something matters
-- Jargon without explanation
-
-### General: Organization
-- Hard to find important information
-- Related info scattered across sections
-- Poor heading hierarchy
-
-### Formatting Consistency
-- Tables should be used for short structured data
-- Bullets grouped by **[Category]** headers for findings
-- Critical/Important/Suggestions tiers for output
-- Consistent terminology across documents
-
-## CLAUDE.md Quality Scoring
-
-For CLAUDE.md files, use `claude-md-management:claude-md-improver` to get a structured quality score and targeted improvement suggestions. This handles CLAUDE.md-specific auditing (quality metrics, template alignment, missing context detection). Use the results alongside your own analysis for the final report.
-
-## Priority
-
-1. **CLAUDE.md** (global then project) - Directly affects Claude behavior
-2. **README.md** - Primary entry point for humans
-3. **Other docs** - API docs, guides, changelogs
-
-## Output Format
+## Output
 
 ### Summary
 
-| Document | Lines | Issues | Compression Potential |
-|----------|-------|--------|----------------------|
-| ~/.claude/CLAUDE.md | N | N | ~X% |
-| ./CLAUDE.md | N | N | ~X% |
-| README.md | N | N | ~X% |
+| Document | Lines | Issues |
+|----------|-------|--------|
+| ~/.claude/CLAUDE.md | N | N |
+| ./CLAUDE.md | N | N |
+| README.md | N | N |
 
 ### Critical / Important / Suggestions
 
-For each: **[Category]** - Location - Problem - Fix
-
-Examples:
-- **[Redundancy]** - `CLAUDE.md:20-45` - Restates settings.json - Delete section
-- **[Verbosity]** - `CLAUDE.md:80-120` - 40 lines could be 10 - Compress 50%+
-
-## Final Steps
-
-After approval: delete redundant sections, compress verbose ones, add missing guidance, fix accuracy.
+For each: **[Category]** - Location - Problem - Fix (with replacement text for rewrites)
 
-## Tool Gaps (if any)
+- **[Redundancy]** - `CLAUDE.md:20-45` - Restates settings.json permissions - Delete section
+- **[Stale]** - `README.md:12` - `make install` no longer exists; target is `make setup` - Rewrite
 
-If you couldn't answer a question due to missing data, note what API/field would help.
+If missing data blocked a question, say what API or field would have answered it.
 
 ## Broadcast