Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

Validate Hermes adapter and clarify community installation instructions

tt-a1ib26b4da0ebe9
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1837ce67..f51d4a50 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -25,6 +25,10 @@ jobs:
run: npm test
working-directory: archify
+ - name: Verify community Hermes adapter
+ if: matrix.node-version == 22
+ run: node --test integrations/hermes-agent/test/plugin-contract.test.mjs
+
webm-artifact:
runs-on: ubuntu-latest
steps:
diff --git a/README.md b/README.md
index c47b60db..bed10d55 100644
--- a/README.md
+++ b/README.md
@@ -265,7 +265,7 @@ The complete generation and viewer contract lives in [`archify/SKILL.md`](archif
| **opencode** | `~/.config/opencode/skills/`, `.opencode/skills/`, or `.agents/skills/` | Full renderer + validation workflow |
| **Claude.ai** | Upload `archify.zip` under Settings → Capabilities → Skills | Depends on Node.js access in the sandbox |
| **Project Knowledge** | Upload `archify.zip` to the project | Prompt-driven architecture fallback |
-| **Hermes Agent** | Opt-in: `hermes skills install skills-sh/tt-a1i/archify/archify -y` | Community Skill-only; Node `>=18`; not official Nous. [Details](integrations/hermes-agent/README.md). |
+| **Hermes Agent** | `hermes skills install skills-sh/tt-a1i/archify/archify -y` | Community opt-in; Node `>=18`. [Details](integrations/hermes-agent/README.md). |
| **DeepSeek Harness** | Opt-in: `dsh plugin --profile web add @tt-a1i/[email protected]`. Invoke: `Use the archify skill to map this repository's runtime architecture.` Remove: `dsh plugin --profile web remove @tt-a1i/archify-dsh`. | Community integration for developer-preview `@deepseek-ai/[email protected]`; Node `^22.19.0 \|\| >=24.0.0`; not an official DeepSeek product. No telemetry. Shell files need exact workspace paths, not Web Produced Files. [Details](integrations/deepseek-harness/README.md). |
## Reference and scope
diff --git a/README_EN.md b/README_EN.md
index c47b60db..bed10d55 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -265,7 +265,7 @@ The complete generation and viewer contract lives in [`archify/SKILL.md`](archif
| **opencode** | `~/.config/opencode/skills/`, `.opencode/skills/`, or `.agents/skills/` | Full renderer + validation workflow |
| **Claude.ai** | Upload `archify.zip` under Settings → Capabilities → Skills | Depends on Node.js access in the sandbox |
| **Project Knowledge** | Upload `archify.zip` to the project | Prompt-driven architecture fallback |
-| **Hermes Agent** | Opt-in: `hermes skills install skills-sh/tt-a1i/archify/archify -y` | Community Skill-only; Node `>=18`; not official Nous. [Details](integrations/hermes-agent/README.md). |
+| **Hermes Agent** | `hermes skills install skills-sh/tt-a1i/archify/archify -y` | Community opt-in; Node `>=18`. [Details](integrations/hermes-agent/README.md). |
| **DeepSeek Harness** | Opt-in: `dsh plugin --profile web add @tt-a1i/[email protected]`. Invoke: `Use the archify skill to map this repository's runtime architecture.` Remove: `dsh plugin --profile web remove @tt-a1i/archify-dsh`. | Community integration for developer-preview `@deepseek-ai/[email protected]`; Node `^22.19.0 \|\| >=24.0.0`; not an official DeepSeek product. No telemetry. Shell files need exact workspace paths, not Web Produced Files. [Details](integrations/deepseek-harness/README.md). |
## Reference and scope
diff --git a/README_ZH.md b/README_ZH.md
index 34177501..e07f3123 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -109,7 +109,6 @@ npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy
npx skills use tt-a1i/archify@archify --agent codex
```
-DeepSeek Harness(社区集成、显式启用):运行 `dsh plugin --profile web add @tt-a1i/[email protected]`;参见[兼容范围、限制与安全说明](integrations/deepseek-harness/README.md)。Hermes:`hermes skills install skills-sh/tt-a1i/archify/archify -y`;参见[说明](integrations/hermes-agent/README.md)。[Agent 切换器](https://tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture)只为 `cursor`、`codex`、`claude-code` 和 `opencode` 生成命令。Raven 仅支持 ZIP 手动安装:将 [`archify.zip`](archify.zip) 解压到 `~/.raven/workspace/skills`,解压后会得到 `~/.raven/workspace/skills/archify`;Raven 不属于切换器目标。
DeepSeek Harness(社区集成、显式启用):运行 `dsh plugin --profile web add @tt-a1i/[email protected]`;参见[兼容范围、限制与安全说明](integrations/deepseek-harness/README.md)。[Agent 切换器](https://tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture)只为 `cursor`、`codex`、`claude-code`、`opencode` 和 `github-copilot` 生成命令。Raven 仅支持 ZIP 手动安装:将 [`archify.zip`](archify.zip) 解压到 `~/.raven/workspace/skills`,解压后会得到 `~/.raven/workspace/skills/archify`;Raven 不属于切换器目标。
安装后的 Skill 包含一个低频、失败静默的发布检查,它最多只显示可选更新提醒,绝不会自行下载或安装更新。一次成功检查后,下次网络请求通常约在 72 小时(±20%)后发出;检查失败后,活跃使用可能在首次 6 小时、后续 24 小时退避到期时重试。请求只访问 `https://tt-a1i.github.io/archify/skill-updates/archify/stable.json`。服务端会自然获得 IP、请求时间和常规 HTTP 元数据;检查器不会发送本地版本、Agent、项目数据、用户输入、账户/设备标识,也不会保存或回传 ETag。是否更新以及何时更新始终由你决定。如需完全关闭检查(包括网络请求和提醒状态写入),请在 Agent 环境中设置 `ARCHIFY_UPDATE_CHECK_DISABLED=1`。
@@ -288,8 +287,7 @@ Claude.ai 中的上传入口:
## 参与贡献
欢迎提交 Issue、Pull Request 和真实场景图。请先阅读[贡献指南](CONTRIBUTING.md);遇到问题时使用可复现 Bug 表单,也可以通过[社区 Showcase 表单](https://github.com/tt-a1i/archify/issues/new?template=showcase.yml)提交已验证成品。 如需报告安全漏洞,请遵循[安全报告说明](SECURITY.md)。
-
-较大的功能或行为调整请先通过 Issue 对齐价值、兼容边界和非目标,再基于最新 `main` 开发。一个 PR 尽量只解决一个问题;核心代码和回归测试先行,生成物最后统一重建。Archify 坚持 Agent-first,优先完善稳定的机器可读诊断和现有权威合同,避免新增容易与 CLI 漂移的重复说明。 · [LINUX DO](https://linux.do)
+较大的功能或行为调整请先通过 Issue 对齐价值、兼容边界和非目标,再基于最新 `dev` 开发。一个 PR 尽量只解决一个问题;核心代码和回归测试先行,生成物最后统一重建。Archify 坚持 Agent-first,优先完善稳定的机器可读诊断和现有权威合同,避免新增容易与 CLI 漂移的重复说明。 · [LINUX DO](https://linux.do)
## Star History
diff --git a/integrations/hermes-agent/README.md b/integrations/hermes-agent/README.md
index 68cd43da..118aa6c3 100644
--- a/integrations/hermes-agent/README.md
+++ b/integrations/hermes-agent/README.md
@@ -29,18 +29,21 @@ If `hermes skills inspect skills-sh/tt-a1i/archify/archify` cannot resolve the i
### Local checkout (this branch)
-Replace the source path with your checkout.
+Replace the source path with your checkout. If the destination already exists, inspect it before replacing it; these commands intentionally leave an existing installation in place. Windows symlink creation requires the relevant system permission.
Linux / macOS:
```bash
-ln -sfn /absolute/path/to/archify/archify ~/.hermes/skills/archify
+mkdir -p ~/.hermes/skills
+[ ! -e ~/.hermes/skills/archify ] && [ ! -L ~/.hermes/skills/archify ] && \
+ ln -s /absolute/path/to/archify/archify ~/.hermes/skills/archify
```
Windows PowerShell:
```powershell
-New-Item -ItemType SymbolicLink -Force -Path "$env:USERPROFILE\.hermes\skills\archify" -Target "C:\absolute\path\to\archify\archify"
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.hermes\skills" | Out-Null
+New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.hermes\skills\archify" -Target "C:\absolute\path\to\archify\archify"
```
### Docker
@@ -54,14 +57,17 @@ Plugin skills are opt-in (`skill_view("archify:archify")`) and are not listed in
Linux / macOS:
```bash
-ln -sfn /absolute/path/to/archify/integrations/hermes-agent ~/.hermes/plugins/archify
+mkdir -p ~/.hermes/plugins
+[ ! -e ~/.hermes/plugins/archify ] && [ ! -L ~/.hermes/plugins/archify ] && \
+ ln -s /absolute/path/to/archify/integrations/hermes-agent ~/.hermes/plugins/archify
hermes plugins enable archify
```
Windows PowerShell:
```powershell
-New-Item -ItemType SymbolicLink -Force -Path "$env:USERPROFILE\.hermes\plugins\archify" -Target "C:\absolute\path\to\archify\integrations\hermes-agent"
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.hermes\plugins" | Out-Null
+New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.hermes\plugins\archify" -Target "C:\absolute\path\to\archify\integrations\hermes-agent"
hermes plugins enable archify
```
@@ -92,5 +98,5 @@ Remove-Item "$env:USERPROFILE\.hermes\plugins\archify"
## Scope
- Compatible with Hermes directory plugins (`plugin.yaml` + `register(ctx)`).
-- Does not add Archify to the Cursor / Codex / Claude Code / OpenCode agent switcher.
+- Does not add Archify to the Cursor / Codex / Claude Code / OpenCode / GitHub Copilot agent switcher.
- Does not claim merge safety, blast radius, or live-infrastructure verification.
diff --git a/integrations/hermes-agent/test/plugin-contract.test.mjs b/integrations/hermes-agent/test/plugin-contract.test.mjs
index c7512707..6380b9be 100644
--- a/integrations/hermes-agent/test/plugin-contract.test.mjs
+++ b/integrations/hermes-agent/test/plugin-contract.test.mjs
@@ -35,7 +35,7 @@ test('plugin is skill-only and does not declare native tools', () => {
assert.match(init, /HERMES_HOME/);
});
-test('register() resolves the in-repo Skill without a packed copy', () => {
+test('register() registers the in-repo Skill without a packed copy', () => {
const result = spawnSync('python3', ['-c', `
import importlib.util
from pathlib import Path
@@ -47,6 +47,12 @@ resolved = mod.resolve_skill_md()
print(resolved)
assert resolved.name == 'SKILL.md'
assert resolved.parent.name == 'archify'
+from types import SimpleNamespace
+calls = []
+mod.register(SimpleNamespace(register_skill=lambda *args, **kw: calls.append((args, kw))))
+assert len(calls) == 1
+assert calls[0][0] == ('archify', resolved)
+assert calls[0][1]['description']
`], { encoding: 'utf8' });
assert.equal(result.status, 0, result.stderr || result.stdout);
assert.equal(path.resolve(result.stdout.trim()), path.join(repoRoot, 'archify', 'SKILL.md'));
@@ -93,3 +99,36 @@ test('Archify core does not import or branch on Hermes Agent', () => {
assert.equal(grep.status, 1, grep.stderr || grep.stdout);
assert.equal(grep.stdout.trim(), '');
});
+
+
+test('standalone plugin resolves configured homes and fails when no Skill exists', () => {
+ const result = spawnSync('python3', ['-c', `
+import importlib.util, os, shutil, tempfile
+from pathlib import Path
+with tempfile.TemporaryDirectory() as tmp:
+ root = Path(tmp)
+ plugin = root / 'plugin' / '__init__.py'
+ plugin.parent.mkdir()
+ shutil.copyfile(${JSON.stringify(path.join(integrationRoot, '__init__.py'))}, plugin)
+ os.environ['HERMES_HOME'] = str(root / 'home')
+ os.environ.pop('ARCHIFY_SKILL_ROOT', None)
+ spec = importlib.util.spec_from_file_location('isolated_archify', plugin)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ try:
+ mod.resolve_skill_md()
+ raise AssertionError('missing Skill must fail')
+ except FileNotFoundError:
+ pass
+ home_skill = root / 'home' / 'skills' / 'archify' / 'SKILL.md'
+ home_skill.parent.mkdir(parents=True)
+ home_skill.write_text('home skill')
+ assert mod.resolve_skill_md() == home_skill
+ explicit = root / 'explicit'
+ explicit.mkdir()
+ (explicit / 'SKILL.md').write_text('configured skill')
+ os.environ['ARCHIFY_SKILL_ROOT'] = str(explicit)
+ assert mod.resolve_skill_md() == explicit / 'SKILL.md'
+`], { encoding: 'utf8' });
+ assert.equal(result.status, 0, result.stderr || result.stdout);
+});