From 3a64d68889b8a2a52c60987f9f6fce9eff7580cd Mon Sep 17 00:00:00 2001
From: Hugo Nijhuis <hugo@flowmade.one>
Date: Sat, 10 Jan 2026 01:05:47 +0100
Subject: [PATCH] Add /arch-review-repo command for repository architecture
 reviews

Creates a new command that spawns the software-architect agent to perform
comprehensive architecture audits. The command analyzes directory structure,
package organization, patterns, anti-patterns, dependencies, and test coverage,
then presents prioritized recommendations with a health score.

Closes #58

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 commands/arch-review-repo.md | 73 ++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 commands/arch-review-repo.md

diff --git a/commands/arch-review-repo.md b/commands/arch-review-repo.md
new file mode 100644
index 0000000..01e2246
--- /dev/null
+++ b/commands/arch-review-repo.md
@@ -0,0 +1,73 @@
+---
+description: Perform a full architecture review of the current repository. Analyzes structure, patterns, dependencies, and generates prioritized recommendations.
+argument-hint:
+context: fork
+---
+
+# Architecture Review
+
+@~/.claude/skills/software-architecture/SKILL.md
+
+## Process
+
+1. **Identify the repository**: Use the current working directory as the repository path.
+
+2. **Spawn the software-architect agent** for deep analysis:
+
+   ```
+   ANALYSIS_TYPE: repo-audit
+   TARGET: <repository-path>
+   CONTEXT: Full repository architecture review
+   ```
+
+   The agent will:
+   - Analyze directory structure and package organization
+   - Identify patterns and anti-patterns in the codebase
+   - Assess dependency graph and module boundaries
+   - Review test coverage approach
+   - Generate structured findings with prioritized recommendations
+
+3. **Present the results** to the user in this format:
+
+   ```markdown
+   ## Repository Architecture Review: <repo-name>
+
+   ### Structure: <Good|Needs Work>
+   - [Key observations about package organization]
+   - [Directory structure assessment]
+   - [Naming conventions evaluation]
+
+   ### Patterns Identified
+   - [Positive patterns found in the codebase]
+   - [Architectural styles detected (layered, hexagonal, etc.)]
+
+   ### Anti-Patterns Detected
+   - [Anti-pattern name]: [Location and description]
+   - [Anti-pattern name]: [Location and description]
+
+   ### Concerns
+   - [Specific issues that need attention]
+   - [Technical debt areas]
+
+   ### Recommendations (prioritized)
+   1. **P0 - Critical**: [Most urgent recommendation]
+   2. **P1 - High**: [Important improvement]
+   3. **P2 - Medium**: [Nice-to-have improvement]
+   4. **P3 - Low**: [Minor optimization]
+
+   ### Health Score: <A|B|C|D|F>
+   [Brief justification for the grade]
+   ```
+
+4. **Offer follow-up actions**:
+   - Create issues for critical findings
+   - Generate a detailed report
+   - Review specific components in more depth
+
+## Guidelines
+
+- Be specific: Reference exact files, packages, and locations
+- Be actionable: Every finding should have a clear path to resolution
+- Be balanced: Acknowledge what the codebase does well
+- Be proportionate: Focus on high-impact issues first
+- Stay objective: Focus on patterns and principles, not style preferences
-- 
2.49.1