Working with Specifications
How a session turns a request into a specification, a plan, tasks and working code — and how to carry the work across sessions.
A session is a coding agent working in your project's folder. You talk to it; it reads and writes files. The specification is not a form and not a record Amira keeps — it is Markdown files in your project, which is why a session tomorrow can pick up where one today left off.
Amira tracks no stages and holds no lock. What moves the work forward is the files. The method that writes them is Amira Spec, built on the open-source GitHub Spec Kit, which the agent sets up in your project the first time you ask for something.
Start with one message#
Create a project, then either start from scratch or bring in existing code — a repository, an archive or a folder. Below that, add as much reference material as you like: files, ZIP archives and folders. The two are kept apart:
The project's code becomes the repository the agent builds in. Reference material sits beside that repository for the agent to read, and is not tracked by Git. Studying an existing system or specifying a replacement wants reference material — the original stays untouched while the new work is committed.
Then open a session and describe what you want. Two things are worth saying in that first message, because the agent will otherwise have to ask or assume:
- how big the piece is — one feature a person can use, not the whole system;
- what stays and what changes, when you are rebuilding something that exists.
A request that starts from an existing system looks like this:
The existing expense-approval service is attached as reference material.
Write an account of what it is and how it works, and specify a rebuild of its
approval queue: keep the approval rules, replace the interface.A request for something new looks like this:
I want a small first feature for this project: a quote lookup that shows the
latest price for one stock symbol. Specify it.More examples, by what you are trying to do, are in Example Requests.
What the session then does#
On the first request it installs the specification workflow into your project and writes the project's working principles. You never type a command; the files it creates are yours.
A numbered directory under specs/ with the specification and a
requirements checklist. Where it read reference material, the
specification lists what it consulted.
When something that changes the build is open, it asks — usually one question at a time, with lettered options. Answer with a letter or a sentence. Your answers are written into the specification under Clarifications. When nothing is open, it asks nothing.
When you ask for a plan or say "build it": a plan, the choices it made and why, and a task list grouped into phases.
It writes the code and its tests, runs them, and marks each task done in the task list.
Seeing where it stands#
Two views beside the conversation read those files for you:
- Progress shows the steps the feature has been through, the phases of its task list with what is ticked, what is not committed yet, and one line saying what you can do next.
- Governance shows every feature in the project, what has been committed, by whom and when, and opens any document in place.
Neither one holds anything up. They show what the files say.
A specification shipped with three known unknowns is a decision you made. The same document with those gaps hidden inside confident prose is the problem. Open questions stay marked in the specification until someone answers them.
What you end up with#
| File | What it is |
|---|---|
.specify/memory/constitution.md | The working principles every feature is held to |
specs/<number>-<name>/spec.md | The specification of one feature, with your answers under Clarifications |
specs/<number>-<name>/plan.md, research.md, data-model.md, contracts/, quickstart.md | The plan, the choices behind it, and how to check the result |
specs/<number>-<name>/tasks.md | The list of work, in phases, ticked as it is done |
docs/ | Anything else you asked to have written, such as an account of an existing system |
Then build from it#
All at once:
Build it.Or a phase at a time, which is easier to follow on a larger feature:
Plan the price history feature and break it into tasks. Then commit.Build phase 1 of the price history feature, then stop and commit.When to open a new session#
Whenever you want to — and you never have to in order to make progress. One session can take a request all the way from a sentence to passing tests.
Open a new one when the conversation has grown long, when you want a clean read of the files, when you want a second feature worked in parallel, or when you come back tomorrow. Sessions are siblings: several can be open on one project at once, they share the workspace, and files are how they hand work over.
Amira Spec keeps track of one current feature per project: the last one specified. A new session's plan, build and check steps apply to that feature unless you name another, and a description is not always enough to move it. Say the number — "continue feature 003, the watchlists" — whenever the project has more than one. Progress shows which feature Amira Spec is on. A session that is already working on a feature carries on with it.
The agent sometimes commits as it goes and sometimes does not. Say "Commit." when you want the work in the project's history; Progress shows what is not committed yet. A later session, and Governance, read the commits.
Where the phases are#
In the task list, not in Amira. tasks.md is ordered in phases, with setup
and foundational work before the user stories. The agent walks those itself.
You do not advance a stage, and nothing waits on an approval.
Bringing in your own documents and systems#
Reference material can be a repository, an archive, a folder, PDFs, or plain documents; the agent reads them with ordinary tools. Evidence is read from that material and written into your repository — the material itself is never pulled into your project's Git history.
Where the work needs an external system, the specification records the environment variable names it expects. The values live in the project's Settings and reach the agent that way.