bits

What this skill does

# Bits Task Tracking

## Bits Are Immutable

Once created, bits cannot be updated. This means:

- **No checkboxes** in descriptions (you can't check them off)
- **No sub-tasks** in descriptions (you can't mark them complete)
- **No progress tracking** within a single bit

**Instead:** Create more bits. They're free. Break work into atomic pieces and link them with dependencies using `bits dep <id> <blocker-id>`.

```bash
# Bad: One bit with checkboxes
bits add "Implement auth" -d "- [ ] Add login\n- [ ] Add logout\n- [ ] Add session"

# Good: Multiple linked bits
bits add "Add login endpoint" -d "POST /login with JWT" --json
bits add "Add logout endpoint" -d "POST /logout invalidates token" --json
bits add "Add session middleware" -d "Validate JWT on protected routes" --json
bits dep <logout-id> <login-id>
bits dep <session-id> <login-id>
```

## When to Use

| Scenario | Tool |
|----------|------|
| Multi-step work with dependencies | bits |
| Tasks that block other tasks | bits |
| Tracking progress across sessions | bits |
| Simple one-off checklist | TaskCreate |
| Quick session-scoped todos | TaskCreate |

## Commands

| Task | Command |
|------|---------|
| Find ready work | `bits ready --json` |
| Create task | `bits add "Title" -d "Description" --json` |
| Start work | `bits claim <id>` |
| Pause work | `bits release <id>` |
| Complete work | `bits close <id> "reason"` |
| View details | `bits show <id>` |
| List tasks | `bits list` |

Run `bits --help` for full reference.

## Dependencies

```bash
bits add "Feature B" --json  # Returns: bits-abc123
bits dep bits-abc123 bits-blocker  # B blocked by blocker
```

Tasks with unresolved dependencies won't appear in `bits ready`.

## Session Commands

| Command | Purpose |
|---------|---------|
| `bits session claim` | Claim primary session (reads stdin) |
| `bits session release` | Release session (reads stdin) |
| `bits session prune` | Manual cleanup of stale sessions |
| `bits session hook` | Stop hook with session ownership check |
| `bits session compact` | Output drain context after compaction (for hooks) |

## Drain Commands

| Command | Purpose |
|---------|---------|
| `bits drain claim` | Activate drain mode |
| `bits drain release` | Deactivate drain mode (fails if tasks remain) |
| `bits drain release --force` | Suspend drain mode (for replan/escalation) |

## Task Description Format

```markdown
# Context
What this task solves and why.

# Acceptance Criteria
Concrete conditions that must be true when done:
- Criterion 1
- Criterion 2

# Verification Commands
- `mise run lint`
- `mise run test`
```

Do not use checkboxes in descriptions — bits are immutable so checkboxes cannot be checked off. State criteria as plain text.

## Do NOT Close If

- Tests failing
- Implementation partial
- Unresolved errors

Instead: Create new blocker bits and add them as dependencies.