/ork:glyph

Glyph Render an answer as ASCII art plus semantic emojis inline, right now, with no setup questions. Use for a fast visual take on status, comparisons, trade-offs, architecture, or any ad-hoc 'show me X visually' ask. For a full multi-artifact plan playground, use visualize-plan instead.

Glyph

Render the answer as ASCII art plus semantic emojis, inline, immediately. All output renders in a monospace terminal with no external tools.

Core principle: Encode information into structure, not decoration. Every diagram element should communicate something meaningful.

Execution (run this, do not ask first)

The whole point is speed, so there is no setup phase.

With no argument, the topic is the current conversation. Measured over a real 13-prompt session: zero asks supplied a self-contained topic, and the one direct invocation passed nothing at all. /ork:glyph on its own means "render where we are right now" — the open work, the decision just reached, the state of the thing being discussed. Render that; do not ask what to draw.

Given a topic (or the conversation, when none is given):

1. Render immediately. Do NOT call AskUserQuestion to pick a format, do NOT call TaskCreate, do NOT spawn an Agent. Choose the form yourself from the topic shape and draw it. Asking first defeats the skill.

2. Pick the form from the shape of the data, using the pattern library below:

   Topic shape	Form
   state / progress / health	status box + bar meters
   A vs B, options, trade-offs	comparison table or side-by-side boxes
   steps, pipeline, hand-offs	left-to-right flow with ──▶
   containment, layers, layout	nested boxes / tree
   ranked list, scores, counts	table + bar meters
   over time	sparkline or milestone track

3. Emit inline in the reply. Never write a file unless the user asked for one. This is a chat answer, not an artifact.

4. Use the 12-emoji semantic set and box-drawing vocabulary defined in rules/visual-style.md (shipped with this skill). Semantic, never decorative: an emoji must mean something (✅ pass, ❌ fail, ⚠️ risk, 🔴 blocked).

5. Lead with the answer. The visual comes first; prose after it only if it adds something the diagram cannot carry.

6. Stay honest. If a number is unknown, print ? rather than inventing one. A confident-looking chart built on guesses is worse than prose.

When NOT to use this skill: if the deliverable is a multi-section HTML playground, a persisted plan artifact, or anything needing file output, use visualize-plan instead. Glyph is the cheap inline path; visualize-plan is the full pipeline.

Box-Drawing Character Reference

This block intentionally shows multiple sets together as a key. Authors should use ONE set per real diagram; the single-set lint rule enforces this on production diagrams.

<!-- ascii-lint-disable: single-set,single-arrow-style,density-min -->

default:   ┌─┐ │ └─┘  ├─┤ ┬ ┴ ┼
emphasis:  ┏━┓ ┃ ┗━┛  ┣━┫ ┳ ┻ ╋
title:     ╔═╗ ║ ╚═╝  ╠═╣ ╦ ╩ ╬
soft:      ╭─╮ │ ╰─╯
portable:  +-+ | +-+  +-+ + + +
Arrows:    → ← ↑ ↓ ─> <─ ──> <──
Blocks:    █ ▓ ░ ▏▎▍▌▋▊▉
Status:    ● ○ ✓ ✗ ⚠ ◆ ◇ ▶ ▷  ↑↓→ ▓▒░  (closed-set vocab — see rules)

Set Conventions (D8: intent-driven naming)

Tokens live in tokens.json. Names describe USE not APPEARANCE.

Rename codemod (D8): old light/heavy/double/rounded/ascii-fallback → new names above. Old names accepted with warning for one minor release.

Status Glyph Vocabulary

Closed-set v1 of 11 semantic glyphs (●○✓✗⚠◆◇▶▷ ↑↓→ ▓▒░). Single source of truth — see rules/status-glyph-vocabulary.md. Add-a-glyph process in CONTRIBUTING.md.

Diagram Patterns

Architecture Diagrams

┌──────────────┐      ┌──────────────┐
│   Frontend   │─────>│   Backend    │
│   React 19   │      │   FastAPI    │
└──────────────┘      └───────┬──────┘
                              │
                              v
                      ┌──────────────┐
                      │  PostgreSQL  │
                      └──────────────┘

File Trees with Annotations

src/
├── api/
│   ├── routes.py          [M] +45 -12    !! high-traffic path
│   └── schemas.py         [M] +20 -5
├── services/
│   └── billing.py         [A] +180       ** new file
└── tests/
    └── test_billing.py    [A] +120       ** new file

