Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix(skill): improve natural-use composition and prevent avoidable retries

tt-a1ib92c929b2656
diff --git a/archify.zip b/archify.zip
index 99b3bbef..49a9bce8 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 196f73ab..f4de44be 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -27,8 +27,8 @@ The update check is outside the delivery critical path. A harness may start it c
Use this bounded path for ordinary generation. Do not read the optional Viewer Runtime reference unless the user asks about those features.
1. 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. Start with automatic routes and let them align main-path endpoints. Pin an endpoint side only for a necessary branch/return constraint or user-supplied geometry; facing-side pins can introduce doglegs between unequal-height nodes. Do not guess `via`, `channelX`, `channelY`, or label coordinates before measured geometry. Use the smallest control that expresses the intended route.
+2. Use the exact paths in the Type router; do not list `schemas/` or `examples/` first. For Architecture, read `references/authoring-defaults.md` and the matching showcase example in a bounded output batch separate from project documents and complete schemas. Recover any truncated reference section before writing; raising a nested command limit does not prevent a combined tool response from truncating. The example 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 led by the main user journey, with its necessary branches close. Choose subsystem-level nodes before coordinates; cooperating roles may share an accurately named node when their distinction is not the reader’s question. Keep secondary and opt-in capabilities in concise sourced notes unless their path is needed to understand that journey or a requested boundary. Preserve behavior-changing conditions and the requested scope. Use the defaults’ classic styling and title-only header unless the user requests otherwise. 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 and let them align main-path endpoints. Pin an endpoint side only for a necessary branch/return constraint or user-supplied geometry; facing-side pins can introduce doglegs between unequal-height nodes. 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 `finalize` receipt reports `visualReview: "not-requested"` and creates no screenshots; report the subsequent perceptual review separately.
-Perceptual review is optional in ordinary generation: a new or repositioned Architecture does not by itself require screenshots or an image-reading step. Use it when the user requests a visual review, during development audits, or when a concrete route/browser concern needs visual diagnosis. `visualReviewRecommendation` is advisory, not a delivery gate or proof of a defect. Run `visual-check` on the finalized artifact with `--summary --require-provenance` and the same `--out-dir` as finalize, if used; compact JSON links all captures and the full receipt. If you choose to review, inspect the relevant viewport/theme captures and trace the affected relationships. For tangled routes, follow [Architecture layout repair](references/architecture-layout-repair.md); preserve meaning and evidence, then finalize the revised candidate. Without image inspection, report automated checks only and leave perceptual review unclaimed. If perceptual review is unavailable, report that quality remains unverified for that requested review.
+Perceptual review is optional in ordinary generation: a new or repositioned Architecture does not by itself require screenshots or an image-reading step. Use it when the user requests a visual review, during development audits, or when a concrete route/browser concern needs visual diagnosis. `visualReviewRecommendation` is advisory, not a delivery gate or proof of a defect. Run `node bin/archify.mjs visual-check <output.html> --summary --require-provenance` and the same `--out-dir` as finalize, if used; compact JSON links all captures and the full receipt. If you choose to review, inspect the relevant viewport/theme captures and trace the affected relationships. For tangled routes, follow [Architecture layout repair](references/architecture-layout-repair.md); preserve meaning and evidence, then finalize the revised candidate. Without image inspection, report automated checks only and leave perceptual review unclaimed. If perceptual review is unavailable, report that quality remains unverified for that requested review.
For recovery, the required order stays `deliver` → strict provenance `check` → `browser-check`. Run `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.md
index 8a03d53d..56b39be0 100644
--- a/archify/references/authoring-defaults.md
+++ b/archify/references/authoring-defaults.md
@@ -4,14 +4,14 @@ Read this file once before writing a fresh candidate. A frozen existing candidat
## Repository-backed first draft
-When the diagram reflects a real repository, finish the evidence shape while inspecting source, not after validation fails. Record the canonical remote URL and full 40-character commit, add `meta.repository`, and attach at least one inspected `sources` entry to every key semantic node. Use only real repository-relative files and line numbers; source references are evidence, never decoration. The minimum shape is:
+When the diagram reflects a real repository, finish the evidence shape while inspecting source, not after validation fails. Copy the credential-free origin returned by `git remote get-url origin` without converting its transport or path, and record the full 40-character commit, add `meta.repository`, and attach at least one inspected `sources` entry to every key semantic node. Use only real repository-relative files and line numbers; source references are evidence, never decoration. The minimum shape is:
```json
-"meta": { "repository": { "url": "<canonical-url>", "revision": "<40-char-commit>" } },
+"meta": { "repository": { "url": "<credential-free-origin>", "revision": "<40-char-commit>" } },
"components": [{ "id": "runtime", "sources": [{ "path": "src/runtime.ts", "line": 1, "label": "runtime entry" }] }]
```
-For 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.
+For an SSH origin, an unsupported forge, or intentionally local-only source links, set `meta.repository.link_mode` to `"local-only"` and retain `url` and `revision`. Web links require a supported GitHub/Gitee HTTPS origin. Local-only disables web hyperlinks while preserving local identity and source verification.
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.
@@ -23,8 +23,8 @@ Examples demonstrate valid field shape. Before choosing a different boundary kin
## Composition and meaning
-- For Architecture, default to a system overview unless the user requests a narrower mechanism, module map, or deployment topology. Cover the main user entry points, interactions, and important deployment/trust boundaries described by the project, including opt-in paths. An optional path may be a short branch or a sourced scope note; keep its role and boundary visible without expanding its internals. Name a deliberately narrower scope in the title rather than silently omitting it from a system overview. 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.
+- For Architecture, default to a system overview unless the user requests a narrower mechanism, module map, or deployment topology. Lead with the main user journey and keep necessary branches close. Group cooperating implementation roles into accurately named subsystems; a group may contain multiple processes without implying they are one process. Expose a separate role or interaction when combining it would hide a requested mechanism or an important boundary. Retain secondary and opt-in capabilities as concise sourced notes by default; draw their path when needed to understand the main journey or a requested boundary. Preserve their role and trust conditions in either form. Name a deliberately narrower scope in the title rather than silently omitting it.
+- 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. Keep a behavior-changing condition visible on its affected node or relationship: an approval, authorization, or state-transition gate must not look unconditional while its qualifier appears only in a card. 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.
- When correcting an authored overview's abstraction, map every affected role, relationship direction, protocol, boundary, and source reference to its surviving node or relationship before regrouping. Carry the inspected references for each retained claim onto the relevant surviving component; a citation proving process startup does not also prove its message protocol. Check that requested meaning and evidence still have a home. User-supplied or agreed topology stays fixed; fewer routes alone do not justify merging.
diff --git a/archify/references/repository-authoring.md b/archify/references/repository-authoring.md
index 8e4d64a1..d531be27 100644
--- a/archify/references/repository-authoring.md
+++ b/archify/references/repository-authoring.md
@@ -10,7 +10,8 @@ fact has supporting source evidence.
1. **Freeze identity.** From the target repository, record `git rev-parse
HEAD`, `git remote get-url origin`, and `git status --short`. Remove HTTP(S)
userinfo (including usernames, passwords, and tokens) before recording the
- origin or placing it in the candidate. Pin the credential-free URL and
+ origin or placing it in the candidate. Preserve its transport, port, path and
+ `.git` suffix; do not rewrite an internal SSH origin as HTTPS. Pin the credential-free URL and
forty-character revision in `meta.repository`; use `link_mode: "local-only"`
for a local fixture whose HTTPS URL is only a repository identity. If the
worktree is dirty, record the changed paths. Repository evidence is verified
diff --git a/archify/test/authoring-safety-contract.test.mjs b/archify/test/authoring-safety-contract.test.mjs
index f2df1e04..893f3e93 100644
--- a/archify/test/authoring-safety-contract.test.mjs
+++ b/archify/test/authoring-safety-contract.test.mjs
@@ -43,7 +43,7 @@ test('visual-check stays a pending sidecar receipt instead of a polish claim', (
path.join(skillRoot, 'references', 'delivery-contract.md'),
'utf8',
);
- assert.match(skill, /Run `visual-check` on the finalized artifact/);
+ assert.match(skill, /Run `node bin\/archify\.mjs visual-check <output\.html> --summary --require-provenance`/);
assert.match(skill, /machine-readable browser evidence[\s\S]*perceptual review/i);
assert.match(skill, /references\/delivery-contract\.md/);
assert.match(skill, /without (?:rerendering or )?modifying/i);