dym-archify-cli-authoring-loop

Skill: dym-archify-cli-authoring-loop — Diagram authoring loop with CLI in the terminal

Why use it: when you write JSON IR yourself (or script the diagram generation) and don't want to go through an agent. The CLI is zero-dependency and runs right on a clean source tree.

What you get: a self-contained HTML file that has been atomically verified, along with a JSON receipt containing the SHA-256 and byte count of both the spec and the artifact.

Type all commands below in the terminal. The agent prompt is in 02-agent-chat-authoring.md.

Set a variable to keep things tidy (path to the installed skill directory at 01):

export A=~/.claude/skills/archify

Step 0 — Choose the diagram type with `guide`

node $A/bin/archify.mjs guide "Show an API request with Redis cache miss"

Ran it, real result:

Recommendation: API request chain  [sequence]
Confidence: high
Question answered: Who calls whom, in what order, and what returns?

Use when: API documentation, debugging request latency, auth reviews, or explaining cache fallback.
Avoid when: Order is unimportant and the audience only needs the stable service topology.
Must include: callers and callees; request and return messages; fallback or error path; async side effects
Presentation: classic · trace · views optional

Copy-ready prompt:
Use Archify sequence mode to show this request from caller to final response. …

Machine-readable form, and the Chinese version:

node $A/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json
node $A/bin/archify.mjs guide "CI/CD approval gate" --lang zh

Step 1 — Read exactly three files, no more

For the selected type <type> :

cat $A/schemas/<type>.schema.json
cat $A/schemas/common.schema.json
ls  $A/examples/                       # chọn một ví dụ JSON cùng loại

Ready-made JSON example (19 items in examples/, including the rendered HTML):

agent-run.lifecycle.json          agent-tool-call.workflow.json
async-job-roundtrip.sequence.json brand-aware-delivery.architecture.json
cache-miss-request.sequence.json  checkout-platform.base.architecture.json
checkout-platform.head.architecture.json  deployment-release.lifecycle.json
event-stream.dataflow.json        incident-response.workflow.json
product-analytics.dataflow.json   production-deployment.architecture.json
release-delivery.workflow.json    web-app.architecture.json

Use the example to get the field shape, not the content. New workflow sources use schema_version: 2; keep 1 only when you need to preserve the old geometry.

Step 2 — Three architecture schema traps I stumbled into myself

These are three mistakes I actually hit when writing an architecture spec from scratch, and how the CLI responds:

Trap 1 — the top-level key is connections, not relationships.

/ must NOT have additional properties {"additionalProperty":"relationships"}
  supportedFixes: ["remove unsupported property \"relationships\""]

Valid keys, taken from schemas/architecture.schema.json: schema_version, diagram_type, meta, layout, components, boundaries, connections, cards. Required: schema_version, diagram_type, meta, components.

Trap 2 — there is no layout means free placement, and every component must have pos.

Component "cli" must include pos [x, y] when layout.mode is omitted (free placement).

layout.mode accepts exactly one value: "grid". Add "layout": { "mode": "grid" } then use row/col and you're done.

Trap 3 — a label wider than its box will block validation.

Label "Architecture renderer" (~139px) is wider than component "renderer" (120px) — shorten the label or widen size.

Fix it by shortening the label or setting size: [w, h] for that component. The default box is 120px wide.

Step 3 — Validate after each edit

node $A/bin/archify.mjs validate workflow candidate.json --quality showcase --json

Actually run on the bundled example, human-readable form:

ok workflow /…/examples/agent-tool-call.workflow.json (9 artifact checks; composition showcase: 0 errors, 0 warnings)

Acceptance threshold: enough 9 artifact check, 0 errors, 0 warnings. A receipt with only 4 checks is a basic validate, not a showcase. If meta.quality_profile is missing or the name is mistyped, fix it first before touching the geometry.

On failure, --json returns an object with stable diagnostics[] . Real example (rc 1):

