Plan work as specs

Write a spec for a piece of work before the code, and Tiden keeps that spec visible to your coding agent until the work is built. When the agent finishes, Tiden shows it the specs nearest to what it wrote and asks how each one relates, so a built card becomes Active and no second spec appears for the same behavior.

This guide uses one card: ANYM-235, "Project guardian assignments", in Backlog.

Who this is for

Teams that write a spec for each piece of work before the code, and run that work with a coding agent through the CLI. You need:

• The CLI authorized and the repository bound to a product. See Set up the CLI.
• The Tiden skills installed for your agent (tiden skill install), so it runs tiden intent start and tiden intent settle in each session.

Plan work as specs

Keep each planned piece of work as a spec in Backlog. Tiden treats a spec in Backlog or in Review as planned: not built yet. You can create a card in the web UI, with tiden spec create, or on a branch with --branch.

tiden spec create \
  --title "Project guardian assignments" \
  --content-file guardian-assignments.md

Before it writes, tiden spec create shows the specs nearest to the new text, planned ones included, up to 3 of them. They come from a search by meaning, in order, with no score. The command stops with exit code 3 and creates nothing until --similar answers every one of them. Each answer names the spec and gives one verdict with one sentence of reason:

tiden spec create \
  --title "Project guardian assignments" \
  --content-file guardian-assignments.md \
  --similar '[{"ref":"ANYM-236","verdict":"sibling","reason":"ANYM-236 covers guardian notifications, this card covers assignment."}]'

The four verdicts are same, part, sibling, and different. If a candidate already describes the behavior, change that spec with tiden spec update instead of creating a second one. spec create prints the answers and does not store them. If Tiden cannot compute the nearest specs, it prints one warning and creates the spec.

What the gate does with planned specs

The Quality Gate does not count a Backlog or Review spec as missing tests, and it shows how many planned specs it left out. A test linked to a planned spec still counts, so a failing one still blocks the gate. When the spec is built it becomes Active, and the gate expects tests for it. See Spec statuses for the full rules.

"In work" is not a status. It is the open session whose objective names the card.

Start work on a card

Name the key when you ask the agent for the work, and tell it to look the card up first. In the lookup, Tiden shows the named spec before anything else:

tiden intent lookup "Implement ANYM-235"

## Named specs (named by key in your text; check each is the spec you meant)
- ANYM-235 Project guardian assignments · planned (Backlog)

The card is marked planned (Backlog). Specs in Backlog or Review carry the same planned mark in lookup, in the working contract, and in tiden intent candidates.

Put the key in the objective of the session too. The objective states what the product does when the work is done:

tiden intent start "A guardian is assigned to each project (ANYM-235)"

The working contract then lists the card under "Named specs" and says that a planned spec is not built yet. If the session builds it, the agent records the work as an update of that spec.

Finish the work

When the agent records its work with tiden intent settle, Tiden checks every new spec in the settle before it writes anything. For each new spec it shows:

• the nearest existing specs, up to 3, with their status
• the nearest other new specs of the same settle, up to 2

They come from a search by meaning, in order, with no score. The agent answers each candidate with one verdict and one sentence:

Verdict	Meaning
same	The candidate describes the same behavior.
part	The two overlap, or the new spec changes the candidate's rule.
sibling	They cover different parts of one area.
different	They share words and nothing else.

If the agent built a planned card, it settles the work as an update of that card, with update-existing on ANYM-235, instead of creating a new spec. The card becomes Active and needs tests. An answer looks like this in the item's similar field:

"similar": [
  {"ref": "ANYM-235", "verdict": "same", "reason": "This session built guardian assignment per project."},
  {"ref": "ANYM-236", "verdict": "sibling", "reason": "ANYM-236 covers guardian notifications, this session covers assignment."}
]

Settle stops with exit code 3 and writes nothing until every candidate has an answer. Answers stay valid across retries, so the agent runs the same settle again with the missing ones added. Tiden records the answers with the session.

When Tiden cannot compute the nearest specs, settle prints one warning and continues without the check.

Merged pull requests without a session

When a pull request merges without a session, Tiden reconciles its specs automatically. That reconciliation does not recognize planned cards. A pull request that builds ANYM-235 can leave the card in Backlog and add a new spec beside it.

Run the work in a session. The session is the path where Tiden shows the card to the agent at the start and at settle.

FAQ

Why did my agent stop at settle? The agent wrote a new spec, and Tiden found existing or other new specs near it. Settle exits with code 3, lists those candidates, and writes nothing. The agent adds one answer per candidate, or settles the item as an update of the planned card it built, and runs settle again.

Why is my card still Backlog after the work merged? Either the work was merged without a session, or the agent created a new spec and did not settle the work as an update of the card. In both cases the card stays Backlog, and you can set it to Active in the web UI, the CLI, or the API. In a session, a same answer on the card ends in an update of the card, and the card becomes Active.

Can I turn the check off? No. The check applies to every settle with new specs. Settle skips it only when Tiden cannot compute the nearest specs, and then it prints one warning.

Does the check block the agent for planned specs it did not build? No. A planned spec the agent did not build only appears as a candidate when a new spec is near it, and a sibling or different answer lets the settle go on.