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): restore overview-first architecture authoring
tt-a1i8a0b2febb7b8
diff --git a/archify.zip b/archify.zipindex 7d7bf609..a805f621 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 9175c3e8..79fac578 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. Let the real system determine the number of nodes and relationships: keep separate nodes when merging would hide a responsibility, boundary, trust boundary, protocol, lifecycle, ownership, or persistence seam; group only unified concerns. Never use node, relationship, source-reference, view, card, or boundary counts as an authoring target, ceiling, or performance lever. Audit responsibility ownership rather than counts: keep an evidence-backed controller, broker, runtime, or supervisor separate when it manages multiple participants and merging would hide control-plane ownership or lifecycle. Keep an external caller or client separate from the gateway, relay, or service when source distinguishes runtimes or trust; a transport is not its user. Never use shared source citations as a substitute for an omitted role; omit only roles absent in code. For a repository showcase, add curated `meta.views` for distinct reader questions and evidence-backed conclusion cards for material takeaways; every aid must improve comprehension, with no quota. Set `meta.quality_profile` to `"showcase"` unless the user requests dense `standard`. Keep forward flow monotonic where practical, branches beside their owner, shared stores outside the main lane, and feedback paths on the perimeter; wrap broad systems into meaningful rows. 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`. Keep forward flow monotonic where practical, branches beside their owner, shared stores outside the main lane, and feedback paths on the perimeter; wrap broad systems into meaningful rows. 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.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:```bashdiff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.mdindex 7e688a80..0b9d2c75 100644--- a/archify/references/authoring-contract.md+++ b/archify/references/authoring-contract.md@@ -232,7 +232,7 @@ Run `validate` after every edit. Consume `diagnostics[]` by stable `code`, exact### Architecture-Use one obvious primary reading path, which may step across meaningful rows when the source-driven topology needs room. Include every component required to explain the requested responsibilities and boundaries; omit only genuinely irrelevant detail. Group only real ownership, trust, process, or deployment boundaries. Boundaries do not replace relationships.+Choose overview or mechanism detail using [Composition and meaning](authoring-defaults.md#composition-and-meaning). Use one obvious primary reading path, which may step across meaningful rows when the requested topology needs room. Keep the overview readable at its chosen abstraction; expand implementation details when they answer the reader's question. Group only real ownership, trust, process, or deployment boundaries. Boundaries do not replace relationships.Grid placement is preferred when the schema supports it. Free positions are appropriate for a bounded exception, not for prose-level coordinate planning. Keep external actors outside the system boundary when that is factually true.diff --git a/archify/references/authoring-defaults.md b/archify/references/authoring-defaults.mdindex 5d353a12..d49e2303 100644--- a/archify/references/authoring-defaults.md+++ b/archify/references/authoring-defaults.md@@ -13,7 +13,7 @@ When the diagram reflects a real repository, finish the evidence shape while insFor local-only source links or an unsupported forge, set `meta.repository.link_mode` to `"local-only"` and retain `url` and `revision`. This disables web hyperlinks while preserving local identity and source verification.-Keep `<repo-root>` from source inspection and pass it to the first `finalize` call. Do not omit a required role or merge distinct responsibilities merely to reduce layout work.+Keep `<repo-root>` from source inspection and pass it to the first `finalize` call. Choose the diagram's abstraction using Composition and meaning below; retain required facts and evidence at that level.A source reference proves only the implementation visible at that location. When separate files or locations establish materially different relationships, protocols, lifecycle transitions, persistence behavior, or conclusion-card claims, attach those inspected locations to the relevant semantic node. Let the real claims determine the references; never target a total reference count or reuse one citation as a proxy for evidence it does not contain.@@ -23,10 +23,10 @@ Examples demonstrate valid field shape. Before choosing a different boundary kin## Composition and meaning-- Keep one obvious main path. Side branches leave the nearest main-path node. Omit a relationship only during semantic authoring when repository evidence shows it is genuinely irrelevant or already expresses no distinct fact; never delete it to simplify geometry.-- Treat semantic coverage and reader explanation as quality, never as performance overhead. Let the real system determine node and relationship counts; never target a number or merge facts merely to simplify drawing. Do not reduce distinct components, relationships, source evidence, guided views, or evidence-backed conclusion cards merely to finish sooner. For a repository showcase that introduces several functional concerns to a new reader, add focused `meta.views` for the actual reading questions and concise cards for material conclusions. Every reader aid must earn its place; there is no quota.-- Audit ownership before freezing topology. When one controller, broker, runtime, or supervisor creates, routes to, resumes, or observes multiple participants, keep that shared control plane distinct from the managed participants if merging would hide ownership or lifecycle. A source file cited on multiple participant nodes is a signal to check for this seam, not a reason to invent one: follow the actual code and omit absent roles.-- Audit entry and trust boundaries too. When the repository distinguishes an external caller or client from a gateway, relay, tunnel, or local service, show the caller and transport as separate responsibilities. Do not merge an actor into infrastructure merely because both sit on one side branch.+- For Architecture, default to a system overview unless the user requests a detailed mechanism, module map, or deployment topology. Show the main participants, their essential interactions, and the boundaries needed to understand the requested system. Use one clear main path, short side branches, and sparse labels.+- Choose abstraction by the reader's question: would combining these responsibilities mislead the reader about the requested behavior, control ownership, trust, lifecycle, or persistence? If so, keep them separate; otherwise use an accurately named overview node with supporting labels and source references. Separate source files, classes, protocols, or internal services do not by themselves require separate nodes. For example, an overview may show one local HTTP / WebSocket service; a transport-mechanism diagram may expand it. A cloud relay and a local decrypting bridge stay distinct when the remote trust boundary matters.+- Cover the requested meaning, with evidence for every claim. An overview need not enumerate every implementation role discovered during source reading. Put useful supporting facts in sublabels or concise cards; expand a subsystem in a focused diagram when its mechanism is requested. Guided views focus existing topology and do not collapse a crowded default overview. Add `meta.views` or cards only for a real reader question, with no quota.+- Let the requested question and source facts determine node and relationship counts; never target a number. Choose scope and abstraction before routing. Once authoring or repairing an agreed detailed graph, preserve its required roles, relationships, meaningful labels, and evidence; geometry failures do not authorize silently reducing that scope.- A boundary is evidence, not decoration. Use it when it communicates a real trust, runtime, process, ownership, or persistence boundary; a boundary around one node needs an explicit isolation fact. Do not box every concern or duplicate the node label as a boundary title.- Omit `meta.visual_preset` by default so every diagram opens in `classic`, regardless of whether its resolved color mode is light or dark. Switching Light / Dark preserves the current preset. Set `signal-flow`, `blueprint`, or `editorial` only when the user explicitly requests that visual style.- Omit `meta.subtitle` by default. Never invent a subtitle that restates the title, nodes, or cards; include one short supporting line only when the user explicitly asks for it.diff --git a/archify/references/repository-authoring.md b/archify/references/repository-authoring.mdindex 72048bdb..8e4d64a1 100644--- a/archify/references/repository-authoring.md+++ b/archify/references/repository-authoring.md@@ -30,7 +30,10 @@ fact has supporting source evidence.3. **Trace ownership.** For each step, name the controller that owns thedecision, the runtime that performs it, and the filesystem or durable storethat supplies or receives bytes. Keep control ownership separate from file- I/O. A configured provider, an injected adapter, a local stub, and a durable+ I/O in your source understanding. Choose which distinctions need separate+ nodes using [Composition and meaning](authoring-defaults.md#composition-and-meaning);+ discovering an implementation role does not automatically add it to the overview.+ A configured provider, an injected adapter, a local stub, and a durableservice are different claims; label the one the source supports.4. **Record evidence while reading.** Keep exact repository-relative paths and@@ -86,8 +89,8 @@ boundaries currently use `kind: "region"` or `kind: "security-group"`; sourcereferences use `path`, `line`, and optional `end_line`; guided-view notes havetheir own limit.-Repository-backed components need concise, truthful `sources` references. Keep-control ownership separate from filesystem I/O: the code that reads or writes+Repository-backed components need concise, truthful `sources` references. Preserve+control ownership when summarizing filesystem I/O: the code that reads or writesa file owns that action, while a pure in-memory transform receives and returns-values. Use the existing examples for valid field shape, then replace all+values. This fact-check does not require a separate overview node for every helper. Use the existing examples for valid field shape, then replace allidentifiers, wording, source paths, and claims with inspected repository facts.diff --git a/archify/test/ordinary-model-floor.test.mjs b/archify/test/ordinary-model-floor.test.mjsindex a0788d29..04731de3 100644--- a/archify/test/ordinary-model-floor.test.mjs+++ b/archify/test/ordinary-model-floor.test.mjs@@ -940,9 +940,9 @@ test('packaged skill puts a bounded ordinary-model path before progressive featu}assert.doesNotMatch(skill.slice(fastPath, fastPathEnd), /Then run exactly one `validate/);assert.match(skill.slice(fastPath, fastPathEnd), /references\/authoring-defaults\.md/);- assert.match(skill, /real system determine the number of nodes and relationships/i);+ assert.match(skill, /default to a system overview/i);assert.match(skill, /Never use node, relationship, source-reference, view, card, or boundary counts as an authoring target/i);- assert.match(authoringDefaults, /Let the real system determine node and relationship counts/i);+ assert.match(authoringDefaults, /Let the requested question and source facts determine node and relationship counts/i);assert.match(authoringDefaults, /never target a total reference count/i);for (const instructions of [skill, authoringDefaults]) {assert.doesNotMatch(