Legend: [A]dd [M]odify [D]elete  !! Risk  ** New

Progress Bars

[████████░░] 80% Complete
+ Design    (2 days)
+ Backend   (5 days)
~ Frontend  (3 days)
- Testing   (pending)

Swimlane / Timeline Diagrams

Backend  ===[Schema]======[API]===========================[Deploy]====>
                |            |                                ^
                |            +------blocks------+             |
                |                               |             |
Frontend ------[Wait]--------[Components]=======[Integration]=+

=== Active work   --- Blocked/waiting   | Dependency

Blast Radius (Concentric Rings)

            Ring 3: Tests (8 files)
       +-------------------------------+
       |    Ring 2: Transitive (5)      |
       |   +------------------------+   |
       |   |  Ring 1: Direct (3)     |   |
       |   |   +--------------+      |   |
       |   |   | CHANGED FILE |      |   |
       |   |   +--------------+      |   |
       |   +------------------------+   |
       +-------------------------------+

Comparison Tables

BEFORE                          AFTER
┌────────────┐                  ┌────────────┐
│  Monolith  │                  │  Service A │──┐
│  (all-in-1)│                  └────────────┘  │  ┌──────────┐
└────────────┘                  ┌────────────┐  ├─>│  Shared  │
                                │  Service B │──┘  │  Queue   │
                                └────────────┘     └──────────┘

Reversibility Timeline

Phase 1  [================]  FULLY REVERSIBLE    (add column)
Phase 2  [================]  FULLY REVERSIBLE    (new endpoint)
Phase 3  [============....]  PARTIALLY           (backfill)
              --- POINT OF NO RETURN ---
Phase 4  [........????????]  IRREVERSIBLE        (drop column)

Key Rules

When to Use Each Pattern

Related Skills

• brainstorm — Design exploration where diagrams communicate ideas
• architecture-patterns — System architecture that benefits from ASCII diagrams
• code-review-playbook — Review comments with inline diagrams

Rules (4)

Create structured ASCII architecture diagrams to communicate system design without external tools — MEDIUM

ASCII Architecture Visualization Patterns

Incorrect — flat text descriptions:

The system has a frontend that talks to a backend API which uses
a database and a cache layer. There's also a message queue for
async processing.

Correct — layered architecture diagram:

┌─────────────────────────────────────────────────────┐
│                    Load Balancer                      │
└──────────┬──────────────────────────┬────────────────┘
           │                          │
┌──────────v──────────┐  ┌───────────v────────────┐
│   API Gateway       │  │   API Gateway          │
│   (instance 1)      │  │   (instance 2)         │
└──────────┬──────────┘  └───────────┬────────────┘
           │                          │
           └──────────┬───────────────┘
                      │
        ┌─────────────┼────────────────┐
        │             │                │
┌───────v──────┐ ┌────v─────┐ ┌───────v──────┐
│  PostgreSQL  │ │  Redis   │ │  RabbitMQ    │
│  (primary)   │ │  (cache) │ │  (queue)     │
└──────────────┘ └──────────┘ └──────────────┘

Blast Radius Visualization

                Ring 3: Tests (8 files)
           +-------------------------------+
           |    Ring 2: Transitive (5)      |
           |   +------------------------+   |
           |   |  Ring 1: Direct (3)     |   |
           |   |   +--------------+      |   |
           |   |   | CHANGED FILE |      |   |
           |   |   +--------------+      |   |
           |   +------------------------+   |
           +-------------------------------+

Direct dependents:   auth.py, routes.py, middleware.py
Transitive:          app.py, config.py, utils.py, cli.py, server.py

Reversibility Timeline

REVERSIBILITY TIMELINE
Phase 1  [================]  FULLY REVERSIBLE    (add column, nullable)
Phase 2  [================]  FULLY REVERSIBLE    (new endpoint, additive)
Phase 3  [============....]  PARTIALLY           (backfill data)
              --- POINT OF NO RETURN ---
Phase 4  [........????????]  IRREVERSIBLE        (drop old column)
Phase 5  [================]  FULLY REVERSIBLE    (frontend toggle)

Comparison Tables

