Authored by Michael Nash · AgentForge · First published 2026-10-18. This memo is the research and design record behind Directive Shorthand 1.0 (DIRECTIVES.md): the evidence gathered, the paradigms weighed, the decisions taken and the ones deliberately refused. It is preserved as the public rationale record of the standard's design — dated proof of what was designed, when, and why. (This header was added at publication, and one claim phrase in §4.1 was corrected the same day; the correction is recorded in the field journal, Addendum 56. The standard was published as AgentForge Directives 1.0 and formally retitled Directive Shorthand — nickname Lingo — the same evening, Addendum 57; this memo's body keeps the working name it was written under.)

---

Directives, designed from the evidence — a research + design memo

What this is. A fresh-eyes design pass over the AgentForge message-directive system, written for Michael to pick from. The shipped spec (agentpreneur/DIRECTIVES.md — re: family, axes, type-ahead, stacking) is treated here as one candidate design among others, not as a premise. Where it wins against the alternatives, the memo says why; where it loses, the memo says that too, in §3.3.

The intent that governs everything (Michael's, and not up for redesign): (1) a beginner succeeds on first contact, guessing cold; (2) an expert gets real power; (3) minimum typing buys maximum control over how the agent replies and works; (4) the vocabulary ships inside the toolkit, so every agent knows it always — no per-user teaching.

---

1. Principles the research supports

Each principle is stated once, with its evidence. The design in §3–§5 is just these principles applied.

P1 — Recognition beats recall, and working memory holds about 3–4 chunks. Nielsen's heuristic #6: minimize memory load; users should recognize options, not recall them, because working memory is limited to roughly 3–4 items. Two consequences: names must be guessable (a beginner who has never seen the list should be able to invent the token and be right), and the total vocabulary must be chunked — a handful of families, each small enough to hold in mind as one chunk. (humanstandards.org — Nielsen's heuristics)

P2 — One grammar, many commands. Raycast's whole product runs on one interaction rule (type, Enter runs it) across ~2,500 extensions: "Users do not have to learn 2,500 extensions separately. They only have to learn one grammar," and the cost of each new feature drops toward zero. A directive system lives or dies the same way: one token shape, one set of combination rules, learned once. (bearliu.com — Raycast's interaction model)

P3 — Accept any unambiguous prefix; never guess an ambiguous one. This is not a new idea — Cisco IOS has done it for decades: "You can abbreviate commands and keywords by entering the first few characters… The abbreviation must include sufficient characters to make it unique," and when it isn't, the device answers % Ambiguous command and the user adds a letter. Network engineers type sh ip int br for show ip interface brief all day, having memorized no shorthand list — the shorthand is derived. This is the strongest precedent in all of computing for the type-ahead rule, and it validates the floor too: ambiguity is an error to surface, never a coin to flip. (Cisco NX-OS Fundamentals Guide; Cisco Community — IOS abbreviation)

P4 — One sigil per domain. The most successful modern inline-command system, GitHub Copilot Chat, splits its sigils by what kind of thing is being steered: @ names a participant (who answers), / names a command (what to do), # names a variable (what context to include). Users keep three tiny vocabularies straight because the punctuation itself carries the category. This is exactly Michael's catch about check/remember under re:, generalized: the prefix is the domain, and a token filed under the wrong domain is a bug even if it parses. (GitHub Docs — Copilot Chat cheat sheet)

P5 — Discovery must happen at the moment of typing, or it doesn't happen. Discord replaced prefix bots with slash commands largely because of discoverability: autocomplete "helps users search for and filter all commands," ending the guesswork — and ending the collisions where "every bot has a /play command." Telegram does the same: typing / suggests the registered command list with descriptions. The negative proof is voice assistants: you cannot browse a voice UI, so 69% of Alexa skills had zero or one review (VoiceLabs data) and only ~3% of users who enabled a skill were still active in week 2. A capability nobody can see is a capability nobody uses. A chat-native system has no menu chrome, so discovery has to be an agent behavior (see §3.2, the bare-prefix list). (Discord — "Slash Commands are Here!"; Telegram Bot Features; NEXT Conference — voice discoverability)

P6 — Names: one common word, lowercase, the word users already say. Every surviving system converged here: Discord and Telegram both mandate short lowercase names (Telegram: ≤32 chars, Latin letters/numbers/underscores, "simple lowercase text is recommended"); Slack practitioners add the collision lesson — generic names collide across apps, so teams prefix (/team-order, not /order), which is P4 arriving from the field. For reply-steering specifically, the winning names name the artifact or act in the user's own words: people say "voice note," "show me," "keep it brief" — the token should be the phrase they were already reaching for. (Telegram Bot Features; dev.to — Slack slash commands in practice)

