@codefilabs/tq 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codefilabs/tq",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A lightweight task queue runner that spawns Claude AI tasks as independent tmux sessions",
   "keywords": [
     "claude",

package/skills/tq/SKILL.md

@@ -3,66 +3,92 @@ name: tq
 description: >
   This skill should be used when the user asks to "add to queue", "run queue", "queue these tasks",
   "schedule with tq", "tq status", "check task queue", "create a tq queue", "set up cron for tq",
-  "run claude in background", "batch prompts in tmux", "start a conversation", "converse via telegram",
-  "telegram conversation mode", or wants to manage Claude prompts running in tmux sessions via the
-  tq CLI tool. Triggers on phrases like "queue", "tq", "task queue", "tmux queue", "scheduled claude tasks",
-  "conversation mode", "telegram chat", "converse".
-version: 1.1.0
+  "run claude in background", "batch prompts in tmux", "start a conversation", "start conversation mode",
+  "converse via telegram", "telegram conversation mode", "telegram bot", "message routing",
+  "route a message", "spawn a session", "orchestrator", "reset tasks", "reset queue",
+  "notify on completion", "tq notification", "tq health", "check tq health", "tq setup",
+  "setup telegram bot", "tq install", or wants to manage Claude prompts running
+  in tmux sessions via the tq CLI tool. Triggers on phrases like "queue", "tq", "task queue",
+  "tmux queue", "scheduled claude tasks", "conversation mode", "telegram chat", "converse",
+  "telegram session", "poll telegram", "tq-converse", "tq-message", "task notification".
+version: 1.5.0
 ---
 
-# tq — Claude Task Queue Runner
+# tq -- Claude Task Queue Runner
 
 Script: `${CLAUDE_PLUGIN_ROOT}/scripts/tq`
 
-Installed to PATH via `/install`: `/opt/homebrew/bin/tq`
+Installed to PATH via `/install` (typically `/opt/homebrew/bin/tq` or `/usr/local/bin/tq`; use `command -v tq` to resolve)
 
 ## Overview
 
 tq manages Claude Code sessions via tmux in two modes:
-1. **Queue mode** — batches prompts into YAML queue files, spawns each as an independent tmux session. Idempotent — running `tq` again skips `done` and live `running` tasks.
-2. **Conversation mode** — persistent interactive Claude Code sessions orchestrated via Telegram. An orchestrator routes messages to the right conversation, creating new sessions or resuming existing ones.
+
+1. **Queue mode** -- batch prompts into YAML queue files, spawn each as an independent tmux session. Idempotent: re-running `tq` skips `done` and live `running` tasks.
+2. **Conversation mode** -- maintain persistent interactive Claude Code sessions orchestrated via Telegram. An orchestrator routes messages to the right conversation, spawning new sessions or resuming existing ones.
 
 ## Queue File Format
 
 Location: `~/.tq/queues/<name>.yaml`
 
 ```yaml
-cwd: /path/to/working/directory   # optional — where claude runs for each task
+schedule: "0 9 * * *"              # optional -- auto-managed crontab via tq-cron-sync
+reset: daily                        # optional -- daily|weekly|hourly|always|on-complete
+cwd: /path/to/working/directory     # where claude runs for each task
+message:                            # optional -- notification config
+  service: telegram
+  content: summary                  # summary|status|details|log
 tasks:
-  - prompt: fix the login bug in auth service
+  - name: review-auth               # optional -- used for session naming
+    prompt: fix the login bug in auth service
   - prompt: write unit tests for payment module
 ```
 
-Queue files are **read-only** — tq never modifies them.
+Queue files are read-only -- tq never modifies them.
+
+### Reset Modes
+
+Reset controls when task state is cleared so tasks re-run:
+
+| Mode | Behavior |
+|------|----------|
+| `daily` | Clear once per calendar day |
+| `weekly` | Clear once per ISO week |
+| `hourly` | Clear once per hour |
+| `always` | Clear on every `tq` run |
+| `on-complete` | Per-task: delete state after task finishes |
 
 ## State
 
-State dir: `~/.tq/queues/.tq/<queue-basename>/`
-One file per task, named by 8-char shasum of the prompt:
+State dir: `<queue-dir>/.tq/<queue-basename>/` (e.g., `~/.tq/queues/.tq/morning/`)
+One file per task, named by 8-char SHA-256 of the prompt:
 
 ```
 status=running
-session=fix-the-login-23451
+session=tq-fix-the-login-451234
 window=fix-the
 prompt=fix the login bug in auth service
 started=2026-03-05T10:00:00
 ```
 
-Statuses: `pending` → `running` → `done`
+Statuses: `pending` -> `running` -> `done`
 
 ## Commands
 
 | Command | Purpose |
 |---------|---------|
-| `/todo <natural language>` | Create/update queue + optionally schedule |
+| `/todo <natural language>` | Create/update queue and optionally schedule |
 | `/schedule <natural language>` | Add/update cron schedule for a queue |
 | `/pause <queue>` | Remove run line, keep status-check (resume with `/schedule`) |
 | `/unschedule <queue>` | Remove all cron lines for a queue |
 | `/jobs [filter]` | List all scheduled tq cron jobs |
-| `/health [queue]` | System-wide diagnostics |
+| `/health [queue]` | Run system-wide diagnostics |
 | `/install` | Symlink tq binaries to PATH |
-| `/converse [start\|stop\|status]` | Manage Telegram conversation sessions |
+| `/init` | Configure workspace directories and build project catalog |
+| `/review` | Lint and review staged changes before commit |
+| `/converse [start\|stop\|status\|list]` | Manage conversation orchestrator and sessions |
 | `/tq-reply` | Send response back to Telegram (conversation mode) |
+| `/tq-message` | Write and send task completion summary |
 | `/setup-telegram` | Configure Telegram bot token and notifications |
 
 ## CLI Usage
@@ -72,73 +98,77 @@ tq <queue.yaml>           # spawn pending tasks in tmux; skip running/done
 tq --status <queue.yaml>  # print status table; flip dead sessions to done
 ```
 
-## Crontab Pattern
+## Cron Scheduling
+
+Add `schedule:` to any queue YAML and `tq-cron-sync` auto-manages crontab (runs every 20 min, scans `~/.tq/queues/*.yaml`). Each scheduled queue gets two cron lines:
 
 ```cron
-0 9 * * * /opt/homebrew/bin/tq ~/.tq/queues/morning.yaml >> ~/.tq/logs/tq.log 2>&1
-*/30 * * * * /opt/homebrew/bin/tq --status ~/.tq/queues/morning.yaml >> ~/.tq/logs/tq.log 2>&1
+<schedule> $(command -v tq) ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1
+*/30 * * * * $(command -v tq) --status ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1
 ```
 
-The `tq --status` cron runs every 30 min to reap dead sessions and flip their state to `done`.
+The `tq --status` line runs every 30 min to reap dead sessions and flip their state to `done`.
+
+See `references/cron-expressions.md` for natural language to cron mapping.
 
 ## Queue Name Inference
 
 When using `/todo` without an explicit queue name:
 
-- Schedule keyword present → use it: "every morning" → `morning`, "daily" → `daily`, "weekly" → `weekly`
-- No schedule → use `basename` of current working directory
+- Schedule keyword present -> derive from it: "every morning" -> `morning`, "daily" -> `daily`, "weekly" -> `weekly`
+- No schedule -> use `basename` of current working directory
 
 ## Reset
 
 - One task: delete its state file from `.tq/<queue-basename>/`
 - Entire queue: `rm -rf ~/.tq/queues/.tq/<queue-basename>/`
 
-## Chrome Integration
-
-tq launches claude with `--chrome` and opens **Chrome Profile 5** (halbotkirchner@gmail.com) automatically before connecting.
-
-### Multiple Chrome profiles / extensions
-
-If you need to interact with a Chrome profile that has a different Claude extension instance (e.g. different account), use the `chrome-devtools` MCP with the `--isolated` flag to run isolated browser extension sessions that don't conflict across profiles.
-
-### Setting the browser display name
-
-The Claude extension stores the browser name as `bridgeDisplayName` in the extension's `chrome.storage.local`. To set it for the first time on a profile:
-- Right-click the Claude extension icon in the Chrome toolbar → **Options**
-- Or open the sidepanel and look for a settings/gear icon with a name field
-
 ## Conversation Mode
 
-Start an orchestrator: `tq-converse start` or send `/converse` from Telegram.
+Start the orchestrator via `tq-converse start` or send `/converse` from Telegram.
+
+The orchestrator routes incoming Telegram messages using 3-tier routing:
 
-The orchestrator routes incoming Telegram messages to the appropriate conversation session:
-- Telegram reply to a known message → routes to that session automatically
-- `#slug message` → routes to the named session
-- New topic → orchestrator spawns a new session with a descriptive slug
+1. **Reply threading** -- Telegram reply to a known message routes to that session automatically
+2. **Slug prefix** -- `#slug message` routes to the named session
+3. **Orchestrator fallback** -- new topic triggers the orchestrator to spawn a new session with a descriptive slug
 
 Each conversation is a persistent Claude Code interactive session in its own tmux window.
 Child sessions use `/tq-reply` to send responses back to Telegram as threaded replies.
 
-### Conversation CLI
+### Key CLI commands
 
 ```bash
 tq-converse start                         # start orchestrator
-tq-converse spawn <slug> --cwd <dir>      # new conversation session
-tq-converse route <slug> <message>        # send to a session
+tq-converse spawn <slug> --cwd <dir>      # create new conversation session
+tq-converse route <slug> <message>        # send message to a session
 tq-converse list                          # list active sessions
+tq-converse status                        # show all session statuses
 tq-converse stop [<slug>]                 # stop session or orchestrator
 ```
 
-### Telegram Commands
+## Background Scripts
 
-| Command | Purpose |
-|---------|---------|
-| `/converse` | Start the orchestrator |
-| `/stop [slug]` | Stop orchestrator or a specific session |
-| `/status` | Show all sessions |
-| `/list` | List active conversations |
+| Script | Purpose |
+|--------|---------|
+| `tq-cron-sync` | Scans `~/.tq/queues/*.yaml` every 20 min, syncs `schedule:` to crontab |
+| `tq-telegram-poll` | Long-polls Telegram, routes messages via 3-tier routing |
+| `tq-telegram-watchdog` | Ensures poll cron entry exists |
+| `tq-message` | Sends notifications (Telegram/Slack) on task completion |
+
+## Troubleshooting
+
+| Problem | Likely Cause | Fix |
+|---------|-------------|-----|
+| Tasks stuck in `running` | tmux session died | Run `tq --status <queue>` to reap dead sessions |
+| `tq` command not found | Not installed to PATH | Run `/install` |
+| Queue runs but nothing happens | All tasks already `done` | Delete state: `rm -rf <queue-dir>/.tq/<name>/` |
+| Cron not firing | `tq-cron-sync` not running or schedule missing | Check `crontab -l \| grep tq` and add `schedule:` to queue YAML |
+| Telegram messages not routing | Orchestrator not running | Run `/converse start` |
+| Malformed YAML | Parser does not support anchors | Use only `cwd`, `tasks`, `schedule`, `reset`, `message` top-level keys |
 
 ## Additional Resources
 
-- **`references/session-naming.md`** — Session/window name generation algorithm and examples
-- **`references/cron-expressions.md`** — Natural language → cron expression mapping table
+- **`references/session-naming.md`** -- session/window name generation algorithm and examples
+- **`references/cron-expressions.md`** -- natural language to cron expression mapping table
+- **`references/chrome-integration.md`** -- Chrome `--chrome` flag, profile setup, and browser configuration

package/skills/tq/references/chrome-integration.md

@@ -0,0 +1,52 @@
+# tq Chrome Integration Reference
+
+## When to Use Chrome
+
+Chrome integration is for tasks that interact with web pages (scraping, form filling, visual verification). Most queue tasks that only modify code do **not** need Chrome.
+
+## How `--chrome` Works
+
+When a queue task runs, tq generates a `.launch.py` launcher script that:
+
+1. Opens Chrome with the configured profile directory
+2. Passes `--chrome` to the `claude` CLI, connecting to the Chrome browser extension
+3. Claude interacts with web pages through the browser
+
+```python
+# In the generated .launch.py:
+subprocess.Popen(["open", "-a", "Google Chrome", "--args", "--profile-directory=<ProfileDir>"])
+time.sleep(2)
+os.execvp('claude', ['claude', '--settings', settings_file, '--dangerously-skip-permissions', '--chrome', prompt])
+```
+
+Note: `subprocess.Popen` is correct here (launches Chrome as a sibling process). `os.execvp` replaces the Python process with Claude (per `anti-patterns.md`).
+
+## Chrome Profile Configuration
+
+The Chrome profile directory is hardcoded in `scripts/tq` in the launcher generation section. To find which profile directory maps to which account:
+
+```bash
+for d in ~/Library/Application\ Support/Google/Chrome/Profile*/; do
+  python3 -c "import json; p=json.load(open('$d/Preferences')); print('$(basename $d):', p.get('account_info',[{}])[0].get('email','unknown'))" 2>/dev/null
+done
+```
+
+To use a different profile, edit the `--profile-directory` argument in `scripts/tq`. The profile is not yet configurable per-queue.
+
+## Browser Display Name
+
+The Claude browser extension identifies itself via `bridgeDisplayName` in `chrome.storage.local`. Set it via the extension's Options page (right-click extension icon > Options).
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Chrome doesn't open | Chrome not installed or not at expected path | Verify: `ls /Applications/Google\ Chrome.app` |
+| Extension not connecting | Claude extension not installed in the target profile | Install the Claude Code extension in Chrome, then retry |
+| Wrong profile used | Hardcoded profile doesn't match intended account | Run the profile discovery command above, update `scripts/tq` |
+| `--chrome` flag ignored | Task launched without Chrome integration | Check the launcher generation section in `scripts/tq` |
+
+## Related
+
+- **SKILL.md** — overview of tq modes and CLI usage
+- **session-naming.md** — how tmux session names are derived

package/skills/tq/references/cron-expressions.md

@@ -1,20 +1,29 @@
 # tq Cron Expression Reference
 
-## Natural Language → Cron Mapping
+All cron expressions use the **system timezone** (check with `date +%Z`). There is no per-queue timezone override.
+
+## Natural Language to Cron Mapping
 
 | Natural Language | Cron Expression | Notes |
 |-----------------|-----------------|-------|
 | "every morning" / "daily at 9am" | `0 9 * * *` | Default morning time |
 | "every night" / "nightly" | `0 22 * * *` | 10pm |
-| "every weekday" | `0 9 * * 1-5` | Mon–Fri at 9am |
-| "every weekday at 6pm" | `0 18 * * 1-5` | Mon–Fri at 6pm |
+| "every weekday" | `0 9 * * 1-5` | Mon-Fri at 9am |
+| "every weekday at 6pm" | `0 18 * * 1-5` | Mon-Fri at 6pm |
 | "every monday" / "weekly on mondays" | `0 9 * * 1` | 9am Monday |
 | "every monday at 8am" | `0 8 * * 1` | 8am Monday |
+| "weekends" / "every weekend" | `0 10 * * 0,6` | Sat & Sun at 10am |
 | "every hour" / "hourly" | `0 * * * *` | Top of each hour |
+| "every 2 hours" | `0 */2 * * *` | Every 2 hours |
 | "every 4 hours" | `0 */4 * * *` | Every 4 hours |
 | "every 30 minutes" | `*/30 * * * *` | Every 30 min |
+| "every 15 minutes" | `*/15 * * * *` | Every 15 min |
+| "every 5 minutes" | `*/5 * * * *` | Every 5 min |
+| "twice daily" / "morning and evening" | `0 9,18 * * *` | 9am and 6pm |
+| "business hours" | `0 9-17 * * 1-5` | Every hour 9am-5pm Mon-Fri |
 | "daily" | `0 9 * * *` | Default to 9am |
 | "weekly" | `0 9 * * 1` | Default to Monday 9am |
+| "first of the month" | `0 9 1 * *` | 9am on the 1st |
 
 ## Day-of-Week Numbers
 
@@ -28,31 +37,17 @@
 | 5 | Friday |
 | 6 | Saturday |
 
-## Standard tq Crontab Block
-
-Every scheduled queue gets two cron lines:
-
-```cron
-# Run queue (spawn pending tasks)
-<cron> /opt/homebrew/bin/tq ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1
-
-# Status sweep (reap dead sessions every 30 min)
-*/30 * * * * /opt/homebrew/bin/tq --status ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1
-```
-
-## Updating Crontab
+## Crontab Management
 
-Replace existing lines for the same queue:
+`tq-cron-sync` automatically manages crontab entries — see SKILL.md for details. For manual override, filter out old entries before appending:
 
 ```bash
-(crontab -l 2>/dev/null | grep -v "tq.*<name>.yaml"; \
-  echo "<cron> /opt/homebrew/bin/tq ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1"; \
-  echo "*/30 * * * * /opt/homebrew/bin/tq --status ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1") | crontab -
+(crontab -l 2>/dev/null | grep -v "tq.*/<name>\.yaml"; \
+  echo "<cron> $(command -v tq) ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1"; \
+  echo "*/30 * * * * $(command -v tq) --status ~/.tq/queues/<name>.yaml >> ~/.tq/logs/tq.log 2>&1") | crontab -
 ```
 
-The `grep -v` removes all existing lines referencing this queue before appending the new ones, ensuring no duplicates.
-
-## Queue Name → Schedule Name Inference
+## Queue Name Inference
 
 When no queue name is given, infer from the schedule keyword:
 
@@ -65,3 +60,5 @@ When no queue name is given, infer from the schedule keyword:
 | "hourly" / "every hour" | `hourly` |
 | "nightly" / "night" | `nightly` |
 | no schedule | `basename` of current working directory |
+
+Related: `/schedule` and `/todo` use this mapping. `/jobs` displays active schedules.

package/skills/tq/references/session-naming.md

@@ -2,56 +2,85 @@
 
 ## Algorithm
 
-Given a prompt string, derive a tmux session name and window name as follows:
+Given a task, derive a tmux session name and window name. The YAML `name` field takes priority over prompt-derived words.
+
+### Source Text
+
+1. If the task has a `name:` field in the YAML, use that as the full source text
+2. Otherwise, use the first line of the prompt
 
 ### Session Name
-1. Take the first 3 words of the prompt
+
+1. If using `name:` field: take the full field value. If using prompt: take the first 3 words
 2. Lowercase everything
 3. Replace any non-`[a-z0-9]` character with `-`
-4. Strip trailing `-` characters
+4. Strip leading and trailing `-` characters
 5. Truncate to 20 characters
-6. Append `-<epoch-suffix>` (last 6 digits of Unix epoch)
+6. Prepend `tq-` and append `-<epoch-suffix>` (last 6 digits of Unix epoch)
+
+Result: `tq-<base>-<epoch>`
 
 ### Window Name
-1. Take the first 2 words of the prompt
-2. Same lowercasing and character replacement as above
-3. Truncate to 15 characters (no epoch suffix)
+
+1. If using `name:` field: take the full field value. If using prompt: take the first 2 words
+2. Apply the same lowercasing, character replacement, and dash stripping as above
+3. Truncate to 15 characters (no prefix, no epoch suffix)
 
 ## Examples
 
+### Without `name:` field (prompt-derived)
+
 | Prompt | Session | Window |
 |--------|---------|--------|
-| `fix the login bug in auth service` | `fix-the-login-<epoch>` | `fix-the` |
-| `write unit tests for payment module` | `write-unit-tests-<epoch>` | `write-unit` |
-| `Refactor Auth Module` | `refactor-auth-module-<epoch>` | `refactor-auth` |
-| `check LinkedIn saved posts` | `check-linkedin-saved-<epoch>` | `check-linkedin` |
+| `fix the login bug in auth service` | `tq-fix-the-login-451234` | `fix-the` |
+| `write unit tests for payment module` | `tq-write-unit-tests-451234` | `write-unit` |
+| `Refactor Auth Module` | `tq-refactor-auth-module-451234` | `refactor-auth` |
+
+### With `name:` field
+
+| Name Field | Session | Window |
+|------------|---------|--------|
+| `review-auth` | `tq-review-auth-451234` | `review-auth` |
+| `Update Readme` | `tq-update-readme-451234` | `update-readme` |
 
 ## Bash Implementation
 
 ```bash
 EPOCH_SUFFIX="$(date +%s | tail -c 6)"
-SESSION_BASE="$(echo "$PROMPT" | awk '{print $1" "$2" "$3}' \
-  | tr '[:upper:]' '[:lower:]' \
-  | tr -cs 'a-z0-9' '-' \
-  | sed 's/-*$//' \
-  | cut -c1-20)"
-SESSION="${SESSION_BASE}-${EPOCH_SUFFIX}"
-WINDOW="$(echo "$PROMPT" | awk '{print $1" "$2}' \
-  | tr '[:upper:]' '[:lower:]' \
-  | tr -cs 'a-z0-9' '-' \
-  | sed 's/-*$//' \
-  | cut -c1-15)"
+
+# With name field:
+if [[ -n "$TASK_NAME_FIELD" ]]; then
+  SESSION_BASE="$(echo "$TASK_NAME_FIELD" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//' | sed 's/-*$//' | cut -c1-20)"
+  WINDOW="$(echo "$TASK_NAME_FIELD" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//' | sed 's/-*$//' | cut -c1-15)"
+else
+  # Without name field (prompt-derived):
+  SESSION_BASE="$(echo "$FIRST_LINE" | awk '{print $1" "$2" "$3}' | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//' | sed 's/-*$//' | cut -c1-20)"
+  WINDOW="$(echo "$FIRST_LINE" | awk '{print $1" "$2}' | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//' | sed 's/-*$//' | cut -c1-15)"
+fi
+
+SESSION="tq-${SESSION_BASE}-${EPOCH_SUFFIX}"
 ```
 
+## Edge Cases
+
+| Input | Session Base | Reason |
+|-------|-------------|--------|
+| 1-word prompt: `deploy` | `deploy` | Uses the single word as-is |
+| 2-word prompt: `fix bug` | `fix-bug` | Uses both words (fewer than 3) |
+| Empty prompt | (empty string) | Produces `tq--<epoch>` — malformed; avoid empty prompts |
+| Special chars: `fix "the" bug!` | `fix-the-bug-` | Quotes and punctuation replaced with `-` |
+| Very long name field | Truncated to 20 chars | `cut -c1-20` limits length |
+
 ## Notes
 
-- Epoch suffix prevents collision when the same prompt is re-queued after a reset
-- tmux session names must not contain `.` or `:` — the character replacement handles this
-- The `-` separator between base and epoch is always present; if the base ends with `-`, it gets stripped first to avoid `--`
+- The epoch suffix prevents collision when the same prompt is re-queued after a reset
+- tmux session names must not contain `.` or `:` -- the character replacement handles this
+- The `-` separator between base and epoch is always present; if the base ends with `-`, strip it first to avoid `--`
+- The `tail -c 6` approach for epoch suffix always produces 6 digits since Unix timestamps are 10+ digits
 
 ## Conversation Mode Session Names
 
-Conversation sessions use a different naming scheme — slug-based, no epoch suffix:
+Conversation sessions use a slug-based naming scheme with no epoch suffix:
 
 | Type | Pattern | Example |
 |------|---------|---------|
@@ -59,8 +88,6 @@ Conversation sessions use a different naming scheme — slug-based, no epoch suf
 | Child session | `tq-conv-<slug>` | `tq-conv-fix-auth` |
 | Child window | `<slug>` | `fix-auth` |
 
-Slugs are short kebab-case names (2-4 words) chosen by the orchestrator Claude when a
-new conversation is created. Examples: `fix-auth-bug`, `refactor-api`, `update-docs`.
+Slugs are short kebab-case names (2-4 words) chosen by the orchestrator Claude when creating a new conversation. Examples: `fix-auth-bug`, `refactor-api`, `update-docs`.
 
-Since there is no epoch suffix, conversation session names are unique by slug. Starting
-a session with an already-active slug will reuse the existing session.
+Since there is no epoch suffix, conversation session names are unique by slug. Starting a session with an already-active slug reuses the existing session.