Core concepts of Athenode
An Athenode project holds a specification tree, and an agent setup gives your AI coding tool the skills to work from that tree. A project token connects the two on your computer.
Athenode follows the method known as spec-driven development (SDD): the work is written down and thought through first, and an AI coding agent implements it afterwards.
What a project holds
A project is the top-level container you create in the web app. It holds one specification tree, its ToDo cards, one or more agent setups, its members, their project tokens and its plan. Each of these belongs to one project only.
Take a web shop as the example. It is one project, with one tree that describes the whole shop.
The project's plan is Free, Solo, Team or Business, and it sets the project's limits. A project on the Free plan holds up to 100 specifications and one agent setup. Plans and limits lists every limit, and Projects describes how to create, rename and delete a project.
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. The specification tree is the hierarchy of a project's specifications. Any specification can have sub-specifications, to any depth.
A leaf specification is a specification with no sub-specifications. Leaves are what an AI agent implements. In the web shop, "Checkout flow" has the sub-specifications "Cart", "Payment" and "Shipping". Those three are leaves until one of them is broken down further.
Every specification has one of four statuses. Draft means it is being shaped. Prepared means it is ready to be decomposed or implemented. Processing means an agent is working on it, and Completed means it is implemented.
A blocker is a dependency between two specifications: a specification that is blocked by another is implemented after it. "Payment" is blocked by "Cart", so your agent implements "Cart" first.
Specifications and the specification tree covers all of this in depth, and Specifications in the web app shows how to browse and edit the tree.
Agent setups
An agent setup is a named bundle of what your AI coding tools work with: skills, agents, rules, MCP servers and setup files.
- A skill is a reusable set of instructions that an AI tool loads when it is relevant, usually run as a slash command such as
/atn-mindmap. - An agent is a specialist that an AI tool can hand work to (a subagent in most AI tools).
- Rules are the instructions every agent in a setup follows.
- An MCP server is a connection to a tool server that the agents of the setup may use.
- Setup files are extra Markdown files kept with the setup. The ones under
settings/hold the project's workflow settings.
Every new project starts with its own copy of the standard Athenode setup. That copy contains the skills of the Athenode workflow, the agents they hand work to, the rules and the Athenode MCP server. You can edit it in the web app, and on the Solo, Team and Business plans a project can hold further setups.
The installed setup is the setup whose files are in a local project directory. The Athenode CLI puts it there in the format each of your AI tools reads, for any of the 30 supported AI tools. Two members of a project who install the same setup give their AI tools the same skills, agents and rules.
Agent setups explains what a setup contains and when to create another one. Install a setup describes the install and what it writes to your repository.
Skills and the workflow
The standard Athenode setup contains seven skills. Three of them carry a specification from an idea to code.
A mind map is a session in which your AI agent asks rounds of questions and turns your answers into a specification. You start one with /atn-mindmap, and it ends with a specification in the status Prepared.
To decompose a specification is to break it down into one level of stages, each a sub-specification of its own. You run /atn-decompose on a specification that is too large for one task, and again on any stage that needs more depth.
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. You run /atn-apply on a prepared specification, and each leaf turns Completed as it is finished.
The other four skills are /atn-settings, which records the workflow settings, /atn-manage, which changes setups from your AI tool, and /atn-todo-enqueue and /atn-todo-dequeue, which add and work through ToDo cards. The Athenode workflow presents the skills in the order you meet them.
Project tokens and the Athenode CLI
A project token is a personal access token that lets the Athenode CLI, and your AI agent through it, act on one project. You create it on the Tokens page of the project, and Athenode shows it once. A token acts as the member who created it, with that member's role.
The Athenode CLI is the athenode command, run as npx @athenode/cli. Its init command asks for the token, connects the current directory to the project and installs a setup there. The connection is stored in .athenode/config.json, which holds the token and stays out of version control.
After the install, your AI tool starts the Athenode MCP server by itself. Through that server your agent reads the tree, writes specifications, records questions and answers, sets statuses and creates ToDo cards. Project tokens covers creating and revoking a token, and the Athenode MCP server page lists what the agent can do through it.
How the parts of Athenode fit together
Suppose you want customers of the web shop to pay by card. That one change passes through every part of Athenode.
- In your AI tool you run
/atn-mindmapwith that sentence. The skill comes from the installed setup. - Your agent searches the specification tree through the Athenode MCP server, using your project token, and proposes to place the new specification under "Payment".
- The agent asks its questions. Each question and your answer is stored on the new specification as you go.
- The agent writes the specification "Card payments" and sets it to Prepared. "Payment" is blocked by "Cart", so the new sub-specification waits for "Cart" as well.
- In the web app, "Card payments" appears in the tree under "Payment", with its questions and answers, while the agent works.
- Once "Cart" is Completed, you run
/atn-applyon "Card payments". The agent records an implementation plan on the leaf, writes the code in your repository and sets the leaf to Completed.
Athenode keeps the specification with its questions, answers, implementation plan and status. Your code and the changes the agent made stay in your repository. What Athenode stores states this in full.
Other parts of an Athenode project
| Part | What it is | Read more |
|---|---|---|
| ToDo card | A ToDo card is a short note of work to do later: a follow-up, tech debt, a bug or an idea | ToDo cards |
| Setup library | The setup library is the shared catalogue of agent setups that projects have published | Setup library |
| Member | A person with access to a project, as its owner, an editor or a viewer. Projects on the Team and Business plans can have more than one member | Invite and manage members |
| Search by meaning | A search that finds specifications by what they say as well as by their words | Search by meaning |
What updates live in the web app
The web app shows changes made by other members or by an AI agent without a reload. While an apply run works, you can keep the Specs page open and watch the statuses change. The web app updates all of the following in this way:
- specifications, their statuses and their blockers;
- the questions and answers of a specification;
- ToDo cards and their open questions;
- agent setups, their files and their skills;
- the project's name, and its removal when the owner deletes the project;
- members and invites;
- project tokens, for the owner and for the member who created the token;
- the status of the project's plan.
The results of a search and the pages of the setup library show the state at the moment you opened them. Search again or reload the page to see later changes.