@fmatar/archlens-skill 0.0.1-Alpha-07 → 0.0.1-Alpha-09

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -57,6 +57,8 @@ node ./cli/bin/index.js
57
57
  - **Multi-Agent Skill Deployment**: Installs the `archlens-install-policy` skill globally into Claude Code (`~/.claude/skills/`), Gemini CLI / Antigravity (`~/.gemini/config/skills/`), and custom agent workspaces.
58
58
  - **Safe Incremental Updates**: Re-scans codebases for newly introduced packages, updating `order` and `levels` while preserving user custom rules and configurations.
59
59
  - **Seamless Upgrade Migration**: Automatically migrates legacy `.uml-viewer/` folders and companion files to modern `.archlens/` via `archlens-skill upgrade`.
60
+ - **Model Context Protocol (MCP) Client Auto-Configuration**: Detects and configures host AI client manifests (Claude Desktop, Google Antigravity, Claude Code, Cursor, VS Code) in a single command (`--mcp`).
61
+ - **On-Demand Container Orchestration & Stdio Bridge**: Automatically spins up the Archlens container when needed, bridges MCP over stdio (`mcp` command), and provides an instant offline AST fallback if Docker is unavailable.
60
62
  - **Mailbox Protocol Integration**: Injects the Clean Architecture Companion Protocol into `CLAUDE.md` and `AGENTS.md` for seamless asynchronous mailbox refactoring (`to-agent.json`, `to-viewer.json`).
61
63
 
62
64
  ---
@@ -100,16 +102,54 @@ Migrates older `.uml-viewer/` directories and companions to the standard `.archl
100
102
  npx @fmatar/archlens-skill upgrade
101
103
  ```
102
104
 
105
+ #### 6. Export LLM Refactoring Prompt Dossier
106
+ Generates copy-ready architectural diagnostics and concrete Dependency Inversion Principle (DIP) instructions for Claude Code, Gemini, ChatGPT, or Antigravity:
107
+ ```bash
108
+ # Print dossier to stdout
109
+ npx @fmatar/archlens-skill prompt
110
+
111
+ # Or copy directly to system clipboard
112
+ npx @fmatar/archlens-skill prompt --copy
113
+ ```
114
+
115
+ #### 7. Model Context Protocol (MCP) Setup & Stdio Bridge
116
+ Configures detected AI client manifests or launches an interactive stdio bridge:
117
+ ```bash
118
+ # Auto-configure Claude Desktop, Google Antigravity, Claude Code, Cursor, and VS Code
119
+ npx @fmatar/archlens-skill --mcp
120
+
121
+ # Launch MCP stdio transport bridge (spins up Docker container automatically when needed)
122
+ npx @fmatar/archlens-skill mcp
123
+ ```
124
+
125
+ #### 8. Start Workbench Container & Auto-Resurrection
126
+ Starts the Archlens container, mounts the workspace, verifies readiness, and optionally opens your browser. **If the container is killed or stopped, running `start` (or calling an MCP tool) automatically starts it again:**
127
+ ```bash
128
+ # Start container and automatically open workbench in browser:
129
+ npx @fmatar/archlens-skill start --open
130
+
131
+ # Start container in background on default port 8088:
132
+ npx @fmatar/archlens-skill start
133
+
134
+ # Specify a custom port or target workspace directory:
135
+ npx @fmatar/archlens-skill start --path /path/to/project --port 8088 --open
136
+ ```
137
+
103
138
  ---
104
139
 
105
140
  ### Command-Line Options
106
141
 
107
142
  | Flag | Shorthand | Description | Default |
108
143
  |------|-----------|-------------|---------|
144
+ | `start` | | Start Archlens Workbench container (auto-resurrects on demand) | |
145
+ | `--open` | `-o` | Open visual workbench in default browser upon startup | `false` |
146
+ | `--port <PORT>` | | Workbench HTTP port | `8088` |
109
147
  | `--path <DIR>` | `-p` | Target repository directory | `.` (current directory) |
110
148
  | `--title <NAME>` | `-t` | Project title in visual workbench | Formatted folder name |
111
149
  | `--prefix <PKG>` | | Common package prefix (e.g. `com.example.service`) | Auto-detected |
