Search by meaning

Search by meaning finds specifications by what they say as well as by the words they contain. A search for "customer cannot pay" finds the specification "Payment" even when that specification uses neither "customer" nor "pay".

A specification is one described piece of work, with a title, a summary, Markdown content, a status and its own questions and answers. Specifications are written in people's words, by different people and over months, so the same subject ends up under several names. One author writes "sign-in", another "login" and a third "authentication". With search by meaning, a query in one of these wordings reaches the specifications written in the others.

What search by meaning finds

A search looks through the title, the summary and the content of every specification in one project. Matches by word and matches by meaning come back as one list with the best match first, so there is one search to run and one result to read.

A query for an error code, a field name or a product name finds the specification that contains it. A query that describes a subject finds the specifications about that subject, whatever words they use.

Take a web shop whose specification tree has "Checkout flow" with the sub-specifications "Cart", "Payment" and "Shipping". The specification tree is the hierarchy of a project's specifications.

Query	Finds	Why
declined card	"Payment"	The content describes what happens when a card is refused
customers lose their basket	"Cart"	"Basket" and "cart" mean the same thing here
delivery abroad	"Shipping", "Checkout flow"	Both say which countries the shop delivers to
PAYMENT_TIMEOUT	"Payment"	The content contains that exact name

A match by meaning says that two texts are about similar things. Whether a result is the specification you wanted, a neighbour of it or something unrelated that uses similar language is for you, or your agent, to judge by reading it.

How to phrase a search query

A query can be a single word, a phrase, a whole sentence or an exact identifier.

• Describe the subject the way you would say it to a colleague. "Users are signed out too early" works as a query.
• Search for the symptom as well as the cause. A bug report says "blank page after paying", while the specification may say "payment confirmation".
• Use the exact term when you know it. A name such as PAYMENT_TIMEOUT leads straight to the specification that contains it.
• Search a second time with other wording when the first result is thin. Try your own phrase, then the technical term, then what a user sees.

A search covers the project you are in. Specifications of your other projects are not part of the result.

How to write specifications that search finds

A specification that says little can match little, so the way a specification is written decides how well it is found.

• Give it a title that says what changes. "Authentication errors" names a subject, and "Fixes, part 2" gives a search nothing to match.
• Write a summary. Two sentences on what the specification is for are the clearest statement of its subject.
• Keep one subject per leaf specification. A leaf specification is a specification with no sub-specifications. Leaves are what an AI agent implements. One that covers sign-in, billing and email at once matches each of them weakly.
• Say what a user sees, next to the cause. The next request will describe the symptom.
• Write a full name once next to an abbreviation.

The mind map writes a title, a summary and content organised by topic for you. These points matter most for specifications you write or edit by hand.

How agents use search to place and ground a new specification

Before an AI coding agent writes a specification, it has to learn where the work belongs, what already covers part of it and what must be done first. The skills of the standard Athenode setup find this out by searching the tree.

When you start a mind map with /atn-mindmap, the agent searches before it asks its first question. A mind map is a session in which your AI agent asks rounds of questions and turns your answers into a specification. The agent searches with words from your request and searches again with different wording when little comes back.

From the results, the agent proposes where the specification belongs in the tree and asks you to confirm. A request about refunds is offered a place under "Payment". The agent also works out which existing specifications the new one depends on, overlaps or conflicts with. When the specification is written, the agent adds the blockers that follow from this research and lists them in its report. A blocker is a dependency between two specifications: a specification that is blocked by another is implemented after it.

When you decompose a specification with /atn-decompose, the agent does the same research for each stage. To decompose a specification is to break it down into one level of stages, each a sub-specification of its own. The stages are linked to each other in the order they have to be built, and to related specifications elsewhere in the tree.

The agents read matches together with their ancestors. A match called "Session expiry" means one thing under "Customer accounts" and another under a security review, and the specifications above it carry decisions that apply to it.

/atn-apply also accepts a title in place of an id and searches for it. With one match the run starts on that specification. With several, the skill lists them and asks you for the id.

The mind-map skill, the decompose skill and the apply skill each have a page with the questions they ask. Placing new work beside related work is part of the method described in the guide to spec-driven development (SDD).

Where to search specifications

The same search is available in the web app, in the Athenode CLI and to your AI agent.

Where	How	What comes back
Web app	The Search specifications... field on the Specs page	The matches shown in the tree, each under its parents
Athenode CLI	specs search	Up to 50 matching specifications as a list, best match first
Athenode CLI	specs tree with --query	Up to 20 matches, nested with their ancestors
Athenode MCP server	The tools specs_search and specs_tree	The same results as the two commands

In the web app, enter the query in the search field. The Tree view shrinks to the matches and their parents, and the Orbit view dims everything else. You can combine the search with the status filter. Specifications in the web app describes both views. The result shows the tree as it was when you searched, so search again after specifications change.

From a terminal, run the search in the directory that holds .athenode/config.json:

npx @athenode/cli specs search "declined card"

To get the matches with their place in the tree, use specs tree:

npx @athenode/cli specs tree --query "declined card"

Both commands print JSON. A match that was found by meaning carries the passage that matched in its snippet field, which shows why it is in the result. The Athenode CLI reference lists the other options of both commands.

Your AI agent searches through the Athenode MCP server. You can ask for a search in plain words, such as "search the specifications for anything about declined cards".

Every member of a project can search in the web app. Searching from the CLI or from an AI tool needs a project token, a personal access token that lets the Athenode CLI, and your AI agent through it, act on one project. An editor or the owner creates one on the Tokens page, as Project tokens describes.