Soia Dev Archify Diagrams

soia-dev-archify-diagrams

Use this skill to turn architecture and process explanations into polished Archify diagrams with maintainable JSON source files and README-friendly PNG previews.

The skill owns the reusable workflow and helper scripts. Archify itself remains an external renderer.

soia-dev-archify-diagrams/
├── SKILL.md
├── scripts/
│   ├── render-archify-diagrams.mjs
│   └── export-archify-previews.mjs
└── assets/examples/
    ├── minimal-architecture.architecture.json
    ├── minimal-dataflow.dataflow.json
    └── minimal-workflow.workflow.json

客户可读说明

这个技能可以做什么

Draw, improve, validate, or publish Archify architecture / data-flow / sequence / lifecycle diagrams with JSON IR and PNG previews

客户如何使用

1. 用自然语言说明目标，并提供必要输入：文件、URL、repo、workspace、proposal、vault 或平台账号状态。
2. 能 dry-run 或预览的动作先给预览；涉及删除、覆盖、发送、发布、写远端状态时先征求客户确认。

依赖与安装

仅在客户明确选择整个 dev 插件时安装：

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-dev@soia

Codex 整域入口为 codex plugin marketplace add soia-team/soia-open-skills 与 codex plugin add soia-dev@soia；仍须先确认安装范围。

默认在已选项目内定向安装；不加全局或全部宿主参数。同一使用范围选插件或单技能一种来源：

npx skills add soia-team/soia-open-dev-skills -a <agent> -s soia-dev-archify-diagrams -y

配置约定：

~/.config/soia-skills/soia-dev-archify-diagrams/config.yml
SOIA_DEV_ARCHIFY_DIAGRAMS_CONFIG_FILE=<custom-config-path>

• 如果本技能不需要私有配置，可以不创建 config.yml。
• 凭据只进 provider 官方登录态或系统凭据库，不进入普通 config、命令或日志；私有 config 只保存路径和非秘密偏好。
• 第三方 skill 只能声明依赖和安装方式，不直接修改第三方 skill 文件。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

输出目录契约

输出目录按以下优先级解析：

1. 命令行 --output-dir <path>；
2. 进程环境变量或私有配置中的 ARCHIFY_OUTPUT_DIR；
3. 安全默认值 ~/Downloads/soia-dev-archify-diagrams/。

--output-dir 可以是绝对路径或相对当前工作目录的路径。技能不会把用户交付物默认写入当前目录，也不会把 ~/.soia/workspaces/ 当作通用输出目录。

按交付场景显式指定目录：

• 仓库 README / 文档：--output-dir assets/diagrams；
• 已明确确认的 SOIA proposal：--output-dir <workspace>/proposals/<proposal-id>/design/diagrams；
• 普通临时预览或未指定项目目录：使用上述 ~/Downloads/soia-dev-archify-diagrams/ 默认值。

使用 --png-only 时，HTML 只作为输出目录内的临时中间文件，PNG 导出成功后会删除 HTML；不使用 --png-only 时保留 HTML，便于浏览器预览和排错。

日志与完成回执

每次执行都要让客户看见过程和结果。最低回执格式：

完成：<一句话说明本次完成了什么>。

日志摘要：
- started: <检查到的输入/配置/依赖，不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化：
- <绝对路径或“未改动文件”>

验证：
- <运行过的检查、命令或人工核对点>

问题与下一步：
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>

Choose Diagram Type

If a rough Mermaid flowchart mixes components and process, choose one story and split the rest into a second diagram.

Diagram Rules

1. Keep JSON IR as the source of truth.
2. Generate HTML as a render/check intermediate; with --png-only, delete it after PNG export succeeds.
3. Commit PNG previews for README-visible diagrams.
4. Do not commit generated HTML unless the user explicitly asks for interactive diagrams.
5. Make the main path left-to-right.
6. Put side concerns in cards, not in long crossing arrows.
7. Use few edge labels; label only non-obvious boundaries, policy/security paths, or async/batch paths.
8. Run Archify validate, render, and check before claiming the diagram is done.

Standard Layout

For repository README/docs diagrams, prefer:

assets/diagrams/
├── <slug>.architecture.json
└── <slug>.png

For an explicitly confirmed SOIA proposal, write diagrams under:

<workspace>/proposals/<proposal-id>/design/diagrams/

