---
summary: A unit of work tracked in the workspace.
---
# Issue
An **issue** is a unit of work tracked in the cartulary workspace.
Each issue captures a small, self-contained piece of intent the
team wants to keep visible from inception through completion.
## Concepts it carries
An issue carries:
- An [id](concept://id) — a TSID, lexicographically time-sortable.
- A [status](concept://status) — its current place in the
configured workflow.
- [tags](concept://tag) — typed structured metadata.
- [issue links](concept://issue-link) — typed relationships to
other issues. The relationship vocabulary is closed; see the
issue-link concept for the full list.
- An [event log](concept://event-log) — append-only history of
status transitions; the log keeps only the timestamp and the
action.
- Optional [companions](concept://companion) — sibling files
(`plan.md`, `design-decision.md`, `implementation-notes.md`).
On disk, this is one directory per issue named `<id>-<slug>`,
containing an `index.md` whose YAML frontmatter holds the metadata
above and whose Markdown body holds the description.
## Configuration
`cartu init` writes a minimal `cartulary.toml`: just the issues
directory and the decision-record kinds. Statuses and tag
descriptors fall back to built-in defaults until the workspace
overrides them.
- `[issues]` — the issues directory (`docs/issues` by default).
- `[issues.statuses]` *(optional)* — overrides the built-in
workflow `open` → `in-progress` → `closed` and back, with
`open` as the initial status and `closed` terminal.
- `[tags.<key>]` *(optional)* — one block per tag descriptor,
declared at the config root. Each descriptor's `applies_to`
selects the record kinds it validates; an issue-only key lists
only `"issues"`. None ship by default; what taxonomy a project
uses (categorisation, priority, size, area, …) is a workspace
decision documented in [tag](concept://tag).
## Validation
`cartu check` enforces:
- The YAML frontmatter parses without errors.
- The `id:` field matches the directory's TSID prefix.
- Every other rule lives in the concepts the issue carries — see
the Validation sections of [status](concept://status),
[tag](concept://tag), [issue link](concept://issue-link), and
[event-log](concept://event-log).
## Commands
Grouped by intent — `cartu issue --help` is the catalogue of every
flag.
- **Create**: `cartu issue new "Title"` (add tags with
`--tag <key>:<value>`, repeat for several).
- **Inspect**: `cartu issue list`, `cartu issue show <id>`,
`cartu issue metrics distribution`.
- **Advance**: `cartu issue status update <id> <new>` walks the
workflow; `cartu issue tag add|remove <id> <key>:<value>`
mutates tags.
- **Relate**: `cartu issue link add <from> <to> --relationship <r>`.
- **Validate**: `cartu check` (workspace-wide consistency).
A fresh workspace:
```console
$ cartu init
Initialized cartulary workspace: [..]
$ cartu issue list
No issues found
```