112
150
  | `--server-url <URL>` | | Visual Workbench server endpoint | `http://localhost:8088` |
151
+ | `--mcp` | `-m` | Auto-configure MCP client manifests (Claude, Antigravity, Cursor) | `false` |
152
+ | `--copy` | `-c` | Copy LLM prompt output directly to system clipboard | `false` |
113
153
  | `--global` | `-g` | Install skill into global agent directories | `false` |
114
154
  | `--update` | `-u` | Re-scan code and update existing policy | `false` |
115
155
  | `--upgrade` | | Migrate legacy `.uml-viewer` to `.archlens` | `false` |
package/bin/index.js CHANGED
@@ -11,10 +11,19 @@ import * as fs from 'node:fs';
11
11
  import { fileURLToPath } from 'node:url';
12
12
 
13
13
  import * as ui from '../src/ui.js';
14
- import { detectProjectLanguage, detectSourceRoot, findCommonPackagePrefix } from '../src/analyzer.js';
14
+ import {
15
+ detectProjectLanguage,
16
+ detectSourceRoot,
17
+ findCommonPackagePrefix,
18
+ generateLlmPrompt
19
+ } from '../src/analyzer.js';
15
20
  import { installLocalPolicy, installGlobalSkills } from '../src/installer.js';
16
21
  import { updateLocalPolicy, updateGlobalSkills } from '../src/updater.js';
17
22
  import { upgradeProject } from '../src/upgrader.js';
23
+ import { installMcpConfigs } from '../src/mcp-registry.js';
24
+ import { startMcpStdioServer } from '../src/mcp-server.js';
25
+ import { executeStart, DEFAULT_CONTAINER_NAME, DEFAULT_SERVER_URL } from '../src/docker-runner.js';
26
+ import { spawnSync } from 'node:child_process';
18
27
 
19
28
  const __filename = fileURLToPath(import.meta.url);
20
29
  const __dirname = path.dirname(__filename);
@@ -41,15 +50,22 @@ ${ui.colors.bold}USAGE:${ui.colors.reset}
41
50
 
42
51
  ${ui.colors.bold}COMMANDS:${ui.colors.reset}
43
52
  init Initialize Clean Architecture policy in target project (default)
53
+ start Start Archlens Workbench container (auto-resurrects on demand)
44
54
  update Update existing policy with newly discovered packages and refresh skills
45
55
  upgrade Upgrade legacy .uml-viewer configuration to .archlens
46
56
  global Install Archlens skills globally for AI coding assistants
57
+ prompt Export Clean Architecture LLM Refactoring Prompt Dossier
58
+ mcp Launch Model Context Protocol (MCP) stdio server for AI assistants
47
59
 
48
60
  ${ui.colors.bold}OPTIONS:${ui.colors.reset}
49
61
  -p, --path <DIR> Target repository path (default: current directory)
50
62
  -t, --title <NAME> Project title displayed in Archlens workbench
51
63
  --prefix <PKG> Common package prefix (e.g. com.example.app)
