Prongs Intent Spec

Terms

Principles

• Named by purpose. An id and its description say what something is for, never what it looks like. Looks live in bindings and internal domains, where they can change without renaming call sites.
• Choosable from the code. An agent or a person should be able to pick the right intent from facts in front of them, a handler name or a label, without asking anyone.
• Exceptions are data. When not to use an intent, and what to use instead, is part of the intent (notFor), so it reaches agents and checks alike.
• The format, not the vocabulary. The spec fixes how intents are written and resolved. Which intents a project has is that project's decision.
• Small at run time. What ships with an app is the registry and a merge function. Everything that reads source code stays in tooling.

1. Intents

An intent is a named choice inside a codebase: what it is for, what it resolves to, when not to use it, and how to check it was followed.

1.1 Ids

An id is a domain and a meaning, with an optional variant:

domain.meaning[.variant]        ^[a-z]+(\.[a-z]+){1,2}$

Examples: action.delete, conflict.duplicate, layout.terminal.bar. The first part is the intent's domain. Ids are lowercase letters only, so they can be written, searched and typed without escaping.

Domains are not namespaced: a registry is one project's vocabulary, and the profiles in it MUST NOT claim the same domain (§3). A profile published for others SHOULD document the domains it claims, and SHOULD pick names specific enough that it can sit next to other published profiles.

1.2 Fields

type Intent<B = unknown, C extends Check = Check> = {
  kind: 'primitive' | 'semantic';
  description: string;
  refs?: readonly string[];
  binding?: B;
  notFor?: readonly { context: string; reason?: string; instead?: string }[];
  keywords?: readonly string[];
  checks?: readonly C[];
  status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
  evidence?: Readonly<Record<string, unknown>>;
  meta?: Readonly<Record<string, unknown>>;
};

type Check = { type: string } & Record<string, unknown>;

1.3 Writing a description

A description SHOULD let someone pick the intent from facts in the code or content, without a judgement of taste. "Removes something for good: a project, an account" can be checked against the code; "the red button" cannot.

1.4 Status

An intent without a status is stable.

A deprecated intent SHOULD have a notFor entry with an instead, naming what to use. Validation warns when it does not (§3).

1.5 Meta

meta holds data the spec does not define, for teams and tools: an owner, a design link, a ticket. Every key MUST carry a reverse-DNS prefix and a name, so two tools never claim the same key:

