Proposal: agent-native skills for the architecture model (generate→refine) + Loom lifecycle (terminal-free adopter path)

[montfort]

Motivation

Two durable lessons from the Sentinel dogfooding (#262/#263/#273) point at the same gap:

1. architecture generate always produces a structural seed that needs a refinement pass. The command mines structure (dirs → components) but the model encodes intent — layers, dependency links, naming — that the filesystem doesn't contain. So every adopter, after generate, faces the same manual step: reassign components out of unassigned into real layers, wire dependency links, sync the DrawIO. That refinement is exactly an AI-agent-shaped task — I did it for Sentinel in a single pass (raw 4-component seed → 13-component, 7-layer, 10-link model rendering arrows in 2D + 3D, PR feat(framework+cli): fw-4.13.3 / cli-3.12.3 — audit prompt EN-canonical + CLI i18n wiring #142).

2. A growing class of adopters wants to stay in the agent window and never touch a shell. Driving Loom and the architecture phases is trivial in a terminal, but "terminal-free" is a real persona. StrayMark already ships skills (straymark-ailog, straymark-charter-new, straymark-audit-*, straymark-followups) — the architecture/Loom workflow has none.

Proposal: a small suite of agent-native skills covering generate→refine and the Loom lifecycle.

---

1. straymark-architecture — generate + agent-driven refine (the headline)

Runs generate, then drives the refinement a human would otherwise do in DrawIO, using the agent's repo knowledge:

• Replace the seeded .straymark doc-stage layers with real architecture layers, inferred from directory conventions + ADRs; ask the user when the layering is ambiguous.
• Reassign every component out of unassigned.
• Infer dependency links from the import graph / directory structure / ADR "Affected Components" tables.
• Sync the .drawio (vertices and edges) so the 2D view shows arrows.
• validate → iterate to green.

Gotchas the skill MUST encode — each one cost me a debugging cycle on Sentinel; bake them in so no future agent re-hits them:

• The unassigned layer must exist (components seed into it; deleting it → references unknown layer).
• A component.id must not equal any layer.id — for a single-component layer use a suffixed id (core layer → core-infra component). (fw-4.27.0 now emits a clear error for this, but the skill should pre-empt it rather than trip it.)
• links is a list of target component ids (strings), not objects ([{to: …}] fails to parse).
• 3D renders edges from model.yml links; 2D renders them from .drawio edges — both must be written, or arrows show in only one view.
• generate enriches from ADRs only if present; with none it is structure-only.

This compresses what took me ~a dozen tool calls of trial-and-error into one guided pass.

---

2. straymark-loom — server lifecycle, terminal-free

Start / stop / status of the Loom server from the agent window, so the "never touch the terminal" user just gets a link to click:

• up → launch straymark loom serve in the background, report the URL (127.0.0.1:7779).
• down → stop it.
• status → running? which port?

The agent owns the process lifecycle; the user stays in the chat window.

---

3. straymark-architecture-sync (optional, lower priority)

Wrap architecture sync (append-only) to keep the model alive as code grows: run it, surface new dirs/components, reconcile against human edits, re-validate — without re-refining from scratch.

---

The adopter pattern this enables

generate → agent-refine → loom up, entirely from the agent window — a raw structural seed becomes a curated, arrow-complete model and a running visualization, with the adopter never editing YAML/DrawIO or opening a shell. It's the terminal-free counterpart to the manual DrawIO path, and (per the adopter-program framing in discussions/277) a documentable recommended path: generate the seed, hand it to an agent with repo context, get a refined model in one pass.

Implementation notes

• Distribute as SKILL.md across .claude/ .codex/ .gemini/ .agent/ like the existing skills.
• Grounded in the Sentinel refinement (PR feat(framework+cli): fw-4.13.3 / cli-3.12.3 — audit prompt EN-canonical + CLI i18n wiring #142). Related: Loom: dangling-reference panel is ~98% structural noise — resolver/indexer should account for FU backlog, .telemetry.yaml, templates & i18n #262, i18n robustness: extractors key on English structure (slugs, headings, word boundaries) — breaks silently for zh/es-first adopters #263, architecture model DX: opaque parse errors (unassigned@0, component-id≠layer-id), shallow generate, unpainted has-debt overlay #273 (architecture/Loom DX); adopter registration discussions/277.