Archlens — Clean Architecture Governance & Workbench Companion

1. Enforce Uncle Bob's Dependency Rule (dependencies strictly point inward).
2. Scaffold and maintain

   .archlens/policy.json

   architectural layer policies.
3. Act as the autonomous refactoring companion to the visual workbench via mailbox queues (

   .archlens/to-agent.json

   and

   .archlens/to-viewer.json

   ).
4. Export LLM Refactoring Prompt Dossiers prescribing concrete Dependency Inversion Principle (DIP) interface ports.
5. Invoke Archlens MCP tools (

   inspectArchitecture

   ,

   exportLlmDossier

   ,

   listSnapshots

   ,

   getSnapshot

   ).

🏛️ Clean Architecture Concentric Layer Hierarchy

[Level 3: Infrastructure / Web / DB / CLI]
       │
       ▼
[Level 2: Adapters / Controllers / Presenters / Gateways]
       │
       ▼
[Level 1: Application / Use Cases / Ports]
       │
       ▼
[Level 0: Domain Core / Entities / Value Objects]

• Level 0 (Domain Core): Pure business entities, primitives, domain logic. Zero outward imports or dependencies on frameworks, databases, or UI.
• Level 1 (Application): Use cases, interaction orchestrators, domain ports. Depends only on Domain Core (Level 0).
• Level 2 (Adapters): HTTP controllers, presenters, REST resources, repository implementations. Translates between external formats and application models.
• Level 3 (Infrastructure): Web frameworks, databases, persistence drivers, third-party libraries, CLI entrypoints, configuration.

[!IMPORTANT] Dependency Inversion Principle (DIP): When an inner layer (e.g. Domain or Application) needs a service provided by an outer layer (e.g. Database or External API), declare an interface port in the inner layer. Implement the interface in the outer layer (Adapter), and inject it.

⚡ CLI & Quickstart Commands

skills.sh

# Add Archlens to your active agent skills library:
npx skills add fmatar/archlens

# Initialize Clean Architecture policy in target project:
npx @fmatar/archlens-skill --path . --yes

# Launch Workbench container (auto-resurrects on demand if stopped or killed):
npx @fmatar/archlens-skill start --open

# Export Clean Architecture LLM Refactoring Prompt Dossier:
npx @fmatar/archlens-skill prompt --path .

# Copy LLM refactoring prompt directly to system clipboard:
npx @fmatar/archlens-skill prompt --path . --copy

# Synchronize policy with newly added packages:
npx @fmatar/archlens-skill update --path .

# Migrate legacy .uml-viewer configuration to modern .archlens layout:
npx @fmatar/archlens-skill upgrade --path .

# Auto-configure MCP manifests for AI assistants (Antigravity, Claude, Cursor):
npx @fmatar/archlens-skill --mcp

# Launch Model Context Protocol (MCP) stdio server:
npx @fmatar/archlens-skill mcp

Launching the Workbench & Auto-Resurrection

1. Run

   npx @fmatar/archlens-skill start --open

   (or

   archlens-skill start

   ).
2. The CLI inspects whether the server is active on

   http://localhost:8088

   . If offline, it automatically auto-resurrects:
   • Native Java Runner (Default): If Java 21+ and a runner JAR (

     quarkus-run.jar

     in

     ~/.archlens/

     , project

     target/

     , or via

     --jar <PATH>

     ) are detected, it launches the native JVM server in ~0.5s with bare-metal filesystem speed.
   • Docker Container (Fallback): If Java or a local runner is absent, it automatically starts or creates the

     archlens-server

     Docker container.
   • Use

     --docker

     to force Docker mode, or

     --native

     to force native mode.
3. When using MCP tools (

   inspectArchitecture

   ,

   exportLlmDossier

   ), the stdio bridge also auto-resurrects the server if offline.

🤖 Dynamic Workbench Companion Protocol

http://localhost:8088

• Inbound queue (UI $\rightarrow$ Agent):

  .archlens/to-agent.json

  (or

  .uml-viewer/to-agent.json

  )
• Outbound events (Agent $\rightarrow$ UI):

  .archlens/to-viewer.json

  (or

  .uml-viewer/to-viewer.json

  )

Mailbox Format (

to-agent.json

)

{
  "nextId": 2,
  "queue": [
    {
      "id": 1,
      "op": "REGEN",
      "target": { "id": "project" },
      "payload": {}
    }
  ]
}

Supported Operations:

1. REGEN

   : Re-scan AST, compute violations and instability metrics, compile/test (

   mvn test-compile

   ), and notify UI via

   REGEN_COMPLETE

   .

2. APPLY_PROPOSAL

   : Read requested layers from

   .archlens/policy.json

   . Physically restructure packages to match proposed layers. Where inner layers import outer layers, apply DIP by introducing interface ports. Run test suite to verify zero regressions.

3. REFRESH_CRAP

   : Run tests with code coverage (

   mvn test

   /

   npm test

   ) and update metric snapshots.

4. REFRESH_MUTATION

   : Run mutation testing on target classes.

5. OMIT

   : Add specified package or class to the

   :omit

   list in policy.

Completing Tasks (

to-viewer.json

):

.archlens/to-viewer.json

{
  "op": "REGEN_COMPLETE",
  "target": { "id": "project" },
  "payload": { "status": "SUCCESS" }
}

🛠️ MCP Tool Suite Reference

inspectArchitecture

projectRoot

.

exportLlmDossier

projectRoot

proposalId

listSnapshots

projectRoot

getSnapshot

snapshotId

projectRoot