archlens-install-policy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Archlens Policy & Companion Installer (
archlens-install-policy
)

Archlens 策略与 Companion 安装器 (
archlens-install-policy
)

Use this skill to initialize Clean Architecture governance in any target software project for the Archlens Dynamic Clean Architecture Workbench.
This skill analyzes the project build system and directory layout, infers common package prefixes, organizes architectural packages into concentric rings, generates
.archlens/policy.json
, configures workbench connectivity, and equips AI coding assistants (Claude Code, Gemini CLI, Google Antigravity) with mailbox refactoring protocols.

使用此 skill 为任意目标软件项目初始化 Clean Architecture 治理,以接入 Archlens 动态 Clean Architecture 工作台。
此 skill 分析项目的构建系统和目录布局,推断常见的包前缀,将架构包组织为同心层级,生成
.archlens/policy.json
,配置工作台连接,并为 AI 编程助手(Claude Code、Gemini CLI、Google Antigravity)配备 mailbox 重构协议。

🎯 When to Use This Skill

🎯 何时使用此 skill

Trigger this skill whenever the user asks to:
  • "Install Archlens policy in this project"
  • "Setup Archlens" or "Configure Clean Architecture policy"
  • "Initialize .archlens/policy.json"
  • "Upgrade Archlens config from .uml-viewer to .archlens"
  • "Connect repository to Archlens workbench"
  • "Prepare this repository for Archlens refactoring companion"
  • "Export LLM refactoring prompt / Clean Architecture diagnostic dossier"
  • "Generate prompt for Claude Code or LLM to fix Clean Architecture violations"

当用户提出以下请求时,触发此 skill:
  • "在此项目中安装 Archlens 策略"
  • "设置 Archlens"或"配置 Clean Architecture 策略"
  • "初始化 .archlens/policy.json"
  • "将 Archlens 配置从 .uml-viewer 升级到 .archlens"
  • "将仓库连接到 Archlens 工作台"
  • "为此仓库准备 Archlens 重构 companion"
  • "导出 LLM 重构提示词 / Clean Architecture 诊断档案"
  • "为 Claude Code 或 LLM 生成修复 Clean Architecture 违规问题的提示词"

📋 Core Deliverables

📋 核心交付物

When executed, this skill generates the following artifacts in the target project root:
  1. .archlens/policy.json
    :
    • Declares the project title, source root, and common package prefix.
    • Organizes discovered packages into concentric tiers:
      • Level 0 (Domain Core): Entities, value objects, domain logic (
        domain
        ,
        model
        ,
        entities
        ,
        core
        ).
      • Level 1 (Application): Use cases, interaction services, application ports (
        usecase
        ,
        application
        ,
        service
        ,
        port
        ).
      • Level 2 (Adapters): Controllers, presenters, gateways, repository implementations (
        adapter
        ,
        controller
        ,
        gateway
        ,
        presenter
        ,
        repository
        ,
        dto
        ).
      • Level 3 (Infrastructure): Databases, web frameworks, persistence drivers, configuration (
        infrastructure
        ,
        config
        ,
        db
        ,
        web
        ).
  2. .archlens/workbench.config.json
    :
    • Configures the Archlens server URL (
      http://localhost:8088
      ) and mailbox version.
  3. CLAUDE.md
    and
    AGENTS.md
    :
    • Injects the Clean Architecture Companion Protocol to instruct agents how to handle inbound mailbox tasks (
      REGEN
      ,
      APPLY_PROPOSAL
      ,
      REFRESH_CRAP
      ) and enforce the Dependency Inversion Principle.
[!NOTE] Backward Compatibility: Projects with existing
.uml-viewer/
configurations continue to function without modification. Upgrading to
.archlens/
is recommended for standard alignment.

执行此 skill 后,会在目标项目根目录生成以下产物:
  1. .archlens/policy.json
    :
    • 声明项目标题、源码根目录和公共包前缀。
    • 将发现的包划分为以下同心层级:
      • Level 0 (Domain Core):实体、值对象、领域逻辑(
        domain
        、
        model
        、
        entities
        、
        core
        )。
      • Level 1 (Application):用例、交互服务、应用端口(
        usecase
        、
        application
        、
        service
        、
        port
        )。
      • Level 2 (Adapters):控制器、演示器、网关、仓储实现(
        adapter
        、
        controller
        、
        gateway
        、
        presenter
        、
        repository
        、
        dto
        )。
      • Level 3 (Infrastructure):数据库、Web 框架、持久化驱动、配置(
        infrastructure
        、
        config
        、
        db
        、
        web
        )。
  2. .archlens/workbench.config.json
    :
    • 配置 Archlens 服务器 URL(
      http://localhost:8088
      )和 mailbox 版本。
  3. CLAUDE.md
    和
    AGENTS.md
    :
    • 注入 Clean Architecture Companion Protocol,指示 Agent 如何处理入站 mailbox 任务(
      REGEN
      、
      APPLY_PROPOSAL
      、
      REFRESH_CRAP
      ),并强制执行 Dependency Inversion Principle。
