| name | foundation-visualization |
| description | Generate a self-contained, publishable foundation-visualization artefact (one HTML page) from any repository-local `foundations/<topic>/` packet. Reads the packet, extracts metadata / structural tension / fields (grounded vs reused) / provenance, chooses a centerpiece archetype from the packet's own content, fills a CSP-safe theme-aware template, publishes it via the Artifact mechanism, and records the returned URL back into the packet README. Companion to `deep-research-foundations` (which authors the packet).
|
| version | 0.1.0 |
Foundation Visualization
Turn a foundations/<topic>/ packet into one publishable HTML page: a hero
thesis, an apt centerpiece diagram, a structural-tension band, color-coded field
cards (grounded vs reused), a provenance summary, and a footer of paths and
issue refs.
This skill is self-sufficient. An agent holding only (a) a foundations packet
and (b) this skill directory can go packet → published artefact → URL recorded
back into the packet README, with no reliance on any prior conversation. It is
the visualization companion to deep-research-foundations: that skill authors
the packet; this skill renders it.
When to use
Use it when a foundations/<topic>/ packet exists and someone wants a shareable
visual of it — a card for a review, a link in the README, an entry in a
constellation of foundations. One packet in, one artefact URL out.
Inputs — the packet contract
Read these files from the target foundations/<topic>/ directory. Not every
packet has every file; take what is present and never invent a missing field.
| File | What to pull |
|---|
README.md | topic title (the # heading), Purpose sentence, front-matter lines (tracking issue, related RISE spec, related entity, date created, packet status, verification, and an existing Visualization: URL if any), and the "Fields covered" / "Quick Reference: Fields Covered" table |
intent-understanding.md | the Structural tension — "Current reality" and "Desired outcome" (prose in some packets, a Before/After table in others; distil each side to one sentence) |
context-layer.md | canonical terms, MECE field list, reuse crosswalk (which fields are reused vs grounded here), related issues/specs |
synthesis.md | the composition — how the fields compose; use it to name a centerpiece and write field-card descriptions (may be absent in leaner packets) |
source-ledger.yaml | meta.verification_status, meta.issue, meta.generated, count of sources, and a few representative sources[].id + field for the provenance strip |
Packet element → visual slot mapping
Every slot maps to a field that actually appears in a real packet. If the packet
lacks the source, delete that slot rather than inventing content.
| Packet element (source) | Template slot |
|---|
README # heading | {{TOPIC_TITLE}} (hero <h1> + <title>) |
README Purpose first sentence / intent "Desired outcome" | {{THESIS}} |
packet root label (e.g. Foundation Packet · Miadi · Mighty Eagle) | {{EYEBROW}} |
source-ledger meta.generated / README "Date created" | {{DATE}} chip |
README tracking issue / source-ledger meta.issue | {{TRACKING_ISSUE}} chip |
| README "Related entity" or "Related RISE Spec" | {{RELATED_ENTITY_OR_SPEC}} chip |
source-ledger meta.verification_status | {{VERIFICATION_STATUS}} chip and provenance heading |
| README "Packet status" | {{PACKET_STATUS}} chip |
| canonical terms / synthesis loop-or-set shape | centerpiece archetype + node labels |
| intent "Current reality" | {{CURRENT_REALITY}} |
| intent "Desired outcome" | {{DESIRED_OUTCOME}} |
| README "Fields covered" rows (field, why-it-matters, grounding) | .field cards: {{FIELDn_NAME}} / {{FIELDn_DESC}} |
| grounded-vs-reused tag per field (context-layer reuse crosswalk) | .tag grounded / .tag reused + --fc color |
source-ledger sources[] count + representative id/field | provenance strip |
| context-layer related issues / README front-matter | footer {{REFn}} chips + / |
Repeat .chip, .field, .ref, and .src elements to match the packet; delete
example rows the packet does not fill.
Centerpiece archetypes
The centerpiece must fit the packet's own shape — do not hard-code the
MAPE-K loop. Five archetypes, all built from the template's shared ring / node /
spoke classes and the four-direction medicine-wheel palette:
- radial-loop — a named cycle with stages that return to origin (MAPE-K,
OODA, an autonomic cadence, a four-direction cadence). 3–6 stage nodes around
an optional core; a travelling pulse signals the loop.
- field-constellation — N co-equal fields with cross-references but no cycle
or order. Core = the topic; field nodes on a ring joined by faint spokes.
This is the default when nothing more specific fits.
- pipeline — an ordered, non-cyclic flow (input → transform → output; events
flowing through). Use the
.pipe strip as the centerpiece.
- tension-arc — the packet's before→after transformation is the star and
there are few fields (≤2). Promote the structural-tension band; keep the
diagram minimal.
- layered-stack — fields have explicit dependency/containment order
(foundation → built-on → surface; progressive-disclosure layers).
Selection rule (deterministic — first match wins)
Scan context-layer.md canonical terms + synthesis.md + the fields table, then:
- If
context-layer.md declares a centerpiece (e.g. a line
centerpiece: radial-loop), honor it and skip the heuristic.
- Named cyclic loop present (MAPE-K, OODA, autonomic loop, medicine wheel,
"the loop", stages returning to start) → radial-loop.
- Ordered non-cyclic flow dominates ("flows through", input→…→output, N
sequential stages, an event pipeline) → pipeline.
- Fields carry explicit dependency/containment order or "layer / stack /
progressive" language → layered-stack.
- The before→after transformation dominates and fields ≤ 2 → tension-arc.
- Otherwise (3–6 co-equal fields, no order) → field-constellation (default).
The template stubs radial-loop and field-constellation in full; compose the
other three by editing the kept centerpiece block (pipeline uses .pipe,
tension-arc leans on the tension band, layered-stack stacks nodes vertically with
spokes). Worked example: the event-driven-documentation packet names MAPE-K →
rule 1 → radial-loop. The content-visualization-and-exposure packet is three
co-equal modes with no cycle → rule 5 → field-constellation.
Workflow
1. Locate and read the packet
Read every file listed under Inputs. Note today's date only if the packet has
no generated/"Date created" of its own.
2. Extract
Pull each mapped slot value. For grounded vs reused: a field is reused if the
context-layer reuse crosswalk / README grounding column points it at another
foundations/<other>/ packet; otherwise grounded. Distil the structural
tension to one sentence per side.
3. Choose the centerpiece
Apply the selection rule. Record which archetype and why (one line) — it goes in
the packet note later.
4. Fill the template
Copy template.html from this skill directory to a working file (e.g. the repo
scratchpad or foundations/<topic>/viz.html). Replace every {{SLOT}}. Keep
exactly one centerpiece section; delete the other. Repeat/trim .chip, .field,
.ref, .src rows to match the packet. Delete the optional pipeline section
unless the packet truly has an ordered flow. Leave no {{...}} marker behind.
The file MUST stay content-only: it is <title> + <style> + body markup,
with NO <!doctype>, <html>, <head>, or <body> tags — the Artifact publish
step wraps it. It must stay CSP-safe (no external fonts / scripts / images) and
keep the theme tokens, prefers-reduced-motion guard, and responsive grids
intact.
5. Publish via the Artifact mechanism
Call the Artifact tool on the filled file:
file_path: the filled HTML file (absolute path)title: "<Topic Title> — Foundation" (matches the <title> tag)description: one sentence, e.g. "Foundation-visualization for the <topic> packet: thesis, <archetype> centerpiece, fields, and provenance."favicon: a subject-fitting emoji — the default is "🧭" (a foundation/atlas
compass); pick another only if the topic clearly calls for it, and keep it
stable across redeploys.
The tool returns a private artefact URL on the maintainer's account (shareable
via the page's own share menu). If updating an existing visualization, redeploy
the same file_path (same-session) or pass the packet's recorded
Visualization: URL as url to update it in place.
6. Record the URL back into the packet README
This step is mandatory — the URL must live in the packet, not only in chat.
In foundations/<topic>/README.md, add or update a front-matter line alongside
the other front-matter lines (tracking issue, date, status):
**Visualization**: <returned-url> — private artifact on the maintainer's account; share via the page's share menu
If the line already exists, replace its URL. Then state, in your closing message,
the archetype chosen and the recorded URL.
Quality gate
Do not call the visualization done unless:
- every
{{SLOT}} is filled or its element deleted — no markers remain
- exactly one centerpiece section is present, chosen by the selection rule
- no field was invented; grounded/reused tags match the packet's crosswalk
- the file is content-only, CSP-safe, theme-aware, and reduced-motion-safe
- the Artifact publish returned a URL
- the URL is written into
foundations/<topic>/README.md
- unrelated worktree state is untouched (do not
git add unrelated files)
Common pitfalls
- hard-coding the MAPE-K loop for a packet that has no cycle (run the selection
rule; default to field-constellation)
- inventing metadata the packet does not carry (delete the slot instead)
- adding
<!doctype>/<head>/<body> — breaks the Artifact content-only contract
- linking a webfont or CDN — CSP blocks it and the page falls back silently
- publishing the URL only in chat and never writing it into the README
- staging unrelated changes when saving the packet README edit