P7 — Demand for reply-shaping tokens already exists; users invent them when you don't ship them. The viral "ChatGPT slash commands" phenomenon — /eli5, /humanize, /summarize — is mostly folklore: those aren't real commands, they're plain-language instructions the model happens to honor. Two lessons. First, the desire is real and proven at scale: millions of users independently invented inline tokens to steer reply form. Second, folklore is what you get without a shipped registry: inconsistent behavior, no guarantees, no discovery surface ("only displayed options should be treated as real commands"). A toolkit-shipped vocabulary is the folklore, made reliable. (GizmoTimes — ChatGPT slash commands explained)

P8 — Frequency earns brevity; the most frequent act should cost zero letters. Email's subject-line tokens are the closest historical analog to this whole system — inline tokens steering a reader's behavior, spread with no tooling at all. The ones that survived (EOM, FYI, [ACTION]) are the daily ones, and EOM's insight is the extreme case: the token that means "the message is complete, nothing more needed" sits at the end and adds nothing else. Design consequence: within a family, the default act should need no name at all (see mem: bare, §5.2), and the shortest full names go to the most frequent acts. (Inc. — EOM / NRR / Y-N; Computerworld — subject-line keywords)

P9 — Near-miss names are the silent killer. Email also supplies the warning: FYI/FYR/FYSA/FYA are four tokens meaning four different obligations, and even professional guides warn that some coinages "aren't recognised widely enough to rely on." A vocabulary rots when two names differ by less than their meanings differ. Rule: any two tokens in a family must be distinguishable at a glance, in spelling and in meaning — this is the owner's own "different enough" criterion, and it's why the 2-letter floor on shorthand exists (it's what keeps vo/vs and fi/fo legible). (UplifeWay — email acronyms, the FYI family)

P10 — A category that stops discriminating is dead weight. GTD's @contexts (@phone, @computer, @email) organized a generation of task lists — then quietly died when smartphones made the contexts always-true: "I'm never not @phone." Categories earn their place only while they carve reality at a joint the user actually feels. Registry consequence: every token must name a distinction the user makes in the moment of writing; a token you'd almost always want (or never) is not a token, it's a default or a doctrine. (Lean Crew — "Projects are my contexts"; J. David Carr — Rethinking GTD Contexts)

---

2. The gap — verified: no standard exists

Michael's suspicion is correct. Searching for a cross-platform standard for user-side shorthand that steers AI replies turns up fragments, every one of them missing a different piece:

What none of them covers: a single, published, versioned vocabulary of inline tokens that (a) means the same thing to any agent on any platform, (b) steers reply form, memory, and work method as distinct families, (c) composes, and (d) carries a conformance test. That combination does not exist as a formal standard (no RFC, no standards-body work, no cross-vendor spec surfaced in research) nor as a de facto one. The space is genuinely open. (LinkedIn — Beyond ELI5; SurePrompts — system prompts per platform; OpenClaw docs — slash commands; Alexop — Claude Code slash commands)

Consequence for this memo: the recommendation in §4 is not "adopt the winner" — there isn't one. It is "publish the standard," with our shipped design as the starting draft, corrected where the research beats it.

3. The paradigm shootout

Seven ways humans have steered a system inline, scored on Michael's criteria. (Typing cost and error surface: L = good.)

Notes that matter:

• The palette wins on discovery and loses on existence. It needs host UI chrome. A toolkit that runs inside any chat (including a phone messaging app) cannot assume a palette — so the palette's lesson (surface the vocabulary at the moment of typing) must be imported as an agent behavior, not adopted as the mechanism (§4.2).
• Vim is the ceiling proof and the warning. Its verb–modifier–noun grammar ("any operator can be used with any motion") generates hundreds of commands from ~30 memorized atoms — and charges beginners weeks of rent. The lesson is to take a capped grammar: a few fixed slots that compose (our axes), not an open generative grammar. (Learn X in Y Minutes — Vim's grammar; Daniel Gray — Learning Vim)
• IPython's % vs %% is a scope distinction done right — one sigil = this line, doubled = the whole block. Our bare-vs-on distinction is the same idea in words; the precedent says users handle exactly one such scope bit well, and no more. (IPython reference)
• Natural language is the on-ramp, not the road. It stays as the fallback layer (plain-language equivalents always count), because its failure modes — verbosity, accidental triggers, no state semantics — are precisely what tokens exist to fix.
• Aliases are the expert layer, later. Raycast lets users set 2–3-character personal aliases on top of the standard commands; Claude Code users shell-alias their command files. Personal aliases belong in user state (never the shipped vocabulary), must never shadow a shipped name, and are a v2 concern — type-ahead already delivers most of the speed with zero machinery. (Raycast Manual — aliases & hotkeys)

---

4. Recommended architecture

4.1 Keep from the shipped design (it survives the research)

• Inline tokens in the message stream. The only mechanism that works in every chat surface with no host UI — the portability constraint kills the palette as a mechanism and voice as anything but an output channel.
• The always-known axiom. No researched system has this: theirs are per-app registries or folk habits. Ours — the vocabulary ships in the toolkit's instructions, identical for every user — is what is actually new here, and §2 says nobody else has shipped it.
• Type-ahead shortening (P3, Cisco-grade precedent), stacking on axes (a deliberately capped Vim grammar), plain-language fallback, mention-vs-use judgment, sticky state in agent memory with confirm-the-save, and the conformance test. Each maps to a principle in §1; none of the alternatives beats any of them on the owner's criteria.

4.2 Change or add (where the research beats the draft)

1. check and remember leave re: — Michael's catch, confirmed by P4 (Copilot's sigil-per-domain). remember goes to the new mem: family; check founds a small do: family (§5 gives the full reasoning). The shipped spec's Process axis is dissolved.
2. Discovery becomes a specified agent behavior. A message consisting of just a family prefix (re:, mem:, do:) — or any "what can I type?" — gets that family's registry back, one line per token. This is IPython's %lsmagic and Telegram's typing-/ menu, translated to a surface with no chrome. Without it, we are building the Alexa failure mode into a text system.
3. A Structure axis joins re: (recap/steps/vs, §6.1). The shipped axes (Channel/Length/Register) had no home for "shape of the answer," which is what several of Michael's own candidates actually steer.
4. The registry becomes append-only and versioned (§4.4) — a token, once shipped, never changes meaning and its name is never reused. Folklore can't promise this; a standard must.

4.3 Where the shipped design honestly loses

• Discoverability. As shipped, the vocabulary lives in a spec file the agent reads; the user's only window is the conformance story. Palette systems and Telegram beat this cold. Fix 4.2.2 mitigates it behaviorally; it cannot fully close the gap on a chrome-less surface, and the memo won't pretend otherwise.
• The Process axis was a category error that the spec itself had to spend a paragraph disambiguating (re:remember vs obligation 3). Needing a paragraph to explain why two similar things differ is the smell P9 warns about; the family split removes the paragraph.
• No extension story. The shipped gate ("additions are made here, once") says nothing about toolkit-specific or user-specific extensions, which every mature system grows (Raycast extensions, Claude Code command files). §4.4 reserves the space before someone squats in it.

4.4 Publish it as a standard, not a feature

Since §2 verifies the space is empty, the recommendation is to name and version the thing like one:

• Name: the spec stays Directives — plain, descriptive, and already written toolkit-agnostically on purpose. (The AgentForge toolkits are the reference implementation, the way one browser implements a web standard first.)
• Versioning: the spec carries a version (this proposal = Directives 1.0). Grammar changes require a major version; registry additions are minor; a ratified token's meaning never changes at any version.
• Minimal ratified core (conformance Level 1): the grammar — prefix:name, bare vs on/off, stacking on axes, type-ahead with the ambiguity rule, mention-vs-use, bare-prefix discovery — plus the five core re: tokens (voice, show, brief, deep, plain). Any agent passing Level 1 gives a user the essential experience on day one.
• Extension families (Level 2): mem: and do: as specified in §6 — ratified separately, so a minimal agent can be honestly conformant without them.
• Reserved space: family prefixes are registered in the spec; a toolkit-private family must use an x- style marker (the HTTP header / vendor-prefix pattern) so private experiments can never collide with a future ratified family. Personal aliases (the Raycast layer) live in user state, are never published as vocabulary, and may not shadow a ratified name.
• Reserved convention, noted for the future: if multi-agent routing ever enters scope, Copilot has already settled @ as "who answers." Don't invent a rival; adopt it when needed. It's out of the 1.0 registry.

5. The family map

The do: decision, with reasons (the open question from the brief). check — verify claims against live sources before answering, and say what was checked — is wanted, already used, and homeless twice over: it is not reply form (the reply looks identical, only its provenance differs) and it is not memory. Three options were weighed: (a) drop it — rejected: it fails Michael, and "the agent should just always verify" is a doctrine, not a steering control; users legitimately want rigor on demand for high-stakes answers without paying its cost on casual ones; (b) keep it as a lone exception under re: — rejected: P4 and P9; an exception in a 13-token system is 8% impurity, and the shipped spec's disambiguation paragraph is the receipt; (c) found do: — chosen: the domain boundary is real (work method vs reply form — the same boundary as Copilot's / vs #), and the family has a second honest tenant, draft (§6.3), so it is not a singleton built for one token. The risk — family proliferation — is controlled by the admission gate: a family ships only when a whole domain of steering exists, and do: is capped by its own registry discipline (two tokens, both daily-use).

Why task:/time: fail the gate: they don't steer how the agent replies, remembers, or works — they request actions in the world (create a task, set a reminder). That makes them commands to host tools, not directives; they collide with the approval doctrine (a token must never become a side door around "no state changes without approval"); and plain language already serves them perfectly ("remind me Friday" needs no token). If a future toolkit wants them, the x- reservation is where the experiment belongs.

---

P11 — the agentic difference (addendum to §1, on the owner's final framing)

Every legacy system in §3 steered output or software: a document (Vim), a program (slash commands), a message's handling (email tokens), a session (agent CLIs). An agent is steered in its conduct — how it replies, yes, but also what it remembers, how carefully it verifies, whether it acts or only drafts, someday how it delegates. That larger surface is why this standard needs to exist at all: nobody ever needed one grammar for "format the text" and "remember this" and "don't send that yet," because no pre-agent system did all three.

The scaling test, stated as a principle: a new behavior domain must arrive as a new family under the same grammar — never as a grammar change. If adding "how the agent delegates" or "how the agent spends" someday requires new syntax, the design has failed. Families are the scaling unit; the grammar is the constitution. Note that the design has already passed this test once, live: mem: and do: were added to a reply-only system without touching a single grammar rule — the strongest internal evidence that the constitution is the right size.

---

6. Registries

Type-ahead resolves within a family (the prefix has already selected the namespace), so collision checks are per-family. Floors: ≥2 letters; a name beginning with its own family's prefix letters takes one more (recap → rec, since re is the prefix itself).

6.1 re: — the reply

Axes: Channel (voice, show) · Length (brief, deep) · Register (plain) · Structure (recap, steps, vs).

6.2 mem: — the agent's memory of the user

Axes: Operation (save / fix / forget — last wins) × Priority (pin). recall is a standalone read act and does not stack with writes.

6.3 do: — the work method

do:check/draft stacks legally: verified content, unexecuted.

7. The bench — designed, one promotion away

Registry additions are minor versions (§4.4), so the bench is a pipeline, not a rejection:

• re:next (ne, Length) — "just the next move." Benched: brief covers most cases; next is its limit case. Promote when the ask proves daily.
• re:example (ex, Structure) — explain through one concrete example. Benched: plain language ("give me an example") is already reliable here; tokens are for where NL is fuzzy.
• re:raw (ra, Channel-adjacent) — unformatted plain text, no markdown, for copy-paste into other tools. Real but narrower; promote on demand.
• mem:forget (fo) — semantics ready (request removal; the host's forget process governs; confirm completion). Withheld on principle: forgetting is the one operation where a deliberate process beats a fast token — speed is the wrong value for irreversible deletion.

8. Killed on purpose

• re:eli5 — folk-famous, wrong tool: it sets a childish register that misfires at work, and duplicates plain. The grown-up word wins (P6, P9).
• re:tldr as a separate name — one concept, one name; brief wins on family consistency (an adjective set: brief/deep/plain).
• re:draw — folded into show: one command per intent, not per output technology (owner's earlier ruling; the research agrees).
• re:list — steps and show already cover every case it would name.
• Renaming voice (to talk/speak/audio) — settled: voice is the artifact's common name; talk promises a conversation, speak sounds live, audio names a file format. Churn without gain.
• do:ask ("ask me first") — clarification appetite is set by the host's approval rules; a token that duplicates them adds nothing, and one that contradicts them is a hazard.
• do:undo — promises reversibility an agent often cannot deliver (an email sent, a payment made). Fails the honest-degradation rule: never name a token after a promise you can't keep.
• do:fast — either you'd always want it (then it's a doctrine, P10) or it means "skip verification," which no token should be able to say.
• mem:all / a remember-everything mode — destroys the signal that makes mem: and pin meaningful, and makes memory indiscriminate by default. Memory stays deliberate.
• re:secret / re:private — implies a privacy property a token cannot confer. Privacy is a platform property; naming a reply mode after it would be a false promise.
• task: / time: families — actions in the world, not steering (§5); also a side door around approval rules.
• Single-letter shorthand — killed by the 2-letter floor: v/b blur at a glance; "different enough" is the owner's own criterion (P9).

9. The ship set — Directives 1.0

Level 1 (ratified core) — the grammar of §4.4 plus:

re: — voice · show · brief · deep · plain

Level 2 (ratified extensions):

re: — recap · steps · vs mem: — (bare) · pin · fix · recall do: — check · draft

Total: 13 named tokens + the bare mem: form, in three families small enough to hold as three chunks (P1) — every one guessable cold (P6), every shorthand derived rather than memorized (P3), every family a behavior domain an agent — not a text editor, not a program — actually has (P11).

Sources are cited inline at each principle and claim throughout §§1–5.