improve-architecture

Audit codebases to surface shallow modules and ADR-ready deepening opportunities.

Updated Feb 8, 2026

Search Tags:#architecture #codebase #adr #refactor #seams #deepening #domain-vocabulary

Ready to run

npx skills add https://github.com/ckallum/calsuite --skill improve-architecture-ckallum

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: improve-architecture
Source: https://github.com/ckallum/calsuite/tree/main/skills/improve-architecture
Command: npx skills add https://github.com/ckallum/calsuite --skill improve-architecture-ckallum

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Identifies architectural friction in a codebase and surfaces opportunities to deepen modules, improving testability and AI navigability over time.

Core Features & Use Cases

Surface shallow modules and seams that increase cognitive load and change-cost.
Propose ADR-ready deepening opportunities aligned to the project's CONTEXT.md domain glossary.
Support scoped audits (path-level) or full-repo health checks, with traceable notes and ADRs.

Quick Start

Run /improve-architecture to scan your repository and surface deepening opportunities.

Frequently Asked Questions about improve-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I identify architectural friction and shallow modules in my codebase?▼

You can perform a full-repo health check or a scoped path-level audit to surface architectural friction, identifying shallow modules and seams that increase cognitive load and change-cost.

What are seams in software architecture and how do they affect codebase health?▼

Seams are structural points in a codebase that allow module isolation. Surfacing shallow seams through an architectural audit highlights areas where deepening modules can reduce cognitive load and change-cost.

How do I generate ADR-ready notes for a codebase refactoring effort?▼

Generate ADR-ready notes by auditing your codebase for deepening opportunities aligned to your domain vocabulary, outputting traceable observations and Architecture Decision Records candidates for refactor planning.

Do I need a CONTEXT.md and LANGUAGE.md file to audit my repository architecture?▼

Yes, auditing your repository architecture requires a CONTEXT.md file and docs/adr/ directory, and uses the domain vocabulary defined in LANGUAGE.md to align deepening opportunities with your project context.

Can I scope an architectural audit to a specific directory path instead of the full repository?▼

Yes, you can scope architectural audits to specific directory paths rather than running a full-repo health check, allowing targeted identification of shallow modules and seams within bounded codebase areas.

When should I surface deepening opportunities in my software architecture?▼

Surface deepening opportunities when architectural friction, such as shallow modules and seams, increases cognitive load and change-cost, degrading testability and navigability across your codebase over time.