tix-tracker 0.2.0

# tix — a terminal issue tracker

**tix** is a kanban-style issue tracker that lives entirely in your repository:
issues are plain **Markdown + YAML frontmatter** files. There is no database, no
server, and no proprietary format — you get a terminal UI (TUI), a full CLI, and
optional GitLab/Linear sync in one Rust binary.

> **Heavily AI assisted.** This project was designed, specified, and built
> end-to-end with AI agents under a spec-kitty-SPEC style governed workflow
> (spec → plan → tasks → implement → review → merge). All 6 work packages, 27
> functional requirements, and 33 subtasks were implemented and reviewed by
> AI agents (`implementer-ivan`, `reviewer-renata`) steered by a human operator.
>
> - The human owns the repo and the decisions; the agents wrote the code.
> - Every feature went through a review cycle with real gate checks
>   (`cargo test`, `clippy -D warnings`, `cargo fmt`) before merge.
> - The full mission trail lives in `kitty-specs/issue-tracker-tui-01M27PTN/`
>   (spec, plan, tasks, acceptance matrix, review report, retrospective) if you
>   want an audit-grade record of how the software was produced.
> - How Spec Kitty and tix interoperate (`.kittify/`, missions, merge drivers,
>   task mirroring) is documented in
>   [`docs/spec-kitty-integration.md`](docs/spec-kitty-integration.md).
> - `tix init-agents` itself writes an AI-agent usage section into `AGENTS.md`,
>   so other agents can operate this tracker autonomously.

## Install

The crate is published to crates.io as **`tix-tracker`** (the binary is still
called `tix`). See [docs/packaging.md](docs/packaging.md) for the full
maintainer workflow (crates.io account, publishing, binary releases).

```bash
cargo install tix-tracker    # build from source via crates.io

# or, with prebuilt binaries (fast, no Rust toolchain needed):
cargo install cargo-binstall --locked   # one-time, if you don't have it
cargo binstall tix-tracker
```

Local development installs (same binary) work too:

```bash
cargo install --path .
```

Requires a Rust toolchain (edition 2024, MSRV 1.85). The only runtime
dependency is your favorite editor for `tix edit`.

## Quickstart

```bash
tix init                        # create the default tix.toml (columns, issues_dir)
tix create --title "First issue" --priority high --labels docs
tix status                      # board summary: column -> count
tix list                        # all issues in a table
tix                             # open the kanban TUI
```

## CLI

| Command | What it does |
| --- | --- |
| `tix init` | Create a default `tix.toml` |
| `tix create` | New issue (title/body/status/priority/assignee/labels/estimate) |
| `tix list` | Table of issues, optional `--status` filter |
| `tix view <issue>` | Full issue (frontmatter + body) |
| `tix status` | Board summary: count per column + total |
| `tix edit <issue>` | Edit fields via flags, or full file via `$EDITOR` |
| `tix move <issue> <column>` | Move between columns; `done` records a commit hash |
| `tix delete <issue> --yes` | Remove an issue file |
| `tix export --target gitlab\|linear` | Push local issues to a remote tracker |
| `tix import --target gitlab\|linear` | Pull open issues from a remote tracker |
| `tix init-agents` | Write/refresh the AI usage section in `AGENTS.md` |

An issue can be referenced by its number, a unique filename fragment, or a
unique title fragment.

## TUI

Launch with `tix` (no arguments) from the repository root:

- **Arrows / h/l** — move between columns, **j/k** — select issues
- **Enter** — view the full issue, **n** — new issue form
- **e** — edit the issue in your `$EDITOR`
- **d** — delete (with confirmation)
- **q / Esc** — quit

## External sync

`tix export/import` talks to GitLab through the `glab` CLI and to Linear
through `linear-cli`. If the tool is missing, `tix` fails with a clear,
actionable error. Repeated exports are idempotent: issues are matched by their
`gitlab_id` / `linear_id`, and conflicts resolve in favor of the newer
`updated` timestamp.

## Storage format

Every issue is a file like `docs/issues/2026-09-11-my-title.md`:

```markdown
---
number: 1
title: My issue
status: todo
priority: high
labels: bug, docs
assignee: @alice
created: 2026-09-11
updated: 2026-09-11
---
The body is plain markdown — screenshots and diagrams work as usual.
```

Human-readable, human-edit-able, git-friendly. No data is locked away.

## Configuration

`tix.toml` (at the repository root) defines the board columns, the issues
directory, and optional `[export]` targets:

```toml
columns = ["todo", "in progress", "done", "mismatch"]
issues_dir = "docs/issues"

[export]
tokens = { gitlab = "/path/to/token" }
project = { gitlab = "", linear = "" }
```

Tokens are never serialized back out after configuration.

## Version

Current version: **0.1.0**. See [CHANGELOG.md](CHANGELOG.md).

## License

MIT OR Apache-2.0.