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
docs: make diagram handoffs concise and artifact first (#892)
tt-a1i65607f4f807f
diff --git a/archify.zip b/archify.zipindex df8df49f..c267dfb6 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex abcab46a..f33a4227 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -87,13 +87,13 @@ When a passing Architecture receipt reports `visualReviewRecommendation.signals.When `layoutReviewRecommendation.action` is `inspect-sequence-width`, follow [Sequence width review](references/delivery-contract.md#sequence-width-review) before handing off a newly authored Sequence.-Perceptual review is optional for ordinary generation, including a newly positioned Architecture. Use [Optional capture evidence](references/delivery-contract.md#optional-capture-evidence), with `--out-dir <folder>/visual-check`, when the user requests visual review, during development audits, or for a concrete route/browser concern. `visualReviewRecommendation` is advisory. Inspect captures before claiming visual quality; otherwise report automated checks only.+Perceptual review is optional for ordinary generation, including a newly positioned Architecture. Use [Optional capture evidence](references/delivery-contract.md#optional-capture-evidence), with `--out-dir <folder>/visual-check`, when the user requests visual review, during development audits, or for a concrete route/browser concern. `visualReviewRecommendation` is advisory. Inspect captures before claiming visual quality; qualify any check claim as automated when perceptual review has not occurred.Read [Delivery contract](references/delivery-contract.md) for failed gates, standalone commands, provenance/recovery, repeated delivery, exports, or opening. Recovery follows `deliver` → strict provenance `check` → `browser-check`; captures require strict provenance.For workflow viewport overflow, read [Workflow viewport repair](references/authoring-contract.md#workflow-viewport-repair) before the next layout edit.-Report artifact checks, browser evidence, captures, and actual perceptual review as distinct results. For an explicitly requested immediate preview or active desktop loop, see [Optional opening](references/delivery-contract.md#optional-opening).+When reporting verification details, distinguish artifact checks, browser evidence, captures, and actual perceptual review. For an explicitly requested immediate preview or active desktop loop, see [Optional opening](references/delivery-contract.md#optional-opening).## Optional viewer capabilities@@ -114,4 +114,13 @@ When shell access is unavailable, hand-place architecture SVG into `assets/templ## Output-Return the checked HTML as an absolute path, diagram type, validation summary, specification/artifact receipt, browser-evidence status, and truthful visual-review status. Do not claim success for a non-zero command or claim visual inspection you did not perform.+Reply in the user's language, as briefly as the result allows; the diagram carries the content, so a single diagram usually needs one line.++- Lead with a clickable Markdown link to the HTML: a descriptive title, not the file name, and its absolute path, wrapped in `<...>` when it contains spaces.+- When the user wants to understand a system or codebase rather than draw a described subject, add one or two sentences with the key takeaway. Skip sentences that only restate what the diagram obviously shows.+- State anything that changes how the diagram should be read: the abstraction level or deliberately omitted parts when a reader might expect them, illustrative rather than measured values, missing source evidence, or requested content dropped or merged during repair.+- For several diagrams, report completion once with a link to an existing overview or compact per-diagram links, not a directory path.++Do not recap commands, repair rounds, hashes, quality profiles, or check lists; they stay in the receipts. If asked whether the diagram was verified, answer in one line, such as “Automated checks passed; not visually reviewed.” Give receipt links and details only for reproducibility or troubleshooting. Disclose requested visual review that could not run, and claim visual inspection only when performed. Keep the required update line under Update awareness.++Example: `Created [Checkout request timing](/abs/path/checkout-timing.html). Durations are illustrative, not measured.`diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdindex e8be2089..ddab4e8b 100644--- a/archify/references/delivery-contract.md+++ b/archify/references/delivery-contract.md@@ -601,7 +601,8 @@ fit, focus/search/passport closure, and export cleanliness. This review issupplementary and never changes `browser_evidence`. An unconstrained browserglance can support perceptual review only.-Report one truthful optional-review status:+In a diagnostic or structured handoff, report one truthful optional-review+status:- `visual_review: not_requested` — no review trigger applies; this is not a visual acceptance claim.- `visual_review: passed` — only after inspecting the rendered artifact.@@ -617,14 +618,16 @@ artifact receipts are no longer current.## Handoff receipt-Return:+For a requested diagnostic or structured handoff, derive the following details+from the existing receipts. Ordinary user-facing replies follow+[Output](../SKILL.md#output); this checklist is not a default chat response.```text-diagram_type: architecture|workflow|sequence|dataflow|lifecycle+diagram_type: <actual diagram type>output: /absolute/path/to/file.htmlspecification_sha256: <receipt value>artifact_sha256: <receipt value>-validation: 9/9 showcase, 0 errors, 0 warnings+validation: <actual quality profile, check counts, errors, and warnings>browser_evidence: passed|failed|skippedvisual_review: not_requested|passed|skipped (image reader unavailable)|failedcorrection_rounds: 0|1|2diff --git a/test/authoring-safety-contract.test.mjs b/test/authoring-safety-contract.test.mjsindex d8399c9f..fa9f0e0c 100644--- a/test/authoring-safety-contract.test.mjs+++ b/test/authoring-safety-contract.test.mjs@@ -43,7 +43,6 @@ test('visual-check stays a pending sidecar receipt instead of a polish claim', ('utf8',);assert.match(skill, /Optional capture evidence\]\(references\/delivery-contract\.md#optional-capture-evidence\)/);- assert.match(skill, /Inspect captures before claiming visual quality; otherwise report automated checks only/);assert.match(skill, /references\/delivery-contract\.md/);assert.match(deliveryContract, /Both browser commands inspect the exact delivered HTML without modifying or rerendering it/);diff --git a/test/delivery-contract.test.mjs b/test/delivery-contract.test.mjsindex 4c560384..6c17fc37 100644--- a/test/delivery-contract.test.mjs+++ b/test/delivery-contract.test.mjs@@ -61,7 +61,7 @@ test('required browser evidence stays deterministic and capture-free', () => {});test('delivery, browser evidence, capture evidence, and perceptual review remain distinct', () => {- assert.match(skill, /artifact checks, browser evidence, captures, and actual perceptual review as distinct results/);+ assert.match(skill, /When reporting verification details, distinguish artifact checks, browser evidence, captures, and actual perceptual review/);assert.match(skill, /Delivery contract\]\(references\/delivery-contract\.md\)/);for (const [name, source] of [['delivery contract', delivery]]) {assert.match(source, /deliver[\s\S]*deterministic/i, name);@@ -91,7 +91,7 @@ test('perceptual review is optional for fresh architectures and available for viassert.match(perceptualReviewSection, /run `visual-check`[\s\S]*contact sheet/i);assert.match(perceptualReviewSection, /never exceed two focused correction rounds/i);assert.match(perceptualReviewSection, /Never report\s+`visual_review: passed` without inspecting/i);- assert.match(skill, /Inspect captures before claiming visual quality; otherwise report automated checks only/);+ assert.match(skill, /Inspect captures before claiming visual quality; qualify any check claim as automated when perceptual review has not occurred/);assert.match(perceptualReviewSection, /visual_review: skipped \(image reader unavailable\)[\s\S]*requested or triggered review could not run/i);assert.match(perceptualReviewSection, /visualReviewRecommendation/);assert.match(delivery, /Open the HTML contact sheet in a browser or inspect the viewport PNGs/i);