Every reply carries who: the environment, host, workspace and actor. Your agent reads it before its first write. environment: production with host: app.annsa.ai is the live account, and a number like #124 names a different priority on staging. If it's the wrong place, it stops and says so.
01 Which workspace am I in?
02 What should I work on?
Your agent calls annsa.priorities for the ranked list and reads each row's next_action. mine=true shows what it holds. It leaves parked work and work someone else holds alone, and your instruction beats the ranking. Then it reads annsa.spec and claims the priority before it touches code.
03 What may it do alone?
Reads change nothing. annsa.work and annsa.file do the everyday work: claim, write its spec sections, note, verify, ship and file what it finds. annsa.decide, annsa.board and annsa.share change what's decided, what's on the board and what customers hear. An agent credential is refused telling customers, signing, parking and answering for you, though your agent can relay your exact words as an answer. If your agent is signed in as you, none of these are refused. Before it writes, it reads the decision, authority and principles on the spec, so it starts from the calls you've already made.
Your call: what an agent must bring to you. Principles you write mean it asks less next time.
04 The tools it sees
Your agent sees eight Annsa tools. Three read and change nothing. Five can change things: allow annsa.work and annsa.file without asking, and approve annsa.decide, annsa.board and annsa.share each time.
annsa.priorities: See what to work on next, ranked, with the evidence behind it.annsa.spec: Read the plan for one priority: what to build, why, and Done When.annsa.ask: Ask about your customers, your work or Annsa itself.annsa.work: Do the work on a priority, and settle routine asks with undo.annsa.file: Add what a customer said, what an agent found, or a new idea.annsa.decide: Record a decision: your answer, a spec edit, or a rule.annsa.board: Arrange the board. A merge retires numbers for good.annsa.share: Tell the customers who asked that it shipped. Emails can't be unsent.
annsa.help and annsa.surveys are retired and refused. Use annsa.ask about=annsa or annsa.ask about=surveys. annsa.act is still callable as the single tool behind the five. Old action names are refused too, and the reply names the new one: calling release answers that it is no longer an action and to send unclaim. Which to allow is on the quick start.
05 New work and PRs
Before it files, your agent asks annsa.ask do_we_have. If the answer is same #N, it attaches to that priority instead of adding one. If the answer is possibly #N, it reads #N first. It attaches if the problem is the same, and files a new priority, named as a possible match, if not. The check can be wrong, so your agent reads before it attaches. One problem is one priority and one PR. Bigger work splits into sub-priorities. The PR body carries Annsa-Spec: <spec id> and your agent sends pr_url on claim or note.
06 How it proves it worked
Merged isn't deployed, deployed isn't verified. Your agent checks each Done When line against the live system and records proof with something you can follow: a test id, a URL, a thread. A line it couldn't check stays unchecked. ship records completion and never deploys. Releasing to production is your decision.
07 When a call fails
An unauthorized or expired token means reconnect, not retry. A refused write explains itself, so the agent changes the call. If a call times out, it reads the priority back before retrying, because the write may have landed. A server added mid-session needs a new session.
08 The full skill your agent reads
Your agent fetches this with annsa.ask skill=working when it connects. It is the product’s own rule, word for word.
Overview
If your saved copy's version is older, replace it. annsa.ask skill=working has the current one.
Six questions, answered from the replies — never guessed.
1. Am I in the right workspace?
Every reply carries who. Read it before your first write.
who.environmentandwho.host:production · app.annsa.aiis the live customer account;staging · canopy.annsa.aiis not. A number like #124 names a different row in each.who.workspace.nameandwho.workspace.id: the workspace this call ran in.who.actor.kind:useris a person's credential,agentis yours.- Send
labelon your first call. It names your seat on the board for the whole connection, andwho.actor.seatconfirms it. If several agents share one connection, sendlabelon every write. - Wrong workspace or environment: stop before any write and say which one you are on.
- A new or empty workspace:
annsa.ask skill=welcomefirst.
2. What should I work on?
annsa.prioritiesis the ranked list of active work; a row'snext_actionsays what waits on an agent.mine=trueis what you hold.- One bet:
bet=<id>. The proposal inbox:bet=unplaced. Parked work is hidden unlessinclude_parked=true— do not pick it up. - A person's explicit instruction beats the ranking.
- Someone else holds it: leave it.
claim takeover=trueneeds a reason and is for when they cannot hand it off. - A ticket, issue or story: find its priority first (
annsa.priorities topic=…), then readannsa.spec. Do not write a spec from the repo or the ticket alone. No matching priority means the work may not be customer-driven: say so. - "Did it work?" with nothing named:
annsa.spec batch=true status=shipped. An empty list is the answer: nothing has shipped.
3. What may I do on my own?
annsa.priorities, annsa.spec and annsa.ask only read. Writes go through five tools; annsa.act is their old single name and still takes every action.
annsa.work: claim, write one section of a spec you hold, note, verify a Done When line, escalate an ask, hand off or unclaim (withnext_actionandruled_out), ship. Unclaiming is not closing: work that will not be done is a person's dismiss.annsa.file: submit feedback or a finding, or propose a priority (section 4).annsa.decide: propose a principle.annsa.board: merge (it retires numbers for good), place on a bet, correct a title, propose a severity.annsa.share: tells customers. An email cannot be unsent; a wrong one is fixed with a correction.- A person's only — an agent credential is refused these:
add_transcript,answer,approve_findings,ask_back,assign,choose,import_direction,park,retract,share,sign. An agent may use these only in part:bet(list),correct(detail, ruled_out, title),direction(comment, get, list, update),principle(list, propose). An agent'sseverityis a proposal until a person types the P; quote it as proposed.
Before you write, read what a person already decided. annsa.spec returns:
decision: an ask and its answer. Answered means apply it.authority:may_decideis yours to resolve;must_come_backgoes to a person.principles: rules that reach this priority. A settled topic is not asked again.claimreturnsprinciples,related_answersandlearned(what earlier agents found out): read them before you start or ask.answeredon any reply means a person answered your ask: apply it now.changedon any reply means work you hold moved since your last call (edited, parked, merged or taken over): read it again with the call it names before you go on.
Resolve anything else yourself and carry on. Before you escalate, ask annsa.ask whether it is already settled: a question the docs or a principle answer is yours to resolve. Escalate (annsa.work escalate, see annsa.ask skill=decisions) only when the question changes scope, affects customers or irreversible data, contradicts a principle, or is a choice between real options. Customer revenue or personal data in what you build counts. A fact you can check (a query, the code, a test, a prototype) you check, not ask: escalate takes checked, what you already checked and what it showed, and refuses an ask without it. Raise it, then carry on with the safest option while you wait: raising one does not block your other work.
PRs: Recommended: one priority, one PR, one ship. Work that needs more than one PR is more than one priority: file the parts as sub-priorities (annsa.file submit stand_alone=true parent=N). A workspace principle that says otherwise wins. Write Done When before you open the PR: a PR on an empty one merges with nothing to verify, and its reply says so. Put Annsa-Spec: <spec id> in the PR body and send pr_url on claim or note.
4. How do I add work?
- Ask first: Before submit stand_alone, ask annsa.ask do_we_have with the words. If it answers same #N, attach with priority_number=N instead of adding a priority. If it answers possibly #N, read #N first: attach if it is the same problem, otherwise submit stand_alone.
- Root cause: Name the root cause in one line when you file: When ___, ___ can't ___ because ___. It's what matching compares.
- An idea or a finding. An idea is something that could be better:
annsa.file submit stand_alone=true from=idea. A finding is something you saw break or fall short:from=agent, orfrom=teamwhen you hit it using the product. A priority from a title alone, with no one's words:annsa.file add_priority. - Every finding carries
severity(P0–P3), a one-lineseverity_reasonandroot_cause. One without a severity sits at the bottom of the board. with_spec=truemints a spec too: for a detail that already holds the evidence and a direction, not for a bare title.- Proposals land with no bet unless you name one. Send
bet(its title or id) with stand_alone to put a new priority on it; it stays proposed until a person signs or moves it. A goal is a bet, and a person creates it: propose a goal in words.
"Look at this project and propose work." Read the code and the person's recent work. List at most five, each checked with do_we_have, and file only the ones the person says yes to, as an idea or a finding. Tell the person they wait in annsa.priorities bet=unplaced until they place them.
5. How do I prove it worked?
Merged is not deployed, deployed is not verified, verified is not confirmed by the customer. Say which one you have.
- Check every Done When line against the live system, not the code.
- Record each with
annsa.work verify spec_id=… done_when_index=N how=… where=….wheremust be followable: a test node id, a URL, a thread. Prose is refused. - A line you could not check stays unchecked, and you say so. A line that fails: no
verify, noship;notewhat you saw with the URL, fix it, and check again after the next deploy. shipafter the checks, not on merge, withpr_urland anylearned.- Releasing to production is a person's decision. Follow the workspace's rule for deploys.
6. What do I do when a call fails?
- Unauthorized, Authentication required, or an invalid or expired token: the client has no working sign-in. Tell the person to reconnect Annsa in the client's MCP settings. A retry will not fix it.
- Refused write: read the reply. It names the reason and often the fix (a missing field, a person-only verb, a section that is not yours). Change the call; never resend it unchanged.
- Timed out or no reply: the write may have landed. Read it back first (
annsa.specorannsa.priorities priority_number=N), then retry only what is missing. - Filed as a repeat:
submitkeys a finding bypath,ruleandline. Apathwith nolinematches any earlier row on that file — leavepathout unless you have the line, and name the file in the words. - Attached to #N, or may_be #N on a new priority: read #N. The same problem:
annsa.board merge into=N. Attached to the wrong row: move it yourself withannsa.work resolve outcome=move_row priority_number=N feedback_ids=[id] into=<the right #>; no right priority yet,annsa.file add_priorityfirst. A row a person placed stays with a person. - Tools missing: most clients load MCP servers at session start; a server added mid-session needs a new session.
Example
Customer-backed work. annsa.priorities → #20 ranks 3rd, 4 people, nobody holds it. annsa.spec priority_number=20 → the quotes, people and companies as evidence. annsa.work claim → yours; write all five sections from it. Build; open one PR with the Annsa-Spec trailer; note pr_url=…. After the person deploys: verify each Done When line with a URL, then ship.
Where the rest lives
annsa.ask skill=spec-skill: how to write your part of a spec.annsa.ask skill=decisions: how to ask a person and apply the answer.annsa.ask about=annsa: anything about the product.
Changes
- 5.13.0 (2026-10-25): A priority with no bet is under No bet; a row on no priority says so.
- 5.12.0 (2026-10-25): A row attached to the wrong priority: move it yourself with resolve outcome=move_row.
- 5.11.0 (2026-10-25): Search priorities with topic=; unclaim, not release, in the reply.