Specifications and the specification tree

A specification is one described piece of work, with a title, a summary, Markdown content, a status and its own questions and answers. A project keeps its specifications in a tree, and your AI coding agent implements the work from that tree.

Writing the work down before any code exists is the core of spec-driven development (SDD). In Athenode your AI agent asks you questions, writes the specification from your answers, and later reads it when it implements the work. You can also write and edit a specification by hand.

What a specification holds

Part	What it is	Who writes it
Title	The name shown in the tree	You or your agent
Summary	A short statement of what the specification is for	You or your agent
Content	The full description, in Markdown	You or your agent
Status	Draft, Prepared, Processing or Completed	You or your agent
Parent	The specification it sits under. A top-level specification has none	You or your agent
Blockers	The specifications that must be completed first	Your agent, or you
Questions and answers	The clarifying questions an agent asked and what you answered	Your agent, from your answers
Implementation plan	How the agent intends to implement the specification	Your agent, before it implements it
Id	The identifier you pass to a skill or a command	Athenode

The title, the summary, the content and the implementation plan can be of any length. The number of specifications in a project depends on the project's plan: 100 on the Free plan and unlimited on the Solo, Team and Business plans. At the limit, Athenode refuses to create another specification and shows "Plan limit reached". The owner can then delete specifications the project does not need, which makes room for as many new ones, or upgrade the project's plan. Plans and limits has the full table.

Athenode keeps a specification with its questions, answers, implementation plan and status. It does not keep your code, the changes an agent made or the name of the AI tool that did the work.

How the specification tree is built

The specification tree is the hierarchy of a project's specifications. Any specification can have sub-specifications, to any depth. A project has one tree, and a specification with no parent is a top-level specification.

The tree describes a product at several levels at once. The top says what the product is, the levels below say what each part does, and the bottom holds tasks small enough to implement. A web shop might look like this:

• Web shop
  • Product catalogue
  • Checkout flow
    • Cart
    • Payment
    • Shipping
  • Customer accounts

"Checkout flow" records the decisions that hold for the whole checkout, such as which countries the shop delivers to. "Cart", "Payment" and "Shipping" each describe one part of it. A sub-specification is read together with the specifications above it, so a decision written once in "Checkout flow" applies to all three.

Branches do not have to be equally deep. "Product catalogue" can stay a single specification while "Payment" gets sub-specifications of its own for card payments and refunds. Any specification can be deepened at any time, whatever its status.

Leaf specifications

A leaf specification is a specification with no sub-specifications. Leaves are what an AI agent implements. In the web shop, "Product catalogue", "Cart", "Payment", "Shipping" and "Customer accounts" are leaves, and "Web shop" and "Checkout flow" are not.

The moment "Payment" gets a sub-specification it stops being a leaf, and the work moves to the specifications below it. The web app's Orbit view calls a leaf a deliverable and counts progress in deliverables.

A good leaf is a task an agent can finish in one go and that you can review as one change. When a leaf covers more than that, decompose it. To decompose a specification is to break it down into one level of stages, each a sub-specification of its own. The /atn-decompose skill does this with you.

For a specification with sub-specifications, the work is in the leaves below it. It turns Completed when every specification below it is.

The four statuses of a specification

The status says where a specification is on its way from an idea to code.

Status	Meaning	Value in commands
Draft	The specification is being shaped. Its content may be incomplete	draft
Prepared	The specification is finished and ready to be decomposed or implemented	prepared
Processing	An agent is planning or implementing it	processing
Completed	It is implemented, and reviewed when your workflow settings include a review	completed

A specification created by hand starts as a Draft. The skills move it on from there:

• A mind map creates a Draft before the first question, so that every answer is stored as you give it, and sets the specification to Prepared when it is written. A mind map is a session in which your AI agent asks rounds of questions and turns your answers into a specification.
• A decomposition creates each stage as a Draft and sets it to Prepared once its questions are answered and the stage is rewritten from them.
• An apply run sets the specification you gave it and each leaf to Processing while it works, and each leaf to Completed when it is done. To apply a specification is to have your AI agent plan and implement each leaf under it, in the order the blockers allow, with tests, review and git handled as your workflow settings say.

A parent turns Completed when everything below it is Completed. A leaf that failed or that you skipped during an apply run stays Processing, and so does the specification the run started from, so the tree shows where a run stopped short. Running /atn-apply again takes up the leaves that are Prepared or Processing. A Draft leaf is left out of a run and keeps its parent from turning Completed.

You can also set a status yourself, in the web app or with the Athenode CLI. Any status can be set from any other. Setting a Completed specification back to Prepared, for example, makes it available to an apply run again. A blocker does not stop you from changing a status.

Continuing a mind map on an existing specification sets it to Prepared at the end, whatever its status was before.

Blockers and the order of work

A blocker is a dependency between two specifications: a specification that is blocked by another is implemented after it. If "Payment" is blocked by "Cart", an apply run implements "Cart" first.

