@yottameta/yotta-dev-mcp-plugin 0.0.0 → 0.2.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "yotta-dev-mcp",
+  "interface": {
+    "displayName": "元开 yotta-dev-mcp (YottaMeta)"
+  },
+  "plugins": [
+    {
+      "name": "yotta-dev-mcp",
+      "source": ".",
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools",
+      "version": "0.2.0",
+      "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architecture_review, impact_analysis, verify_change, self_test, run_adapter, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Reads an optional .yotta/architecture.json contract plus .yotta/verification.json policy for architecture reviews, change impact cones and the L0-L5 evidence ledger. Optional explicit adapters integrate import-linter, dependency-cruiser and Repomix without auto-install or network access. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
+      "interface": {
+        "displayName": "元开 yotta-dev-mcp",
+        "shortDescription": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architec",
+        "developerName": "YottaMeta",
+        "category": "Developer Tools"
+      }
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "yotta-dev-mcp",
+  "interface": {
+    "displayName": "元开 yotta-dev-mcp (YottaMeta)"
+  },
+  "plugins": [
+    {
+      "name": "yotta-dev-mcp",
+      "source": ".",
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools",
+      "version": "0.2.0",
+      "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architecture_review, impact_analysis, verify_change, self_test, run_adapter, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Reads an optional .yotta/architecture.json contract plus .yotta/verification.json policy for architecture reviews, change impact cones and the L0-L5 evidence ledger. Optional explicit adapters integrate import-linter, dependency-cruiser and Repomix without auto-install or network access. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
+      "interface": {
+        "displayName": "元开 yotta-dev-mcp",
+        "shortDescription": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architec",
+        "developerName": "YottaMeta",
+        "category": "Developer Tools"
+      }
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YottaMeta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# 元开 yotta-dev-mcp — Agent Plugin
+
+YuanKai (yotta-dev-mcp): deterministic local development tools over stdio MCP, covering code map, review, secret/dependency scan, release checks, whitelisted checks, scaffold and workflow state.
+
+[English](#english) | [中文](#中文)
+
+## English
+
+This repository is a standalone [Agent Plugins 1.0](https://agent-plugins.org) plugin. It packages one skill and one MCP server in the standard layout (`plugin.json`, `skills/`, `mcp.json`).
+
+### Install
+
+#### Codex (verified)
+
+```bash
+codex plugin marketplace add YottaMeta/yotta-dev-mcp-plugin
+codex plugin add yotta-dev-mcp@yotta-dev-mcp
+```
+
+#### Other compatible clients
+
+Agent Plugins defines the package format, not a universal installer command. Use your client’s official setup instructions:
+
+| Client | Setup instructions |
+| --- | --- |
+| VS Code | [Agent Plugins in VS Code](https://code.visualstudio.com/docs/agent-customization/agent-plugins) |
+| Cursor | [Cursor plugins](https://cursor.com/docs/plugins) |
+| GitHub Copilot | [About plugins](https://docs.github.com/en/copilot/concepts/agents/about-plugins) |
+| ChatGPT & Codex | [OpenAI plugins](https://developers.openai.com/plugins) |
+| Kiro | [Powers](https://kiro.dev/docs/powers/) |
+| Hermes Agent | [Portable Agent Plugins v1 packages](https://hermes-agent.nousresearch.com/docs/developer-guide/plugins#portable-agent-plugins-v1-packages) |
+| OpenClaw | [Plugin bundles](https://docs.openclaw.ai/plugins/bundles) |
+| Grok Bot | [Skills, routines, and automations](https://docs.x.ai/grok-bot/skills-routines-and-automations) |
+| NanoClaw | [Templates](https://github.com/nanocoai/nanoclaw/blob/main/docs/templates.md) |
+
+Codex is verified by YottaMeta. Other clients are linked from the official Agent Plugins compatibility page and are not yet verified here.
+
+### What you get
+
+- **Skill** — `yotta-dev-mcp` skill instructions (`skills/yotta-dev-mcp/SKILL.md`)
+- **MCP server** — started automatically by the client (stdio; requires Python 3.8+)
+
+### Boundaries
+
+- The MCP server runs fully local over stdio; no telemetry, no remote calls from the plugin itself.
+- If the required runtime is missing, the MCP component may fail to start; the skill payload remains available.
+- The skill payload is copied from the source repository release; for full documentation see [YottaMeta/yotta-dev-mcp](https://github.com/YottaMeta/yotta-dev-mcp).
+
+### Source
+
+Upstream skill repository: [YottaMeta/yotta-dev-mcp](https://github.com/YottaMeta/yotta-dev-mcp)
+Plugin repository: [YottaMeta/yotta-dev-mcp-plugin](https://github.com/YottaMeta/yotta-dev-mcp-plugin)
+
+### License
+
+MIT — see `LICENSE` and the license inside the skill payload.
+
+## 中文
+
+本仓库是一个独立的 [Agent Plugins 1.0](https://agent-plugins.org) 插件，按标准目录结构打包一项技能和一个 MCP server（`plugin.json`、`skills/`、`mcp.json`）。
+
+### 安装
+
+#### Codex（已实测）
+
+```bash
+codex plugin marketplace add YottaMeta/yotta-dev-mcp-plugin
+codex plugin add yotta-dev-mcp@yotta-dev-mcp
+```
+
+#### 其他兼容客户端
+
+Agent Plugins 只定义包格式，不定义统一安装命令。请按你所用客户端的官方说明接入：
+
+| 客户端 | 官方说明 |
+| --- | --- |
+| VS Code | [Agent Plugins in VS Code](https://code.visualstudio.com/docs/agent-customization/agent-plugins) |
+| Cursor | [Cursor plugins](https://cursor.com/docs/plugins) |
+| GitHub Copilot | [About plugins](https://docs.github.com/en/copilot/concepts/agents/about-plugins) |
+| ChatGPT & Codex | [OpenAI plugins](https://developers.openai.com/plugins) |
+| Kiro | [Powers](https://kiro.dev/docs/powers/) |
+| Hermes Agent | [Portable Agent Plugins v1 packages](https://hermes-agent.nousresearch.com/docs/developer-guide/plugins#portable-agent-plugins-v1-packages) |
+| OpenClaw | [Plugin bundles](https://docs.openclaw.ai/plugins/bundles) |
+| Grok Bot | [Skills, routines, and automations](https://docs.x.ai/grok-bot/skills-routines-and-automations) |
+| NanoClaw | [Templates](https://github.com/nanocoai/nanoclaw/blob/main/docs/templates.md) |
+
+Codex 已由 YottaMeta 实测；其他客户端仅链接官方说明，尚未在本仓库逐项实测。
+
+### 内容
+
+- **技能** — `yotta-dev-mcp` 技能指令（`skills/yotta-dev-mcp/SKILL.md`）
+- **MCP server** — 由客户端自动启动（stdio；需要 Python 3.8+）
+
+### 边界
+
+- MCP server 完全本地 stdio 运行；插件本身不做遥测、不发起远程调用。
+- 若运行时缺失，MCP 组件可能启动失败；技能内容仍可使用。
+- 技能内容来自源仓库发布版；完整文档见 [YottaMeta/yotta-dev-mcp](https://github.com/YottaMeta/yotta-dev-mcp)。
+
+### 来源
+
+上游技能仓库：[YottaMeta/yotta-dev-mcp](https://github.com/YottaMeta/yotta-dev-mcp)
+插件仓库：[YottaMeta/yotta-dev-mcp-plugin](https://github.com/YottaMeta/yotta-dev-mcp-plugin)
+
+### 许可证
+
+MIT — 见 `LICENSE` 与技能目录内许可证。

package/mcp.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "yotta-dev-mcp": {
+      "type": "stdio",
+      "command": "python",
+      "args": [
+        "${PLUGIN_ROOT}/skills/yotta-dev-mcp/scripts/yotta_dev_mcp.py"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@yottameta/yotta-dev-mcp-plugin",
-  "version": "0.0.0",
-  "description": "Placeholder package for Trusted Publisher setup.",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
+  "version": "0.2.0",
+  "description": "YuanKai (yotta-dev-mcp) Agent Plugin: deterministic local development tools over stdio MCP.",
   "license": "MIT",
-  "type": "commonjs",
   "repository": {
+    "type": "git",
     "url": "git+https://github.com/YottaMeta/yotta-dev-mcp-plugin.git"
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "files": [
+    ".agents",
+    ".claude-plugin",
+    "LICENSE",
+    "README.md",
+    "mcp.json",
+    "plugin.json",
+    "skills"
+  ]
 }

package/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "yotta-dev-mcp",
+  "version": "0.2.0",
+  "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architecture_review, impact_analysis, verify_change, self_test, run_adapter, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Reads an optional .yotta/architecture.json contract plus .yotta/verification.json policy for architecture reviews, change impact cones and the L0-L5 evidence ledger. Optional explicit adapters integrate import-linter, dependency-cruiser and Repomix without auto-install or network access. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
+  "author": {
+    "name": "YottaMeta",
+    "url": "https://github.com/YottaMeta"
+  },
+  "homepage": "https://github.com/YottaMeta/yotta-dev-mcp-plugin",
+  "repository": "https://github.com/YottaMeta/yotta-dev-mcp-plugin",
+  "license": "MIT",
+  "keywords": [
+    "yottameta",
+    "agent-plugins",
+    "agent-skills",
+    "mcp",
+    "yotta-dev-mcp"
+  ]
+}

package/skills/yotta-dev-mcp/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YottaMeta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/yotta-dev-mcp/NOTICE

@@ -0,0 +1,7 @@
+# NOTICE - YottaMeta 品牌声明
+
+「YottaMeta」「元阁」「yotta-dev-mcp」以及本家族各技能名称（yotta-* 前缀）
+是 YottaMeta 的品牌与标识。
+
+本软件以 MIT 许可证开源。派生作品不得继续使用 YottaMeta 或本家族名称作为名称，
+不得暗示派生作品由 YottaMeta 官方维护或认可。

package/skills/yotta-dev-mcp/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: yotta-dev-mcp
+description: 元开（yotta-dev-mcp）—— 本地、确定性的开发工具 MCP，把只读默认的开发能力暴露为 stdio MCP server：repo_map / system_model / architecture_review / impact_analysis / verify_change / self_test / run_adapter / find_code / compress_output / review_code / review_diff / mcp_doctor / scan_secrets / scan_dependencies / check_publish_readiness / run_checks / scaffold_skill / workflow_state。触发：让 AI 在陌生项目里先做结构盘点、构建系统模型或架构契约（.yotta/architecture.json）、按契约评审架构、分析改动影响锥与回归面、按验证阶梯产出证据账本、对元开自身做完整性 / 反证自测、探测或显式运行 import-linter / dependency-cruiser / Repomix 可选适配器、定位代码、评审改动、扫描密钥/依赖、检查发布就绪、运行白名单检查、生成脚手架或读取 .workflow 状态时；或用户说 元开 / 开发能力 MCP / yotta-dev-mcp / 代码库地图 / 系统模型 / 架构契约 / 架构评审 / 影响分析 / 验证账本 / 反证自测 / 代码评审 MCP / 适配器 等。边界：Python 3.8+ 标准库、离线默认；除 run_checks（显式 allow_execute）、verify_change 的 L2-L4 策略检查（显式 allow_execute）与 self_test 的测试子集（显式 allow_execute）、run_adapter 的 action=run（显式 allow_execute）、scaffold_skill / workflow_state 的显式 apply 外均为只读；不上传源码、不自动修改、不提交、不联网查询包是否存在、不自动安装或下载适配器。
+version: 0.2.0
+license: MIT
+---
+
+# 元开（yotta-dev-mcp）
+
+元开（YuanKai）把一组本地、确定性的开发工具做成一个 stdio MCP server。任何支持 MCP 的客户端接上后，
+都能在真实开发任务里调用这些工具；输出带文件、行号、规则和证据，便于直接进入修复清单。
+
+## 何时使用
+
+- 接手陌生项目：先 `repo_map` 看模块、依赖和入口，再 `find_code` 定位。
+- 架构与影响分析：先写 `.yotta/architecture.json`，再用 `system_model` 拿分层、依赖、测试映射与 `UNKNOWN` 清单。
+- 契约评审：用 `architecture_review` 查依赖规则、边界可见性与数据归属，每条给证据与严重级。
+- 改动前评估：用 `impact_analysis` 从改动文件 / diff / 目标符号走出影响锥、映射测试与回滚探针。
+- 改动后验证：用 `verify_change` 跑 L0 / L1 默认检查，按需结合 `.yotta/verification.json` 与 `allow_execute=true` 执行 L2-L4 白名单检查，产出可复算账本。
+- 自身完整性：用 `self_test` 检查文件、版本、工具契约、写闸门与 seeded defect / mutation 反证。
+- 可选增强：用 `run_adapter` 先 `action=list` 探测 import-linter / dependency-cruiser / Repomix，再按需 `action=run` + `allow_execute=true`；缺工具或配置返回 UNKNOWN，不自动安装、不自动下载。
+- 评审改动：`review_diff` 只看新增行；`review_code` 对文件或仓库做规则检查。
+- 长日志 / 长命令输出：`compress_output` 保错误、错误栈和首尾上下文。
+- 本机排查：`mcp_doctor` 只读检查技能目录和 MCP JSON 配置。
+
+## MCP 接入
+
+启动命令：
+
+```bash
+npx -y @yottameta/yotta-dev-mcp
+```
+
+或直接用本地脚本：
+
+```bash
+python scripts/yotta_dev_mcp.py
+```
+
+自动接入说明：AI 首次协助配置时，必须先展示目标配置文件、完整配置片段和影响，
+并获得用户明确同意后再写入 `mcpServers`。用户拒绝时不要写文件，直接提供上面的启动命令
+让用户手动接入。
+
+## 工具
+
+| 工具 | 用途 | 写入 |
+|---|---|---|
+| `repo_map` | 模块、导入、入口点地图 | 否 |
+| `system_model` | 系统模型：模块、依赖、入口、测试映射、配置与数据归属；附带契约分层，输出 PASS / FAIL / UNKNOWN | 否 |
+| `architecture_review` | 按契约评审依赖规则、边界可见性与数据归属；critical / high 判 FAIL，medium / low 只告警 | 否 |
+| `impact_analysis` | 变更影响锥：直接消费者、受影响层 / 边界 / 存储 / 不变量、映射测试、风险分级与回滚探针 | 否 |
+| `verify_change` | L0-L5 验证阶梯与证据账本：L0 / L1 默认，L2-L4 需策略声明 + 显式执行，L5 始终留在未验证项 | 仅显式 allow_execute 的 L2-L4 |
+| `self_test` | 文件 / 版本 / 工具契约 / 写闸门 / seeded defect 与 mutation 反证自测 | 仅显式 allow_execute 的测试子集 |
+| `run_adapter` | 探测或显式运行 import-linter / dependency-cruiser / Repomix；固定 argv、项目内 cwd、有界输出与哈希 | 仅 action=run + 显式 allow_execute |
+| `find_code` | 符号 / 文本定位，结果有上限 | 否 |
+| `compress_output` | 保留错误与首尾的长输出压缩 | 否 |
+| `review_code` | 规则化代码评审，带行号与建议 | 否 |
+| `review_diff` | 只评审 diff 的新增行 | 否 |
+| `mcp_doctor` | 技能版本与 MCP JSON 配置体检 | 否 |
+| `scan_secrets` | 密钥 / 凭据 / 高熵令牌扫描（强制脱敏） | 否 |
+| `scan_dependencies` | 依赖清单、lockfile、来源与 typosquat 启发式检查 | 否 |
+| `check_publish_readiness` | 版本四件、发布文件、仓库与 publishConfig 检查 | 否 |
+| `run_checks` | 白名单测试 / lint / compile 并返回结构化摘要 | 仅显式 allow_execute |
+| `scaffold_skill` | 生成最小技能脚手架，默认 dry-run | 仅显式 apply |
+| `workflow_state` | 读取 `.workflow`，可选显式追加日志 | 仅显式 apply |
+
+详细契约见 `references/tools.md`；架构契约、评审语义与影响锥字段见 `references/architecture-contract.md`。
+
+## 边界
+
+- 会执行项目代码的工具默认关闭：`run_checks`、`verify_change` 的 L2-L4 策略检查、`self_test` 的测试子集都必须显式 `allow_execute=true`，且只运行白名单检查或已声明的策略检查。
+- 外部适配器只在用户已安装时接入：`run_adapter` 不安装、不下载、不访问远端、不接收任意命令参数；工具缺失或配置缺失一律返回 `UNKNOWN` 并给出 next_step。
+- `scaffold_skill` / `workflow_state` 默认只预览，显式 `apply=true` 才写入；脚手架拒绝覆盖已有非空目录，状态写入使用原子替换并为被覆盖文件保留 `.bak`。
+- 不联网，不查询包是否存在于公共仓库。
+- 不读取或修改 YottaCode 仓库。
+- 结论是确定性静态判断，不替代人工评审与最终决策。
+
+## 当前版本
+
+- v0.2.0（2026-09-25）：新增 `system_model`、`architecture_review`、`impact_analysis`、`verify_change`、`self_test`、`run_adapter`，以及 `.yotta/architecture.json` 与可选 `.yotta/verification.json` 契约（版本 1）；工具总数 18，原 12 个工具行为不变。
+- v0.1.1：品牌显示名统一为「元开」；功能与 12 个工具不变。

package/skills/yotta-dev-mcp/bin/yotta-dev-mcp.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * yotta-dev-mcp launcher.
+ *
+ * Default: start the stdio MCP server.
+ * Install flags: delegate to bin/install.js.
+ */
+'use strict';
+const { spawn, spawnSync } = require('child_process');
+const path = require('path');
+
+const PKG_ROOT = path.join(__dirname, '..');
+const SERVER = path.join(PKG_ROOT, 'scripts', 'yotta_dev_mcp.py');
+const INSTALL_FLAGS = ['--agent', '--dir', '--list', '-l', '-g', '--global', '--dry-run', '--yes'];
+
+function isInstallRequest(args) {
+  return args.some(function (item) {
+    if (INSTALL_FLAGS.indexOf(item) !== -1) return true;
+    return item.indexOf('--agent=') === 0 || item.indexOf('--dir=') === 0;
+  });
+}
+
+function findPython() {
+  const candidates = [];
+  if (process.env.YOTTA_MCP_PYTHON) candidates.push(process.env.YOTTA_MCP_PYTHON);
+  candidates.push('python3', 'python', 'py');
+  for (let i = 0; i < candidates.length; i++) {
+    try {
+      const result = spawnSync(candidates[i], ['--version'], { encoding: 'utf8', timeout: 5000 });
+      if (result.status === 0) return candidates[i];
+    } catch (error) {
+      // Try the next candidate.
+    }
+  }
+  return 'python';
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.indexOf('--version') !== -1 || args.indexOf('-v') !== -1) {
+    process.stdout.write(require(path.join(PKG_ROOT, 'package.json')).version + '\n');
+    return;
+  }
+  if (isInstallRequest(args)) {
+    require(path.join(__dirname, 'install.js'));
+    return;
+  }
+  const python = findPython();
+  const child = spawn(python, [SERVER].concat(args), { stdio: 'inherit' });
+  child.on('exit', function (code) { process.exit(code || 0); });
+  child.on('error', function (error) {
+    process.stderr.write('yotta-dev-mcp: cannot start Python MCP server: ' + error.message + '\n');
+    process.exit(1);
+  });
+}
+
+main();

package/skills/yotta-dev-mcp/references/adapters.md

@@ -0,0 +1,69 @@
+# Optional external adapters
+
+`run_adapter` probes and explicitly runs mature third-party tools that the user
+already installed. The core engine stays Python-standard-library-only; adapters
+are optional evidence sources, never a required dependency.
+
+## Adapter matrix
+
+| Adapter | License | What it adds | Required config |
+|---|---|---|---|
+| `import-linter` | BSD-2-Clause | Python import boundaries and layered contracts | `.importlinter`, `setup.cfg`, `tox.ini` or `pyproject.toml` |
+| `dependency-cruiser` | MIT | JavaScript / TypeScript dependency rules | `.dependency-cruiser.js` / `.cjs` / `.mjs` / `.json` |
+| `repomix` | MIT | Repository packing and context budget enforcement | optional `repomix.config.json` |
+
+## Commands
+
+`action=list` only inspects the project-local `node_modules/.bin`, project
+virtualenv directories and `PATH`. It does not execute anything. Each adapter
+entry reports `available`, `ready`, `executable`, `executable_source`, `config`
+and a reason when it is not ready.
+
+`action=run` requires `allow_execute=true` and exactly one adapter. The command
+arguments are fixed by the adapter implementation:
+
+```text
+lint-imports --config <detected-config>
+depcruise --config <detected-config> --output-type json --progress none --exclude node_modules <target>
+repomix --stdout --style xml --quiet --no-git-sort-by-changes [--token-budget N] <target>
+```
+
+No adapter accepts arbitrary arguments, shell strings, remote repositories or
+package installation. Repomix never receives `--remote` or
+`--no-security-check`.
+
+## Output
+
+The run result contains:
+
+- `status`: `PASS`, `FAIL` or `UNKNOWN`;
+- `adapter`: detected executable, source, config and version;
+- `command`: fixed argv, relative cwd, exit code, timeout flag and output hash;
+- `findings`: normalized adapter violations with rule, severity, path and target;
+- `content`: Repomix-only packed text metadata and bounded text;
+- `next_step`: what to install, configure or rerun when the result is not PASS.
+
+Missing tools, missing required config, invalid JSON output, timeouts and
+non-whitelisted execution all degrade to `UNKNOWN`. Adapter findings are
+reported separately; they do not silently change the status of
+`system_model`, `architecture_review`, `impact_analysis` or `verify_change`.
+
+## Safety boundary
+
+Adapters are local-only and deterministic under the same repository state:
+
+- executable discovery is limited to the project `node_modules/.bin`, project
+  virtualenvs and `PATH`;
+- execution uses a fixed argv with `shell=False`;
+- the working directory and target must stay inside the repository;
+- output is bounded, hashed and never contains wall-clock timestamps;
+- no package is installed, downloaded or updated by this tool.
+
+## Command line
+
+```bash
+python scripts/dev_engine.py adapter . --action list
+python scripts/dev_engine.py adapter . --action run --adapter import-linter --allow-execute
+python scripts/dev_engine.py adapter . --action run --adapter dependency-cruiser --allow-execute
+python scripts/dev_engine.py adapter . --action run --adapter repomix --allow-execute --token-budget 50000
+```