Do not infer a proposal workspace from the current directory, and do not hardcode a maintainer-specific workspace path in SKILL.md, JSON examples, README files, or scripts. If the caller has not supplied a project destination, use the output-directory contract above.

Setup

Do not copy the Archify upstream source into a skill repository. Use one of these locations at runtime:

1. Explicit binary: ARCHIFY_BIN=<path-to-archify.mjs>
2. Command arg: --archify-root <path-to-archify-root>
3. Explicit root: ARCHIFY_ROOT=<path-to-archify-root>
4. Installed skill locations:
   • .agents/skills/archify (current workspace)
   • ~/.gemini/antigravity-cli/skills/archify
   • ~/.agents/skills/archify
   • ~/.codex/skills/archify
   • ~/.claude/skills/archify

If Archify is not available, clone it outside the skill repo and point ARCHIFY_ROOT to that checkout:

git clone https://github.com/tt-a1i/archify.git <workspace>/archify
cd <workspace>/archify/archify
npm install

Render Workflow

Render all diagrams in a directory and keep only JSON + PNG:

node skills/soia-dev-archify-diagrams/scripts/render-archify-diagrams.mjs \
  --dir assets/diagrams \
  --output-dir assets/diagrams \
  --png-only \
  --theme light \
  --width 1400 \
  --height 1000 \
  --scale 2

Render one diagram:

node skills/soia-dev-archify-diagrams/scripts/render-archify-diagrams.mjs \
  --file assets/diagrams/system.architecture.json \
  --output-dir assets/diagrams \
  --png-only

The helper:

• Finds *.architecture.json, *.workflow.json, *.sequence.json, *.dataflow.json, and *.lifecycle.json
• Runs archify validate
• Runs archify render
• Runs archify check
• Writes HTML previews to the resolved output directory
• With --png-only, exports PNG previews to the same directory and deletes temporary HTML files
• Without --output-dir, uses ARCHIFY_OUTPUT_DIR and then ~/Downloads/soia-dev-archify-diagrams/

README Preview Workflow

GitHub README should use committed PNG previews:

1. Render Archify HTML.
2. Export a PNG preview.
3. Delete the temporary HTML.
4. Commit JSON source and PNG preview.
5. Embed the PNG directly.

Use the bundled exporter when HTML already exists:

node skills/soia-dev-archify-diagrams/scripts/export-archify-previews.mjs \
  --dir assets/diagrams \
  --output-dir assets/diagrams \
  --theme light \
  --width 1400 \
  --height 1000 \
  --scale 2

Markdown:

![Diagram](assets/diagrams/example.png)

Centered HTML:

<p align="center">
  <img src="assets/diagrams/example.png" alt="Example architecture diagram" width="100%">
</p>

Minimal JSON Patterns

Start from assets/examples/ when creating new diagrams. Use the suffix to select the renderer:

• *.architecture.json
• *.dataflow.json
• *.workflow.json

Keep examples generic. Do not include personal directories, private repo paths, tokens, cookies, or private workspace names.

Layout Debugging

Archify validation errors are usually actionable. Apply its suggestions directly:

• label collision: set labelDy, labelDx, labelAt, or labelSegment
• node collision: move row / col, change pos, or reduce size / width
• short workflow edge: skip adjacent columns or route through drop / bottom-channel
• viewBox overflow: increase meta.viewBox or reduce node count

Do not ignore overlap errors. Fix JSON and re-render.

Output Checklist

Before final response:

• JSON IR exists and is ready to commit.
• Temporary HTML rendered and passed archify check.
• README PNG exists if the diagram should be visible on GitHub.
• README-visible diagram HTML was deleted unless explicitly requested.
• Markdown links/images resolve locally.
• Report the resolved output directory and whether it came from --output-dir, ARCHIFY_OUTPUT_DIR, or the safe default.
• Report which scripts were used and which checks passed.

私密信息与中间数据

只读取客户授权的图表与素材，不上传源文件；JSON 和交付预览写指定输出，临时数据使用 OS 临时目录。凭据不进入配置、图表或回执。脚本生成的 HTML 仅在本次成功导出并确认属于临时输出后清理；不自动提交、发布或安装 Archify。

前向验证

使用 assets/examples 中的公开 fixture 或客户授权图表，实际运行 validate → render → check，核对节点/边与 PNG 预览，不只检查退出码。缺少真实 Archify 时可检查输入和包装器，但必须保留实际渲染未验证的说明。