/ase-arch-analyze

name: ase-arch-analyze
argument-hint: "[--help|-h] <source-reference>"
description: Review software architecture, including package cohesion and inter-package coupling
user-invocable: true
disable-model-invocation: false
effort: high
allowed-tools:
    - "Bash(wc *)"
    - "Bash(ls *)"
    - "Bash(tree *)"
    - "Bash(file *)"
    - "Bash(du *)"
    - "Bash(stat *)"
    - "Bash(grep *)"
    - "Bash(awk *)"
    - "Bash(head *)"
    - "Bash(tail *)"
    - "Bash(sort *)"
    - "Bash(uniq *)"
    - "Bash(cat *)"
    - "Bash(cut *)"
    - "Bash(tr *)"
    - "Bash(nl *)"
    - "Bash(column *)"
    - "Bash(diff *)"
    - "Bash(cmp *)"
    - "Bash(jq *)"
    - "Bash(cloc *)"
    - "Bash(tokei *)"
    - "Bash(scc *)"
    - "Bash(basename *)"
    - "Bash(dirname *)"
    - "Bash(realpath *)"
    - "Bash(readlink *)"
    - "Bash(pwd *)"
    - "Bash(which *)"
    - "Bash(whereis *)"
    - "Bash(type *)"
    - "Bash(namei *)"
    - "Bash(git log *)"
    - "Bash(git show *)"
    - "Bash(git diff *)"
    - "Bash(git blame *)"
    - "Bash(git ls-files *)"
    - "Bash(git ls-tree *)"
    - "Bash(git grep *)"
    - "Bash(git status *)"
    - "Bash(git rev-list *)"
    - "Bash(git rev-parse *)"
    - "Bash(git for-each-ref *)"
    - "Bash(git reflog *)"
    - "Bash(git cat-file *)"
    - "Bash(git config --get *)"
    - "Bash(git config --list *)"
    - "Bash(git remote *)"
    - "Bash(git branch *)"
    - "Bash(git tag --list *)"
    - "Bash(git describe *)"
    - "Bash(git shortlog *)"
    - "Bash(find * -name *)"
    - "Bash(find * -type *)"
    - "Bash(find * -path *)"
    - "Bash(find * -maxdepth *)"
    - "Bash(find * -mindepth *)"
    - "Bash(find * -size *)"
    - "Bash(find * -mtime *)"
    - "Bash(find * -newer *)"
    - "Bash(git diff * | awk *)"
    - "Bash(git diff * | grep *)"
    - "Bash(git diff * | head *)"
    - "Bash(git diff * | tail *)"
    - "Bash(git diff * | wc *)"
    - "Bash(git log * | head *)"
    - "Bash(git log * | grep *)"
    - "Bash(git log * | wc *)"
    - "Bash(git show * | head *)"
    - "Bash(git show * | grep *)"
    - "Bash(git grep * | head *)"
    - "Bash(git grep * | wc *)"
    - "Bash(git ls-files * | grep *)"
    - "Bash(git ls-files * | head *)"
    - "Bash(git ls-files * | wc *)"
    - "Bash(grep * | head *)"
    - "Bash(grep * | sort *)"
    - "Bash(grep * | wc *)"
    - "Bash(grep * | sort * | uniq *)"
    - "Bash(cat * | grep *)"
    - "Bash(cat * | awk *)"
    - "Bash(cat * | head *)"
    - "Bash(cat * | wc *)"
    - "Bash(find * | head *)"
    - "Bash(find * | wc *)"
    - "Bash(awk * | head *)"
    - "Bash(sort * | uniq *)"
    - "Bash(sort * | head *)"
    - "Agent"
    - "Skill"

@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md

<purpose name="ase-arch-analyze"> Review Software Architecture </purpose>

<expand name="getopt" arg1="ase-arch-analyze" arg2="--prefix|-P="> $ARGUMENTS </expand>

<objective> With the mindset of an *expert-level software architect*, *review* the *software architecture* of <getopt-arguments/>, and its directly related source code, for *potential problems* across component boundaries, structural organization, architecture principles, interface quality, quality attributes, and architecture governance. </objective>

<flow> 1. <step id="STEP 1: Investigate Code Base">

<if condition="<ase-project-boxing/> is equal `black`">

The project source artifacts are classified as a *black box*, so the user does *not* want the architecture inspected or its findings surfaced. *Skip* the entire investigation and reporting: do *not* invoke any `Agent` tool and do *not* read any source, only output the following <template/> and then *SKIP* the remaining steps STEP 2 through STEP 4:

<template> <ase-tpl-bullet-normal/> **ARCHITECTURE ANALYSIS**: *suppressed* (`project.boxing` is `black`) </template>

</if>

Investigate the code from an *architectural* perspective. If the code base is large, you *MUST* use the `Agent` tool (not inline work) to create multiple sub-agents to split the investigation task into appropriate chunks.

*Determine* the *target programming language* and the *declared architecture style* (if any) - e.g., Layered, Hexagonal (Ports & Adapters), Onion, Clean, CQRS, Microservices, Event-Driven, Modular Monolith - from code, project documentation, README files, or folder structure.

Investigate the following architecture quality aspects across 7 thematic blocks:

**Block 1 - Component Boundaries**:

• **SA01 COMPONENT-RESPONSIBILITY**: each component (module,

class, package) addresses exactly *one single concern* - i.e., has exactly *one reason to change*.

• **SA02 COMPONENT-GRANULARITY**: components have *appropriate

size* - neither monolithic nor fragmented.

• **SA03 COMPONENT-HIERARCHY**: components placed at the *correct

level* of the component hierarchy (system / program / module / class / function).

**Block 2 - Structural Organization**:

• **SA04 LAYERING**: *layers* (horizontal cuts) clearly

separated, named, and ranked; no upward dependencies.

• **SA05 SLICING**: *slices* (vertical cuts - e.g., feature

modules, bounded contexts) clearly separated and *cycle-free*.

• **SA06 DEPENDENCY-DIRECTION**: dependencies flow in exactly

*one direction*; no *circular dependencies*.

• **SA07 REFERENCE-ARCHITECTURE**: *declared-style conformance* -

the chosen architecture style (see STEP 1 intro for the recognized style list) is applied *consistently* throughout the codebase, without accidental mixing of styles.

**Block 3 - Architecture Principles**:

• **SA08 COUPLING**: *loose data coupling* between components -

no *concrete-type dependencies* where abstractions exist, no shared data structures leaking across boundaries,