CROSS-LAYER CONSISTENCY
Backend Endpoint          Frontend Consumer     Status
POST /invoices            createInvoice()       PLANNED
GET  /invoices/:id        useInvoice(id)        PLANNED
GET  /invoices            InvoiceList.tsx        MISSING  !!

Key Patterns

Use consistent box-drawing characters and formatting for correct terminal rendering — MEDIUM

ASCII Diagram Fundamentals

Incorrect — inconsistent characters and alignment:

+-------+    +-------+
| Frontend | -> | Backend |
+-------+    +-------+
              |
          +--------+
          | Database |
          +--------+

Correct — proper box-drawing characters with alignment:

Box-Drawing Characters:
┌─┐│└─┘  Standard weight
┏━┓┃┗━┛  Heavy weight
├─┤┬┴    Connectors
╔═╗║╚═╝  Double lines

┌──────────────┐      ┌──────────────┐
│   Frontend   │─────>│   Backend    │
│   React 19   │      │   FastAPI    │
└──────────────┘      └───────┬──────┘
                              │
                              v
                      ┌──────────────┐
                      │  PostgreSQL  │
                      └──────────────┘

Progress Tracking

[████████░░] 80% Complete
+ Design    (2 days)
+ Backend   (5 days)
~ Frontend  (3 days)
- Testing   (pending)

File Trees

src/
├── api/
│   ├── routes.py          [M] +45 -12    !! high-traffic path
│   └── schemas.py         [M] +20 -5
├── services/
│   └── billing.py         [A] +180       ** new file
└── tests/
    └── test_billing.py    [A] +120       ** new file

Legend: [A]dd [M]odify [D]elete  !! Risk  ** New

Workflow Diagrams

Backend  ===[Schema]======[API]===========================[Deploy]====>
                |            |                                ^
                |            +------blocks------+             |
                |                               |             |
Frontend ------[Wait]--------[Components]=======[Integration]=+

=== Active work   --- Blocked/waiting   | Dependency

Key Rules

Use the closed-set status glyph vocabulary for semantic indicators — HIGH

Closed Status Glyph Vocabulary (v1)

Eleven glyphs, frozen at v1.0.0. Adding a 12th is a MINOR bump via the process in CONTRIBUTING.md. Removing or repurposing any of the 11 is a MAJOR bump (rare).

Vocabulary

GLYPH   SEMANTIC                    DON'T USE FOR
─────   ────────                    ─────────────
●       active / on / current       generic bullet
○       inactive / off / pending    decoration
✓       passed / completed          decoration
✗       failed / blocked            general "no"
⚠       warning / attention         hard error
◆       primary / focused           random emphasis
◇       secondary / unfocused       decoration
▶       running / in-progress       generic arrow
▷       paused / awaiting input     generic arrow
↑↓→     trend up/down/forward       random direction
▓▒░     fill: high/med/low          decoration

Incorrect — generic decoration

* Build passed
> Tests running
- Linter clean

Correct — semantic glyphs

✓ Build passed
▶ Tests running
✓ Linter clean

Anti-pattern — repurposing a semantic for decoration

✓ Item 1
✓ Item 2
✓ Item 3

A list of items isn't passing/failing — ✓ is reserved for pass/completed states. Use ● for active items and ○ for inactive/pending ones, or plain - for an unmarked list.

Anti-pattern — mixing semantically-loaded glyphs with decoration

■  Phase 1   ✓  Phase 2   ◉  Phase 3

■ and ◉ are not in the vocabulary — they read as decoration. Pick exactly one glyph from the table above per slot:

✓  Phase 1   ▶  Phase 2   ○  Phase 3
   done       running       pending

Visual Style — ASCII Art and Emoji Usage — MEDIUM

Visual Style

OrchestKit leans into ASCII art and semantic emojis for visual scanability — but only with a fixed vocabulary, only where they earn their keep, and never where they break greppability, byte budgets, or accessibility.

The Twelve-Glyph Vocabulary

Every emoji must come from this list. No decorative additions. Adding to the list requires a PR.

Risk and ranking glyphs (always paired, never solo):

• Risk: 🟢 low · 🟡 medium · 🔴 high
• Ranking: 🥇 1st · 🥈 2nd · 🥉 3rd

ASCII Palette

Use these character sets only — keeps rendering predictable across terminals, GitHub, and CI logs.

<!-- ascii-lint-disable: single-set -->

