issue-tracker

name	issue-tracker
description	Create and manage issues in the kanban repo. Create new issues (investigator) or pick and implement backlog items (tackle-worker).

Issue Tracker

The project uses a kanban-style issue tracker stored in a separate git repo.

• Main project: PROJECT_DIR
• Kanban repo: KANBAN_DIR
• Issues: KANBAN_DIR/issues/

Issue File Format

Issues are markdown files with state encoded in the suffix:

• *.backlog.md — idea captured, not yet started
• *.active.md — being worked on
• *.done.md — completed

ID Reservation

Use flock-based atomic counter:

ID=$(__KANBAN_DIR__/.tools/reserve-issue-id)

Creating a New Issue

Write to KANBAN_DIR/issues/-.backlog.md with frontmatter: type, state: backlog, created: <YYYY-MM-DD>, severity.

Optionally include subcommit-ref: refs/heads/_sub/<id> to suggest that the tackle-worker unfold and modify an existing sub-commit (from nathan/git-subcommit). This is a best-effort suggestion — the worker will verify the ref still exists.

Then commit in the kanban repo.

Severity scale

Level	When to use
critical	Data loss, crash, security, broken core functionality
major	Incorrect behavior, important missing feature
minor	Edge case, cosmetic bug, minor validation gap
cosmetic	Documentation, formatting, code style, nice-to-have

Picking Up an Issue

The tackle-loop script selects the highest-severity *.backlog.md (critical > major > minor > cosmetic, ties broken by lowest issue number) and passes the file path to the agent.

The loop script:

1. Renames .backlog.md → .active.md
2. Creates an isolated git worktree
3. Runs the agent inside the worktree
4. After the agent finishes, merges worktree changes back to main
5. Cleans up the worktree
6. Renames .active.md → .done.md and commits in the kanban repo

Subcommit-Aware Workflows

When git-subcommit (nathan) is available, agents can:

• Investigator: Scan git subcommit list — if a new bug/feature clearly overlaps an existing _sub/<id>, set subcommit-ref in the issue frontmatter.
• Tackle-worker: If the issue has subcommit-ref:, unfold that subcommit, modify it, and resquash. Verify the ref exists first.