Add architecture guidance and capability-aware escalation

[obra]

Summary

• Add modular design guidance (unit decomposition, clean boundaries, well-defined interfaces) to brainstorming and writing-plans skills
• Add file size awareness throughout the pipeline — framed as reasoning quality, not hard rules
• Add capability-aware model selection and structured escalation protocol (DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT) to subagent-driven development
• Add architecture and file size checks to all three review loops (spec, plan, code quality)
• Brownfield-safe: reviewers focus on what this change contributed, not pre-existing file sizes

Files changed

• skills/brainstorming/SKILL.md — design for isolation and clarity, working in existing codebases
• skills/brainstorming/spec-document-reviewer-prompt.md — architecture review criteria
• skills/writing-plans/SKILL.md — file structure section
• skills/writing-plans/plan-document-reviewer-prompt.md — file structure and size review criteria
• skills/subagent-driven-development/SKILL.md — model selection, implementer status handling
• skills/subagent-driven-development/implementer-prompt.md — code organization, escalation protocol, structured status reporting
• skills/subagent-driven-development/code-quality-reviewer-prompt.md — decomposition and file growth checks

Design decisions

• No hard line-count rules — explains WHY smaller files matter (reasoning quality, edit reliability) and lets the model decide
• Provider-agnostic model tiers — "cheap/standard/most capable" instead of Haiku/Sonnet/Opus
• Brownfield-safe — "improve what you touch like a good developer would, don't do unrelated refactoring"
• Reviewer focus on contribution — code quality reviewer checks whether THIS implementation grew files, not pre-existing sizes

Test plan

• Run brainstorming skill on a greenfield project — verify it asks about unit decomposition
• Run brainstorming skill on a brownfield project — verify it explores existing patterns before proposing changes
• Run writing-plans skill — verify File Structure section appears before task definitions
• Run subagent-driven-development — verify model selection guidance is followed
• Test implementer escalation — verify BLOCKED/NEEDS_CONTEXT statuses are handled by controller
• Test code quality reviewer — verify it flags file growth from implementation

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch wip/architecture-guidance

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}