Specifications in the web app

A specification is one described piece of work, with a title, a summary, Markdown content, a status and its own questions and answers. The Specs page of a project, headed Specifications, shows the project's specification tree, which is the hierarchy of its specifications. It is where you read, create and edit specifications by hand.

Every member of the project can open the page and read everything on it. Creating and editing specifications, changing a status and editing blockers need the editor or owner role. Deleting a specification needs the owner role. Roles and permissions lists what each role can do.

The page has two views of the same tree, Orbit and Tree, with a switch between them next to the page heading. A project opens in the Orbit view, and after that the web app opens the view you used last in this browser.

Browse the specification tree in the Tree view

Use the Tree view when you want to read the tree as an outline and move through it quickly.

1. On the Specs page, select Tree in the view switch.
2. Select the arrow in front of a specification to show or hide its sub-specifications.
3. Select a title to open that specification in the panel on the right.

A specification with sub-specifications has a folder icon, and a leaf specification has a document icon. A leaf specification is a specification with no sub-specifications. Leaves are what an AI agent implements. The colour of a row follows its status, and the icon pulses while the status is Processing.

A lock on a row marks a specification that waits for a blocker. A blocker is a dependency between two specifications: a specification that is blocked by another is implemented after it. Point at the lock to read "Blocked by:" with the title and status of each blocker that is not Completed.

Drag the divider between the tree and the panel to change their widths.

See progress in the Orbit view

Use the Orbit view when you want to see how much of the tree is done and what can be worked on next.

1. On the Specs page, select Orbit in the view switch.
2. Select a ring segment to open that specification and bring its part of the tree to the centre.
3. Select the centre to step back one level.

The map is a circle. The top-level specifications share the circle, and their sub-specifications fill the outer rings. The coloured edge of each segment marks its status, and the legend shows the mark for Blocked specifications. The centre shows how much is done, as a count such as "4 of 9 done". The Orbit view calls a leaf a deliverable.

While no specification is open, an overview beside the map counts the deliverables that are done and groups the rest:

Group	What it lists
Waiting on others	Specifications with a blocker that is not Completed, each with "Waiting on" and the blocker's title
In progress	Leaves that are Processing
Ready to start	Leaves that are Prepared and have no blocker left to wait for

Select a row in the overview to open that specification.

An open specification shows where it sits. Part of names its parent, a position such as "2 of 3" counts it among the specifications at the same level, and two arrows open the previous and the next one. Sub-specifications lists what is below it, with the number of deliverables done. Close the specification to return to the overview.

Find a specification with search and the status filter

Use search when you know what a specification is about, and the status filter when you want to see one stage of the work, such as everything that is Prepared.

1. On the Specs page, select the Search specifications... field, or use Ctrl+K (Cmd+K on macOS).
2. Enter a word, a phrase or a description of what you are looking for.
3. Optional: select Filter by status and tick one or more statuses.

In the Tree view, the tree shrinks to the matches. Each match is shown under its parents, and a parent that is not itself a match is dimmed. In the Orbit view, the whole map stays and everything that does not match is dimmed. When nothing matches, the page shows "No matches".

The search finds specifications by the words in their title, summary and content, and also by meaning, so a description in your own words finds a specification that uses different ones. Search by meaning explains how to phrase a query.

Search and the status filter work together: with both set, you see the matches that have one of the ticked statuses. Each ticked status appears as a chip under the search field, and removing the chip removes it from the filter. The filter is remembered for each project in this browser. Clear the search field to see the whole tree again.

Search results show the tree as it was when you searched. Search again to include a specification that was added or changed afterwards.

Create a specification by hand

Create a specification by hand when you already know what to write, or when you want a place in the tree that an agent will fill later. To have your AI agent ask you questions and write the specification with you, run the /atn-mindmap skill in your AI tool.

You need the editor or owner role.

1. To add a top-level specification, select New next to the view switch. To add a sub-specification, select Add sub-specification on the row of its parent in the Tree view, or on the open parent in the Orbit view.
2. In the Add specification dialog, enter a Title. For a sub-specification the dialog names the parent it will be added under.
3. Select Add specification.

The specification appears in the tree with the status Draft and an empty summary and content.

In a project with no specifications, the page shows how to connect the Athenode CLI and start a mind map. Select Or create manually in the Tree view, or Or add one manually in the Orbit view, to open the same dialog.

A project on the Free plan holds up to 100 specifications. At the limit the web app shows "Plan limit reached", and the owner can delete specifications the project does not need or upgrade the project's plan. The Solo, Team and Business plans have no limit on specifications. See Plans and limits.

Edit the title, summary and content

Edit a specification in place to correct it or to add detail an agent should work from. You need the editor or owner role.

1. Open the specification.
2. Select the title, the summary or the text on the Content tab. The text becomes a field you can type in.
3. Change the text. The content is Markdown, and the tab shows it formatted when you are not editing.
4. Select the check mark next to the field to save. Leaving the field saves it too, and in the title Enter does the same.

A title cannot be empty. An empty summary shows "No summary", and an empty Content tab invites you to write the specification or build it with /atn-mindmap.

