ADR-516: One item descriptor of kind, origin, path, source, version and state for themes, mods, sensors, ways and judge profiles, shared by the store, the settings screens and the CLI¶
Summary¶
- Decided: Every theme, mod, sensor, way and judge profile is described by one descriptor:
family,name,kind,origin,path,overrides,source,version,stateanddetail.originisbuiltin,userorproject. It is taken from where the definition is found and is never written into a file. A user or project item that shares a built-in's name is that built-in with an override, which eitherextendsit orreplacesit. One serializable type inagent-settingsholds the descriptor. Each family builds its items in one function, and both the CLI and the screens call it. Every listing command's--jsonprints the descriptor under these field names, and a newways settings itemslists every family at once. The settings screens head each item's detail with one card drawn from it. The wordsbundled,shipped,core,global,your waysandoverrideleave every surface. - Trades away: The current JSON of
ways settings theme list(source,file,active), thewaysblock ofways status --json, and theKindcolumn ofattend sensor listall change, with no aliases (ADR-506). The ways tab's section names and the module card's own state wording, such asinstalled · enabled, give way to the shared words. A user's ownnord.themereadsbuiltinwith an override line instead ofuser. Each family loses the freedom to name these facts its own way. - One-way? No. Reversible: the change covers words, JSON field names in five commands, and one Rust type. No file a person writes changes, since origin is never stored. Reverting gets more expensive as scripts and agents come to read the new field names, which ADR-185 §2 makes part of each verb's contract.
- Probes: Not confident (words): anything agent-ways did not ship reads
userwhen it sits in your own config folder andprojectwhen it sits in a project's.claude/folder. You have called these "new" and "external", and this record keeps "external" for the kind, a sensor run by a command or an MCP server, which can sit in either place. Confident (tweaked): a built-in you have changed staysbuiltinat a glance, with a line under it naming your file and whether it adds to or replaces the built-in. That covers the git sensor with your own interval, or your ownnord.themein place of the bundled Nord. - Inversion: At one end each surface describes items in its own words, tuned to its family and drifting apart. At the other end one generic registry holds every item as the same record, with nothing particular to its family. This record takes one shape for the facts every family shares and puts each family's own fields after them.
Context¶
The settings store, the ways settings screens and the CLI each describe the items a person can add beside the ones agent-ways ships: themes, Claude Code mods, attend sensors, ways and judge profiles. ADR-515 audits all three surfaces. They describe the same six facts in different words. The built-in origin has five names (builtin, bundled, shipped, core, global), and the added origin has six (user, your ways, your own, override, this project, another project). attend folds origin into its kind column. A theme override is a third origin. A project's script sensor reads user, and the path sits under four field names. Two listing commands have no --json, which falls short of ADR-185 §2. No family stores an origin field: each one implies it by directory, by a compiled-in list or by the presence of a key.
The operator asked for the store, the screens and the CLI to keep and present an item the same way, including its type, whether it is built in, and its path. The detail pane should show at a glance whether a sensor, mod or theme is built in or new, and should list sensors that run on attend's generic engine beside the compiled ones. An unmerged branch adds one module card to the detail pane for mods, sensors and themes, with two origin values. ADR-403 moves sensors to one file per sensor in shipped, user and project directories, and ADR-503 §7 already holds that the CLI and the screens read one model.
Decision¶
1. The descriptor¶
| Field | Type | Meaning |
|---|---|---|
family |
theme, mod, sensor, way, profile |
the kind of item |
name |
text | unique within the family; a way's name is its id, such as softwaredev/delivery/commits |
kind |
text or null | what implements the item, from the family's list in §2; null where the family has one implementation |
origin |
builtin, user, project |
the lowest layer that defines an item of this name |
path |
absolute path or null | the origin layer's definition; null when it exists only inside a binary |
overrides |
list | every other layer that changes the item, in layer order: {origin, how, path}, where how is extends (it sets fields over the definition beneath) or replaces (a whole definition of the same name takes its place) |
source |
text or null | what runs or supplies the item when that is something other than its file: a crate, a command, an MCP server and tool, a plugin, a model |
version |
text or null | the source's version as the source reports it |
state |
one word | from the family's list in §2 |
detail |
text or null | one line that qualifies the state |
The origins:
- builtin: agent-ways ships the item, either compiled into a binary or as a file in the app dir, $XDG_DATA_HOME/agent-ways. A built-in can be copied to a new name and cannot be renamed or deleted (ADR-403 §5, and the theme tab's flow).
- user: the item is defined in the person's config root under $XDG_CONFIG_HOME and applies in every project.
- project: the item is defined under a project's .claude/ and travels with the repository. A project's command and MCP sensors load only for a project on the allow-list (ADR-403 §2).
A target's config file sets keys and defines no items, so target is not an origin.
An item is identified by its family and name. A user or project definition that shares a built-in's name is an override of the built-in, and the item's origin stays builtin. A whole same-named file is replaces: a theme file, or a way under ADR-143's whole-file shadow. Field-level layering is extends: ADR-403's sensor files, a gate.profiles patch of a shipped profile, or an attend.sensors.<name>.* key in a config file today. The same rule applies between user and project for an item a person added. Whether an item is built in then depends only on its name, and the override entries show what changed it.
2. Each family's words¶
| Family | kind |
source |
version |
state |
|---|---|---|---|---|
| theme | null | null | null | active, inactive, invalid, unknown |
| mod | plugin |
the plugin id, such as attend@agent-ways |
the shipped plugin version | converged, drift, pending, disabled, removed, held, off (ADR-512), unknown |
| sensor | crate, script; under ADR-403, crate, command, mcp, and ways for ADR-199's sensors |
the crate; the command's executable; <server> <tool> |
the crate's version; null for the others | active, off, not-compiled, missing, refused, failing, invalid, degraded, unknown |
| way | null | null | null | enabled, disabled, invalid, unknown |
| profile | the provider: anthropic, openrouter, claude-code |
the model | null | active, inactive, invalid, unknown |
A state that takes more than one word is written as a hyphenated token. A definition that fails its schema is listed with state invalid, and its detail names the first finding. It is never left out of a list. Fields that belong to one family follow the descriptor: a mod's wanted and its per-target installed versions, a sensor's description, interval and min_interval, a theme's label.
3. The store encodes origin by where a definition is found¶
No item file carries an origin. A file takes its origin from the directory it is found in, so a file copied between layers takes the origin of the place it was copied to.
| Family | builtin |
user |
project |
|---|---|---|---|
| theme | compiled into agent-theme |
$XDG_CONFIG_HOME/agent-ways/themes/<name>.theme or .toml |
none |
| mod | plugins/<name> in the app dir |
none | none |
| sensor, under ADR-403 | shipped files, projected to $XDG_DATA_HOME/agent-ways/attend/sensors/ |
$XDG_CONFIG_HOME/attend/sensors/<name>.yaml |
.claude/attend/sensors/<name>.yaml |
| sensor, until then | a name in BUILTINS |
attend.sensors.<name>.script in $XDG_CONFIG_HOME/attend/config.yaml |
the same key in .claude/attend.yaml |
| way | $XDG_DATA_HOME/agent-ways/hooks/ways |
$XDG_CONFIG_HOME/agent-ways/ways |
<project>/.claude/ways |
| profile | profiles.yaml, compiled into ways-agent-core |
gate.profiles.<name> in agent.yaml |
none |
A mod's mods.<name>.* keys are settings that apply to the mod, and the mod is defined by its plugin folder.
The settings layer field (ADR-503 §9) uses the same words. A key set by a shipped file reports layer: builtin, which is ADR-403's shipped layer. default remains the schema's canonical value, and user, target, project and file are unchanged.
4. One type, one producer per family¶
The descriptor is one type, Item, in agent-settings. That crate depends on no other workspace crate, and ways-cli, attend and agent-tui can all reach it. It serializes to the JSON of §5. Each family's owner builds its items in one function, which the family's list verb and the screens both call. The screens read sensors from attend sensor list --json until the sensor spec of ADR-403 §7 lets ways read the files itself. The branch's Card is built from an Item plus the family's rows, and its Origin gains Project.
5. The CLI¶
Every command that lists or shows items prints one object per item under --json. The descriptor's fields come first, under the names of §1, and are always present, null where they do not apply. The family's own fields follow. Text output uses the same words.
ways settings items [<family>] [--json]is new. It lists every item of every family, or of one, and is the CLI form of the screens' cards. Its text prints one line per item: family, name, origin, kind, state and path.ways settings theme listdropssource,fileandactiveand printsorigin,path,overridesandstate, withlabelafter them. Its text prints the origin and the state, and lists invalid files.ways manage mod listgains--json: the descriptor,wanted, and atargetslist carrying the fieldsways statusprints for each target.attend sensor listgains--json: the descriptor, thendescription,intervalandmin_interval.kindcarries the kind, and<crate>@<version>splits intosourceandversion. The text table gains anOrigincolumn, and itsKindcolumn prints the kind.- In
ways status,ways.global_total,global_semantic,user_totalanduser_semanticbecomeways.builtinandways.user, each{total, semantic}. The text lineCore ways:becomesBuiltin ways:, and the project counts stay underprojects. This amends ADR-143 §3, which named that linecore. ADR-143's roots keep their locations and precedence.
6. The card¶
Every item node on the mod, sensors, theme, ways and gate tabs heads its detail with the card for its Item. The figure shows three cards: a built-in sensor a user file extends, a project's command sensor that the allow-list refuses, and a bundled theme that a user file replaces.
- Rows, in order: the title and a dim summary line; a blank line;
origin(the word, then·and the path when there is one); oneoverriderow per entry, as<origin> <how> · <path>;kind;source;version;state(the word, then·and the detail); then the family's rows. A null field draws no row. - Colour:
builtintakes the info role.userandprojecttake the off-default accent, in bold. Each family has one table that maps its state words to a tone (ok, plain, warn, err), and the card and the CLI's coloured text both read it. - Ways tab: its scope sections are named
project,userandbuiltin.other projects,prefixesandnot foundstay, since they are views and placeholders. The way box'sfrom,rootandfilerows become the card's origin and path rows. - Sensors tab: it lists every sensor that
attend sensor list --jsonreturns, of every kind. - Engine picker: it shows each profile's origin word beside its name.
Consequences¶
Positive¶
- The detail pane shows whether an item is built in, added by its user or added by its project, in the same row and word on every tab.
- An agent or a script can find what a person added with one command and one field, across every family.
- A project's own sensors, ways and their files can be told apart from the user's, which is where the allow-list of ADR-403 §2 applies.
- A file that fails to load shows up as
invalidinstead of being missing from the list. - The card, the text output and the JSON come from one function per family, so they cannot drift apart again.
Negative¶
- Scripts that read
ways settings theme list --json, thewaysblock ofways status --jsonor theKindcolumn ofattend sensor listbreak, and nothing keeps the old names. - The screens depend on
attend sensor list --jsonfor sensor descriptors, so an absent or slowattendleaves the sensor cards with only what the settings layers say. - Every family has to define a list of state words and their tones, and keep the list closed.
- The branch in flight changes before it merges:
OrigingainsProject, a theme override readsbuiltin, and the card's state words become the CLI's.
Neutral¶
- This record amends ADR-403 §2 and §5, which call the lowest sensor layer
shippedand its filesbundled. That layer is the originbuiltinand reportslayer: builtin. The dated note goes on ADR-403 when this record is accepted. - Targets, skills, agents, commands, the MCP server and guard hooks have no origin to show and stay outside the descriptor (ADR-515).
- Internal names such as
manifest.global_hashandWayScopecan keep their names. Only what a surface prints changes.
Alternatives Considered¶
- Two origins,
builtinanduser, as the branch has them. A project's items would read as the user's, and the screens could not show which items came with a repository and run code its author chose. builtinandexternal, with the layer in a second field. This needs two fields for one fact. "External" is also the operator's word for a sensor run by a command or an MCP server, which is a kind and can be a user's or a project's.- An
originkey in each item file. A copied file would carry a stale origin, and the directory already says where the file is, which ADR-143 and ADR-403 §2 rely on. - Origin as the layer of the definition in effect, so a user's
nord.themereadsuser. Whether a name is shipped would no longer be a fact of the item, and the copy, rename and delete rules of ADR-403 §5 key on exactly that. - A shared vocabulary with JSON shaped per family. The screens and scripts would still parse each family separately, and
ways settings itemscould not exist. layer: defaultfor keys set by shipped sensor files.defaultwould then mean both the schema's canonical value and a file agent-ways ships.
Addendum, 2026-10-29: decisions from slice 1's review¶
Appended after acceptance. The operator answered the four questions slice 1's review left open, and §1 and §2 above now read as follows.
overrideslists every other layer that changes the item, in layer order. A user switch kept for a project's sensor lists asuser extendsahead of the project origin.- The sensor states gain
degraded. A sensor whose kind attend does not run yet readsdegraded, in the warn tone, with the reason indetail: a command or mcp sensor until ADR-403's later slices, and aways-kind sensor. It replaces the earlier mapping of attend's "not hosted" tomissing. - Every family's states gain
unknown, in the plain tone, for a state not yet read: a mod not yet read, or an enabled sensor while attend is absent.detailsays why.stateis never null. - Tone comes from the state word alone. A critical mod in drift reads warn, and the bottom-bar notice still flags it.