Each specification shows both directions. "Blocked by" lists what it waits for, and "Blocks" lists what waits for it. In the web app's Tree view, a specification with a blocker that is not Completed carries a lock.

Sub-specifications inherit the blockers of the specifications above them. If "Checkout flow" is blocked by "Customer accounts", then "Cart", "Payment" and "Shipping" all wait for "Customer accounts", and you set the blocker once.

Your agent sets most blockers for you. During a mind map it researches which existing specifications the new one depends on, overlaps or conflicts with, and adds the blockers it found when it writes the specification. A decomposition does the same for each stage, including the order between the stages. Both skills list the blockers they added, removed and skipped in their report. You can change any of them afterwards.

A blocker has to satisfy these rules:

• It is another specification of the same project.
• It is not above or below the blocked specification in the tree.
• It is not Completed at the moment you add it.
• It does not repeat an existing blocker.
• It does not create a cycle, in which two specifications would wait for each other directly or through others.

Blockers decide the order of an apply run. They do not limit which status you can set. When a leaf waits for a specification outside the part of the tree you are applying, the run offers "Stop" and "Run only the leaves not blocked by external blockers". When the blockers under the specification form a cycle, the run stops before it changes anything. A blocker that becomes Completed stays in the list and stops holding the specification back.

Questions and answers of a specification

The questions and answers of a specification are the record of what an agent asked about it and what you decided. Each entry holds one question, with the options that were offered, and your answer.

They are recorded while you work, and the specification is written afterwards from all of them. During a mind map, every round of questions is stored on the specification as soon as you answer it. During a decomposition, each stage gets its own questions, and your answers are stored on that stage.

The record keeps every decision traceable. Six weeks after "Payment" was implemented, you can open it and read that you chose to keep the cart when a card is declined, and which alternatives you turned down.

The agents use the record too. When you continue a mind map on an existing specification, the agent reads the earlier questions and answers and goes on from the topics they cover.

A question can be answered again, and the new answer replaces the old one. Questions are not edited or deleted. In the web app the record is on the Questions & answers tab of a specification, where a question without an answer is marked "Unanswered". The tab is for reading. Questions and answers are added from your AI tool by the skills, or with the Athenode CLI.

The implementation plan

The implementation plan is what an agent records for a leaf specification before it implements it. It says how the agent intends to build the leaf in your codebase.

An apply run writes one plan per leaf. For each leaf, the agent first checks the specification against your code and records the plan, then implements it, then reviews it as your workflow settings say. You can read the plan on the Plan tab of the leaf while the run is working on it, and at any time afterwards. Until a leaf has been applied, the tab shows "No plan yet".

If the agent finds that a leaf cannot be implemented as it is written, it records no plan. The run offers "Provide a resolution", "Skip this leaf" and "Stop the run".

The implementation plan is unrelated to the project's plan, which is the subscription the project is on.

A specification from first question to finished code

Take the checkout of the web shop. You run /atn-mindmap and describe it. The agent proposes to place the new specification under "Web shop", and "Checkout flow" appears in the tree as a Draft. You answer three rounds of questions about the cart, payment methods and delivery. Each answer is stored on the specification. The agent then writes the content, adds "Customer accounts" as a blocker because the checkout needs a signed-in customer, and sets "Checkout flow" to Prepared.

"Checkout flow" is too large for one task, so you decompose it. The stages "Cart", "Payment" and "Shipping" appear below it as Drafts. You answer the questions of each stage. The agent rewrites the three stages, marks "Payment" as blocked by "Cart" and "Shipping" as blocked by "Payment", and sets them to Prepared.

You run /atn-apply on "Checkout flow". The run reports that "Customer accounts", which is outside "Checkout flow", blocks all three leaves, and you choose "Stop". After "Customer accounts" is Completed, you run it again. "Checkout flow" and "Cart" turn Processing, a plan appears on "Cart", and "Cart" turns Completed. "Payment" and "Shipping" follow in that order, and "Checkout flow" turns Completed after the last of them.

A month later you want refunds. You continue the mind map on "Payment" or add a sub-specification below it, and the same sequence starts on that part of the tree.

Where you work with specifications

• In the web app, on the Specs page of a project, you browse the tree, read and edit specifications, change statuses and edit blockers. See Specifications in the web app.
• In your AI tool, the skills create and change specifications for you. See the Athenode workflow.
• In a terminal, the athenode specs commands read and change specifications and print JSON. See the Athenode CLI reference.
• Through the Athenode MCP server, an AI agent has the same commands as tools.

To find a specification in a large tree, use search by meaning.

Who can change a specification

Every member of a project can read its specifications, with their questions and answers, plans and blockers. An editor or the owner can create, edit and move specifications, change statuses and edit blockers. The owner can delete a specification. An AI agent acts through a project token and can do what the member who created the token can do. Roles and permissions has the full matrix.

A specification that others are blocked by can be deleted, and those specifications then stop waiting for it. A ToDo card that came from a deleted specification, or that became one, is kept and loses its link to it.