/atn-apply: implement a prepared specification
/atn-apply implements a Prepared specification, or every leaf under it, in your repository. It plans each leaf, writes the code and the tests, reviews the result and handles git as your workflow settings say. Run it when a specification has been shaped with /atn-mindmap and, for larger work, broken into stages with /atn-decompose.
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 leaf specification is a specification with no sub-specifications. A blocker is a dependency between two specifications: a specification that is blocked by another is implemented after it.
An apply run works on its own and stops only when something falls outside the specification and needs you.
Run /atn-apply
/atn-apply <spec-id-or-title>| Argument | Description |
|---|---|
<spec-id-or-title> |
The id of the specification to apply, or its title or part of it. Required. |
The specification you name is the root of the run. A root with sub-specifications is applied leaf by leaf. A root without sub-specifications is itself the one leaf, which is how a small change goes from the mind map straight to code.
A title is looked up in your project. One match starts the run. If nothing matches, or several specifications match, the skill reports that, lists the candidates with their ids and stops, and you run it again with an id.
/atn-apply Checkout flowIn the web app, a Prepared specification offers Copy apply command, which copies the command with the id filled in. The page on specifications in the web app shows where to find it.
The skill follows the workflow settings you chose with /atn-settings. A category that has no settings is left out of the run and named in the report.
What /atn-apply does
- Finds the root specification from the id or the title.
- Works out the order of the run from the blockers. The run takes the leaves under the root that are Prepared or Processing. A leaf comes after every leaf that blocks it.
- Checks that the run can start. It stops, without changing a status, when the blockers form a cycle or when nothing under the root is Prepared. It asks you when a specification outside the root blocks some of the leaves.
- Sets the root to Processing and creates branches as your gitflow settings say.
- Plans the first leaf. The agent checks the leaf against your codebase and records an implementation plan, which you can read on the leaf's Plan tab in the web app. The leaf turns Processing.
- Implements the leaf from its plan, writing and running tests as your testing and methodology settings say.
- Commits and reviews the leaf at the moments your gitflow and code review settings name, then repeats steps 5 to 7 for each following leaf, one at a time.
- Runs the review at the end of the run, if your settings ask for one, and sets each leaf that passed to Completed. A parent turns Completed when everything under it is Completed, and the root follows when the whole run succeeded.
- Finishes the git work: the commit at the end of the run, tags, the push and the pull request, each only if your settings ask for it.
- Asks which of the out-of-scope items the agents noticed should become ToDo cards, then reports.
One apply run implements its leaves one at a time. Several apply runs can work at the same time in separate sessions or on separate branches, each on its own specification.
Which leaves run and which are skipped
A Draft leaf is not part of the run. A leaf that is blocked by a specification inside the root which is not Prepared, such as a Draft stage, is skipped, and the report says which blocker held it back.
When a leaf is skipped or fails, every later leaf that it blocks, directly or through other leaves, is skipped too. The remaining leaves run.
Blockers decide the order of implementation. With one review at the end of the run, a leaf is implemented before the leaves that block it have been reviewed.
Tests during an apply run
The agent that implements a leaf writes the tests your settings ask for and runs the tests that cover the changed code, using the test commands it finds in your project. When tests fail, it fixes the cause and runs them again, up to the number of attempts in your settings, which is 5 by default. If they keep failing after the last attempt, the run asks you what to do with that leaf. With the setting "no tests", no test is written or run.
Review during an apply run
When and how the review runs follows your code review settings:
| Setting | What the run does |
|---|---|
| No code review | A leaf turns Completed as soon as it is implemented and its tests pass. |
| Each specification right after it is implemented | Each leaf is reviewed on its own and turns Completed when the review passes. |
| One review at the end of the run | All implemented leaves are reviewed together after the last one, including how their code fits together. |
| Both | Each leaf is reviewed on its own, and a second review at the end checks how the leaves fit together when at least two were completed. |
The review compares the code with the leaf's specification and runs the check groups you enabled, together with the rules in the ## Custom sections of your settings files. Findings are fixed automatically and the code is reviewed again, for up to the number of fix rounds in your settings, which is 3 by default. Findings that are open after the last round, and findings that need a product decision, are put to you.
What /atn-apply does with git
Every git step follows the gitflow settings, and a run changes your repository's history only at the points in this table. With the settings "no new branches", "never commit", "no tags" and "do not push", the run leaves all its changes uncommitted in your working tree.
| Setting | Choice | What the run does |
|---|---|---|
| Branches | No new branches | Works on the branch that is checked out. |
| Branches | One per apply run | Creates one branch before the first leaf, named from your branch template and the root's title, starting from your base branch. |
| Branches | One per implemented specification | Creates a branch before each leaf, named from the leaf's title. The first starts from the base branch and each later one from the branch of the leaf before it, so a leaf sees the code of the earlier leaves. |
| Commits | Never | Leaves the changes in the working tree. |
| Commits | After each implemented specification | Commits a leaf when it is implemented. Fixes made after a review go into a follow-up commit with the summary "address review findings for" and the leaf's title. |
| Commits | Only after the code review approves | Commits a leaf when its review has passed. |
| Commits | One commit at the end of the run | Makes one commit per repository that carries the root's id and title, with each included leaf in the body. |
| Tags | No tags | Creates no tag. |
| Tags | When the top specification is completed | Creates one annotated tag when the root reached Completed. |
| Tags | Automatic version tag | Raises the latest version tag by the kind of change in the commits since it, when the root reached Completed. |
| End of run | Do not push | Leaves the branches and commits local. |
| End of run | Push | Pushes the branch the run ended on to origin. |
| End of run | Push and open a pull request | Pushes, then opens one pull request per repository into the base branch. |
Branches an apply run creates
A branch name is your branch template with <slug> replaced by the title in lowercase, with hyphens for everything other than letters and digits, cut to 50 characters. With the default template, the root "Checkout flow" gives feature/checkout-flow.
Before the run creates a branch, it checks for uncommitted changes and for a branch of the same name, and asks you in either case. At the end of the run it deletes each branch it created that holds no change and switches back to the branch you were on. It does not delete a branch that existed before the run.
Commits an apply run makes
A commit holds the files the leaf changed and nothing else. A file that had uncommitted changes before the leaf started is left out of the leaf's commit. If a commit contains a file that had uncommitted changes before the run, the report marks it.
The commit message comes from your commit template. With the default template, a leaf "Cart" in a repository directory named web-shop gives the message feat(web-shop): cart [spec <spec-id>], where the id is the leaf's. The type is feat unless the leaf is a fix, documentation, tests, a refactoring or a chore, and it is marked as a breaking change only when the specification describes one. The scope is the name of the sub-project the files belong to, or of the repository's directory. The summary is the leaf's title.
Tags an apply run creates
A tag is created only when the root reached Completed, and only in a repository the run committed to. The tag for a completed root is your tag prefix followed by the root's title as a slug. When the prefix is a version prefix such as v, the tag is named spec/ and the slug, as in spec/checkout-flow. If the name is taken, the run adds a numeric suffix. The automatic version tag takes the latest version tag on the branch and raises the major version for a breaking change, the minor version for a feature and the patch version for a fix. The first version tag in a repository is 0.1.0 with your prefix. When no commit since the latest tag is a feature, a fix or a breaking change, no tag is created.
Push and pull request at the end of a run
The run pushes each repository it committed to. A pull request is opened with gh, or with glab when the remote is on GitLab, so the tool for your host must be installed and signed in. The pull request has the root's title and lists the root and every implemented leaf. With one branch per implemented specification, the pull request is opened for the last leaf's branch, and the report lists the other branches.
A failed push or pull request does not fail the run. The run records it and carries on. When any other git command fails, the run stops using git in that repository, says why in the report and continues the implementation there without git.
Several repositories in one apply run
When your workflow settings list sub-projects that are git repositories of their own, the run treats each repository separately. Each one follows its own gitflow settings, gets its own branches, commits, tags and pull request, and is committed to only when a leaf changed files in it.
Questions /atn-apply asks
| When | What you are shown | Options |
|---|---|---|
| Before the run starts, when specifications outside the root block some leaves | Each outside blocker with its title, id, status and place in the tree, and the leaves it blocks | "Stop" or "Run only the leaves not blocked by external blockers" |
| A branch is about to be created and the repository has uncommitted changes | The changed paths | "Commit them first", "Stash them", "Carry them over onto the new branch" or "Abort git operations for this repository" |
| The name of a branch to create is taken | The name | "Reuse it", or create the branch with a numeric suffix such as -2 |
| A leaf cannot be planned because the codebase does not allow it as specified | What blocks it and, where it is evident, what would resolve it | "Provide a resolution", "Skip this leaf" or "Stop the run" |
| Tests keep failing after the allowed attempts | The failing tests, the command and the last output | "Retry", "Skip" or "Stop" |
| Review findings are open after the automatic fix rounds | The open findings of one leaf | "Retry", "Accept as is", "Skip" or "Stop" |
| A review finding needs a product decision | The finding and the change the reviewer proposes | "Apply the proposed change", "Drop this finding", "Skip" or "Stop", or a resolution you type |
A pull request is due and gh or glab is missing or not signed in |
The repository | "Retry after fixing", "Push only (skip the PR)" or "Skip this repository" |
| At the very end, when the agents noticed out-of-scope work | Each item with a title, a description, a type and a priority | Any number of the items, as a multiple-choice list |
What each answer does
- "Run only the leaves not blocked by external blockers" skips the blocked leaves. When an outside specification blocks the root itself, every leaf is blocked and nothing runs.
- "Commit them first" commits your uncommitted changes on the current branch with a message that starts with
chore: wip before. "Carry them over onto the new branch" leaves them uncommitted and does not ask about them again. - "Provide a resolution" takes your text as a decision, and the leaf is planned again with it.
- "Retry" after failing tests gives the leaf another run of attempts. "Retry" after open findings runs the same number of fix rounds again.
- "Accept as is" sets the leaf to Completed with its findings open, and the report lists them.
- "Skip" leaves the leaf Processing and goes on with the next leaf. A leaf skipped after failing tests is not committed.
- "Stop" ends the implementation of further leaves. The run then finishes: the git work at the end of the run is done as your settings say, and the remaining leaves are reported as not processed.
A run that another skill started with --auto-apply asks the same questions.
What /atn-apply changes
| Where | What changes |
|---|---|
| Statuses | The root turns Processing at the start. Each leaf turns Processing when it is planned and Completed when it is implemented and has passed the review your settings ask for. A parent turns Completed when everything under it is Completed. The root turns Completed when every leaf of the run did. |
| The implementation plan | Each leaf gets a plan with the scope, the affected sub-projects, the files to create or change and the approach. Planning a leaf again replaces its plan. |
| Your repository | Code and tests in the working tree, and the branches, commits, tags and pushes your gitflow settings ask for. |
| Your code host | A pull request per repository, if your settings ask for one. |
| ToDo cards | One card for each out-of-scope item you select at the end. |
A leaf that failed, was skipped or was left with open findings stays Processing, and the root stays Processing with it. To resume, fix what stopped the leaf and run /atn-apply on the same root again. The run takes the leaves that are Prepared or Processing, plans them again and leaves the Completed ones as they are.
The web app shows the statuses as they change, in the Tree and Orbit views. Athenode keeps the plans and the statuses. The code, the list of changed files and the commits exist only in your repository.
ToDo cards from a run
A ToDo card is a short note of work to do later: a follow-up, tech debt, a bug or an idea. While they plan, implement and review, the agents note work that lies outside the specifications of the run. The skill collects those items and, as its last step, drops each one that an open card covers and asks you which of the others become ToDo cards. You can select several, all or none.
Each card is created open, with a type, a priority and a link to the specification it came from, shown under From in the web app. A card carries up to 3 open questions when it cannot be carried out without a decision only you can make. A problem inside the run, such as a failing test or an open review finding, does not become a card. It stays with its leaf and appears in the report.
The question is asked in every run that got as far as implementing a leaf, whatever the outcome. If the project has reached its plan's limit of ToDo cards, the item is not created and the report says so.
The report
The report covers:
- every leaf of the run in order, with the files it touched and its outcome: completed after review, completed without review, accepted with open findings, skipped, failed tests or not processed;
- whether the root was set to Completed or left Processing, and why;
- every question the run asked and the answer you chose;
- the dependencies that shaped the run, each written as "Payment is blocked by Cart": a cycle, blockers that were not Prepared, outside blockers and the leaves skipped because of them, and the parents that were completed;
- per repository, the branches, commits, tags, pushes and pull requests, the git steps that were skipped with their reasons, and the uncommitted changes left behind;
- the ToDo cards created, with type, priority and origin, and the items skipped as duplicates, declined or not created;
- any workflow settings that were missing.