# Ase Arch Analyze > Review software architecture, including package cohesion and inter-package coupling - **Type:** Skill - **Install:** `agentstack add skill-rse-ase-ase-arch-analyze` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [rse](https://agentstack.voostack.com/s/rse) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [rse](https://github.com/rse) - **Source:** https://github.com/rse/ase/tree/master/plugin/skills/ase-arch-analyze - **Website:** https://ase.tools ## Install ```sh agentstack add skill-rse-ase-ase-arch-analyze ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About @${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md Review Software Architecture $ARGUMENTS With the mindset of an *expert-level software architect*, *review* the *software architecture* of , and its directly related source code, for *potential problems* across component boundaries, structural organization, architecture principles, interface quality, quality attributes, and architecture governance. 1. 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, communication via defined ports / facades / DTOs. (Runtime coupling such as races and shared mutable state is covered by SA17.) - **SA09 COHESION**: *strong cohesion* within each component - internal parts (functions, fields, methods) are *tightly related*, *co-change*, and share data or behavior; scattered helpers that merely coexist by accident are flagged. - **SA10 EXTENSIBILITY**: components are *open for extension* (plugins, SPIs, hooks) but *closed for modification*. - **SA11 SEPARATION**: *cross-cutting concerns* (logging, security, caching, transactions, tracing) isolated from domain logic; trace context propagated across component boundaries. - **SA12 ENCAPSULATION**: unavoidable complexity *encapsulated* behind a simple interface that *shields* its implementation details. **Block 4 - Interface Quality**: - **SA13 INTERFACE-SIZE**: each interface *proportional in size* to its functionality. - **SA14 INTERFACE-COMPOSABILITY**: interface methods are *orthogonal* and enable combinatorial use-cases without boilerplate. - **SA15 INTERFACE-CONTRACT**: each interface declares clear *syntactic* and *semantic* contracts (pre/post-conditions, invariants, idempotency, thread-safety). **Block 5 - Quality Attributes**: - **SA16 TESTABILITY**: architectural *seams* enable testing in isolation - dependency injection at component boundaries, mockable interfaces, side effects (DB, filesystem, network, time, randomness) hidden behind abstractions. - **SA17 CONCURRENCY**: the *concurrency model* (event loop, threads, goroutines, async/await, actors, ...) is *explicitly chosen* and applied *consistently*. *Runtime coupling* - thread-safety boundaries, shared mutable state, races, lock hold times, async/sync boundaries - is explicit and localized; shared mutable state is protected. **Block 6 - Architecture Governance**: - **SA18 DECISION-RECORDS**: non-trivial architectural decisions are *documented* with rationale (Architecture Decision Records / ADRs, README sections, or in-code comments capturing *why*). The chosen style, deviations from defaults, and trade-offs are traceable. **Block 7 - Package Cohesion**: - **SA19 PACKAGE-COHESION**: each first-party package has a coherent role *and* topical theme - its members serve a common purpose, share a dominant noun-cluster, and have non-trivial cross-package use. Flag: - *grab-bag*: members split into ≥3 unrelated topical clusters (e.g. a `util` package mixing date-parsing, network-retry, and string-formatting helpers) - *misplaced class*: a class only imported once cross-package but referenced *≥3 times* inside the consumer (likely belongs in the consumer or in a shared utility package) - *topical outlier*: a class whose name-tokens share * 2. Render the *discovered architecture* as a concise *diagram* so the user can verify what you understood as the architecture before reading the findings. Use the following output : 📐 **ARCHITECTURE OVERVIEW** *Detected style*: *Target language*: Hints: - For , name the detected architecture style or "*undeclared*" if none is documented. - For , build a Mermaid specification for a `flowchart TB` of the high-level component or layer structure and dispatch the rendering to the `ase-meta-diagram` sub-agent by calling the tool `Agent(name: "ase-meta-diagram", description: "Diagram Rendering", subagent_type: "ase:ase-meta-diagram", prompt: )`, using its returned fenced code block verbatim. Show layers / slices / major components and their dependency direction. - Mark detected *anomalies* directly in the Mermaid source. Because `!` and `?` are Mermaid special characters, *always quote* anomaly-bearing node labels: - *Problem node* - prefix label with `!` inside quotes: `A["!ComponentA"]`. - *Unclear node* - suffix label with `(?)` inside quotes: `B["ComponentB (?)"]`. - *Cyclic edge* - annotate the *edge* (not a node) with a `cycle` label on a bidirectional arrow: `A B` (or two labelled one-way edges if the renderer rejects ``). The renderer preserves these glyphs verbatim inside the boxes and along the edges. 3. Before reporting, classify every finding into one of three categories: - *Unpaired* - single aspect violated, no partner in the tension matrix hit → emit `PROBLEM` template. - *Paired* - exactly two aspects of a single tension pair hit → emit `TRADEOFF` template (cluster of size 2). - *Clustered* - an aspect appears in *multiple* triggered tensions (e.g., SA10 hit against both SA12 and SA13) → collapse into *one* `TRADEOFF` with the recurring aspect as *focal aspect* and the others as *partners*. One direction for the whole cluster. **Tension matrix** (use to detect paired/clustered findings): ``` ┌─────────────┬───────────────────────────────────────────────┐ │ Pair │ Tension │ ├─────────────┼───────────────────────────────────────────────┤ │ SA01 ↔ SA02 │ single concern/responsibility vs. granularity │ │ SA08 ↔ SA09 │ loose coupling vs. strong cohesion │ │ SA10 ↔ SA12 │ extensibility vs. encapsulation │ │ SA10 ↔ SA13 │ extensibility vs. interface size │ │ SA11 ↔ SA08 │ cross-cutting separation vs. coupling │ │ SA12 ↔ SA14 │ encapsulation vs. composability │ │ SA16 ↔ SA12 │ testability vs. encapsulation │ │ SA16 ↔ SA13 │ testability vs. interface size │ │ SA05 ↔ SA09 │ slice cycle-freeness vs. cohesion │ │ SA06 ↔ SA10 │ single dependency direction vs. extensibility │ └─────────────┴───────────────────────────────────────────────┘ ``` Report each unpaired finding with the following : **PROBLEM** P (Severity: , Aspect: ): **** Report each paired or clustered finding with the following : **TRADEOFF** T (Severity: ): **** - *Focal aspect*: - - *In tension with*: **RECOMMENDED**: lean toward ** *Reason*: *Implies*: - : - ... For each partner in , repeat the `*Implies*` line, set to the partner aspect, and set to its brief implication. Set to the aspect direction the recommendation favors (the *focal aspect* or the *partners*). Hints: - For the final results, do *not* output anything else, especially do *not* give any further explanations or information. - For , and every entry in , name the aspect (e.g., `SA06 DEPENDENCY-DIRECTION`). - The is the aspect that participates in *all* tensions of the cluster. In a size-2 cluster both aspects participate equally in the single tension, so this rule cannot disambiguate; instead pick the focal aspect by the first applicable tiebreaker: (1) the aspect whose direction is more constrained by the detected style; else (2) the aspect carrying the *higher* finding severity; else (3) the aspect listed *first* in the tension matrix pair. - *Brevity and precision*: all free-form placeholders (, , partner-implications) are *very brief* but *precise*. is exactly *one sentence* grounded in the detected style, domain constraints, or language idioms - never generic principles. - Highlight *code* as `` and *key aspects* as **. - Add inline *references* to related code positions in the form of either (`:`), (`:-`) or (`#`). - Classify each finding with a of LOW, MEDIUM, HIGH, or ACCEPTED. Use ACCEPTED when the contract-already-addressed check applies (see skill meta rules on Findings). - *Per-aspect consistency (mandatory)*: every aspect may appear in *at most one* output. Collapse both halves of a hit tension pair into a single TRADEOFF; if an aspect participates in *multiple* hit tensions, collapse all of them into one clustered TRADEOFF with that aspect as the focal aspect. Never emit contradictory recommendations for the same aspect, and never emit both halves of a tension pair as separate PROBLEMs. - *Additionally*, persist all reported findings in a *single* `ase_kv_batch` call to the `ase` MCP server with `transactional` set to `true`. The `commands` parameter array of this call starts with one `{ command: "clear", prefix: "ase-issue-" }` entry (which removes only the previously persisted `ase-issue-*` keys, leaving any unrelated keys in the shared store intact), followed by one `{ command: "set", key: "ase-issue-P", val: ": " }` entry per reported PROBLEM and one `{ command: "set", key: "ase-issue-T", val: ": " }` entry per reported TRADEOFF. 4. Finally, output the following to give a final hint: ⧉ **ASE**: ↪ hint: **For deeper analysis, suggestions on solution approaches and then final source code changes, use `/ase-code-resolve P{n}` or `/ase-code-resolve T{n}` in the same or even a different session.** ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [rse](https://github.com/rse) - **Source:** [rse/ase](https://github.com/rse/ase) - **License:** Apache-2.0 - **Homepage:** https://ase.tools Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-rse-ase-ase-arch-analyze - Seller: https://agentstack.voostack.com/s/rse - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.