issue-tracker

AI-native issue management for SDD coding agent workflows — markdown-first with SQLite index and optional remote sync.

Each issue is a markdown file with YAML frontmatter. Local SQLite provides fast CLI queries. Optional Supabase/PostgreSQL enables shared multi-user access.

Features

• SDD Integration — Spec-driven development with plan decomposition
• Multi-Agent Support — Atomic claim, capability routing, lifecycle hooks
• Reporter Tracking — Auto-detects reporter from git config
• Scratch Notes — Agent working memory separate from issue description
• FTS5 Search — Full-text search across all issue content
• MCP Server — 25 tools for direct agent integration
• Health Checks — Doctor command for data integrity validation
• Output Formats — compact, ids, json, markdown, plain

Architecture

• Markdown files (~/.local/share/issue-tracker/issues/<project>/) — source of truth
• Local SQLite (.issues.db) — derived index, rebuilt via issue reindex
• FTS5 Index (.issues.fts.db) — full-text search index
• Supabase PostgreSQL — optional shared remote state

See docs/supabase.md for database details.

Configuration

All paths are configurable via environment variables:

Database Backend

Variable	Default	Description
ISSUE_DB_BACKEND	sqlite	Database backend: sqlite, supabase, etc.
ISSUE_DB_URL	(backend-specific)	Database connection URL
ISSUE_DB_KEY	(backend-specific)	Database connection key/token
ISSUE_SQLITE_PATH	~/.local/share/issue-tracker/issues/.issues.db	SQLite database path (sqlite backend only)

Paths

Variable	Default	Description
ISSUE_DATA_DIR	~/.local/share/issue-tracker/issues	Base directory for issue data
ISSUE_GOTCHA_DIR	~/.local/share/issue-tracker/gotchas	Directory for gotcha files
ISSUE_TODOS_PATH	~/.local/share/issue-tracker/todos.json	Path to todos.json
ISSUE_BLOCKED_PATH	~/.local/share/issue-tracker/blocked-tickets.json	Path to blocked-tickets.json
ISSUE_PROJECTS_DIR	~/projects	Base directory for project scanning
ISSUE_REGISTRY_DIR	~/.config/issue-tracker	Registry directory

Supported Backends

Backend	ISSUE_DB_URL	ISSUE_DB_KEY
sqlite	(not used)	(not used)
supabase	Supabase project URL	Supabase service role key

Usage

Basic Commands

# Create issue (reporter auto-detected from git config)
issue open "title" --project myapp --type bug --severity P1
issue open "title" --project myapp --reporter "user@example.com"

# Quick create (auto-detect project from git remote)
issue quick "title"

# List issues
issue list                              # all, grouped by project
issue list --project myapp --state open # filtered
issue list --format json                # JSON output
issue list --format ids                 # project#id only (for shell pipes)

# Show issue detail
issue show myapp#7

# Edit fields
issue edit myapp#7 --severity P0
issue edit myapp#7 --state in_progress  # validates state transition

# Add comment
issue comment myapp#7 "investigation notes"

Agent Commands (Multi-Agent Workflows)

# Atomic claim (prevents duplicate work)
issue claim myapp#7 --agent coder-1

# Actionable issues with dependencies met
issue ready --project myapp

# Tiered brief (context window optimization)
issue brief myapp#7                   # L1: frontmatter + acceptance criteria
issue brief myapp#7 --full            # L2: everything
issue brief --list --state open       # L0: index lines only

Plan Decomposition (SDD)

# Generate LLM prompt for plan
issue plan prompt myapp#7

# Submit plan and spawn child issues
issue plan submit myapp#7 --plan plan.json

# Show plan with children status
issue plan show myapp#7

Scratch Notes (Agent Working Memory)

# Add scratch note
issue scratch add myapp#7 "Investigated auth flow, found race condition"

# Show scratch notes
issue scratch show myapp#7

# Clear scratch notes (after resolution)
issue scratch clear myapp#7

Lifecycle Hooks (Session Context)

# Show in-progress issues for session resume
issue hook session-start --project myapp

# Checkpoint before context compaction
issue hook pre-compact --project myapp

# Auto-detect completions from agent output
echo "Completed myapp#7" | issue hook stop

Search & Analysis

# Full-text search
issue search "auth token" --project myapp

# Health checks
issue doctor --project myapp

# Triage
issue triage
issue triage --recommend

# Statistics
issue stats --project myapp

MCP Server (Agent Integration)

# Start MCP server over stdio (for Claude Code / agent integration)
issue mcp serve

# Show MCP configuration
issue mcp config

# List available tools
issue mcp tools

# Call a tool
issue mcp call issue_open --args '{"title":"Bug fix","project":"myapp"}'

Maintenance

# Rebuild index from markdown files
issue reindex

# Sync with remote (Supabase backend only)
issue sync
issue pull

# Show configuration
issue config

Issue Format

Each issue is a markdown file with YAML frontmatter:

---
id: 1
project: myapp
type: bug
state: open
severity: P2
reporter: user@example.com
assignee: coder-1
tags: [auth, security]
linked_specs: [SPEC-042]
linked_tests: [tests/unit/auth.test.ts]
linked_files: [src/auth.ts]
deps: [myapp#2]
created: 2026-06-05T10:00:00.000Z
updated: 2026-06-05T14:30:00.000Z
---

# Auth token refresh fails

## Description
The refresh endpoint returns 401 when token expires.

## Acceptance Criteria
- [ ] Refresh endpoint returns new token pair
- [ ] Expired refresh tokens are rejected

## Scratch Notes
- Investigated token flow
- Found race condition in refresh logic

## History
- 2026-06-05T10:00:00.000Z — opened by user@example.com (assigned: coder-1)
- 2026-06-05T11:00:00.000Z — in_progress (coder-1)

## Comments
- 2026-06-05T12:00:00.000Z (user@example.com): Found the root cause

Issue Lifecycle

backlog → planned → open → in_progress → review → resolved → verified → closed
                                    ↑            ↓
                                    ← blocked    → wontfix → closed
                                    ↑
                              blocked → open (when unblocked)

State Transitions

From	To	Command
open	in_progress	issue start <ref> or issue claim <ref> --agent <name>
in_progress	review	issue review <ref>
review	resolved	issue resolve <ref> --resolution "text"
resolved	verified	Automatic after 7 days (or issue verify <ref> --force)
verified	closed	issue close <ref>
any	blocked	issue block <ref> --reason "text"
blocked	open	issue unblock <ref>

Multi-Agent Workflow

1. Supervisor creates issue → reporter = git user email
2. Test-manager writes tests → linked_tests updated
3. Sprint-manager dispatches coder → issue claim <ref> --agent coder-1
4. Coder implements → scratch notes for investigation
5. Reviewer verifies → issue review <ref>
6. Supervisor closes → issue close <ref>

Agent Integration

Claude Code MCP

Add to .claude/settings.json:

{
  "mcpServers": {
    "issue-tracker": {
      "command": "issue",
      "args": ["mcp", "serve"]
    }
  }
}

Lifecycle Hooks

# In agent session start
issue hook session-start --project myapp

# Before context compaction
issue hook pre-compact --project myapp

# On session end
echo "Completed myapp#7" | issue hook stop

Stack

• TypeScript, Node.js 22, tsx (no build step)
• better-sqlite3, zod, gray-matter
• @supabase/supabase-js (optional remote sync)

Development

cd tools/issue-cli
npm install
npm test