Claude Code Skill for Ticket House

# Ticket House

This project uses **Ticket House** for AI-assisted development. Work is organized into tickets, each with its own git worktree and branch.

## How It Works

1. A remote Ticket House server manages tickets for the project
2. A local **workstation** (`npx ticket-house`) connects your repo to the server
3. When you start work on a ticket, a **git worktree** is created at `.ticket-house/worktrees/<name>/` with its own branch
4. You work inside the worktree, commit, push, and the ticket tracks your progress

## Your Working Environment

- You are working inside a **worktree** — an isolated copy of the repo with its own branch
- The worktree lives under `.ticket-house/worktrees/` relative to the main repo root
- The branch name is derived from the ticket (e.g., `ma-42-fix-login-bug`)
- Do **not** modify files outside your worktree
- Shared files like `.env` may be symlinked from the repo root — do not delete or replace symlinks with regular files

To find the main repo root from within a worktree:

```bash
git worktree list
```

## Configuration

The project's Ticket House configuration is in `.ticket-house.json` at the repo root. Key sections:

- **`remote`** — URL of the Ticket House server project endpoint (required)
- **`environments`** — deployment environments with URLs for health monitoring
- **`container`** — container pool settings (image, ports, idle pool size)
- **`devWatch`** — symlink-based file watching for hot-reload dev servers
- **`hooks`** — lifecycle scripts for worktree and track events
- **`worktrees`** — storage limits, cleanup delay, shared file symlinks
- **`commands`** — auto-start scripts for workstation launch
- **`logFile`** — path for workstation log output

Read `.ticket-house.json` to understand the project's specific setup before making configuration changes.

## Hooks

If the project uses hooks, they are defined in `.ticket-house.json` under `hooks`:

| Hook | When | Arguments |
|------|------|-----------|
| `post-worktree-create` | After worktree is created | `$1` worktree path, `$2` ticket ID, `$3` branch name |
| `pre-worktree-remove` | Before worktree is removed | Same as above |
| `post-track-activate` | After symlinks created for Dev Watch | Same as above |
| `pre-track-deactivate` | Before symlinks removed when ejecting | Same as above |

The `REPO_ROOT` environment variable is set for all hooks. Hook scripts have a 30-second timeout.

## Dev Watch

If `devWatch` is configured, source directories are symlinked from the active worktree into a work directory (default: `work/`). A dev process watches this directory for changes.

- Do **not** modify files in `work/` directly — edit them in the worktree
- When you switch tracks, the symlinks are re-pointed automatically
- The dev process environment receives `TICKET_HOUSE_WORK_DIR`, `TICKET_HOUSE_ACTIVE_WORKTREE`, and `TICKET_HOUSE_ACTIVE_TICKET`

## CLI

Start the workstation from the project root:

```bash
npx ticket-house
```

Common flags:
- `--port <number>` — server port (default: 3412)
- `--data-dir <path>` — override data directory (default: `.ticket-house/`)
- `--debug` — enable debug logging
- `--log-file <path>` — write logs to file

Tickets are managed through the **web UI** (opens automatically) or the **Ticket House server API**, not through CLI commands directly.

## Best Practices

- **Stay in your worktree.** All changes should happen within the worktree directory.
- **Commit and push** before finishing work on a ticket so progress is tracked.
- **Keep changes scoped** to the ticket's requirements — avoid unrelated refactors.
- **Read `.ticket-house.json`** before modifying project configuration.
- **Check for shared symlinks** — if `.env` or similar files are symlinked, they are shared across worktrees. Changes affect all worktrees.
- **Don't delete `.ticket-house/`** — it contains worktrees, audit logs, and runtime state.