Luminair
← Blog Architecture 8 August 2026 9 min read

Abilities: specs that travel with the session

In late 2025, spec-driven development was the new way to keep coding agents on track, and the backlash called it waterfall in Markdown. Luminair's abilities sit at the small end of that idea: a few plain rules, attached to one session, sent on every turn. The hard part turned out not to be the rules. It was where their text lived.

ELElion Labs · Sessions & sync Luminair 1.0.243 Checked against the source and git history
Fig 01  How an ability reaches every turnSchematic · from renderDirectivesBlock in desktop/main.js
WHERE RULES COME FROM Controller rules rules you adopted in Solace Team abilities shared by your Team, for every member This session's lines typed in the //abilities sheet, or set by a ///macro UP TO 40 LINES Macro text, in your account synced settings, not the app bundle ONE BLOCK PER TURN === SESSION ABILITIES (HARD RULES ...) === - only touch mobile/ - no new dependencies deduplicated · capped at 120 lines · “say so and stop rather than violating it” Turn from the Mac added to the instructions Turn from the phone relay carries the abilities Cloud run same block in its instructions
The two example lines are illustrations, taken from the placeholder and example text of the Abilities sheet. The header, the 40 and 120 line caps, the order and the closing instruction are read from the current code. The same function builds the block for Mac turns, phone relays and cloud runs.

The short version

  1. Spec-driven development, as in GitHub's Spec Kit and AWS's Kiro, writes a detailed spec before the agent codes. Critics said it buries agility under Markdown.
  2. Luminair's //abilities are much smaller: plain one-line rules for one session, added to the model's instructions on every turn as hard rules.
  3. ///macros set an ability with one keystroke. Their text first lived inside the app, so each installed build carried its own copy of the rule, and two Macs could disagree.
  4. On 6 August 2026 the text moved into synced account settings. The first version of that move froze old text in place; the fix a day later taught us how defaults and edits should mix.
02The spec-driven wave

Write it down first.

Coding agents are good at writing code that looks right. They are less good at remembering what you actually wanted three prompts ago. In September 2025, GitHub's answer was Spec Kit, an open source toolkit that walks an agent through /specify, /plan and /tasks. The post argues for treating specifications “not as static documents, but as living, executable artifacts that evolve with the project.” Its summary line: “Specs become the shared source of truth.”

A month later, Birgitta Böckeler compared Kiro, spec-kit and Tessl on martinfowler.com. She found the term covers three different levels. Spec-first: “A well thought-out spec is written first, and then used in the AI-assisted development workflow for the task at hand.” Spec-anchored: “The spec is kept even after the task is complete.” Spec-as-source: the human edits only the spec, never the code. She also noted that the tools keep a standing context she calls a memory bank; Kiro calls it “steering”.

Then came the pushback. In November, François Zaninotto at marmelab published “Spec-Driven Development: The Waterfall Strikes Back”. One example spec to display the current date ran to “8 files and 1,300 lines of text”. His list of problems included “Markdown Madness” and a “False Sense of Security”: “agents don’t always follow the spec.”

Somewhere between no plan and 1,300 lines of plan, there is a line you write once and never want broken.
03The small end of a spec

One rule per line.

Abilities shipped in Luminair on 31 July 2026 (commit 5c8e0d9e). Type //abilities in a session and a sheet opens with one text box. Each line is a rule. The sheet's own placeholder gives the flavour: “only touch the mobile/ folder”, “explain your plan before editing anything”, “never use emojis”, “keep replies under 5 lines”.

//abilities · this session
Abilities

Boundaries for how this session behaves. Write one rule per line, plain language, and they're added to the model's instructions every turn, so it stays inside the lines you draw. Separate from the Sandbox (that fences what it can write and reach; this fences how it acts).

only touch the mobile/ folderexplain your plan before editing anythingnever use emojiskeep replies under 5 lines
CancelSave
Redrawn from the sheet's markup in desktop/renderer.js, with its placeholder rules typed in. The hint text is the app's own, lightly re-punctuated. Custom abilities are part of Pro+.

That is the whole interface. What makes it different from a note in a chat is where the text goes. On every turn, Luminair adds a block to the model's instructions headed SESSION ABILITIES. The header calls them hard rules the user set for this session, which override the model's defaults and apply on every turn. The lines follow, then one more instruction: “If a request would require breaking an ability above, say so and stop rather than violating it.”

In Böckeler's terms, an ability is spec-anchored, but anchored to a session rather than a feature. It is written once and kept for every later turn, and it survives the conversation getting long, because it is re-sent each time rather than remembered. It is also nowhere near a full spec. It says nothing about what to build, only about the lines not to cross while building it. That is closer to Spec Kit's standing context than to its task lists.

The same block carries two other kinds of rule. Rules you adopt in Solace come first, and if you are on a Team, Team abilities are added for every member with a label that says so. The block is deduplicated and capped at 120 lines in total.

04One keystroke, one rule

Macros flip a live session.

Seven minutes after abilities, commit c81b65fd added a second namespace: ///. A macro is not a message to the model and not an app action. It changes the session's abilities. The first two were a pair, ///dd (Direct Deploy, over cable) and ///ota (a link to install over the air), in a group called Deploy mode. Firing one removes the other's line and adds its own, so the session always has exactly one deploy mode, and your own abilities are left alone.

