97 lines
2.7 KiB
Markdown
97 lines
2.7 KiB
Markdown
# Work Items backend
|
|
|
|
`work-items/` is the canonical file backend for repository work after the migration from `TODO.md` and `tickets/*.md`.
|
|
|
|
## Layout
|
|
|
|
```text
|
|
work-items/
|
|
README.md
|
|
open/
|
|
<id>/
|
|
item.md
|
|
thread.md
|
|
artifacts/
|
|
pending/
|
|
<id>/
|
|
item.md
|
|
thread.md
|
|
artifacts/
|
|
closed/
|
|
<id>/
|
|
item.md
|
|
thread.md
|
|
resolution.md
|
|
artifacts/
|
|
```
|
|
|
|
`<id>` is timestamp based: `YYYYMMDD-HHMMSS-<slug>`. There is no central sequence file.
|
|
|
|
## `item.md` schema
|
|
|
|
`item.md` is Markdown with YAML-like frontmatter. The MVP parser intentionally supports only simple `key: value` lines.
|
|
|
|
Required fields:
|
|
|
|
```yaml
|
|
---
|
|
id: 20260527-000001-example
|
|
slug: example
|
|
title: Human-readable title
|
|
status: open
|
|
kind: feature
|
|
priority: P2
|
|
labels: [maintainer, workflow]
|
|
created_at: 2026-05-27T00:00:01Z
|
|
updated_at: 2026-05-27T00:00:01Z
|
|
assignee: null
|
|
legacy_ticket: tickets/example.md
|
|
---
|
|
```
|
|
|
|
`status` must match the containing directory (`open`, `pending`, or `closed`). `legacy_ticket` records the migrated source path when one existed; use `null` for items created from a TODO-only entry or new work.
|
|
|
|
## `thread.md` schema
|
|
|
|
`thread.md` is an append-only Markdown event log. `tickets.sh comment`, `tickets.sh review`, and `tickets.sh close` append an HTML-comment event header, a Markdown heading, the event body, and a `---` separator.
|
|
|
|
Example:
|
|
|
|
```md
|
|
<!-- event: review author: orchestrator at: 2026-05-27T12:00:00Z status: request_changes -->
|
|
|
|
## Review: request changes
|
|
|
|
Review notes.
|
|
|
|
---
|
|
```
|
|
|
|
Review state belongs in `thread.md`; new `tickets/*.review.md` files should not be created.
|
|
|
|
## Commands
|
|
|
|
Use `../tickets.sh --help` from this repository root for the command reference. The script performs file operations only; it does not run `git add` or `git commit`.
|
|
|
|
Common commands:
|
|
|
|
```sh
|
|
./tickets.sh list --status all
|
|
./tickets.sh show <id-or-slug>
|
|
./tickets.sh create --title "Title" --slug title
|
|
./tickets.sh comment <id-or-slug> --role plan --file notes.md
|
|
./tickets.sh review <id-or-slug> --approve --file review.md
|
|
./tickets.sh close <id-or-slug> --resolution "Done"
|
|
./tickets.sh doctor
|
|
```
|
|
|
|
## Migration policy
|
|
|
|
The migration moved unfinished `TODO.md` entries and `tickets/*.md` bodies into `work-items/open/*/item.md`. Existing review files, when present, must be represented as `review` events in `thread.md`. After migration:
|
|
|
|
- `work-items/` is the source of truth.
|
|
- `TODO.md` is only a legacy/generated-view notice and must not carry open ticket state.
|
|
- `tickets/*.md` and `tickets/*.review.md` must not remain as canonical unfinished items.
|
|
- Closed items are moved to `work-items/closed/` instead of being deleted.
|
|
- `./tickets.sh doctor` checks schema, status placement, duplicate IDs/slugs, and leftover legacy ticket files.
|