Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
fix(skill): preserve composition choices and review every new architecture
tt-a1ibf2c1e21c00c
diff --git a/archify.zip b/archify.zipindex bf231839..8cd14287 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 03035196..dad24458 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -28,7 +28,7 @@ Use this bounded path for ordinary generation. Do not read the optional Viewer R1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question.2. Use the exact paths in the Type router; do not list `schemas/` or `examples/` first. For Architecture, select the matching showcase example in the Type router before loading it with `references/authoring-defaults.md` in one parallel batch; it includes boundaries, guided views, and conclusion cards. For Workflow, read defaults and its starter together. Read the relevant schema definition for any new field, enum choice, or constrained text; an example shows shape, not every allowed value or length. Boundary kinds and guided-view notes need their schema constraints before writing. For Sequence, Dataflow, and Lifecycle, read defaults, schema, common schema, and example together. Fresh authorship means new IDs, domain wording, and layout; examples provide shape, not facts. Do not run help, doctor, validate a starter, create a temporary diagram, pre-create/list output paths, or query brands. Only for explicitly requested branded marks may you query `node bin/archify.mjs brands "<name>" --json`; read `references/brand-marks.md` only for an unknown brand with a user-provided URL.-3. Artifact first: once requested scope and source evidence are covered, write the candidate directly; do not plan coordinates in prose. For Architecture, default to a system overview: one clear main path, short side branches, and sparse labels. Choose abstraction for the reader's question using [Composition and meaning](references/authoring-defaults.md#composition-and-meaning). Split an overview node only when combining it would mislead the reader about a requested interaction or important boundary; expand internals when the user asks for that mechanism. Keep source evidence for every claim. Never use node, relationship, source-reference, view, card, or boundary counts as an authoring target, ceiling, or performance lever. Add guided views and conclusion cards only when they answer an additional reader question. Set `meta.quality_profile` to `"showcase"` unless the user requests dense `standard`. Place nodes by their actual connections using Layout and routing in the defaults: main-path neighbors stay adjacent, branches sit beside their owner, and return paths have an outside corridor. Check every relationship against that placement before writing positions; automatic routing cannot rearrange nodes. Leave clear gaps for actual relationship labels and add whitespace rather than route controls. On the first draft, let the renderer route every connection: omit `via`, `route`, `fromSide`, `toSide`, `channelX`, `channelY`, `labelAt`, `labelDx`, `labelDy`, and `labelSegment` unless the user supplied that exact route intent. Add the smallest control only after a measured diagnostic.+3. Artifact first: once requested scope and source evidence are covered, write the candidate directly; do not plan coordinates in prose. For Architecture, default to a system overview: one clear main path, short side branches, and sparse labels. Choose abstraction for the reader's question using [Composition and meaning](references/authoring-defaults.md#composition-and-meaning). Split an overview node only when combining it would mislead the reader about a requested interaction or important boundary; expand internals when the user asks for that mechanism. Keep source evidence for every claim. Never use node, relationship, source-reference, view, card, or boundary counts as an authoring target, ceiling, or performance lever. Add guided views and conclusion cards only when they answer an additional reader question. Set `meta.quality_profile` to `"showcase"` unless the user requests dense `standard`. Place nodes by their actual connections using Layout and routing in the defaults: main-path neighbors stay adjacent, branches sit beside their owner, and return paths have an outside corridor. Check every relationship against that placement before writing positions; automatic routing cannot rearrange nodes. Leave clear gaps for actual relationship labels. Start with automatic routes; use simple endpoint sides when the composition needs a main rail and a distinct branch. Do not guess `via`, `channelX`, `channelY`, or label coordinates before measured geometry. Use the smallest control that expresses the intended route.4. Once the complete first candidate is written, run `finalize` directly. Its first gate is showcase validation; successful first drafts need no separate pre-validation. Keep the candidate unchanged while the command runs:```bash@@ -76,7 +76,7 @@ Use the `finalize` command above for the first candidate and after a repair.`finalize` stops at the first non-passing gate. Its compact stdout and `<output-stem>.finalize-summary.json` are the normal evidence; `<output-stem>.finalize.json` is full audit detail, not ordinary repair context. A passing handoff reports `visualReview: "not-requested"` and creates no screenshots.-Escalate to perceptual review when the summary includes `visualReviewRecommendation`, the user requests an aesthetic review, a template/renderer/viewer change needs visual regression evidence, a novel layout or browser diagnostic leaves low confidence, or the run is a sampled audit. Run `visual-check` on the finalized artifact, open its HTML contact sheet in a browser or inspect the viewport PNGs with a capable image reader, and trace the affected routes at the common desktop viewport. Each arrow must remain distinct and each relationship traceable through crossings and bends. Repair unreadable placement or routes while preserving semantic coverage, then finalize the new candidate. The recommendation's counts trigger inspection; they are not content budgets or proof of a defect. If perceptual review is unavailable, report that quality remains unverified rather than treating automated success as visual approval.+For every newly authored or repositioned Architecture, run `visual-check` and inspect its desktop captures before handoff. Check that the main interaction and each secondary chain read in order, branches stay near their owner, and labels visibly belong to their lines. A low crossing count does not establish this. For other artifacts, escalate to perceptual review when the summary includes `visualReviewRecommendation`, the user requests an aesthetic review, a template/renderer/viewer change needs visual regression evidence, a novel layout or browser diagnostic leaves low confidence, or the run is a sampled audit. Run `visual-check` on the finalized artifact, open its HTML contact sheet in a browser or inspect the viewport PNGs with a capable image reader, and trace the affected routes at the common desktop viewport. Each arrow must remain distinct and each relationship traceable through crossings and bends. Repair unreadable placement or routes while preserving semantic coverage, then finalize the new candidate. The recommendation's counts trigger inspection; they are not content budgets or proof of a defect. If perceptual review is unavailable, report that quality remains unverified rather than treating automated success as visual approval.For recovery, the required order stays `deliver` → strict provenance `check` → `browser-check`. Run optional `visual-check` only against a strict-provenance artifact. Read `references/delivery-contract.md` for standalone syntax, any failed gate, stale provenance, recovery metadata, repeated delivery to one path, export evidence, or post-delivery opening.diff --git a/archify/references/authoring-defaults.md b/archify/references/authoring-defaults.mdindex c3f547a4..586a0f3d 100644--- a/archify/references/authoring-defaults.md+++ b/archify/references/authoring-defaults.md@@ -53,10 +53,10 @@ Set required `meta.output` to a portable POSIX-relative `.html` path, such as `r- Architecture sublabels render at a preferred 9px before responsive projection. Size each component for that preferred size (`5.4px × text units + 8px`, counting each CJK character as two units) instead of relying on shrink-to-fit. If a supporting phrase would make the node disproportionately wide, keep the node's exact role or protocol concise and preserve the supplementary fact in a guided-view note or conclusion card. Never remove a responsibility, protocol, or boundary fact just to shorten text.- If the largest viewport still has a conspicuous empty lower band at the viewer's width cap, redistribute authored Y positions and increase the viewBox height proportionally; do not add filler copy or decorative cards.- Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; follow the label-preserving repair order.-- Place Architecture nodes from connectivity before assigning coordinates: lay the main interaction path in order, place a branch beside the node it actually connects to, and place a shared store beside its main readers/writers. A category row (all runtimes, then all workers, then all stores) is useful only when the actual edges also follow it. Keep each tightly connected neighborhood together; give real return paths a clear outside corridor. Mentally trace every relationship across the proposed boxes before writing: if an unrelated node or another neighborhood blocks it, move the connected neighborhood now. The router chooses paths around fixed boxes; it does not rearrange a poor node layout. This is part of writing the first JSON, not an extra planning document or tool pass.-- For a medium Architecture, encode one obvious main path, but let it step across multiple rows when one horizontal rail would create a shallow strip, long empty corridors, or force semantic compression. Put short branches above or below their nearest hub. The first draft leaves every connection on automatic routing and omits `via`, `route`, `fromSide`, `toSide`, `channelX`, `channelY`, and label-position controls unless the user supplied that exact route intent. After a measured diagnostic, add only the smallest named control: at a crowded hub reserve facing sides for the main path and other sides for branches, or give a real return edge one compact outer side pair or perimeter corridor. Never make unrelated orthogonal segments share the same axis for 8px or more; keep nonzero segments at least 8px and interior turns at least 16px.+- Place Architecture nodes from connectivity before assigning coordinates: lay the main interaction path in order, place a branch beside the node it actually connects to, and place a shared store beside its main readers/writers. A category row (all runtimes, then all workers, then all stores) is useful only when the actual edges also follow it. Keep each tightly connected neighborhood together; give real return paths a clear outside corridor. Mentally trace every relationship across the proposed boxes before writing: if an unrelated node or another neighborhood blocks it, move the connected neighborhood now. The router chooses paths around fixed boxes; it does not rearrange a poor node layout. Choose the main path by the reader’s task, not by component category or the longest graph path. Keep a second data-processing chain in its own consistent reading order; place its scheduler beside the stage it drives. Do not move the main actor to a distant row to make room for a background worker. This is part of writing the first JSON, not an extra planning document or tool pass.+- For a medium Architecture, encode one obvious main path, but let it step across multiple rows when one horizontal rail would create a shallow strip, long empty corridors, or force semantic compression. Put short branches above or below their nearest hub. Start with automatic routes. Simple `fromSide` / `toSide` choices may express a deliberate composition on the first draft; reserve `via`, `channelX`, `channelY`, and label-position controls for measured geometry. For example, at a crowded hub reserve facing sides for the main path and other sides for branches, or give a real return edge one compact outer side pair or perimeter corridor. Never make unrelated orthogonal segments share the same axis for 8px or more; keep nonzero segments at least 8px and interior turns at least 16px.- Before writing, apply `6.5px × ASCII units + 21px`, counting each CJK character as two units, to every labeled connection on the main path. Treat the result as that edge's minimum clear gap, never as one fixed gap shared across the row. Increase the gap or choose a clear segment when the budget does not fit; do not wait for a predictable label-route collision.-- Automatic routes own their endpoint sides. A relationship does not accept a `side` field; only after a diagnostic proves endpoint routing is required, use `fromSide` or `toSide` on the diagnosed endpoint. Each endpoint side is a direction contract: the first and final segment must leave/enter perpendicular to that side.+- Automatic routes own their endpoint sides. A relationship does not accept a `side` field; use `fromSide` or `toSide` when a deliberate branch or return direction is needed. Each endpoint side is a direction contract: the first and final segment must leave/enter perpendicular to that side.- Estimate the resolved Architecture content width before the first write. At 1440px, legacy, unknown, and authored-viewBox artifacts use the conservative 930px diagram budget. A fresh automatic wide Architecture with the recognized Reader contract instead reports its declared budget and cap in `composition.desktopReadability`; use that evidence before changing a semantic node or relationship label. Keep ordinary context text comfortably above the 6px hard floor by adding meaningful rows or using intrinsic-height layout, not by dropping meaning or designing to a fixed viewBox width.- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle. It skips single relationships and explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes. Near parallel ports use an outside bridge so automatic routing cannot create a sub-8px segment or sub-16px interior turn. Architecture separately keeps unobstructed facing automatic ports (`left`/`right` or `top`/`bottom`) on one shared axis when their offset is under 16px and both ports retain corner clearance. If exactly one endpoint was spread, only the unshared endpoint may move onto that axis; if both endpoints were spread, keep the outside bridge so competing ports remain distinct.- In showcase Architecture, an explicit route must stay proportionate to the shortest legal orthogonal route. `composition/excessive-route-detour` reports the actual length, obstacle-aware shortest length, ratio, and empty-space excursion. Remove an unnecessary `via` or move the diagnosed corridor inward; do not enlarge the canvas to legitimize the detour. Related edges may share one deliberate outer bus.diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdindex deed20f5..d61ee9d5 100644--- a/archify/references/delivery-contract.md+++ b/archify/references/delivery-contract.md@@ -488,12 +488,13 @@ The preview runtime ships inside the zero-dependency Skill ZIP and must work witNever start it by default. Do not use it for CI, unattended agents, remote sharing, or mobile use. `--no-open` is only for a user who will open the printed local URL or for loop testing. Stop it with Ctrl-C before handoff. The first Ctrl-C drains the active delivery without publishing it; a second Ctrl-C forces shutdown of both delivery processes and HTTP connections, including incomplete requests. Shutdown preserves the last verified artifact and removes only staging files whose ownership can be verified. If delivery is interrupted before its receipt reaches Preview, unconfirmed files and recovery material may remain in the private staging directory; shutdown does not recursively delete unknown contents. Server state, port, source path, diagnostics, error text, and reload tokens must never enter the generated artifact or any export.-## Optional perceptual review+## Perceptual reviewThe automated path ends with the deterministic browser gate and reports`visual_review: not_requested`. Escalate to perceptual review when any of theseconditions applies:+- an Architecture is newly authored or its nodes have been repositioned;- the compact finalizer includes `visualReviewRecommendation` for crossings or detours;- the user explicitly requests an aesthetic or visual review;- a template, renderer, or Viewer change needs visual regression evidence;@@ -511,7 +512,7 @@ glance can support perceptual review only.Report one truthful optional-review status:-- `visual_review: not_requested` — the default successful handoff.+- `visual_review: not_requested` — no review trigger applies; this is not a visual acceptance claim.- `visual_review: passed` — only after inspecting the rendered artifact.- `visual_review: skipped (image reader unavailable)` — a requested or triggered review could not run.- `visual_review: failed` — with the concrete visible defect.diff --git a/archify/test/ordinary-model-floor.test.mjs b/archify/test/ordinary-model-floor.test.mjsindex 96c83fee..a4dacbe5 100644--- a/archify/test/ordinary-model-floor.test.mjs+++ b/archify/test/ordinary-model-floor.test.mjs@@ -915,9 +915,9 @@ test('packaged skill puts a bounded ordinary-model path before progressive featu'once requested scope and source evidence are covered, write the candidate directly','do not plan coordinates in prose','Fresh authorship means new IDs, domain wording, and layout',- 'let the renderer route every connection',- 'omit `via`, `route`, `fromSide`, `toSide`, `channelX`, `channelY`, `labelAt`, `labelDx`, `labelDy`, and `labelSegment`',- 'Add the smallest control only after a measured diagnostic',+ 'Start with automatic routes',+ 'use simple endpoint sides when the composition needs a main rail and a distinct branch',+ 'Do not guess `via`, `channelX`, `channelY`, or label coordinates before measured geometry','Set `meta.quality_profile` to `"showcase"`','Once the complete first candidate is written, run `finalize` directly','Keep the candidate unchanged while the command runs',