[!NOTE] 向后兼容性:带有现有
.uml-viewer/
配置的项目无需修改即可继续使用。建议升级到
.archlens/
,以实现标准化对齐。

🛠️ Execution Instructions for Agents

🛠️ Agent 执行说明

Step 1: Run the Archlens Installer or Upgrader

第 1 步:运行 Archlens 安装器或升级器

Execute the cross-platform CLI via NPX against the target repository:
bash
undefined
通过 NPX 针对目标仓库执行跨平台 CLI:
bash
undefined

Initialize a new project with defaults

Initialize a new project with defaults

npx @fmatar/archlens-skill --path . --yes
npx @fmatar/archlens-skill --path . --yes

Or upgrade an existing project from .uml-viewer to .archlens

Or upgrade an existing project from .uml-viewer to .archlens

npx @fmatar/archlens-skill upgrade --path .
npx @fmatar/archlens-skill upgrade --path .

Or export LLM Refactoring Prompt Dossier (copy-ready markdown)

Or export LLM Refactoring Prompt Dossier (copy-ready markdown)

npx @fmatar/archlens-skill prompt --path .
npx @fmatar/archlens-skill prompt --path .

Copy LLM Refactoring Prompt directly to system clipboard

Copy LLM Refactoring Prompt directly to system clipboard

npx @fmatar/archlens-skill prompt --path . --copy

*Flags available:*
- `--path <DIR>`: Target project directory (defaults to current directory).
- `--title <NAME>`: Custom project display title.
- `--prefix <PKG>`: Explicit package prefix (e.g. `com.mycompany.service`).
- `--server-url <URL>`: Archlens workbench endpoint (defaults to `http://localhost:8088`).
- `--update`: Re-scans code for new packages and updates existing policy.
- `--upgrade`: Migrates legacy `.uml-viewer/` configuration and mailboxes to `.archlens/`.
- `--force`: Overwrite existing `.archlens/policy.json` if present.

Alternatively, agents can run the bundled Python script:
```bash
python3 scripts/init_policy.py --path .
npx @fmatar/archlens-skill prompt --path . --copy

*可用参数:*
- `--path <DIR>`:目标项目目录(默认为当前目录)。
- `--title <NAME>`:自定义项目显示标题。
- `--prefix <PKG>`:显式指定包前缀(例如 `com.mycompany.service`)。
- `--server-url <URL>`:Archlens 工作台端点(默认为 `http://localhost:8088`)。
- `--update`:重新扫描代码中的新包并更新现有策略。
- `--upgrade`:将旧版 `.uml-viewer/` 配置和 mailbox 迁移到 `.archlens/`。
- `--force`:覆盖已存在的 `.archlens/policy.json`。

或者,Agent 可以运行自带的 Python 脚本:
```bash
python3 scripts/init_policy.py --path .

Or upgrade:

Or upgrade:

python3 scripts/init_policy.py --path . --upgrade
undefined
python3 scripts/init_policy.py --path . --upgrade
undefined

Step 2: Review Generated Policy

第 2 步:审查生成的策略

Inspect the generated
.archlens/policy.json
to confirm the packages align with the developer's architecture intent. If the project uses custom domain terminology, adjust the
levels
array accordingly.
检查生成的
.archlens/policy.json
,确认各包与开发者的架构意图一致。如果项目使用自定义领域术语,请相应调整
levels
数组。

Step 3: Verify with Archlens Workbench

第 3 步:使用 Archlens 工作台进行验证

Once configured, developers can open the project in the visual workbench:
text
http://localhost:8088/?projectRoot=<ABSOLUTE_PATH_TO_PROJECT>
Or open Archlens and use
⌘O
/
Ctrl+O
to select the project via the visual filesystem explorer.
配置完成后,开发者可以在可视化工作台中打开项目:
text
http://localhost:8088/?projectRoot=<ABSOLUTE_PATH_TO_PROJECT>
也可以打开 Archlens,使用
⌘O
/
Ctrl+O
通过可视化文件系统浏览器选择项目。