If you open another specification while a change is unsaved, the web app asks "Discard unsaved changes?". Select Keep editing to go back, or Discard changes to drop the change.

The title, the summary and the content can be of any length.

Read the questions and answers and the implementation plan

Open these two tabs when you want to know why a specification says what it says, or how an agent intends to build it.

1. Open the specification.
2. Select the Questions & answers tab to read every question an agent asked about this specification, each followed by your answer. A question that was not answered is marked "Unanswered".
3. Select the Plan tab to read the implementation plan, which an agent records for a leaf before it implements it.

Both tabs are for reading. Questions and answers are recorded by the skills while you answer them in your AI tool, and a plan is recorded when the specification is applied with /atn-apply. A specification that no skill has worked on shows "No questions yet" and "No plan yet".

Change the status of a specification

Change a status by hand when the tree and the real state of the work have drifted apart, for example to mark work you did yourself as Completed. The skills set statuses on their own as they work. You need the editor or owner role.

1. Open the specification.
2. Select the status next to the title.
3. Choose Draft, Prepared, Processing or Completed.

The new status shows at once, in the tree and for every member who has the page open. Any status can be set from any other, whatever the blockers are.

Edit the blockers of a specification

Add a blocker when one specification must be implemented after another. The mind-map and decompose skills add blockers from their own research, so you edit them by hand mainly to correct the order. You need the editor or owner role.

1. Open the specification that has to wait.
2. Under Blocked by, select Edit blockers.
3. In the field Search specifications to add as blocker, enter part of a title and choose the specification to wait for. The blocker is saved as soon as you choose it.
4. To take a blocker away, select Remove blocker next to it.
5. Select Done.

Blocked by lists what this specification waits for and Blocks lists what waits for it, each with its status. Select a title in either list to open that specification. To change an entry under Blocks, open the specification named there and edit its Blocked by list.

The field offers the specifications of this project that are not Completed and are not blockers of this specification already. A choice is refused, with a message under the field, when the two specifications are above and below each other in the tree or when the blocker would create a cycle. A sub-specification also waits for the blockers of the specifications above it, so a blocker that holds for a whole branch is set once, on the top of that branch.

Move a specification to another parent

Move a specification when it belongs under another part of the tree. You need the editor or owner role. A specification is moved from your AI tool or from a terminal. Ask your AI agent to move it, or use the Athenode CLI with the ids that Copy ID gives you:

npx @athenode/cli specs update <spec-id> --parent <parent-id>

Use --clear-parent in place of --parent <parent-id> to make it a top-level specification. The sub-specifications move with it, and the web app shows the new position without a reload.

A move is refused when it would put a specification above or below one of its own blockers, or when the blockers would form a cycle in the new position. Remove the blocker that is named in the refusal, then move the specification again.

Delete a specification

Delete a specification when the work has been dropped. You need the owner role.

1. In the Tree view, select Delete on the row of the specification. In the Orbit view, open the specification and select Delete above it.
2. In the Delete specification? dialog, select Delete.
3. If other specifications are blocked by this one, or by one below it, the web app lists them under "This specification blocks others". Select Delete anyway to go on.

The specifications that were blocked by a deleted one stop waiting for it. A ToDo card linked to a deleted specification is kept and loses the link. A member who has the specification open sees "Specification removed".

Copy the next command for your AI agent

Each specification has a copy button that gives you the command for its next step, with the specification's id already in it. Paste the command into your AI tool.

1. Open the specification.
2. Select the copy button on the specification. Its label names the command it copies.
3. To copy something else, open the menu beside the button and choose from it.

Status	The button copies	Also in the menu
Draft	Copy mind-map command: /atn-mindmap --continue <spec-id>	Copy ID
Prepared, with no sub-specifications	Copy apply command: /atn-apply <spec-id>	Copy decompose command: /atn-decompose <spec-id>, and Copy ID
Prepared, with sub-specifications	Copy apply command: /atn-apply <spec-id>	Copy ID
Processing or Completed	Copy ID

In the Orbit view the button is an icon, and all of its commands are in its menu. The id that Copy ID gives you is what the athenode specs commands of the Athenode CLI take as their argument.

The commands are written as slash commands. The way you run a skill differs by AI tool, and the supported AI tools gives the form for each one.

Link to a specification

Opening a specification puts it in the address of the page. Copy the address from your browser to send another member straight to that specification. The link opens for members of the project. If the specification was deleted in the meantime, the page shows "That specification isn't available in this project."

Follow changes as they happen

The Specs page updates without a reload. When another member edits a specification, or your AI agent creates one, sets a status, adds a blocker or records an answer, the change appears in the tree and in the open specification. During an apply run you can watch each leaf turn Processing and then Completed, and read its plan on the Plan tab as soon as it is recorded.

Work with specifications from other interfaces

In your AI tool, the skills of the Athenode workflow create, break down and implement specifications. In a terminal, the athenode specs commands list, search, create, update and delete specifications and manage their status, blockers, questions and plan. An AI agent has the same commands as tools of the Athenode MCP server.