Add stage-awareness rules to Refiner agent#26
Open
digitalgrove-bit wants to merge 1 commit into
Open
Conversation
The Refiner currently applies SoC and tactical-DDD patterns without
regard to project stage, team size, or existing layout — which produces
designs that the Critique agent then rejects wholesale (in one real
case: triple file-count, two new bounded contexts, typed UUID classes,
and aggregate roots for a solo-developer pre-customer project).
This patch adds a mandatory pre-refinement check:
1. Read CLAUDE.md and docs/prd.md to extract team size and stage
2. Write a Stage Preamble at the top of refinements.md
3. Apply three constraint rules:
- R-1: No new layout conventions without explicit request
- R-2: 50% file-count growth budget (each excess file needs a
concrete present-tense justification)
- R-3: Match patterns to stage (pre-customer/MVP/scaling/mature)
4. Self-check before writing refined.md
Default bias: when in doubt about stage, do less. Critique flags
under-engineering as readily as over-engineering, and adding
structure later is cheaper than ripping it out.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a mandatory stage-awareness check to the Refiner agent so it stops over-engineering MVPs.
Motivation
In its current form, the Refiner applies SoC and tactical-DDD patterns without regard to project stage, team size, or existing layout. In one real case, it produced a design with:
…all for a solo-developer, pre-customer project. The Critique agent rejected nearly all of it (4 CRITICAL + 10 HIGH + 10 MEDIUM + 8 LOW findings). The over-engineering wasn't a Critique failure — the Refiner had no instruction to ask "is this stage-appropriate?" before applying the patterns.
What this changes
Adds a
## Stage-Awareness (MANDATORY before proposing refinements)section toarchitect-refine-critique/agents/refiner.mdwith four steps:refinements.mddeclaring team size, stage, existing layout, and any conflicts.features/platform/shellonto a flatapp/)refined.md.Default bias: when in doubt about stage, do less. The Critique agent flags under-engineering as readily as over-engineering, and adding structure later is cheaper than ripping it out.
Why this fits the chain
The Architect → Refine → Critique chain works because each agent has a clear job. Adding stage-awareness to the Refiner doesn't change its responsibility — it constrains the search space the Refiner explores. The Critique agent still has the final word; it just has less to push back on when the Refiner stays in scope.
Test plan
/arcon a solo-developer pre-customer project; confirm refinements.md opens with a Stage Preamble and respects R-1/R-2/R-3./arcon a project withCLAUDE.mddeclaring team size; confirm Refiner extracts and uses that signal./arcon a project with an existingfeatures/platform/shelllayout; confirm Refiner doesn't propose alternative layouts.Notes
This change has been running locally in production for a week without regression. Happy to iterate on wording or scope if you'd prefer a lighter touch.