Working with work items

Organizerprojects5 min read

A work item is anything tracked in a project — a task, story, bug, epic, feature, or subtask. The same entity backs every view (Kanban card, Agile story, Waterfall task), so switching methodologies doesn't move data around.

Quick add

The fastest way to create an item is the inline row at the top of /projects/{id}. Type a title, press Enter — done. The item lands in the project's first Kanban column with type task. Want a different type? Use the + New work item dropdown next to it; pick Story, Bug, etc. and the modal opens pre-set with the right type.

The full editor

Click any item title to open the editor. It has six tabs:

Details

Title, type, status, priority
Assignee — searchable picker (see below)
Tags — pill-style typeahead; reuse tags across items
Phase — only shown when the project has phases (see Waterfall, Gantt & phases)
Sprint — flowing through the Backlog page on Agile projects
Description — full Markdown editor with image upload, mermaid diagrams, link-to-other-work-items
Type-specific fields:
- Story → Acceptance criteria (Markdown editor)
- Bug → Repro steps, System info, Severity
- Epic / Feature → just description
Estimate — Optimistic / Likely / Pessimistic (the PERT triple); see Estimation
Story points (Agile only) for stories
Start date / Due date — used by the Gantt
Billable toggle

History

A timeline of every change made to the item, with who-changed-what diff chips. The status-flow stepper at the top lights up every state the item has visited.

Time

Timer + manual entries — see Time tracking.

Link this item to others in four kinds of relationship:

Parent — the higher-level item this one belongs to.
Children — items nested under this one.
Blocked by (Predecessors) — items that have to finish before this one can start.
Blocks (Successors) — items waiting on this one.

Adding a link

Click + Add link. The dialog asks for:

Link type — Parent / Child / Predecessor / Successor.
Pick work item — search by number or title; multi-pick is supported for Children / Blocked by / Blocks.
Dependency type (Predecessor / Successor only) — Finish-to-Start (default), Start-to-Start, Finish-to-Finish, or Start-to-Finish.
Comment (optional) — a short note explaining the link, shown as a tooltip on the chip.

Cycle detection rejects loops automatically — the dialog will show a yellow warning if the link would create one.

Removing a link

Every chip has an X button:

Parent X → clears the parent pointer; this item becomes a root item.
Children X → unparents the child (the child stays as a root item, NOT deleted; it's just no longer nested under this one).
Blocked by X → drops the dependency.
Blocks X → drops the dependency from the other item's side. (Behind the scenes the row is stored against the other item; this is the same edge, just removed from this side for symmetry.)

Attachments

Drag-and-drop or click to upload. Up to 25 MB per file by default. Image attachments render as thumbnails. Files are scoped to the project; deleting an item deletes its attachments.

AI activity

Visible only when the item has been picked up by an AI agent — see AI agents.

Templates

Above the title, every type with templates available shows a Use template button. Stories get "User story" / "Job story" / "Spike"; bugs get "Classic" / "Minimal"; epics and features get problem / outcome / success-metric outlines. Templates only fill empty fields — your existing content is never overwritten.

Markdown rich-text fields

Description, Acceptance criteria, and Repro steps all use the same Markdown editor with:

Toolbar — bold, italic, headings, lists, link, table, code block, insert mermaid diagram, link to work item (#5 or PROJ-5 syntax)
Image paste — paste a screenshot or drag a file from disk; uploads scoped to the project
Mermaid diagrams — fenced ```mermaid blocks render server-side to PNG references
Code highlighting — fenced blocks with a language tag get syntax colours

Assignee picker

Type to search, pick from the dropdown:

Yourself — always available
Members of organizations you belong to — active memberships only

If you don't have an organisation, the picker only shows yourself. Create or join one via Organization. Selected user's avatar (Gravatar fallback if no stored avatar) shows on the row, in the editor, and on Kanban cards.

Lifecycle timestamps

Status changes update timestamps automatically:

Moving from a "to do" state to anything else sets StartedAt
Moving to a state flagged Done (project setting) sets CompletedAt
Moving back from Done clears CompletedAt

These power the burndown, calibration, and reports.

Numbering

Work items get a per-project number (#5) or a project-prefixed number (WEB-5) depending on the global numbering mode. Either way, click the number to copy a stable reference link. The toolbar on Markdown editors has a Link to work item button that opens a picker for inserting [#5 Title](url) references into your text.