Arch lens
Production-ready AI agent skills for Claude Code, Codex, Cursor, and the Agent Skills Open Standard
npx -y skills add psenger/ai-agent-skills --skill arch-lensAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 9 stars9 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Explores a codebase for architectural friction through the lens of Ousterhout's deep-module principle (small interface, large implementation). Seven-step interactive workflow: an Explore sub-agent navigates the codebase organically — the friction it experiences IS the signal. Surfaces candidate clusters with coupling reasons, call patterns, shared types, dependency categories, and existing tests that a boundary test would replace. User picks what to explore, frames the problem, then 3–4 parallel sub-agents design competing deep-module interfaces. Chosen design becomes a structured RFC action file readable by GitHub MCP or ROVO (Jira) MCP. Use when the user says "arch review", "find shallow modules", "module depth", "deep module", "Ousterhout", "testability audit", "surface coupling", "design interfaces", "RFC issues", or "architectural friction".
SKILL.md
3.5 KB, as published. Nobody here has run it
Arch Lens
Seven-step interactive architectural review. An Explore sub-agent navigates the codebase the way a developer would — the confusion, file-bouncing, and untestable seams it encounters are the findings. No checklists, no rigid heuristics.
Deep module: small interface surface hiding a large, self-contained implementation. Lets callers test at the boundary. Lets AI agents reason without reading internals.
Quick start
- If a path argument is given, scope to that directory; otherwise whole repo
- Load
${CLAUDE_SKILL_DIR}/references/WORKFLOW.md— full step-by-step instructions - Load
${CLAUDE_SKILL_DIR}/references/DETECTION-PATTERNS.md - Load
${CLAUDE_SKILL_DIR}/references/INTERFACE-DESIGN.md - Load
${CLAUDE_SKILL_DIR}/references/RFC-FILE-FORMAT.md - Execute the seven steps in WORKFLOW.md
Workflows
| Step | What happens | Requires user input |
|---|---|---|
| 1. Explore | Spawn Explore sub-agent; navigate organically; record friction | — |
| 2. Candidates | Synthesise friction into clusters; present max 8 with full context | — |
| 3. Pick | User selects a cluster and directs the angle | wait |
| 4. Frame | Problem statement, dependency category, blast radius, test boundary today | — |
| 5. Design | Spawn 3–4 parallel sub-agents with competing interface designs | — |
| 6. Choose | User picks interface or accepts recommendation | wait |
| 7. RFC file | Write arch-rfcs-YYYY-MM-DD.md to project root | — |
Full prompt text, cluster format, and step detail: see WORKFLOW.md.
Behavioural rules
- Explore agent friction observations are primary evidence — never override with static analysis
- Never propose interface designs before Step 5
- Never advance past Steps 3 or 6 without a user response
- Every RFC must include exact
file:linereferences and a before/after illustration - Name every dependency category explicitly — it determines the testing strategy
- Rank clusters: testability impact first, then cognitive load, then interface stability
Advanced features
- Full workflow detail and Explore agent prompt:
${CLAUDE_SKILL_DIR}/references/WORKFLOW.md - Friction vocabulary and dependency categories:
${CLAUDE_SKILL_DIR}/references/DETECTION-PATTERNS.md - Sub-agent brief template and design constraints:
${CLAUDE_SKILL_DIR}/references/INTERFACE-DESIGN.md - RFC action file format and complete example:
${CLAUDE_SKILL_DIR}/references/RFC-FILE-FORMAT.md