Clean Architecture toolkit: four tools for gradual transformation

[svarlet]

Why a toolkit, not a roadmap

The codebase has 62 Riverpod providers across 22 files. Providers absorbed
domain responsibilities — sealed classes, state machines, business logic —
rather than serving as thin glue. The root cause: Claude's default
decomposition strategy optimizes for local correctness ("one concern = one
file") over global cohesion.

A rigid refactoring roadmap would go stale when priorities shift. Instead,
this PR introduces four tools that codify architectural judgment so any
developer can apply the Clean Architecture dependency rule on demand, at
the moment it matters.

The four tools

Tool	When	What it does
/rework <feature>	Touching existing code	Diagnoses anti-patterns in a feature's providers and proposes a scoped refactoring — domain logic out, rich domain objects in. One PR, one reviewer's head.
claude --agent architect	Planning a new feature	Decomposes a functional spec into Clean Architecture layers through conversation. Produces an ADR where domain concepts, use cases, and providers are designed before code is written.
Provider-lint hook	Every file write	Catches sealed class in providers, oversized files, and state machine signals the moment Claude writes them. Non-blocking feedback via Claude hooks.
/rework-sharpen <feedback>	After using any tool	Evaluates feedback against the Clean Architecture principles. Patches tools if the gap is real; educates the developer if the feedback itself violates the dependency rule.

What's in the box

Analysis & design (read these first):

• PLANS/0004-clean-architecture/ADR.md — the decision and rationale
• PLANS/0004-clean-architecture/ANALYSIS.md — provider inventory, diagnosis
• PLANS/0004-clean-architecture/TARGET.md — concrete before/after transformations
• PLANS/0004-clean-architecture/SPEC.md — specifications for all four tools

Tools:

• .claude/skills/rework/ — the /rework skill + diagnosis checklist
• .claude/agents/architect.md — the architect agent
• .claude/hooks/provider-lint.sh + .claude/settings.json — the lint hook
• .claude/skills/rework-sharpen/ — the /rework-sharpen skill

Rules:

• CLAUDE.md — updated with Clean Architecture provider constraints

All tools share one source of truth

The Clean Architecture dependency rule from Uncle Bob's blog post.
Every tool eagerly reads it at execution time to stay grounded in
principles, not just local conventions. TARGET.md is illustrative but
the principles are enduring.

Test plan

• Run /rework quiz — verify it diagnoses sealed classes and state machine in quiz_provider.dart
• Run /rework-sharpen "the hook flagged a comment mentioning sealed class" — verify it recognizes the hook already strips comments
• Edit a provider file to exceed 100 lines — verify the hook fires a warning
• Run claude --agent architect with a simple feature spec — verify it walks through the steps conversationally

🤖 Generated with Claude Code

[svarlet]

Note: see if this can utilise any/all of:

• https://pub.dev/packages/riverpod_lint?
• DCM?

Meanwhile, this script still introduces a quick feedback loop to Claude.