The Athenode workflow
The Athenode workflow is the sequence of skills your AI coding agent runs to take a piece of work from a first description to implemented code. 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. You run /atn-settings once, then /atn-mindmap for each piece of work, /atn-decompose when the work is large, and /atn-apply to have it built.
The skills are part of the standard Athenode setup. They are available in your AI coding tool after you install the setup in your repository and restart the tool. The quickstart takes you through a first run, and the guide to spec-driven development explains the method the workflow follows.
What the workflow works on
A specification is one described piece of work, with a title, a summary, Markdown content, a status and its own questions and answers. The workflow creates specifications, deepens them and implements them.
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, so a small change is one leaf and a whole application is a tree with many.
A blocker is a dependency between two specifications: a specification that is blocked by another is implemented after it. The skills set blockers from their own research into your tree, and an apply run reads them to decide its order. The page on specifications covers statuses, blockers and the tree in full.
The skills in the order you meet them
Workflow settings are your project's choices for how agents test, review and use git. /atn-settings asks for them once, after the install, and you can run it again whenever a choice should change. The other skills read the settings each time they run.
A mind map is a session in which your AI agent asks rounds of questions and turns your answers into a specification. /atn-mindmap researches your tree and your codebase first, then asks about what you have not decided, and you choose the topic of each next round. A mind map works at any scale, and a small change needs nothing more before it is applied.
To decompose a specification is to break it down into one level of stages, each a sub-specification of its own. /atn-decompose creates the stages, asks the open questions of each one and links them in build order. You decompose a stage again to go a level deeper, and you stop where a leaf is small enough for an agent to finish in one go.
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. /atn-apply runs on its own and stops only when something falls outside the specification and needs you.
| Skill | What it needs | What it produces |
|---|---|---|
/atn-settings |
A repository with the setup installed | The project's workflow settings for testing, methodology, code review and gitflow |
/atn-mindmap |
A subject in your own words, an existing specification or a ToDo card | One Prepared specification with its questions and answers and its blockers |
/atn-decompose |
A specification to break down | One level of Prepared stages under it, with the blockers that order them |
/atn-apply |
A Prepared specification, with or without sub-specifications | Code in your repository, an implementation plan on each leaf and Completed statuses |
An example from idea to code
A web shop needs a checkout. You run /atn-mindmap Checkout flow for the web shop, confirm where the specification goes in the tree and answer rounds of questions about scope, guest orders, taxes and failed payments. The skill writes the specification "Checkout flow" and sets it to Prepared.
"Checkout flow" is too large to build in one go, so you choose "Decompose into stages". The skill proposes the stages "Cart", "Payment" and "Shipping", you confirm them and answer the questions of each stage. The three stages become Prepared, with "Payment" blocked by "Cart".
You then choose "Apply now". The apply run plans and implements "Cart" before "Payment", takes "Shipping" in its turn, and reviews and commits as your settings say. Each stage turns Completed as it finishes, and "Checkout flow" turns Completed after the last one.
How statuses move through the workflow
A specification has one of four statuses: Draft, Prepared, Processing or Completed. The skills set them as they work, and the Tree and Orbit views of the web app show each change without a reload.
| Moment | Status |
|---|---|
/atn-mindmap creates the specification before its first round |
Draft |
/atn-mindmap has written the specification from your answers |
Prepared |
/atn-decompose creates a stage |
Draft |
/atn-decompose has rewritten the stage from your answers |
Prepared |
/atn-apply starts on the specification you named, and later on each leaf |
Processing |
| A leaf is implemented and has passed the review your settings ask for | Completed |
| Every specification under a parent is Completed | The parent turns Completed |
A leaf that failed or that you skipped during an apply run stays Processing, and so does every specification above it. Running /atn-apply again on the same specification picks up the leaves that are Prepared or Processing and leaves the Completed ones alone.
Blockers decide the order of an apply run and nothing else. You can set any status by hand in the web app at any time.
How the automation flags join the steps
The mind map and the decomposition each end with a question about the next step. The mind map offers "Apply now", "Decompose into stages" and "Nothing else". The decomposition offers "Apply now", "Decompose a stage further" and "Nothing else". An automation flag answers that question in advance, so one command carries the work through several steps.
| Command | What follows without the next-step question |
|---|---|
/atn-mindmap --auto-apply |
An apply run on the specification the mind map prepared |
/atn-mindmap --auto-decompose |
A decomposition into the stages the skill proposes, created without asking you to confirm the list |
/atn-mindmap --auto-decompose --auto-apply |
The decomposition, then one apply run on the specification and its stages |
/atn-decompose <spec-id> --auto-apply |
One apply run on the decomposed specification, after every stage is Prepared |
The flags remove the next-step question and leave every other question in place. You answer the mind map's rounds, the questions of each stage and whatever the apply run needs to ask.
How to run a skill in your AI tool
In an AI tool with slash commands you run a skill in its slash form, such as /atn-apply <spec-id>. In the others you ask the agent in plain words to use the skill by its name. init prints the form for each AI tool you selected, and the page on supported AI tools lists it for every tool.
The web app gives you the next command for a specification, with its id filled in: the mind-map command for a Draft, the decompose and apply commands for a Prepared one. Copy it from the specification and paste it into your AI tool.
Before the first skill of a session runs, your agent checks whether the workflow settings have been chosen. If they have not, it asks once and offers "Run atn-settings now (Recommended)" and "Continue without initializing".
How the skills ask questions
A skill asks through your AI tool's own question interface where the tool has one. Elsewhere it writes each question in bold with lettered options, and you reply with the letters. In both cases the recommended option comes first and is marked "(Recommended)", and you can type an answer of your own in place of any option. A skill asks at most four questions in one message, then waits.
The skills talk to you in the language you write in. Specifications, questions, answers and implementation plans are stored in English.
What Athenode keeps from a run
Athenode keeps each specification with its questions and answers, its implementation plan, its status and its blockers. You read them in the web app, on the specification's Content, Questions & answers and Plan tabs. Your code, your branches and your commits stay in your repository. The page on what Athenode stores has the full account.
Work that falls outside a specification
A ToDo card is a short note of work to do later: a follow-up, tech debt, a bug or an idea. At the end of an apply run the skill lists the out-of-scope work the agents noticed and asks which items become ToDo cards. You add a card of your own from a session with /atn-todo-enqueue, and /atn-todo-dequeue works through the open cards, turning each into a specification or carrying it out directly.
The seventh skill of the standard setup, /atn-manage, changes the setup itself and takes no part in building a specification.
Several apply runs at the same time
One apply run implements its leaves one at a time, in dependency order. Several apply runs can work at the same time in separate sessions or on separate branches, each on its own specification. When the leaves of a run are blocked by a specification outside that run, the run asks you first whether to stop or to run only the leaves that are not blocked.
Pages about the workflow
/atn-settings: every question about testing, methodology, code review and gitflow, with its choices and defaults./atn-mindmap: the question rounds, continuing a specification and starting from a ToDo card./atn-decompose: breaking a specification into one level of stages./atn-apply: the order of an apply run, its review, what it does with git and the questions it asks.