52
64
  --server-url <URL> Archlens visual workbench URL (default: http://localhost:8088)
65
+ --port <PORT> Workbench HTTP port (default: 8088)
66
+ -o, --open Open visual workbench in default browser upon startup
67
+ -m, --mcp Auto-configure MCP server manifests in AI clients (Claude, Antigravity, Cursor)
68
+ -c, --copy Copy LLM prompt output directly to system clipboard
53
69
  -g, --global Install or update skill globally in ~/.claude and ~/.gemini
54
70
  -u, --update Update mode: sync new packages into existing policy
55
71
  --upgrade Upgrade mode: migrate .uml-viewer to .archlens
@@ -60,6 +76,20 @@ ${ui.colors.bold}OPTIONS:${ui.colors.reset}
60
76
  -h, --help Display this help guide
61
77
 
62
78
  ${ui.colors.bold}EXAMPLES:${ui.colors.reset}
79
+ ${ui.colors.dim}# Start Archlens workbench container and open in browser:${ui.colors.reset}
80
+ npx @fmatar/archlens-skill start --open
81
+ ${ui.colors.dim}# Configure MCP manifests across Claude, Antigravity, and Cursor:${ui.colors.reset}
82
+ npx @fmatar/archlens-skill --mcp
83
+
84
+ ${ui.colors.dim}# Launch MCP stdio bridge server for AI coding assistants:${ui.colors.reset}
85
+ npx @fmatar/archlens-skill mcp
86
+
87
+ ${ui.colors.dim}# Export Clean Architecture LLM Refactoring Prompt to stdout:${ui.colors.reset}
88
+ npx @fmatar/archlens-skill prompt
89
+
90
+ ${ui.colors.dim}# Copy prompt directly to system clipboard:${ui.colors.reset}
91
+ npx @fmatar/archlens-skill prompt --copy
92
+
63
93
  ${ui.colors.dim}# Interactive setup wizard:${ui.colors.reset}
64
94
  npx @fmatar/archlens-skill
65
95
 
@@ -84,9 +114,15 @@ function parseArgs(args) {
84
114
  title: null,
85
115
  prefix: null,
86
116
  serverUrl: 'http://localhost:8088',
117
+ port: '8088',
118
+ open: false,
119
+ start: false,
120
+ copy: false,
121
+ prompt: false,
87
122
  global: false,
88
123
  update: false,
89
124
  upgrade: false,
125
+ mcp: false,
90
126
  force: false,
91
127
  dryRun: false,
92
128
  yes: false,
@@ -103,12 +139,22 @@ function parseArgs(args) {
103
139
  parsed.help = true;
104
140
  } else if (arg === '--version' || arg === '-v') {
105
141
  parsed.version = true;
142
+ } else if (arg === '--open' || arg === '-o') {
143
+ parsed.open = true;
144
+ } else if (arg === '--port') {
145
+ parsed.port = args[++i] || '8088';
146
+ } else if (arg === '--mcp' || arg === '-m') {
147
+ parsed.mcp = true;
106
148
  } else if (arg === '--global' || arg === '-g') {
107
149
  parsed.global = true;
108
150
  } else if (arg === '--update' || arg === '-u') {
109
151
  parsed.update = true;
110
152
  } else if (arg === '--upgrade') {
111
153
  parsed.upgrade = true;
154
+ } else if (arg === '--prompt') {
155
+ parsed.prompt = true;
156
+ } else if (arg === '--copy' || arg === '-c') {
157
+ parsed.copy = true;
112
158
  } else if (arg === '--force' || arg === '-f') {
113
159
  parsed.force = true;
114
160
  } else if (arg === '--dry-run') {
@@ -130,7 +176,7 @@ function parseArgs(args) {
130
176
 
131
177
  if (positional.length > 0) {
132
178
  const cmd = positional[0].toLowerCase();
133
- if (['init', 'update', 'upgrade', 'global', 'help', 'version'].includes(cmd)) {
179
+ if (['init', 'start', 'update', 'upgrade', 'global', 'prompt', 'mcp', 'help', 'version'].includes(cmd)) {
134
180
  parsed.command = cmd;
135
181
  } else if (!parsed.title && !parsed.path) {
136
182
  parsed.path = positional[0];
@@ -139,9 +185,12 @@ function parseArgs(args) {
139
185
 
140
186
  if (parsed.command === 'help') parsed.help = true;
141
187
  if (parsed.command === 'version') parsed.version = true;
188
+ if (parsed.command === 'start') parsed.start = true;
142
189
  if (parsed.command === 'update') parsed.update = true;
143
190
  if (parsed.command === 'upgrade') parsed.upgrade = true;
144
191
  if (parsed.command === 'global') parsed.global = true;
192
+ if (parsed.command === 'prompt') parsed.prompt = true;
193
+ if (parsed.command === 'mcp') parsed.mcp = true;
145
194
 
146
195
  return parsed;
147
196
  }
@@ -175,8 +224,13 @@ async function runInteractive(options) {
175
224
  },
176
225
  {
177
226
  value: 'both',
178
- label: `${ui.colors.bold}Full Suite (Local Policy + Global Skills)${ui.colors.reset}`,
179
- description: 'Configures current repository and installs global AI assistant skills'
227
+ label: `${ui.colors.bold}Full Suite (Local Policy + Global Skills + MCP)${ui.colors.reset}`,
228
+ description: 'Configures repository, global AI skills, and Model Context Protocol manifests'
229
+ },
230
+ {
231
+ value: 'mcp',
232
+ label: `${ui.colors.bold}Configure Model Context Protocol (MCP)${ui.colors.reset}`,
233
+ description: 'Register Archlens MCP tools into Claude Desktop, Antigravity, and Cursor'
180
234
  },
181
235
  {
182
236
  value: 'update',
@@ -214,6 +268,10 @@ async function runInteractive(options) {
214
268
  executeGlobalInstall(execOptions);
215
269
  }
216
270
 
271
+ if (selectedAction === 'mcp' || selectedAction === 'both') {
272
+ executeMcpInstall(execOptions);
273
+ }
274
+
217
275
  if (selectedAction === 'update') {
218
276
  executeUpdate(targetRoot, execOptions);
219
277
  }
@@ -225,6 +283,20 @@ async function runInteractive(options) {
225
283
  printCompletionMessage(targetRoot, execOptions.serverUrl);
226
284
  }
227
285
 
286
+ function executeMcpInstall(options) {
287
+ const modeSuffix = options.dryRun ? ' (dry run)' : '';
288
+ ui.step(3, 3, `Configuring Model Context Protocol (MCP) Clients${modeSuffix}`);
289
+ const result = installMcpConfigs(options);
290
+
291
+ if (result.configuredClients.length === 0) {
292
+ ui.warn('No active AI client configurations found (~/.claude, ~/.gemini). Use --force to deploy anyway.');
293
+ } else {
294
+ for (const client of result.configuredClients) {
295
+ ui.success(`Configured MCP for ${client.name} (${client.action}): ${client.path}${modeSuffix}`);
296
+ }
297
+ }
298
+ }
299
+
228
300
  function executeLocalInit(targetRoot, options) {
229
301
  ui.step(1, 2, 'Scaffolding Clean Architecture Policy');
230
302
  const result = installLocalPolicy(targetRoot, options);
@@ -316,6 +388,26 @@ function printCompletionMessage(targetRoot, serverUrl) {
316
388
  console.log(` 3. Or press ${ui.colors.bold}⌘O / Ctrl+O${ui.colors.reset} inside Archlens to select this workspace.\n`);
317
389
  }
318
390
 
391
+ function copyToSystemClipboard(text) {
392
+ try {
393
+ if (process.platform === 'darwin') {
394
+ spawnSync('pbcopy', { input: text, encoding: 'utf8' });
395
+ return true;
396
+ } else if (process.platform === 'win32') {
397
+ spawnSync('clip', { input: text, encoding: 'utf8' });
398
+ return true;
399
+ } else {
400
+ const res = spawnSync('xclip', ['-selection', 'clipboard'], { input: text, encoding: 'utf8' });
401
+ if (res.error) {
402
+ spawnSync('wl-copy', { input: text, encoding: 'utf8' });
403
+ }
404
+ return true;
405
+ }
406
+ } catch {
407
+ return false;
408
+ }
409
+ }
410
+
319
411
  async function main() {
320
412
  const options = parseArgs(process.argv.slice(2));
321
413
 
@@ -329,15 +421,75 @@ async function main() {
329
421
  process.exit(0);
330
422
  }
331
423
 
424
+ if (options.command === 'prompt' || options.prompt) {
425
+ const targetRoot = path.resolve(options.path || '.');
426
+ try {
427
+ const dossier = await generateLlmPrompt(targetRoot, options);
428
+ if (options.copy) {
429
+ const ok = copyToSystemClipboard(dossier);
430
+ if (ok) {
431
+ ui.success('Clean Architecture Refactoring Dossier copied to system clipboard!');
432
+ } else {
433
+ process.stdout.write(dossier);
434
+ }
435
+ } else {
436
+ process.stdout.write(dossier);
437
+ }
438
+ process.exit(0);
439
+ } catch (err) {
440
+ ui.error(err.message || String(err));
441
+ process.exit(1);
442
+ }
443
+ }
444
+
445
+ if (options.command === 'mcp') {
446
+ startMcpStdioServer({
447
+ version: getPackageVersion(),
448
+ ...options
449
+ });
450
+ return;
451
+ }
452
+
453
+ if (options.command === 'start' || options.start) {
454
+ try {
455
+ const port = options.port || '8088';
456
+ const targetUrl = options.serverUrl || (port === '8088' ? DEFAULT_SERVER_URL : `http://localhost:${port}`);
457
+ ui.info(`Checking Archlens Workbench server on ${targetUrl}...`);
458
+ const status = await executeStart(options);
459
+ if (status.status === 'running') {
460
+ if (status.spawned) {
461
+ ui.success(`Archlens container (${DEFAULT_CONTAINER_NAME}) launched successfully!`);
462
+ } else {
463
+ ui.success(`Archlens Workbench server is active (${status.version || 'running'}).`);
464
+ }
465
+ console.log(`\n ${ui.colors.bold}Workbench URL:${ui.colors.reset} ${ui.colors.cyan}${status.serverUrl}${ui.colors.reset}\n`);
466
+ } else if (status.status === 'offline') {
467
+ ui.warn(status.message || 'Archlens server is offline and Docker daemon is unavailable.');
468
+ console.log(`\n ${ui.colors.dim}To run offline architecture analysis:${ui.colors.reset}`);
469
+ console.log(` npx @fmatar/archlens-skill prompt\n`);
470
+ } else {
471
+ ui.error(status.message || 'Failed to start Archlens container.');
472
+ process.exit(1);
473
+ }
474
+ process.exit(0);
475
+ } catch (err) {
476
+ ui.error(err.message || String(err));
477
+ process.exit(1);
478
+ }
479
+ }
480
+
332
481
  const isInteractive = Boolean(
333
482
  process.stdin.isTTY &&
334
483
  process.stdout.isTTY &&
335
484
  !options.yes &&
336
485
  !options.dryRun &&
337
486
  !options.command &&
487
+ !options.start &&
338
488
  !options.global &&
339
489
  !options.update &&
340
- !options.upgrade
490
+ !options.upgrade &&
491
+ !options.prompt &&
492
+ !options.mcp
341
493
  );
342
494
 
343
495
  if (isInteractive) {
@@ -367,6 +519,10 @@ async function main() {
367
519
  executeLocalInit(targetRoot, options);
368
520
  }
369
521
 
522
+ if (options.mcp) {
523
+ executeMcpInstall(options);
524
+ }
525
+
370
526
  if (!options.dryRun) {
371
527
  printCompletionMessage(targetRoot, options.serverUrl);
372
528
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fmatar/archlens-skill",
3
- "version": "0.0.1-Alpha-07",
3
+ "version": "0.0.1-Alpha-09",
4
4
  "description": "Cross-platform CLI and installer for Archlens Clean Architecture governance policies and AI assistant skills",
5
5
  "main": "src/installer.js",
6
6
  "type": "module",
@@ -0,0 +1,139 @@
1
+ ---
2
+ name: archlens
3
+ description: >-
4
+ Polyglot Clean Architecture governance, dynamic visual workbench companion,
5
+ policy scaffolding, mailbox refactoring protocols, LLM prompt dossiers,
6
+ and Model Context Protocol (MCP) diagnostics for Archlens.
7
+ version: 1.2.0
8
+ license: Apache-2.0
9
+ ---
10
+
11
+ # Archlens — Clean Architecture Governance & Workbench Companion
12
+
13
+ Use this skill when analyzing, governing, or refactoring codebases using **Archlens (Dynamic Clean Architecture Workbench)**.
14
+
15
+ This skill equips agents (Antigravity, Gemini CLI, Claude Code) to:
16
+ 1. Enforce Uncle Bob's **Dependency Rule** (dependencies strictly point inward).
17
+ 2. Scaffold and maintain `.archlens/policy.json` architectural layer policies.
18
+ 3. Act as the autonomous refactoring companion to the visual workbench via mailbox queues (`.archlens/to-agent.json` and `.archlens/to-viewer.json`).
19
+ 4. Export LLM Refactoring Prompt Dossiers prescribing concrete Dependency Inversion Principle (DIP) interface ports.
20
+ 5. Invoke Archlens MCP tools (`inspectArchitecture`, `exportLlmDossier`, `listSnapshots`, `getSnapshot`).
21
+
22
+ ---
23
+
24
+ ## 🏛️ Clean Architecture Concentric Layer Hierarchy
25
+
26
+ Archlens models codebases as concentric circular rings. Source code dependencies (imports, inheritance, calls) MUST point strictly inward:
27
+
28
+ ```
29
+ [Level 3: Infrastructure / Web / DB / CLI]
30
+ │
31
+ ▼
32
+ [Level 2: Adapters / Controllers / Presenters / Gateways]
33
+ │
34
+ ▼
35
+ [Level 1: Application / Use Cases / Ports]
36
+ │
37
+ ▼
38
+ [Level 0: Domain Core / Entities / Value Objects]
39
+ ```
40
+
41
+ - **Level 0 (Domain Core)**: Pure business entities, primitives, domain logic. Zero outward imports or dependencies on frameworks, databases, or UI.
42
+ - **Level 1 (Application)**: Use cases, interaction orchestrators, domain ports. Depends only on Domain Core (Level 0).
43
+ - **Level 2 (Adapters)**: HTTP controllers, presenters, REST resources, repository implementations. Translates between external formats and application models.
44
+ - **Level 3 (Infrastructure)**: Web frameworks, databases, persistence drivers, third-party libraries, CLI entrypoints, configuration.
45
+
46
+ > [!IMPORTANT]
47
+ > **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.
48
+
49
+ ---
50
+
51
+ ## ⚡ CLI & Quickstart Commands
52
+
53
+ Archlens is executed cross-platform via NPX or Node CLI:
54
+
55
+ ```bash
56
+ # Initialize Clean Architecture policy in target project:
57
+ npx @fmatar/archlens-skill --path . --yes
58
+
59
+ # Launch Workbench container (auto-resurrects on demand if stopped or killed):
60
+ npx @fmatar/archlens-skill start --open
61
+
62
+ # Export Clean Architecture LLM Refactoring Prompt Dossier:
63
+ npx @fmatar/archlens-skill prompt --path .
64
+
65
+ # Copy LLM refactoring prompt directly to system clipboard:
66
+ npx @fmatar/archlens-skill prompt --path . --copy
67
+
68
+ # Synchronize policy with newly added packages:
69
+ npx @fmatar/archlens-skill update --path .
70
+
71
+ # Migrate legacy .uml-viewer configuration to modern .archlens layout:
72
+ npx @fmatar/archlens-skill upgrade --path .
73
+
74
+ # Auto-configure MCP manifests for AI assistants (Antigravity, Claude, Cursor):
75
+ npx @fmatar/archlens-skill --mcp
76
+
77
+ # Launch Model Context Protocol (MCP) stdio server:
78
+ npx @fmatar/archlens-skill mcp
79
+ ```
80
+
81
+ ### Launching the Workbench & Auto-Resurrection
82
+ When the user asks to start Archlens, launch the studio, or open the visual workbench:
83
+ 1. Run `npx @fmatar/archlens-skill start --open` (or `archlens-skill start`).
84
+ 2. The CLI inspects whether the container (`archlens-server`) is active. If stopped or killed, it immediately starts it again on demand and confirms readiness at `http://localhost:8088`.
85
+ 3. When using MCP tools (`inspectArchitecture`, `exportLlmDossier`), the stdio bridge also auto-resurrects the container if offline.
86
+
87
+ ---
88
+
89
+ ## 🤖 Dynamic Workbench Companion Protocol
90
+
91
+ Archlens provides a real-time visual canvas (`http://localhost:8088`). When human architects interact with the UI, tasks are dispatched through a bidirectional mailbox IPC protocol:
92
+
93
+ - **Inbound queue (UI $\rightarrow$ Agent)**: `.archlens/to-agent.json` (or `.uml-viewer/to-agent.json`)
94
+ - **Outbound events (Agent $\rightarrow$ UI)**: `.archlens/to-viewer.json` (or `.uml-viewer/to-viewer.json`)
95
+
96
+ ### Mailbox Format (`to-agent.json`)
97
+ ```json
98
+ {
99
+ "nextId": 2,
100
+ "queue": [
101
+ {
102
+ "id": 1,
103
+ "op": "REGEN",
104
+ "target": { "id": "project" },
105
+ "payload": {}
106
+ }
107
+ ]
108
+ }
109
+ ```
110
+
111
+ ### Supported Operations:
112
+ 1. **`REGEN`**: Re-scan AST, compute violations and instability metrics, compile/test (`mvn test-compile`), and notify UI via `REGEN_COMPLETE`.
113
+ 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.
114
+ 3. **`REFRESH_CRAP`**: Run tests with code coverage (`mvn test` / `npm test`) and update metric snapshots.
115
+ 4. **`REFRESH_MUTATION`**: Run mutation testing on target classes.
116
+ 5. **`OMIT`**: Add specified package or class to the `:omit` list in policy.
117
+
118
+ ### Completing Tasks (`to-viewer.json`):
119
+ Write completion acknowledgment to `.archlens/to-viewer.json`. The backend file watcher pushes an SSE event to hot-reload the canvas:
120
+ ```json
121
+ {
122
+ "op": "REGEN_COMPLETE",
123
+ "target": { "id": "project" },
124
+ "payload": { "status": "SUCCESS" }
125
+ }
126
+ ```
127
+
128
+ ---
129
+
130
+ ## 🛠️ MCP Tool Suite Reference
131
+
132
+ When Archlens is registered as an MCP server, use the following tools:
133
+
134
+ | MCP Tool | Purpose | Key Arguments |
135
+ | :--- | :--- | :--- |
136
+ | `inspectArchitecture` | Inspect concentric rings, outward violations, and instability metrics | `projectRoot` (default: `.`) |
137
+ | `exportLlmDossier` | Generate copy-ready LLM refactoring prompt with DIP prescriptions | `projectRoot`, `proposalId` |
138
+ | `listSnapshots` | List historical Git release tags and pre-compiled architecture snapshots | `projectRoot` |
139
+ | `getSnapshot` | Retrieve graph model for a historical release or snapshot tag | `snapshotId`, `projectRoot` |
@@ -21,6 +21,8 @@ Trigger this skill whenever the user asks to:
21
21
  - "Upgrade Archlens config from .uml-viewer to .archlens"
22
22
  - "Connect repository to Archlens workbench"
23
23
  - "Prepare this repository for Archlens refactoring companion"
24
+ - "Export LLM refactoring prompt / Clean Architecture diagnostic dossier"
25
+ - "Generate prompt for Claude Code or LLM to fix Clean Architecture violations"
24
26
 
25
27
  ---
26
28
 
@@ -54,6 +56,12 @@ npx @fmatar/archlens-skill --path . --yes
54
56
 
55
57
  # Or upgrade an existing project from .uml-viewer to .archlens
56
58
  npx @fmatar/archlens-skill upgrade --path .
59
+
60
+ # Or export LLM Refactoring Prompt Dossier (copy-ready markdown)
61
+ npx @fmatar/archlens-skill prompt --path .
62
+
63
+ # Copy LLM Refactoring Prompt directly to system clipboard
64
+ npx @fmatar/archlens-skill prompt --path . --copy
57
65
  ```
58
66
 
59
67
  *Flags available:*
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: uml-workbench-companion
3
+ description: >-
4
+ Companion agent for the Clean Architecture Dynamic UML Workbench.
5
+ Monitors .archlens/ and .uml-viewer/ mailbox queues, processes architectural refactoring requests,
6
+ evaluates Clean Architecture violations, runs builds and tests, and signals live diagram reloads.
7
+ version: 1.2.0
8
+ license: Apache-2.0
9
+ ---
10
+
11
+ # UML Workbench Companion Skill (`uml-workbench-companion`)
12
+
13
+ Use this skill when interacting with the **Clean Architecture Dynamic UML Workbench**. This skill enables Antigravity or Gemini agents to act as the autonomous coding companion to the human architect who is using the visual UML viewer.
14
+
15
+ ---
16
+
17
+ ## ⚙️ Configuration & Service Endpoints
18
+
19
+ The workbench service endpoint defaults to `http://localhost:8088`, configurable via `.archlens/workbench.config.json` (or `.uml-viewer/workbench.config.json`) or the `ARCHLENS_SERVER_URL` / `WORKBENCH_URL` environment variables.
20
+
21
+ - **Graph & Violation API**: `GET http://localhost:8088/api/graph?proposalId=<id>&projectRoot=<root>`
22
+ - **Mailbox Files**: Located in `.archlens/` (or legacy `.uml-viewer/`) under the examined repository root.
23
+
24
+ ## 📋 Core Responsibilities
25
+
26
+ 1. **Mailbox Polling & Queue Processing**:
27
+ - Continuously check `.archlens/to-agent.json` (falling back to `.uml-viewer/to-agent.json`).
28
+ - Process commands sequentially in FIFO order (`nextId`, `queue`).
29
+ - Pop handled items from `queue` and atomically rewrite the mailbox file.
30
+
31
+ 2. **Command Handlers**:
32
+ - **`REGEN`**: Re-scan the project's AST, re-calculate Clean Architecture levels and dependency violations, and trigger a live graph refresh.
33
+ - **`APPLY_PROPOSAL`**: Read the requested proposal from `.archlens/policy.json` (or `.uml-viewer/policy.json`), physically restructure packages to match the proposed layers, introduce interfaces to invert violating inward-to-outward dependencies, and ensure tests pass.
34
+ - **`REFRESH_CRAP`**: Run tests (`mvn test` / `npm test`) for the target class or package and update JaCoCo coverage metrics.
35
+ - **`REFRESH_MUTATION`**: Run mutation testing on the specified target files and update metrics snapshots.
36
+ - **`OMIT`**: Add the target class or package to the active proposal's `:omit` list in policy.json.
37
+
38
+ 3. **Acknowledging to the Viewer**:
39
+ - Append completion status and results to `.archlens/to-viewer.json` (or `.uml-viewer/to-viewer.json`).
40
+ - The Quarkus backend file watcher detects this change and pushes an SSE event to the Svelte frontend, hot-reloading the diagram immediately.
41
+
42
+ ---
43
+
44
+ ## 🛠️ Step-by-Step Execution Workflow
45
+
46
+ ### When a User Says: "Check for workbench commands" or "Act as UML companion"
47
+
48
+ 1. **Inspect the Outbox**:
49
+ - Read `.archlens/to-agent.json` (or `.uml-viewer/to-agent.json`).
50
+ - If `queue` is empty, report that no commands are pending.
51
+ - If commands exist, select the first command `cmd = queue[0]`.
52
+
53
+ 2. **Execute the Requested Operation**:
54
+ - If `cmd.op == "REGEN"`:
55
+ - Verify source integrity.
56
+ - Compile or test if required (`mvn test-compile` or `npm run build`).
57
+ - Write an acknowledgment to `.archlens/to-viewer.json`:
58
+ ```json
59
+ {
60
+ "op": "REGEN_COMPLETE",
61
+ "target": { "id": "project" },
62
+ "payload": { "status": "SUCCESS" }
63
+ }
64
+ ```
65
+ - If `cmd.op == "APPLY_PROPOSAL"`:
66
+ - Read `.archlens/policy.json` to inspect the requested layer boundaries.
67
+ - Move or refactor classes to conform to the Clean Architecture rule:
68
+ - **Rule**: Dependencies must only point inward (e.g. `adapters` $\rightarrow$ `application` $\rightarrow$ `domain`).
69
+ - If `domain` depends on `adapters`, introduce an interface in `domain` and implement it in `adapters` (Dependency Inversion Principle).
70
+ - Run tests to verify zero regressions.
71
+ - Acknowledge completion in `.archlens/to-viewer.json`.
72
+
73
+ 3. **Pop Handled Command**:
74
+ - Remove `cmd` from the queue and update `nextId`.
75
+
76
+ ---
77
+
78
+ ## 🔄 Autonomous Background Monitoring
79
+
80
+ To monitor the workbench autonomously in the background while the architect is using the browser UI:
81
+
82
+ ```python
83
+ schedule(
84
+ CronExpression="*/1 * * * *",
85
+ Prompt="Check .archlens/to-agent.json (or .uml-viewer/to-agent.json) for pending workbench commands and process them.",
86
+ IsDaemon=false
87
+ )
88
+ ```