A work order is a named, persistent container for an agent session. Each order keeps its own chat transcript, remembers the component or recipe it produced, and records every human/AI exchange: including the provider and model used: to a file on disk you can export as Markdown.
Why Work Orders?
Some teams need more than a one-shot chat. Auditable history matters when:
- You work in a regulated environment and need to prove what the AI did to your codebase.
- You're migrating a messy legacy design system and want a surgical trail per task.
- You use Jira, Linear, or a similar tracker and want each ticket to have a bound AI conversation with an attachable audit artifact.
- You want to compare how different models (Sonnet, Opus, GPT-4o) approach the same problem: each order records the exact model used per turn.
Work orders are fully optional. When the feature is off, Spektral works exactly as before. When it's on, you can still freestyle without any order bound: nothing is persisted. Binding an order starts recording.
Enabling the Feature
Open Settings → Work Orders and toggle Enable Work Orders. A new Work Orders tab appears in the top nav, and a banner appears on the Components page showing the current recording state.
Turn it off and the tab disappears, the banner disappears, and no interactions are recorded. Your existing order files remain on disk: they're just not surfaced in the UI until you turn the feature back on.
Core Concepts
Two ideas matter: selecting an order (viewing its detail) and binding an order (recording into it). They're independent: you can view any order without changing which one receives the next agent turn.
Selected
The order whose detail panel is showing on the Work Orders page. Purely a viewing concern: switching selection doesn't affect recording.
Bound (recording)
The order that the next agent turn will be appended to. Marked with a green recording pill in the sidebar. Only one order is bound at a time.
Freestyle mode is the state where no order is bound. Turns still work: they just aren't persisted anywhere.
Typical Workflow
Create an order
Type a title in the sidebar input (e.g. "JIRA-482 button size tokens") and hit the + button. The new order is auto-bound: you can start working immediately and the first turn is captured.
Tag it (optional)
In the detail pane you can set:
- Status: open, in progress, completed, archived.
- Description: a short note about what the order is for.
- External reference: a system name (e.g. "Jira"), ID (e.g. "PROJ-482"), and URL. Shows up in the exported audit log and keeps each order tied to your tracker.
Work as usual
Head over to the Components tab. The banner at the top shows "Recording to <title>". Generate or iterate on components and recipes normally: every user prompt, assistant response, tool call, tool result, and turn boundary is appended to the bound order in real time.
Need a break from recording? Click the banner's × or pick Freestyle from the Work Orders sidebar. The order stays where it is; new turns simply stop being written to it.
Resume later
Pick an order and click Resume to reopen its saved chat transcript, rebind recording to that order, switch back to the platform it was created on, and load the current component or recipe files from disk into the preview/refinement workspace.
Export the audit log
When the work is done, click Export audit log in the order's detail pane. You'll get a Markdown file containing the metadata header (title, status, timestamps, artifact, platform, provider, model, external reference) and a chronological log of every event. Attach it to the Jira ticket or check it into your repo: it's a self-contained record of what the AI did.
Where It Lives
Work orders are stored in the design system project repo, one JSON file per order:
<project-root>/ .spektral/ work-orders/ <uuid>.json // one file per order: metadata + artifact + messages + events
Because they live inside your project, audit trails travel with the design system. Commit them if your team wants a shared record, or add .spektral/work-orders/ to .gitignore if each contributor should keep their own.
Event Schema
Each order carries an ordered list of events. All events have kind and at (ISO timestamp), plus kind-specific fields.
| kind | Fields | Meaning |
|---|---|---|
| turn_start | role, text, imageCount, provider, model | User submitted a prompt. Captures the exact model that was about to run. |
| assistant_text | text | A complete assistant message (flushed when the agent ends a thought or calls a tool). |
| tool_use | id, name, input | Agent invoked a tool. The call id lets you match it to the result. |
| tool_result | id, name, result, isError | The output the tool returned to the agent. |
| questionnaire_presented | questionCount | Agent asked the user a set of clarifying questions. |
| questionnaire_answered | status | User submitted or skipped the questionnaire. |
| turn_end | stopReason | Agent finished the turn: end_turn, max_tokens, etc. |
| error | message | Something failed mid-turn. |
| note | text | Free-form annotation (reserved for future manual entries). |
Messages (the chat bubbles you see in the transcript) are stored separately under messages alongside events: that keeps the chat render fast without walking the full event log.
Integrity Guarantees
A single agent turn fires dozens of append operations in rapid succession. To keep the order file valid:
- Per-order write serialization. All appends for a given order run in order via an in-memory promise chain: no races on the read-modify-write cycle.
- Atomic writes. Each save writes to
<id>.json.<pid>.<ts>.tmpand then renames it. A crash mid-write can't leave a partial file on disk. - Restart persistence. The currently-selected and currently-bound order IDs are saved to
localStorageand restored (after validating they still exist on disk) when Spektral starts.
Integrating with Jira, Linear, or Your Tracker
The external-reference fields on each order are intentionally minimal: a system name, an ID, and a URL. Fill in whatever your workflow needs:
System Jira ID DS-482 URL https://yourorg.atlassian.net/browse/DS-482
The exported Markdown includes these in the metadata header so the auditor can click straight through to the tracker. If you use an agent plugin for your tracker, you can also have the agent create the ticket itself and then paste the ID back here.