---
title: "Working with Annsa | Annsa Docs"
product: annsa
url: /docs/working-with-annsa
canonical_url: "https://annsa.ai/docs/working-with-annsa"
last_updated: 2026-11-22
type: doc
related:
  - /docs/working-from-your-terminal
  - /agents
summary: "The skill your agent reads when it connects, in plain words: pick the work, what it may do alone, prove it shipped and recover from a failed call."
mcp_server: https://app.annsa.ai/mcp
disambiguation: "Annsa (annsa.ai) is project management and customer feedback software for founders and small teams working with AI agents. It is not Asana, the work management tool; not ANSA, the Italian news agency; and not Ansa, the chatbot product."
---

> For agents: connect to the Annsa MCP server at https://app.annsa.ai/mcp to give every agent one shared plan. Setup guide: https://annsa.ai/docs/quick-start. Index of every page: https://annsa.ai/llms.txt.

# Working with Annsa | Annsa Docs

> The skill your agent reads when it connects, in plain words: pick the work, what it may do alone, prove it shipped and recover from a failed call.

[Docs / Agents](https://annsa.ai/docs)

The skill every agent fetches when it connects, in human words, with the full text below.

## 01 Which workspace am I in?

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.

## 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](https://annsa.ai/docs/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.environment` and `who.host`: `production · app.annsa.ai` is the live customer account; `staging · canopy.annsa.ai` is not. A number like #124 names a different row in each.
- `who.workspace.name` and `who.workspace.id`: the workspace this call ran in.
- `who.actor.kind`: `user` is a person's credential, `agent` is yours.
- Send `label` on your first call. It names your seat on the board for the whole connection, and `who.actor.seat` confirms it. If several agents share one connection, send `label` on 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=welcome` first.

**2. What should I work on?**

- `annsa.priorities` is the ranked list of active work; a row's `next_action` says what waits on an agent. `mine=true` is what you hold.
- One bet: `bet=<id>`. The proposal inbox: `bet=unplaced`. Parked work is hidden unless `include_parked=true` — do not pick it up.
- A person's explicit instruction beats the ranking.
- Someone else holds it: leave it. `claim takeover=true` needs a reason and is for when they cannot hand it off.
- A ticket, issue or story: find its priority first (`annsa.priorities topic=…`), then read `annsa.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 (with `next_action` and `ruled_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's `severity` is 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_decide` is yours to resolve; `must_come_back` goes to a person.
- `principles`: rules that reach this priority. A settled topic is not asked again.
- `claim` returns `principles`, `related_answers` and `learned` (what earlier agents found out): read them before you start or ask. `answered` on any reply means a person answered your ask: apply it now. `changed` on 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`, or `from=team` when 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-line `severity_reason` and `root_cause`. One without a severity sits at the bottom of the board.
- `with_spec=true` mints 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=…`. `where` must 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`, no `ship`; `note` what you saw with the URL, fix it, and check again after the next deploy.
- `ship` after the checks, not on merge, with `pr_url` and any `learned`.
- 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.spec` or `annsa.priorities priority_number=N`), then retry only what is missing.
- **Filed as a repeat:** `submit` keys a finding by `path`, `rule` and `line`. A `path` with no `line` matches any earlier row on that file — leave `path` out 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 with `annsa.work resolve outcome=move_row priority_number=N feedback_ids=[id] into=<the right #>`; no right priority yet, `annsa.file add_priority` first. 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.
- [Writing a spec](https://annsa.ai/docs/writing-a-spec)

## Keep reading

- [](https://annsa.ai/docs/working-from-your-terminal)
- [Every agent works from the same plan.](https://annsa.ai/agents)

## Related pages

> For AI agents: the pages that follow this one on annsa.ai. The full index is https://annsa.ai/llms.txt.

- [Working from your terminal](https://annsa.ai/docs/working-from-your-terminal)
- [AI agent platform: one plan for every agent](https://annsa.ai/agents)

If anything on this page is wrong or missing, tell us: https://annsa.ai/contact
