/start

argument-hint: [agent-name | task-id | agent-name task-id]

/jat:start - Begin Working

**One agent = one session = one task.** Each Claude session handles exactly one task from start to completion.

Usage

/jat:start                      # Create agent, show available tasks
/jat:start task-id              # Create agent, start that task
/jat:start AgentName            # Resume as AgentName, show tasks
/jat:start AgentName task-id    # Resume as AgentName, start task

**Quick mode** (skip conflict checks): Add `quick` to any command.

---

What This Command Does

1. **Establish identity** - Use pre-registered agent (IDE-spawned) or create new (CLI) 2. **Select task** - From parameter or show recommendations 3. **Set session identity** - `/rename` auto via hook, `/color` hint in banner 4. **Search memory** - Surface relevant context from past sessions 5. **Review prior tasks** - Check for duplicates and related work 6. **Start work** - Declare reserved files (`--files`), claim file lease (`jat-lease-claim`), update task status, announce start 7. **Plan approach** - Analyze task, emit rich working signal 8. **Signal review when done** - ALWAYS emit `jat-signal review` before presenting results

---

Implementation Steps

> ⚡ **BEGIN WITH TOOL CALLS — NO TEXT PREAMBLE.** Do NOT write any explanatory text before your first tool call. Generating text before tools causes Claude Code to pause and wait for user input, breaking autonomous operation. Jump directly to ROUND 1 tool calls. > > ⚡ **DO NOT END YOUR TURN ON THE BANNER.** The banner is not the finish line — it is a status line printed *on the way into* the work. A turn that ends on text returns control to the composer and the session sits idle until a human types something. In the SAME assistant turn that prints the banner, continue straight into the first tool call of the actual task. See "After the Banner — Keep Going" below.

**IMPORTANT: Minimize LLM round-trips by issuing independent tool calls in parallel.**

The startup sequence is organized into 3 parallel rounds. Each round issues all its calls simultaneously in a single message, then processes the results before moving to the next round. This cuts startup from ~7 sequential turns to ~3.

hook auto        ROUND 1 (parallel) ──► ROUND 2 (parallel) ──► ROUND 3 (parallel) ──► Banner
/rename via      Identity               Starting signal        Task update (--files)  /color hint
sessionTitle     Task details           Memory search          Lease claim (3A.5)
                 Git status             Prior task search      Working signal (files)
                 Context audit
                 Project color (1E)
                 Worktree check (1G)

---

ROUND 1: Gather Context (all parallel)

**Issue ALL of these tool calls in a single message:**

1A: Identity — Pre-reg check + Session ID (one Bash call)

TMUX_SESSION=$(tmux display-message -p '#S' 2>/dev/null); PRE_REG_FILE=".claude/sessions/.tmux-agent-${TMUX_SESSION}"; test -f "$PRE_REG_FILE" && cat "$PRE_REG_FILE" || echo "NO_PRE_REG"

get-current-session-id

If `NO_PRE_REG` → manual/CLI session, must register (see Manual Registration below).

1B: Task Details (description + comments)

jt show "$TASK_ID" --json

The returned JSON includes `.comments[]` alongside `.description` — **scan both**. Devs direct agents through task comments during `/inbox` triage rather than editing the description (this preserves the reporter's verbatim text and the audit trail — see `ide/docs/inbox-design.md` "Comments as Input Pattern"). Pay particular attention to comments with `metadata.external == false` (internal notes): these are dev-to-agent direction that should shape your approach, and they override any guesses you'd make from the description alone.

**If no task-id was provided**, show recommendations and EXIT instead:

jt ready --json | jq -r '.[] | "  [\(.priority)] \(.id) - \(.title)"'

1C: Git Status

git branch --show-current && git diff-index --quiet HEAD -- && echo "clean" || echo "dirty"

1D: Context Audit

jt audit 2>&1 || true

This checks if the project follows the context injection standard (thin CLAUDE.md + always-inject bases). **Non-blocking** — warn in the banner but don't stop work.

1E: Project Color

PROJECT=$(git rev-parse --show-toplevel 2>/dev/null | xargs basename 2>/dev/null || echo "")
python3 -c "
import json, os, sys
try:
    cfg = json.load(open(os.path.expanduser('~/.config/jat/projects.json')))
    print(cfg.get('projects', {}).get(sys.argv[1], {}).get('active_color', ''))
except:
    print('')
" "$PROJECT" 2>/dev/null

Returns the project's `active_color` (e.g. `rgb(5588ff)` for jat). Used in the Session Identity step below.

1F: Overseer / Pilot

jat-overseer-for "$TASK_ID" --agent "$AGENT_NAME"

Prints who is watching this task — `DeepBeach732 (L2 pilot of mos-0a23k)`, `LightHeath (wave driver)`, or `n/a`. It checks all three registrations in the IDE's own precedence order (pilot mission → wave claim → fanout orchestrator), suppresses a self-match (nobody oversees the overseer), and **fails open to `n/a`** if the IDE is unreachable — it can never stall startup. `--json` for the structured form, `--name-only` for the bare name.

Pass `--agent` as the name you were invoked with (`/jat:start AgentName task-id`); omit it and the tool falls back to your own signal file. Use the output verbatim on the banner's `Overseer:` line. If you can't run it, print `Overseer: n/a` — never omit the line, and never guess a name.

1G: Worktree Awareness — where am I?

git rev-parse --git-dir --git-common-dir --show-toplevel --abbrev-ref HEAD 2>/dev/null

Per-agent git-worktree isolation (`specs/prd-merge-queue.md`) is the spawn default: `--git-dir` and `--git-common-dir` differ in a linked worktree (`--git-dir` resolves to `.../.git/worktrees/<name>`)