Back to app

Example Requests

Requests that work, by what you are trying to do — understand a codebase, specify a slice of a rebuild, build, extend, review, recover.

A session takes ordinary sentences. These are examples, not commands and not templates: say what you want the way you would say it to a colleague. The requests under Build, Extend, Review and Recover were sent to a session exactly as written, and the note under each says what the agent did with it. The two that name an expense-approval service are the same kind of request about a made-up system.

They are a supplement to Working with Specifications, which explains the files these requests produce.

Understand an existing codebase#

Bring the code in as reference material, then:

The existing expense-approval service is attached as reference material.
Write an account of what it is and how it works.

The agent reads the material where it sits, beside your repository, and writes the account into your project under docs/. Nothing from the material is copied into your repository.

Worth adding when it matters to you: who will read the account, and what you would consider wrong in it ("say what you ran and what you only read").

Specify one slice of a rebuild#

Specify a rebuild of its approval queue: one screen where a manager sees the
pending claims, opens one, and approves or rejects it with a reason. Keep the
existing approval rules; replace the interface.

Two things make this request work: it names one slice a person can use, and it says what stays and what changes. If you leave the second out, the agent asks — one question at a time, with lettered options — and writes your answers into the specification under Clarifications.

A specification for the whole system in one go is the request to avoid: the document is too large to check, and so is the build that follows it.

Build#

All at once, for a small feature:

Build it.

The agent plans, breaks the work into phases, writes the code and its tests, runs them, and ticks the task list, usually in one turn of a few minutes.

A phase at a time, for anything larger:

Plan the price history feature and break it into tasks. Then commit.
Build phase 1 of the price history feature, then stop and commit.
Build the next phase of the price history feature, then stop and commit.

Each of these can be its own session. Name the feature by its number every time.

Extend what was built#

There are two ways, and they leave different records.

A direct change:

Add a refresh button to the quote lookup that fetches the latest price again
for the symbol on screen.

The agent changes the code and its tests. The specification, the plan and the task list are not touched, so they no longer describe everything the feature does.

A new feature:

Specify a new feature: price alerts on a watchlist. A person sets a price
above or below which they want to be told, and sees which alerts have
triggered.

The agent writes a new specification with its own plan and task list, and the project's record shows the feature beside the others.

Use the first for a small change you would not want a document for. Use the second when someone will later ask what was agreed.

Review a build you are not sure of#

For a report, with nothing changed:

I'm not confident this still matches the specification. Check the build
against it.

For a check that writes down what is missing:

Check the quote lookup feature against its specification with the converge
step.

The agent compares the code with the specification, the plan and the task list, and adds whatever is missing to the task list as new tasks under a phase of their own. It changes no code. Read what it added, then:

Do the tasks it added.
In a project with several features, read the added tasks first

The check compares the whole codebase with one feature's documents, so it may list another feature's code as something this specification never asked for. Say which tasks to leave: "Do the tasks it added, except T021. The other features are meant to be there."

Recover#

The session is not running. The page says so and offers Resume.

A command is stuck. Use Stop, then say what you saw.

Something that was working stopped:

The preview stopped responding. Find out why and bring it back.

A session ended in the middle of the work. Open a new one and say where to carry on:

Carry on with the watchlists feature where it stopped. Do the next three
tasks, mark them done, then stop.

The new session reads the task list and the files, finds what was already written, and continues from the first task that is not ticked.

Working across sessions#

  • Name the feature by its number. Amira Spec keeps track of one current feature per project, the last one specified, and a new session's plan, build and check steps apply to that one. A description is not always enough: asked to "plan the temperature converter feature", an agent planned the current feature instead. "Plan feature 001, the temperature converter" planned the right one. The number is the start of the feature's name in Progress and Governance.
  • Commit what you want kept in the history. "Commit." works. So does "Commit only the quote lookup work." when another session has changes of its own in the same project.
  • Several sessions can be open at once. They share the files. Progress shows where each feature's task list stands, and Governance shows what has been committed.