# WorkItem definition and API shape > Superseded on 2026-06-05: the durable orchestration record concept is now named `Ticket`, not `WorkItem`. See `ticket-definition-and-api-shape-20260605.md` and the ticket thread decision for current terminology. This file is retained as historical design context. ## Definition In Insomnia, a WorkItem is not primarily an issue tracker item. A WorkItem is an agreed execution contract that fixes user intent into a bounded unit that Pods can schedule, delegate, implement, review, and close safely. Short definition: > A WorkItem is a durable work contract that preserves user/system-agreed intent and gives Pod groups enough boundary, readiness, and evidence to execute, verify, and complete the work without degrading the original intent. A ticket file, GitHub Issue, Linear issue, Jira issue, or another tracker record can be a persistence representation of a WorkItem, but none of those representations define the concept itself. ## Roles served by a WorkItem A WorkItem is simultaneously: - Intent anchor: preserves what the user and Intake agreed to. - Delegation packet: lets Orchestrator/Coder understand what should be done and where to stop. - Review contract: gives Reviewer an explicit basis for approval or request-changes. - Scheduling unit: lets Orchestrator prioritize, interrupt, parallelize, and assign work. - Boundary: records scope, non-goals, authority limits, privacy constraints, and escalation conditions. - Lifecycle record: records plans, decisions, implementation reports, reviews, commits, validation, and resolution. ## Relationship to tickets and issue trackers - WorkItem is the Insomnia orchestration concept. - Local markdown ticket is one backend representation. - GitHub/Linear/Jira issue is another possible backend representation. - The backend should be abstracted below the WorkItem API. The WorkItem abstraction should not try to become a complete issue tracker abstraction. It should cover only the subset needed for Insomnia orchestration: create/list/show, structured lifecycle events, status/readiness, review, close, consistency checks, and references/evidence. ## Typing strategy Use a thin typed envelope with rich Markdown/freeform bodies and events. The API should type fields that the system reads mechanically, while leaving the content that carries human intent as Markdown/freeform text. This keeps compatibility with external issue trackers and avoids turning Intake into a rigid form-filling flow. ### Typed fields These should be typed because Orchestrator, TUI, policy, or tools branch on them: - Identity: - backend id - external/work item id - Classification: - kind - priority - labels as free strings - State: - canonical status - readiness - action-required state - needs-preflight flag - risk flags - Lifecycle operation/event kind: - comment - plan - decision - implementation report - review approved - review request-changes - status changed - closed - References: - related WorkItems - files - branches - commits - Pods - URLs/artifacts - Backend capability metadata: - create/comment/review/close support - artifact support - offline support - transactional/local-git support Enums should not be closed too tightly. Use escape hatches such as `Other(String)` or canonical+raw mappings for tracker compatibility. Examples: ```rust enum WorkItemKind { Bug, Task, Feature, Design, Chore, Other(String), } struct MappedStatus { canonical: WorkItemStatus, raw: Option, } ``` ### Freeform / Markdown fields These should remain Markdown/freeform because AI agents and humans can read them well and external trackers can round-trip them: - issue / problem statement - user intent - background / rationale - requirements - acceptance criteria - non-goals - invariants - escalation conditions - investigation notes - implementation reports - review comments - resolution details The event kind should be typed, but event body should remain Markdown. ```rust struct WorkItemEvent { kind: WorkItemEventKind, body: MarkdownText, refs: Vec, } ``` ## Suggested initial model ```rust struct WorkItem { id: WorkItemId, title: String, classification: WorkItemClassification, state: WorkItemState, body: WorkItemDocument, events: Vec, refs: Vec, backend: BackendMetadata, extensions: serde_json::Map, } ``` ```rust struct WorkItemState { status: MappedStatus, readiness: Readiness, action_required: Option, needs_preflight: bool, risk_flags: Vec, } ``` ```rust struct WorkItemDocument { issue: MarkdownText, requirements: MarkdownText, acceptance_criteria: MarkdownText, non_goals: Option, notes: Option, } ``` ## API principle Operations should be typed; payload bodies should be flexible. Examples: - `CreateWorkItem(NewWorkItem)` is typed. - `AddWorkItemEvent { kind, body }` is typed by operation/event kind, freeform in body. - `UpdateWorkItemState { readiness, action_required, risk_flags }` is typed. - `CloseWorkItem { resolution: MarkdownText }` has typed operation semantics and freeform resolution text. This gives enough structure for audit, scheduling, TUI display, and automation, without forcing issue-tracker-specific fields into the core model. ## Lint over hard schema Prefer a WorkItem linter/policy layer over strict structural enforcement for body content. Examples: - title must be present. - issue/requirements should not be empty. - P0/P1 items without acceptance criteria should warn. - risk flags with `needs_preflight = false` should warn. - secret-like literals should warn or fail depending on policy. - closing without review/resolution can warn or fail depending on project policy. This makes the system agent-friendly and backend-compatible while still catching low-quality WorkItems. ## Backend abstraction Backends should implement WorkItem storage/sync, not redefine WorkItem semantics. ```text Intake / Orchestrator / TUI / Workflows ↓ WorkItem API ↓ WorkItemBackend ├─ LocalFilesBackend ├─ GitHubIssuesBackend ├─ LinearBackend ├─ JiraBackend └─ MCPWorkItemBackend ``` Each backend should expose capabilities. The tool/TUI surface should show only operations supported by the configured backend. ## Scope and authority WorkItem tool authority is separate from normal code/worktree filesystem scope. Filesystem scope protects exclusive editing of implementation areas. WorkItem management is shared project coordination state and should be mediated by typed WorkItem operations, backend locks/conflict handling, and audit records rather than ordinary delegated write scope. This does not imply unlimited file access. The WorkItem tool should be limited to configured WorkItem backends and operations. ## Design consequence The first implementation can be LocalFilesBackend over current `work-items/`, preserving markdown/frontmatter/thread/artifacts and `tickets.sh` compatibility. The API should already be backend-shaped so GitHub Issues or other trackers can be added later without changing Intake/Orchestrator semantics.