Box drawing:  ┌─┐ │ ┘─└   (light)
              ╔═╗ ║ ╝═╚   (heavy — reserve for top-level section headers)
Dividers:     ───  ═══
Arrows:       → ↓ ▶ ◀
Progress:     ▓▓▓░░  ████████░░
Bullets:      • ◦ ‣

Do not use: 3D box characters, shaded blocks for decoration, ASCII-art logos, or any character that requires a non-default monospace font.

Per-Surface Rules

✅ Assistant chat output (UNLIMITED)

Lean in. ASCII boxes, tables, diagrams, semantic emoji — all encouraged. This is the highest-leverage surface; cost is per-response, not per-repo.

✅ SKILL.md files

• Allowed: H2 emoji prefix from vocabulary (e.g. ## 🎯 When to use), ASCII diagrams in workflow sections, emoji in table-status columns.
• Forbidden: decorative inline emoji in body prose, emoji-only headings (always pair with text), emoji in code blocks or shell examples.
• 500-line cap still applies. Diagrams pushing the cap → move to references/*.md.

✅ Agent .md files

• Allowed: role emoji in description: field, one ASCII "card" block in body showing scope/tools/cost, emoji in capability tables.
• Forbidden: emoji in YAML keys, name: field, tools: array, or anywhere automation parses structurally.

🔥 Hook source (TypeScript) — strongest yes

Hook stdout renders directly in chat. Every hook message should lead with a severity glyph:

🚨 BLOCK · ⚠ WARN · 💡 HINT · ⏭ SKIP

Wrap multi-line deny messages in ┌─ ─┐ boxes so they disambiguate from assistant output.

✅ README, CHANGELOG, docs/*.md

GitHub renders both natively. Use ASCII architecture diagrams and emoji section headers freely. CHANGELOG entries lead with type emoji: ✨ feat · 🐛 fix · 📝 docs · 🔥 perf · ♻ refactor.

⚠️ CLAUDE.md (project root + .claude/)

Hard 4800-byte cap enforced by tests/perf/test-token-overhead.sh. Box-drawing chars are 3 bytes each — a single 60-char border row costs ~180 bytes.

• Allowed: one emoji per H2 heading.
• Forbidden: ASCII boxes, multi-line diagrams, decorative dividers. Extract to docs/<topic>.md with a one-line pointer.

✅ PR bodies

GitHub renders these natively, same as README. ASCII diagrams from the palette above are encouraged — a before/after box or a file tree carries a review point faster than a paragraph. Emoji are limited to the twelve-glyph vocabulary.

Enforced by bin/validate-visual-style.py --mode body in the Visual-Style PR Lint check. The palette and the emoji vocabulary are two separate lists: box drawing, dividers, arrows and progress blocks are governed by ASCII Palette, everything emoji by The Twelve-Glyph Vocabulary. The validator once conflated them (both report Unicode category So) and rejected plain box-drawn diagrams; keep the two tables distinct when editing either.

❌ Code, commit messages, PR titles

No emoji. No ASCII art. Conventional Commits stays plain (feat:, fix:, etc.) — the type prefix is already the signal. Code comments stay plain so grep stays useful.

The PR title is the strict surface; the PR body is not. --mode title rejects every non-ASCII symbol including the palette, which is why a diagram belongs in the body.

Greppability Contract

Any emoji-prefixed heading must keep the original text intact so grep still works:

✅ ## 🎯 When to use      → grep "## " finds it, grep "When to use" finds it
❌ ## 🎯                  → text-less heading; ungreppable

Accessibility

• Screen readers announce every emoji literally ("check mark", "warning sign"). Don't stack them: one glyph per heading or status, not 🎯🔥✅ chains.
• Box-drawing characters are pronounced as their Unicode names — use them in visual chunks (diagrams, table borders), not inline with prose.
• Never convey meaning via emoji alone. Always pair with text: ✅ Passed not ✅.

Echo-Chamber Mitigation

Heavy emoji in OrchestKit's own SKILL.md files trains the model to emoji-bomb every response when those skills are loaded. The vocabulary cap is the mitigation: when Claude sees the same 12 glyphs used consistently with the same semantics across 100+ files, it learns "these glyphs = these meanings" rather than "emoji = always-on style." Drift from the vocabulary defeats the mitigation — reject PRs that add glyphs outside the list.