From fc6408171223f84a86fcd7b7d9111f8591c0e9d9 Mon Sep 17 00:00:00 2001
From: Ole-Morten Duesund <olemd@glemt.net>
Date: Mon, 11 May 2026 13:50:39 +0200
Subject: [PATCH] Add dcat issue tracking setup

Introduce AGENTS.md with dcat workflow, .gitattributes merge driver for
dcat JSONL files, and .dogcats/ config + empty issue store. Update
CLAUDE.md to point agents at AGENTS.md and avoid the TodoWrite tool, and
ignore local-only dcat files (config.local.toml, .issues.lock).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .dogcats/config.toml  |  1 +
 .dogcats/issues.jsonl |  0
 .gitattributes        |  2 ++
 .gitignore            |  2 ++
 AGENTS.md             | 30 ++++++++++++++++++++++++++++++
 CLAUDE.md             |  3 +++
 6 files changed, 38 insertions(+)
 create mode 100644 .dogcats/config.toml
 create mode 100644 .dogcats/issues.jsonl
 create mode 100644 .gitattributes
 create mode 100644 AGENTS.md

diff --git a/.dogcats/config.toml b/.dogcats/config.toml
new file mode 100644
index 0000000..7d9577a
--- /dev/null
+++ b/.dogcats/config.toml
@@ -0,0 +1 @@
+namespace = "tilt-shift-camera"
diff --git a/.dogcats/issues.jsonl b/.dogcats/issues.jsonl
new file mode 100644
index 0000000..e69de29
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..8598de8
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,2 @@
+# Dogcat JSONL merge driver
+.dogcats/*.jsonl merge=dcat-jsonl
diff --git a/.gitignore b/.gitignore
index b084b0c..ac015b8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -92,3 +92,5 @@ lint/tmp/
 ehthumbs.db
 Thumbs.db
 .signing/
+.dogcats/config.local.toml
+.dogcats/.issues.lock
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d180f1e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,30 @@
+# Agent Instructions
+
+## Issue tracking
+
+This project uses **dcat** for issue tracking. You MUST run `dcat prime --opinionated` for instructions.
+Then run `dcat list --agent-only` to see the list of issues. Generally we work on bugs first, and always on high priority issues first.
+
+When running multiple `dcat` commands, make separate parallel Bash tool calls instead of chaining them with `&&` and `echo` separators.
+
+Mark each issue `in_progress` right when you start working on it — not before. Set `in_review` when work on that issue is done before moving on. The status should reflect what you are *actually* working on right now.
+
+It is okay to work on multiple related issues at the same time, but do NOT batch-mark an entire backlog as `in_progress` upfront. If there is a priority conflict, ask the user which to focus on first.
+
+If the user brings up a new bug, feature or anything else that warrants changes to the code, ALWAYS ask if we should create an issue for it before you start working on the code. When creating issues, set appropriate labels using `--labels` based on the issue content (e.g. `cli`, `tui`, `api`, `docs`, `testing`, `refactor`, `ux`, `performance`, etc.).
+
+When research or discussion produces findings relevant to an existing issue, ask these as **separate questions in order**:
+
+1. First ask: "Should I update issue [id] with these findings?"
+2. Only after that, separately ask: "Should I start working on the implementation?"
+Do NOT combine these into one question. The user may want to update the issue without starting work.
+
+### Closing Issues - IMPORTANT
+
+NEVER close issues without explicit user approval. When work is complete:
+
+1. Set status to `in_review`: `dcat update --status in_review $issueId`
+2. Ask the user to test
+3. Ask if we can close it: "Can I close issue [id] '[title]'?"
+4. Only run `dcat close` after user confirms
+5. Ask: "Should I add this to CHANGELOG.md?" — update if yes
diff --git a/CLAUDE.md b/CLAUDE.md
index 09d9b5d..6e1a655 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -101,3 +101,6 @@ Bitmaps emitted to `StateFlow`s are **never eagerly recycled** immediately after
 - `minSdk = 35` (Android 15) — intentional for personal use. Lower to 26-29 if distributing.
 - Dependencies updated to March 2026 versions (AGP 9.1, Kotlin 2.3, Compose BOM 2026.03).
 - Fragment shader uses `int` uniform branching in GLSL ES 1.00 — works but could be cleaner with ES 3.00.
+
+## Issue tracking & task management
+- Do NOT use the `TodoWrite` tool in this project. Issue tracking and progress is managed with **dcat** as specified in `AGENTS.md` — see that file for the full workflow (`dcat prime --opinionated`, `dcat list --agent-only`, status transitions, closing rules, etc.).