{
  "schemaVersion": 1,
  "ok": false,
  "command": "validate",
  "stage": "render",
  "type": "workflow",
  "diagnostics": [
    {
      "code": "schema/required",
      "severity": "error",
      "message": "/ must have required property 'schema_version' …",
      "subject": { "diagramType": "workflow", "path": "/" },
      "evidence": { "keyword": "required", "missingProperty": "schema_version" },
      "supportedFixes": ["add required property \"schema_version\""]
    }
  ]
}

Fixing rule: only touch the subject that was diagnosed, cross-check evidence, choose one approach from supportedFixes, run again. If two consecutive rounds fail to reduce the objective error count, stop and report honestly — don't guess blindly.

Workflow geometry diagnostics v2 use stable compiler receipts:

node $A/bin/archify.mjs validate workflow candidate.json --layout-json

For architecture, inspect is an alias for exactly that command:

node $A/bin/archify.mjs inspect architecture candidate.json

Step 4 — Deliver artifacts

node $A/bin/archify.mjs deliver workflow candidate.json out/workflow.html --quality showcase --json

Real receipts already run:

{
  "schemaVersion": 1,
  "ok": true,
  "command": "deliver",
  "type": "workflow",
  "input": "/…/agent-tool-call.workflow.json",
  "output": "/…/wf.html",
  "specification": { "sha256": "4d3f6c23…", "bytes": 5687 },
  "artifact":      { "sha256": "e083cfe2…", "bytes": 723038 },
  "validation": {
    "checksPassed": 9, "checkCount": 9,
    "compositionProfile": "showcase", "compositionStatus": "pass",
    "errors": 0, "warnings": 0
  }
}

deliver freezes exactly the spec's bytes into a separate snapshot in the same directory, renders and checks that snapshot, then atomically replaces the target HTML file. On failure the old file is kept intact — so don't run visual-check after a deliver failure: you'll be inspecting the old good artifact instead of the one that just failed.

Add --open to open the file just committed right away:

node $A/bin/archify.mjs deliver workflow candidate.json out/workflow.html --quality showcase --open --json

An opener error doesn't undo success: JSON still goes to stdout, the absolute fallback path goes to stderr.

Step 5 — Re-check an existing HTML

node $A/bin/archify.mjs check out/workflow.html

Prints JSON with 9 named checks (single_svg, finite_svg, orthogonal_arrows, label_route_clearance, relationship_crossings, relationship_corridors, container_border_runs, route_rhythm, legend_clearance) plus the composition block with real measurements (properCrossings, maxBends, maxStretch, minSegmentPx, …) and suggestedLimits. rc 0 when green, 1 when failed (scripts/check-render-output.mjs:276).

Common auxiliary commands

node $A/bin/archify.mjs render workflow candidate.json out/raw.html   # render trần, KHÔNG kiểm — không dùng để nghiệm thu
node $A/bin/archify.mjs brands postgres                                # → "data: postgresql"
node $A/bin/archify.mjs brands "grafana" --json
node $A/bin/archify.mjs brands capture "https://example.com" --json    # ghim digest cho brand chưa có preset
node $A/bin/archify.mjs demo /tmp/archify-demo

brands only use when the node really is that product. Don't infer brand from an ambiguous role like "database", and a badge can never replace type/label/relationships.

node $A/bin/archify.mjs examples overwrite the HTML files in $A/examples/ in place (it calls scripts/render-examples.mjs with no arguments, outputting to skillRoot/examples). To output elsewhere, call the script directly: node $A/scripts/render-examples.mjs /tmp/out.

Exit code table

rc	Meaning	Verification
`0`	Success	`validate` e.g. packaging, `deliver`, `check`, `compare`, `doctor`, `demo`
`1`	Real failure: schema/layout/artifact-check failed, doctor "not ready", visual-check fail	`validate` broken JSON → `1`; missing `--repo-root` when spec declares evidence → `1`
`2`	Misuse: unknown command, unknown flag, unknown diagram type, `--repo-root` on an unsupported type. And visual-check skipped because there is no Chrome	`bogus` → `2`; `--repo-root` on workflow → `2`; `EXIT.skipped = 2` at `bin/visual-check.mjs:24`

2 carries two different meanings depending on the command. In CI scripts, branch on command first, then on the code; don't merge != 0 into a single branch.