com.example/owner        ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+/[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$

• Values MAY be any JSON value.
• Prefixes whose second label is prongs (dev.prongs/, io.prongs/) are reserved for keys this spec defines. This draft defines none.
• Tooling MUST ignore keys it does not know, and resolution (§4) MUST NOT read meta.

2. Profiles

A profile gives meaning to the bindings of the domains it owns. Core knows no domains: UI, errors, logs, and anything else plug in as profiles.

type Profile<B = unknown> = {
  name: string;
  domains: readonly string[];          // id prefixes this profile owns
  internalDomains?: readonly string[]; // owned domains usable only as refs targets
  validate?(id: string, intent: Intent<B>, defs: IntentDefs): ProfileIssue[];
  validateAll?(defs: IntentDefs): { id: string; message: string; severity: 'error' | 'warning' }[];
  merge(base: B | undefined, next: B | undefined): B;
};

type ProfileIssue = string | { message: string; severity: 'error' | 'warning' };

• domains: every domain MUST be owned by exactly one profile in a registry.
• internalDomains: intents in these domains MUST NOT be used at call sites; they exist to be referenced. In the UI profile the look domains (control, tone, arrange, …) are internal, so call sites use action.delete and never control.destructive.
• validate: checks one intent's binding and refs. A plain string is an error.
• validateAll: checks the vocabulary as a whole, for example that neighbouring intents contrast with each other.
• merge: layers one binding over another. It MUST accept undefined for either side. It defines how refs compose (§4).

The runtime part of a profile ships with the app, so it SHOULD stay small. Tooling, such as finding usages in source files and rules, lives in a separate object that only the CLI loads.

3. Registries

A registry is a map of id → intent plus the profiles that own its domains. A registry is valid when it has no errors; warnings are reported but allowed.

Validation MUST report every issue rather than stop at the first. Each issue names the intent (or, for profile problems, the domain) it is about, a severity, a message, and a code from the tables below. Messages are free text; codes are stable, so tools and the conformance fixtures compare codes, not wording.

3.1 Errors

3.2 Warnings

3.3 When to validate

Implementations SHOULD validate when a registry is created in development, and MAY skip validation in production builds.

4. Resolution

Resolving an intent gives its effective binding. For an intent I owned by profile P:

1. Start from undefined.
2. For each ref in I.refs, in order, resolve it and merge the result in: binding = P.merge(binding, resolve(ref)).
3. Merge I's own binding last: binding = P.merge(binding, I.binding).

Later refs override earlier ones, and an intent's own binding overrides all its refs. Resolution MUST fail on an unknown id or a cycle, whether or not the registry was validated. It reads only refs and binding: status, evidence and meta never change a result. Implementations MAY cache results, since a registry does not change at run time.

type ResolvedIntent<B = unknown> = { id: string; profile: string; binding: B };

5. Usage

These rules apply to code that uses a registry, not to the registry itself. They are what prongs check enforces.

• Call sites MUST NOT use an intent in an internal domain.
• A component or helper SHOULD accept only the domains it renders or handles. The UI profile's Text accepts heading.*, text.* and feedback.*, and passing action.save to it is a type error.
• Tooling SHOULD report code that bypasses the vocabulary, such as a styled raw <button> or a hand-written Response.json({ error }, { status: 400 }), and suggest the intent to use.
• When the words in the code (a handler name, a label) match another intent's keywords better than the one used, tooling SHOULD warn.
• A call site that uses a deprecated intent SHOULD get a warning that names the replacement from its notFor.

5.1 Findings

A checker that reports findings to other programs SHOULD give each one this shape, so editors, CI and agent hooks can read any checker the same way:

prongs check --json prints { "violations": [ … ] } in this shape. When it runs as an agent hook, it reads the edited file from the hook's payload and answers in that agent's own format; the hook formats belong to the agents, not to this spec.

6. Agent spec

An implementation SHOULD compile a registry into a document agents read (in Prongs, PRONGS.md). It SHOULD list, for every call-site intent, its id and description first, grouped by what consumes it, and then its notFor guidance. Intents that are not stable SHOULD carry their status next to their id. Internal intents MAY be listed separately as reference.

The output SHOULD be deterministic: the same registry and options give the same bytes, with intents in definition order. That lets CI fail when the committed document is out of date (prongs spec --check) and keeps diffs to what changed.

7. Registry export

A registry MAY be exported as JSON for tools in other languages. An export is an object with the spec version, the profiles (their names and domains, not their code) and the intents by id, in definition order:

{
  "spec": "draft",
  "profiles": [{ "name": "ui", "domains": ["action", "control"], "internalDomains": ["control"] }],
  "intents": {
    "control.destructive": { "kind": "primitive", "description": "…", "binding": { "classes": "…" } },
    "action.delete": { "kind": "semantic", "description": "…", "refs": ["control.destructive"] }
  }
}

schema.json describes this shape. It checks the format only: whether a binding makes sense is up to its profile, so binding is any object. In Prongs, prongs export writes it.

A reader SHOULD check spec before anything else. It MUST NOT treat an export from a version it does not know as one it does without saying so: it SHOULD warn, and MAY go on to read the fields it knows, ignoring the rest.

8. At run time

Intents are not only a build-time idea: the same names SHOULD survive into what the app produces, so analytics, tests, logs and API clients can work by purpose. A profile SHOULD carry the intent's id into its output:

• UI elements carry it as data-intent="action.delete". A project MAY turn this off in production. It MUST NOT be used for styling; looks come from the registry.
• Error responses carry it as a machine-readable code: { "ok": false, "error": "…", "code": "conflict.duplicate" }.
• Log entries carry it as a field: { "intent": "audit.deleted", "level": "info", … }.

9. Conformance

An implementation conforms to this draft when it passes every case in conformance/: validation must report the listed issue codes and severities, and resolution must give the listed bindings or fail where listed. The fixtures are JSON, so an implementation in any language can run them. Their README describes the format and the reference profile they assume.

@prongsjs/core runs them on every test run. A behaviour this document describes that the fixtures do not cover is a missing fixture, and a fixture that contradicts this document is a bug in one of them.

10. Security

A registry is code. Loading one, as prongs check, prongs spec and every tool built on them do, runs it with the permissions of whoever runs the tool.

• Treat a registry like any other source file in review. Tooling MUST NOT load a registry from somewhere the user did not point it at.
• Descriptions, notFor and keywords are written into the agent spec, which agents follow. A change to them is a change to agent instructions, and SHOULD be reviewed as one. Tooling SHOULD NOT copy registry text into an agent's context from sources the project does not control.
• Agent hooks run on every edit an agent makes. Installing one SHOULD be an explicit step, and a hook SHOULD only read the files it was given.
• data-intent attributes and error codes expose intent names to anyone who reads the page or the response. Names SHOULD NOT contain anything secret; a project that considers them sensitive SHOULD turn the attribute off in production.

11. Versioning

This is a draft. Frozen versions will be published by date (for example 2026-11-01) and never change; the draft is where changes land first, and the changelog records each one. The spec's dates are independent of package versions: a release of @prongsjs/core says which spec version it implements.

A change to this spec is breaking when a registry, export or implementation that conformed before no longer does: a new error, a removed or renamed field, a field that becomes required, or a changed meaning. Adding optional fields, warnings or SHOULDs is not. Breaking changes only happen in a new dated version.

A change to a registry is breaking for the code that uses it when it removes or renames an intent, moves it to an internal domain, or narrows what it is for. Adding intents, notFor entries or keywords is not. A registry SHOULD mark an intent deprecated, with an instead, for at least one release before removing it, so checks can walk call sites to the replacement.

Planned before the first dated version:

• The shape of evidence, agreed together with the tooling that writes it.
• Composed intents (recipes with slots), as a third kind.