tix

Files (2)

• SKILL.md
• tix-status.sh · scripts/

SKILL.md (first lines)

# Using tix - Git-Based Ticket Management

Use this skill when managing tasks, issues, and notes through the `tix` CLI. tix is a high-performance C binary for git-based ticket management, reading and writing `.tix/plan.jsonl` (with legacy fallback to `ralph/plan.jsonl`).

## Quick Reference

```bash
tix init                          # Initialize .tix/ in current repo
tix status                        # Human-readable dashboard
tix query                         # Full state as JSON
tix task add '<json>'             # Add task(s)
tix task done [id]                # Mark task done
tix task accept <id>              # Accept done task
tix task reject <id> "reason"     # Reject done task
tix task update <id> '<json>'     # Update fields on existing ticket
tix issue add '<json>'            # Add issue
tix issue done [id]               # Resolve issue
tix search "keywords"             # Search tickets
tix tree [id]                     # Dependency tree
tix report                        # Progress report
tix validate                      # Integrity check
tix log                           # Git history of plan changes
tix sync [branch|--all]           # Sync cache from git history
tix compact                       # Sync + compact plan.jsonl
```

## Data Flow

```
.tix/plan.jsonl  <---->  tix  <---->  .tix/cache.db (SQLite)
      |                                      |
   git tracked                          gitignored
   (primary storage)                    (read cache)
```

tix reads/writes `.tix/plan.jsonl` (the git-tracked source of truth) and caches state in `.tix/cache.db` for fast reads. The cache is rebuilt automatically when plan.jsonl changes or the schema version bumps.

## Task Management

### Adding Tasks

Single task:
```bash
tix task add '{"name": "Implement feature X", "spec": "my-spec.md", "notes": "Details here", "accept": "tests pass", "priority": "high", "labels": ["module:core", "epic:v2"]}'
```

Batch add (faster, supports intra-batch dependencies):
```bash
tix task add '[
  {"name": "Create module A", "spec": "feature.md", "accept": "import works"},
  {"name": "Create module B", "spec": "feature.md", "accept": "import works", "deps": ["t-previous"]}
]'
```

### Task Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Short description |
| `spec` | No | Spec file this belongs to |
| `notes` | No | Implementation details |
| `accept` | No | Acceptance criteria |
| `deps` | No | Array of dependency task IDs |
| `labels` | No | Array of freeform label strings (max 16, e.g. `"module:parser"`) |
| `priority` | No | `"high"`, `"medium"`, or `"low"` |
| `parent` | No | Decomposed from task ID |
| `created_from` | No | Created from issue ID |
| `supersedes` | No | Replaces task ID |

### Auto-filled Fields

These fields are populated automatically by tix:

| Field | When | Source |
|-------|------|--------|
| `author` | Ticket creation | `git config user.name` |
| `completed_at` | Task marked done | ISO 8601 timestamp with timezone |
| `branch` | Ticket creation/update | Current git branch |

### Agent Telemetry Fields

These fields are populated by the orchestrator (via `tix task update`) after stage completion:

| Field | Type | Description |
|-------|------|-------------|
| `cost` | float | Total dollar cost for this task |
| `tokens_in` | int | Total input tokens consumed |
| `tokens_out` | int | Total output tokens consumed |
| `iterations` | int | Construct loop iterations |
| `model` | string | Model used (e.g. `"claude-sonnet-4-20250514"`) |
| `retries` | int | Retries after failure before success |
| `kill_count` | int | Times iteration was killed before success |

### Task Lifecycle

```
pending -> done -> accepted (tombstone created)
                -> rejected (tombstone created, may retry)
```

```bash
tix task done                     # Mark current/first pending task done
tix task done t-a1b2c3d4          # Mark specific task done
tix task accept t-a1b2c3d4        # Accept after verification
tix task reject t-a1b2c3d4 "Tests fail on edge case"
tix task delete t-a1b2c3d4        # Remove task entirely
tix task prioritize t-a1b2c3d4 high  # Set priority
tix task update t-a1b2c3d4 '{"cost": 0.52, "tokens_in": 50000}'  # Attach telemetry
tix task update t-a1b2c3d4 '{"labels": ["module:parser", "epic:auth"]}'  # Set labels
```

## Issue Management

Issues are lightweight items for the INVESTIGATE stage:

```bash
tix issue add '{"desc":"Memory leak in parser module"}'
tix issue done                    # Resolve first issue
tix issue done i-a1b2c3d4         # Resolve specific issue

From djmittens/neo-mittens, MIT.

More from djmittens/neo-mittens