Help us improve
Share bugs, ideas, or general feedback.
From hb
Explores a codebase for architectural friction and proposes refactors toward deep modules with simple interfaces. Surfaces tightly-coupled modules and suggests GitHub issue RFCs.
npx claudepluginhub helderberto/agent-skills --plugin hbHow this skill is triggered — by the user, by Claude, or both
Slash command
/hb:architecture-auditThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A **deep module** has a simple interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the seam instead of inside. See [references/deep-modules.md](references/deep-modules.md) for examples and anti-patterns.
Explores codebases to identify architectural friction and opportunities to deepen shallow modules, improving testability, refactoring, and AI navigability.
Explores codebase for architectural improvement, focusing on testability by deepening shallow modules. Use when seeking refactoring opportunities or consolidating tightly-coupled code.
Analyzes a codebase to surface architectural friction and propose refactoring opportunities that deepen modules, improve testability, and make the code more AI-navigable.
Share bugs, ideas, or general feedback.
A deep module has a simple interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the seam instead of inside. See references/deep-modules.md for examples and anti-patterns.
Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary." Consistent language is the point. Full definitions in references/language.md.
Key principles:
Use the Agent tool with subagent_type=Explore to navigate the codebase organically. Note where you experience friction:
The friction you encounter IS the signal.
Show a numbered list. For each candidate:
Do NOT propose interfaces yet. Ask: "Which candidate would you like to explore?" — list each candidate as an option with its cluster name as label and coupling summary as description. Use AskUserQuestion when available; otherwise present as a numbered list.
Write a user-facing explanation of the chosen candidate:
Show this to the user, then immediately proceed to Step 5. User reads while sub-agents work.
Spawn 3+ sub-agents in parallel using the Agent tool. Each produces a radically different interface. Give each a separate technical brief (file paths, coupling details, dependency category). Assign distinct constraints:
Each sub-agent outputs:
Present designs sequentially, compare in prose, then give your own recommendation. Be opinionated — if elements from multiple designs combine well, propose a hybrid.
Ask: "Which interface design should we use?" — list each design as an option with preview showing the interface signature. Add "Your recommendation" as first option (Recommended) with the hybrid/recommended design in preview. Use AskUserQuestion when available; otherwise present as a numbered list.
Save a markdown file named architecture-<cluster-name>.md using the template in references/improvement-template.md. If .specs/prds/ exists, save there; otherwise, save in prds/.
Fill with concrete details: file paths, function names, migration steps. Share the file path with the user when done.