# User expectations

How the user expects a Claude Code session to behave under this workflow. Read this
once per session; it rarely changes.

## Work autonomously

Do not stop to ask which task to pick up next, or for confirmation before routine work.
Default sensibly and keep shipping. Read `state/TODO.md`, choose the next sensible
item, do it. Only ask when a decision is genuinely the user's to make and cannot be
resolved from the repo or sensible defaults.

## Cost before speed

Staying within usage limits is more important than finishing fast or gold plating.
When in doubt, take the cheaper path. See [Cost and tokens](cost-and-tokens.md).

## Subagents are allowed

Spawning subagents, parallel agents, background tasks and multi-agent workflows is a
normal, permitted part of the workflow. Using them is not a breach of the cost rule
when they are the effective path: fan-out searches that keep bulk file contents out of
the main context, independent pieces of work run in parallel, or verification passes
over completed work.

The cost rule still applies to each one. A subagent must earn its keep: do not spawn
one for work a single cheap tool call can do, and do not fan out speculatively. Record
subagent use in the PR under "Tools used" so the cost trail stays honest.

## Leave a clean trail

Every feature ends as: a merged branch, full commit notes, a complete PR, current
`state/` files, and code commented well enough to document later. The user should be
able to open the repo weeks later, with no memory of the session, and understand what
happened and why from the repo alone.

## Report honestly

If tests fail, say so with the output. If a step was skipped, say that. If something is
done and verified, say so plainly without hedging. Do not claim more than was done.

## Writing style

- No em dashes in prose. Use commas, full stops, or restructure.
- British spelling in prose and copy. Preserve code identifiers as written.
- Plain, direct language. Say what happened.

## Confirm before the hard to reverse

Routine coding is autonomous. But confirm first for actions that are hard to undo or
that reach outside the repo: force pushes, history rewrites, deleting things you did
not create, deploying, or sending data to external services. Approval for one such
action does not carry to the next.

## The building session stops at merge

Do not write the user facing documentation in the building session. That is a separate
session's job. See [Documentation policy](documentation-policy.md).