Macros grew into a family of deploy rules for our own release work. A comment in the code explains why they existed at all. The deploy rule had been moved out of CLAUDE.md, the project instructions file, into an ability, because an ability is “injected on every turn of the session and overrides defaults, which CLAUDE.md prose does not.”

We also learned that where a rule sits in the block matters. On 6 August, one deploy rule was being treated as optional; buried as one bullet among many, the model narrated each fallback instead of just doing the work. The fix hoists that rule out of the list into its own header at the top of the block. A rule's position is part of its wording.

05The rule was in the bundle

Two Macs, two laws.

Here is the problem we did not see coming. The text of every macro was a constant inside the app's JavaScript. Whatever build you had installed was the law. A Mac that had not updated yet, a second Mac, and the phone app each carried their own copy of the rule, and a session could apply a stale one without anyone noticing.

The backlog entry written that day records the founder's words: “these abilities ALWAYS need to be absolutely synced. Not an option. They have to be stored in the account, not the desktop app.” The trigger was a deploy macro that ran an outdated rule.

Fig 02  Where the macro text livedFrom git history, 2026
31 JUL 6 AUG 7 AUG 8 AUG 6 SEP In the bundle each build's own copy In the account ow:macros syncs to the phone Seed empty defaults win until you edit Second Mac pulls it down on sign-in Deploy macros retired; the list is empty 5c8e0d9eaa19e76f4b292db7FIX-E1f12d6e0 How the live text is built today defaults in the app + your edits, in the account = what every device runs
Commit hashes from git; “FIX-E” is the label on the 8 August hydration change in desktop/renderer.js. Only the text fields of a macro (label, description, help, group, ability) can be edited from the account. What a macro does stays in code.

Commit aa19e76f moved the definitions into a settings key, ow:macros, that rides the existing account settings sync to the phone. The bundle's copy became a seed, written to the account once.

That seed caused the next bug. It copied every default's full text into the account. So the next time we improved a built-in rule in the app, every account that had already been seeded kept the old text, because an account copy wins over a default. We had frozen the rules we meant to free. The fix, a day later, seeds an empty entry per macro instead, so defaults win until you actually edit one, and a one-time cleanup deleted any stored text that was identical to the current default. From 8 August, a second Mac also pulls ow:macros down on sign-in, so it adopts the account's version instead of its own seed.

In early September the built-in deploy macros were retired from the Mac app. The default list is empty today; the /// namespace and the synced store remain.

06What a rule needs to hold

Small, re-sent, single-sourced.

Set against the spec-driven debate, abilities are a narrow answer to a narrow question: how do you make one constraint stick for the life of a session? What we learned maps onto the critiques.

Fig 03  Specs and abilities, side by sideFrom the sources and our code
Spec-firstStanding contextAbilities
SaysWhat to build and howHow the project worksWhat not to do while working
SizeSeveral filesA few documentsUp to 40 lines
Lives forOne taskThe projectOne session
Reaches the modelWhen the agent reads itWhen the tool loads itRe-sent every turn
The first two columns summarize Böckeler's descriptions of spec-kit and Kiro, and marmelab's example. The last column is Luminair's code. None of this says one approach is better; they answer different questions.

Three things made abilities hold. They are short, so reading them costs nothing and conflicts are easy to see. They are re-sent on every turn, so they do not fade as the conversation grows. And since August, the text of a shared rule has one home, the account, so every device reads the same words.

They are not a guarantee. marmelab's point that agents do not always follow the spec applies here too. That is why the block tells the model to stop and say so rather than break a rule, and why the things that must never happen, such as writing outside a folder, belong in the Sandbox, which the operating system enforces. An ability shapes behaviour; a fence prevents it.

And a rule that is sent is only useful if it arrives. In September we found that the Agent SDK version we bundled had been ignoring the option we used to add our instructions, abilities included, to Claude turns. We wrote that story up in Your model didn't get dumber.

The lesson we tookA rule has two parts: its words and its address. We spent our effort on the words. The bugs were all in the address: a copy per build, a copy per device, and a seed that froze old text in place.
07Find it in the app

Draw the lines in one minute.

  1. 1In any session, type //abilities and press Enter. Write one rule per line and press Save.
  2. 2A // button appears next to the session title while it carries abilities. Click it to review or change them.
  3. 3To fence what a session can write or reach, rather than how it behaves, type /sandbox instead.

Every // command is listed under Settings › General › Luminair Abilities › View.

08What we checked

Checked, and not claimed.

40
Ability lines kept per session
120
Lines in the combined block, after controller, Team and session rules are merged
7 min
From abilities (12:18) to the first /// macros (12:25), 31 July 2026
5
Account-editable text fields on a macro; its behaviour stays in code

What this post does not claim

  • That the model always obeys a ability. It is an instruction, not an enforcement mechanism.
  • That one session's abilities sync between devices on their own. The macro definitions sync through the account; the phone sends its session's abilities with each prompt it relays. We did not verify a Mac adopting abilities set on the phone.
  • That the phone and the Mac ship identical defaults today. The phone app's source still lists deploy macros the Mac retired in September; account edits apply to both.

Sources

Rules that ride every turn

Write the lines once with //abilities, and the session keeps them for as long as it lives.

Download Luminair →
← All dispatches Share XLinkedIn