Spec agent and build orders

A spec agent turns a rough ticket into a build order: a goal, explicit boundaries, testable acceptance criteria, the affected surfaces and any migration work. It asks the ticket author about unresolved decisions before releasing the work.

Enable specification readiness

In project settings, enable Require specification before agent work and select the required ticket types. The defaults are stories and epics; existing projects start with the feature disabled. At least one type must be selected. Choose whether a spec agent can release work or the human author must release it.

An administrator gives the spec bot the routing tag spec and permission to edit tickets in the project. Its session receives the spec role and format rules. Connect its MCP session with ?toolset=full or set ORBOTO_MCP_TOOLSET=full for stdio so the named specification tools are available. The existing always-on inbox connection receives the work notifications. Declaring a role in a prompt does not grant access.

Required tickets move through Needs specification, In specification and Ready. Worker agents cannot claim an unreleased required ticket. Human work continues normally; an explicit worker override needs a reason and is audited. Epics describe groups of child stories and cannot be claimed by implementation agents.

Enabling the feature prepares existing unheld tickets. Work already held by an agent can continue until its lease closes or expires. Removing a required type or disabling the feature immediately clears obsolete specification states.

Write the build order

Keep the original idea outside the marked section. The section uses these exact markers and headings, in this order:

<!-- orboto:build-order:start -->
## Build order

### Goal
Remember the user's selected project filter after a reload.

### Non-goals
Sharing filters with other users.

### Acceptance criteria
1. Given a selected filter, reloading restores that selection.
2. An invalid saved filter falls back to all projects.

### Touched surfaces
UI: project filter and its persistence helper; docs: filter behavior.
API, MCP, CLI, skill and chat tools: no change.

### Migration needs
No schema migration. Existing saved preferences remain readable.

### Open questions

<!-- orboto:build-order:end -->

Write the goal in one sentence. Each acceptance criterion must be testable. Name affected API routes, MCP and CLI commands, skill instructions, chat tools, UI components and documentation when known. Record schema, data and settings migrations explicitly. Keep unresolved questions as a numbered list; remove answered questions before release. An empty Open questions section means there are no remaining questions.

The ticket detail can insert an empty template after the existing description. It shows the validation result beside the specification badge. The empty template still needs a goal and acceptance criteria before it can be released.

Ask and resume

On a specification wake, the bot acquires the ticket's spec work lease and reads its description and comment thread. It puts all open questions in one comment mentioning the author, then waits for answers. It must not invent product decisions to clear the questions.

An author reply wakes the eligible spec agents again, including while the ticket is In specification. Another participant can mention the specific bot using the editor's user mention picker. The Markdown form is @[Name](user:UUID); plain @spec is not an alias.

Replies wait while autonomy is paused. Several pending replies can coalesce into one wake, so the bot rereads the thread. Delivery rechecks access, the spec tag, the ticket state and comment visibility. A deleted or inaccessible answer is not delivered, and a later reply is not suppressed as a duplicate of an earlier one.

Check and release

orboto spec check ACME-42

The command reports missing, repeated or reordered headings, empty criteria and the number of open questions. It also returns the canonical template. It exits with 0 when valid, 1 when invalid or the request fails, and 2 for incorrect usage. The full MCP toolset and in-app chat expose orboto_spec_check. Curated MCP sessions discover the endpoint with orboto_api_search and call it with orboto_api_call: GET /projects/:projectId/tickets/:id/spec-check.

Validation reads the real section, not headings inside a code block or quoted example. It checks structure; the author and spec agent remain responsible for the decisions and the quality of the acceptance criteria.

With agent release enabled, an authorized spec bot can set the ticket to Ready after validation passes. With author release selected, the bot requests release in a comment and the human author or project administrator releases it. The server checks both the format and the release permission; a successful check alone does not grant that permission.

Editing the marked build order invalidates a released specification. Changes to context outside the markers preserve readiness. Each child story of an epic needs its own build order and release before a worker implements it.