Directive Shorthand 1.0 — the specification

Authored by Michael Nash · AgentForge · First published 2026-10-18

Provenance. Directives was designed by Michael Nash on 2026-10-18 and first implemented the same day in the AgentForge toolkits, which are its reference implementation. The full design record — the research, the alternatives weighed, and the reasons for every decision in this document — is published alongside it as DIRECTIVES_RESEARCH.md. This specification is published, dated, and attributed so that its authorship is a matter of public record.

This file is the canonical text of Directive Shorthand 1.0 — Lingo, to most people: Lingo is the specification's nickname, the name it goes by in conversation ("learn the Lingo"). The specification defines a small, published vocabulary of shorthand directives — tokens a user drops into an ordinary message to steer how an AI agent replies, what it remembers, and how it works. It is a proposed standard: written to be adopted by any agent, on any platform, in any toolkit — not just AgentForge's.

A directive system for agents has to steer more than text. Legacy command systems steered output or software; an agent is steered in its conduct — how it replies, what it remembers, how carefully it verifies, whether it acts or only drafts. Directives is one unchanged grammar over all of those domains: each new domain arrives as a new family under the same rules, never as new syntax.

The design axiom: the vocabulary is always known

The directive vocabulary lives here — in the shipped instructions of whatever carries this standard (a toolkit's AGENTS.md carries the doctrine; this file carries the spec). An agent that has loaded the standard knows every directive on first contact, with zero history with the user. Nobody teaches the agent the commands, and no agent memorizes them per-user — there is nothing to learn. If an agent does not know a directive, the standard was not loaded; that is a loading failure, not a memory gap.

Persistence (obligation 3, below) exists for exactly one thing: the user's sticky state — which modes are currently switched on. State is per-user and changes over time; the vocabulary is per-standard and permanent. Never confuse the two, and never describe the commands themselves as something remembered about a user.

Grammar

A directive is a token of the form:

<family>:<name>            bare form
<family>:<name> on         sticky on        (modes only)
<family>:<name> off        sticky off       (modes only)
<family>:<name>/<name>     stacked form     (see Stacking)
mem:                       the mem: family's bare form (see its registry)

• <family> — a registered family prefix (re:, mem:, do:). The prefix is the domain: it names the part of the agent's conduct being steered — the reply, the memory, the doing (work method). A token filed under the wrong family is a bug even if it parses.
• <name> — the directive's name, lowercase, from its family's registry below.
• Bare form applies to the reply (or the work) for the message it appears in, and only that message. Nothing is persisted.
• on turns a mode on and leaves it on (sticky) until cleared. It also applies to the current reply.
• off clears the sticky mode. The reply to the off message itself follows the cleared state — re:voice off gets a text reply.
• A directive may appear anywhere in the message — start, middle, or end. Position carries no meaning.
• Plain language that clearly means the same thing ("go back to text") sets or clears the same state. The token is the reliable form, not the only form: honor the expressed intent, and treat the state as changed.

Stacking

Several directives can ride in one token, chained with /:

re:voice/brief       a short voice note
re:show/deep         a thorough visual
re:vo/br             the same as the first, shortened (below)
do:check/draft       verified content, never executed
mem:fix/pin          a correction, saved at top priority

Directives sit on axes — each name owns exactly one axis within its family (the registries below name each token's axis). A stack composes across axes — channel + length + register + structure all apply at once. Within one axis, the last mention wins: re:brief/deep is a deep reply. The same rules govern multiple separate tokens in one message (re:voice re:brief = re:voice/brief); stacking is sugar, not a second grammar. Stacks carry bare names only and never change persisted state — set or clear a sticky mode with the plain single form (re:voice on, re:voice off).

Shortening — the type-ahead rule

There is no shorthand list to memorize. A name may be shortened to any prefix that matches exactly one name in its family's registry — start typing the word, stop when it can only be one thing (the tab-completion rule; network engineers have typed Cisco's version of it for decades). Type-ahead resolves within a family: the prefix has already selected the namespace.

Two floors keep the short forms distinct enough to read at a glance: never fewer than two letters, and a name that begins with its own family's prefix letters takes one more (recap → rec, because re is the family prefix itself).

The full name always works; a shorthand is derived, never learned, so knowing the rule for one name is knowing it for all. An ambiguous prefix — one that matches two or more names — is not a directive at all: never guess-fire. If a registry grows into a collision, the shortest forms simply grow with it, and full names are untouched.

Discovery — ask the prefix

A chat surface has no menu chrome, so discovery is an agent behavior, specified here — not a help document the user must find.

• A message consisting of just a family prefix (re:, mem:, do:) — or any plain "what can I type?" — gets that family's registry back: one line per token, name, shortest form, and a plain-language gloss.
• A message of just re: families unknown to the user — likewise, naming the families themselves gets the family map.
• The listing is always rendered in the user's language, from their active language pack (see International by design).
• An agent that cannot honor a listed token says so in the listing — discovery never advertises a capability the agent doesn't have.

An invisible vocabulary is a dead vocabulary; this behavior is what keeps Directives visible at the exact moment of typing.

The agent's three obligations

1. RECOGNIZE. Scan every user message for directive tokens before replying. Recognition is part of reading the message — it never depends on remembering past conversations.
2. ACT. Honor the directive in the reply to that message (and in the work behind it, for do:). A bare re:voice makes this reply a voice note; a sticky mode colors every reply until cleared. If the platform genuinely cannot do what a directive asks (e.g. no voice capability), say so plainly in the reply — never silently substitute.
3. PERSIST. When sticky state changes (on / off, or the plain-language equivalent), write the new state into your own persistent memory as a standing user preference, as part of the same turn, and confirm to the user what was saved ("Saved: voice replies on, until re:voice off."). The write is how the mode survives across sessions; the confirmation is how the user knows it did. Persist state only — never the vocabulary; that is re-read from the standard every time.

Directives shape how you reply and work, never whether you may act: they do not grant, widen, or waive any approval, safety, or credential rule of the host toolkit.

The families

Conformance levels. Level 1 is the ratified core: the grammar (families, 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. Level 2 is the ratified extensions: the re: structure tokens, the mem: family, and the do: family. An agent may be honestly Level-1 conformant without Level 2.

re: — the reply

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

Level 1 — the core five:

Level 2 — structure:

mem: — the agent's memory of the user (Level 2)

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

mem: persistence is the deliberate counterpart of obligation 3: obligation 3 persists directive state automatically; mem: persists content the user points at, on request. The confirmation rule is the same — the user hears exactly what was saved, in the same turn.

do: — the work method (Level 2)

do: steers how the task is done. It is invisible in the reply's form except as evidence — which is precisely why it is not under re:.

do:check/draft stacks legally: verified content, never executed.

Where sticky state lives (host-agnostic)

This spec specifies behavior, not format. Every agent platform has some durable memory — a memory file, a preferences store, a profile database. On a state change, write one plain statement of the current state into whatever that mechanism is, e.g.:

Directives state: voice replies ON (set by user via re:voice on, 2026-10-18). Reply with voice notes until re:voice off.

An agent loading the standard in a new session honors a state entry it finds, without being re-asked. Sticky state belongs to the agent's memory of the user — never write it into the standard's own files: the standard is shared by everyone who uses it; a user's state is not.

Mention vs use

A token can appear in a message without being used — quoted text, a code block, a forwarded message, or a conversation about directives ("what does re:voice do?", "add a directive to the spec"). Telling use from mention is the agent's judgment, by these defaults:

• A token standing in the user's own prose, addressed to the agent, is a use — act on it.
• A token inside quotation, code, or a question about the system is a mention — answer it; don't fire it.
• When genuinely ambiguous: act, and note that you did ("Treating that as a voice request — say the word if you meant otherwise"). Acting-with-a-note beats asking: the user corrects a note in seconds, while a directive ignored silently reads as a directive unknown — which, per the axiom, must never happen.

International by design

Directives is an international standard, and it stays one by refusing to fork.

The canonical registry is the agnostic core — semantics plus an interchange form. The canonical tokens stay identical in every language, like programming keywords, airport codes, and the ON/OFF printed on every device on earth: they are the form in which directives are interchanged between users, agents, and documents, and they always work, everywhere — one standard, or portability dies: a forked token set per language means a user can no longer carry their vocabulary across agents, platforms, or borders.

But canonical tokens alone would fail the standard's own first principle in most of the world: a name is only guessable cold to a speaker of its language. So languages do not enter by translation. They enter as packs.

Language packs

Each language gets an authored command pack: a full native vocabulary for the same directives, in the same architecture as the standard itself —

• Names designed for native-speaker guessability. A pack restores the beginner property per language: a first-time user who has never seen the list should be able to invent the token and be right, in their language, with its naming taste. Mere translation cannot do this — and a literal translation actively misleads: the German word Brief means a letter (a piece of mail), not "the short version." A translated registry would hand German users a token that says the opposite of what it does.
• Its own type-ahead space. Shortening resolves within the pack's vocabulary, under the same floors and the same ambiguity rule.
• Authored, never machine-translated. A pack is researched and designed for its language the way the canonical registry was designed for the standard — per language, by someone who knows how its speakers actually talk to machines.
• Resolution to canonical semantics. An agent resolves a pack token to the canonical directive it names; the token steers the identical behavior. Canonical tokens are the fallback: a pack is complete when it covers the Level 1 core, and where a pack has a gap, the canonical form works — the pack states its gaps honestly rather than papering over them.
• Discovery renders from the active pack. The discovery listing (§Discovery) is rendered in the user's language, from their active pack — the menu speaks your language, with your pack's names.
• Packs register like families. A language pack is registered with the standard under the same governance (§Governance): registered packs are the ones agents should accept; an unregistered experiment uses the x- reservation like any private extension.

The pack files

Packs are files, mirroring how the standard's carriers organize everything else. A carrier of this standard keeps a directives-packs/ directory beside this spec, one file per language, named by its ISO 639-1 code (directives-packs/en.md, directives-packs/es.md, …). Each pack file carries, in order: a header block (pack code, language, author, date, provenance); a completeness line (which conformance levels it covers in full, and its gaps stated honestly); its vocabulary — every covered directive, each entry mapped to its canonical directive ID; and its own type-ahead table.

The authoring rule is part of the format: a pack is authored once, thoughtfully, per language — a one-time designed artifact, written from knowledge of the language, never machine-translated and never derived from another pack by substitution. An agent loads the core (this spec's canonical registry) plus the user's active pack; pack tokens resolve to canonical semantics, and the canonical tokens remain the fallback wherever a pack is partial. English (en) is the reference pack: it is the canonical set itself, written in pack format, and it ships with the standard as the worked example every future pack is modeled on.

The launch set

Packs follow the footprint: a standard's first packs belong to the languages of the places its carriers already serve. For Directives 1.0, the committed launch set is six packs:

Six packs natively cover 13 of the 17 countries in the reference implementation's service footprint, and South Africa rides the English pack officially, as it does in that footprint. The named fast-follow tier is Scandinavia — sv (Swedish), no (Norwegian), fi (Finnish) — whose interim bridge is the world's highest English proficiency; that is stated as a bridge, not a dismissal, and the packs remain owed.

The other five packs in the launch set are registered and intended, to be authored by native-grade work — designed per language, never fabricated to fill a table. The selection rule outlives the set: when a carrier's footprint grows into a new country, its language's pack joins the roadmap by the same rule that chose these six.

The grammar itself needs no localization: the family: prefix shape, / stacking, and on/off as universal device symbols are script- and direction-neutral, and tokens — canonical or pack — embed as symbol islands inside any writing system, the way URLs do.

Governance — how the standard grows

• The registry is append-only. A token, once ratified, never changes meaning, at any version. A retired token's name is never reused — a name means one thing forever, or the vocabulary can't be trusted.
• Versioning. This document is Directives 1.0. A grammar change requires a major version; registry additions (a new token, a new family's ratification, a new language pack) are minor versions.
• Families are earned. A family ships only when a whole domain of steering exists (a part of the agent's conduct users steer in the moment of writing), not for a single token. Family prefixes are registered here.
• Private families use x-. A toolkit or vendor experimenting with its own family must mark it with an x- prefix (e.g. x-acme:), so private experiments can never collide with a future ratified family.
• Personal aliases (a user's own pet names for directives) live in the user's state, are never published as vocabulary, and may not shadow a ratified name.
• Reserved: @ is not used by this standard. If multi-agent routing ever enters scope, @ is the industry-settled sigil for "who answers" (GitHub Copilot's convention) and will be adopted, not reinvented.

The bench — designed, not ratified

These tokens are designed and one promotion away; they are not part of 1.0 conformance. Registry additions are minor versions, so the bench is a pipeline, not a rejection.

• mem:forget (fo) — request removal of the designated memory; the host's forget process governs; completion is confirmed. Withheld on principle: forgetting is the one operation where a deliberate process beats a fast token — speed is the wrong value for irreversible deletion.
• re:next (ne, Length) — "just the next move." Benched: re: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 natural language is fuzzy.
• re:raw (ra, Channel-adjacent) — unformatted plain text, no markdown, for copy-paste into other tools. Real but narrower; promote on demand.

A note on what was killed on purpose, so the reasoning survives: re:eli5 (a childish register that misfires at work; plain is the grown-up word), re:draw (folded into show — one command per intent, not per output technology), do:undo (promises reversibility an agent often cannot deliver), do:fast (either always wanted — then it's a doctrine — or it means "skip verification," which no token may say), mem:all (destroys the signal that makes mem: and pin meaningful), and the task: / time: families (actions in the world, not steering — and a side door around approval rules). The full killed list, with evidence, is in DIRECTIVES_RESEARCH.md §8.

Conformance — test a fresh agent against this

A brand-new agent, given only a carrier of this standard and no user history, must behave as follows. This is the standard's test: if any line fails, the implementation — not the user — is wrong.

Worked example — Level 1.

1. The user's first-ever message: "Book the venue and get me the quotes. re:voice" → The reply is a voice note containing the answer. Nothing is persisted (bare form).
2. Next message: "re:voice on — and did the venue reply?" → The reply is a voice note; the agent writes "voice replies on" into its persistent memory; and the reply confirms the save.
3. Next message, next day, new session: "Any news?" → The reply is a voice note — the persisted state was read back. No token was needed.
4. The user: "re:voice off, thanks" → The reply is text; the agent clears the state in memory and confirms the clearance.
5. The user: "How do the two providers compare on price? re:show" → The reply's substance is a chart (the medium that fits a price comparison), with at most a one-line takeaway as accompanying text. Nothing is persisted.
6. The user: "Did the venue confirm? re:vo/br" → A short voice note: vo and br are the shortest unique prefixes of voice and brief. (Had either matched two names, it would not fire at all — ambiguous prefixes never guess.)

Worked example — Level 2.

1. The user: "My sister's name is Ana. mem:" → The agent saves the fact to persistent memory and confirms exactly what was saved, in this reply.
2. The user: "Correction — Ana spells it with one n now. mem:fix/pi" (or mem:fix/pin) → The agent replaces the stored fact with the corrected one, marks it pinned, and confirms both the change and the priority.
3. The user: "What do you have saved about my family? mem:recall" → The agent answers from memory, citing what is actually saved — and would say so plainly if nothing were.
4. The user: "Write the landlord email about the leak. do:draft" → The agent produces the email text and stops: it does not send it. The artifact is handed over for approval.
5. The user: "Is that supplement actually safe with my prescription? do:check" → The agent verifies against live sources before answering and states what it checked.
6. The user: "re:" (nothing else) → The agent replies with the re: registry — one line per token, in the user's language. Discovery is a behavior, not a document.

Checklist — Level 1.

• ☐Bare token → honored in that reply only; nothing persisted.
• ☐on → honored in that reply and persisted and the save confirmed to the user.
• ☐Persisted state survives a session boundary with no token repeated.
• ☐off → text reply; state cleared in memory; clearance confirmed.
• ☐Token mid-sentence or at the end of a message → still recognized (position-independent).
• ☐Token inside a quoted example in a question about directives → treated as a mention: answered, not fired.
• ☐The agent can say where the vocabulary lives (this spec, in the carrier) — and never claims it "learned" or "remembered" the commands from the user.
• ☐Bare re:show → the reply's substance is a visual in the medium that fits the content (diagram / chart / map / image), with at most minimal labeling text; nothing persisted.
• ☐Stacked token (re:voice/brief) → all elements honored; cross-axis elements compose, same-axis conflicts resolve last-wins; no state persisted by a stack.
• ☐Unique prefixes (re:vo/br) → fire as their full names; an ambiguous prefix → does not fire, and is never guessed.
• ☐Bare family prefix (re: alone) → the family's registry, rendered in the user's language.

Checklist — Level 2.

• ☐mem: bare → the designated content is saved to persistent memory and the save confirmed, in the same reply.
• ☐mem:pin → saved at special priority; mem:fix → the prior memory is replaced and the change confirmed; the two stack (mem:fix/pin).
• ☐mem:recall → the answer comes from what is actually remembered, with gaps admitted, never confabulated.
• ☐do:check → factual claims are verified against live sources before the answer, and the answer states what was checked.
• ☐do:draft → the artifact exists; no external action (send / post / pay / publish) was taken.
• ☐Tokens from the user's active language pack → resolve to the same canonical directives as the canonical tokens; where the pack has a gap, the canonical token works.