---
id: joewinke/jat/jat-start
version: "9660a684"
license: MIT
install: manual
updated: 2026-07-27
---

# jat-start — jat-start initializes a new work session by registering agent identity, selecting a task, and surfacing relevant context from past sessions. It checks for duplicate or conflicting work, declares files, and emits IDE signals to track session state. Run this at the beginning of every JAT session.

Publisher: joewinke · Stars: 248 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/joewinke/jat`

## SKILL.md

# /skill:jat-start - Begin Working

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

## Usage

```
/skill:jat-start                    # Show available tasks
/skill:jat-start task-id            # Start specific task
/skill:jat-start AgentName          # Resume as AgentName
/skill:jat-start AgentName task-id  # Resume as AgentName on task
```

Add `quick` to skip conflict checks.

## What This Does

1. **Establish identity** - Register or resume agent in Agent Registry
2. **Select task** - From parameter or show recommendations
3. **Search memory** - Surface context from past sessions
4. **Review prior tasks** - Check for duplicates and related work
5. **Start work** - Declare files, update task status
6. **Emit signals** - IDE tracks state through jat-signal

## Step-by-Step Instructions

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

Startup uses 3 parallel rounds. Each round issues all calls simultaneously, then processes results before the next round.

```
ROUND 1 (parallel) → ROUND 2 (parallel) → ROUND 3 (parallel) → Banner
  Identity              Starting signal       Task update
  Task details          Memory search          Working signal
  Git status            Prior task search      Integration sync
```

### ROUND 1: Gather Context (all parallel)

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

**1A: Identity** — Check for IDE pre-registration + get session ID:
```bash
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"
```
```bash
get-current-session-id
```

**1B: Task details** (if task-id provided):
```bash
jt show "$TASK_ID" --json
```
If no task-id, show `jt ready` and stop here.

**1C: Git status:**
```bash
git branch --show-current && git diff-index --quiet HEAD -- && echo "clean" || echo "dirty"
```

**Manual Registration** (only if `NO_PRE_REG`):
```bash
am-register --name "$AGENT_NAME" --program pi --model "$MODEL_ID"
tmux rename-session "jat-${AGENT_NAME}" 2>/dev/null
mkdir -p .claude/sessions
echo "$AGENT_NAME" > ".claude/sessions/agent-${SESSION_ID}.txt"
```

### ROUND 2: Signal + Context Search (all parallel)

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

**2A: Starting signal:**
```bash
jat-signal starting '{
  "agentName": "NAME", "sessionId": "ID", "taskId": "TASK_ID",
  "taskTitle": "TITLE", "project": "PROJECT", "model": "MODEL_ID",
  "tools": ["bash","read","write","edit"], "gitBranch": "BRANCH",
  "gitStatus": "clean", "uncommittedFiles": []
}'
```

**2B: Memory search:**
```bash
jat-memory search "key terms from task title" --limit 5 2>/dev/null || echo "NO_MEMORY_INDEX"
```

**2C: Prior task search:**
```bash
DATE_7=$(date -d '7 days ago' +%Y-%m-%d 2>/dev/null || date -v-7d +%Y-%m-%d); jt search "$SEARCH_TERM" --updated-after "$DATE_7" --limit 20 --json
```

Look for duplicates, related work, and in-progress tasks in similar areas.

### ROUND 3: Start Work (all parallel)

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

**3A: Update task status:**
```bash
jt update "$TASK_ID" --status in_progress --assignee "$AGENT_NAME" --files "relevant/files/**"
```

**3B: Working signal** (incorporate memory results into approach):
```bash
jat-signal working '{
  "taskId": "TASK_ID", "taskTitle": "TASK_TITLE",
  "approach": "Brief description of implementation plan",
  "expectedFiles": ["src/**/*.ts"], "baselineCommit": "COMMIT_HASH"
}'
```

> **Note:** Integration status sync (`in_progress`) fires automatically from `jt update --status in_progress` — no agent action needed.

### Output Banner

```
╔════════════════════════════════════════════════════════════╗
║         STARTING WORK: {TASK_ID}                           ║
╚════════════════════════════════════════════════════════════╝

Agent: {AGENT_NAME}
Overseer: {OVERSEER_LABEL | n/a}
Task: {TASK_TITLE}
Priority: P{X}

Approach:
  {YOUR_APPROACH_DESCRIPTION}
```

The `Overseer:` line comes verbatim from:

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

which prints who is watching this task — `DeepBeach732 (L2 pilot of mos-0a23k)`, `LightHeath (wave driver)`, or `n/a`. It checks a pilot mission, a wave-ownership claim and a fanout orchestrator (in that precedence), suppresses a self-match, and fails open to `n/a` when the IDE is unreachable, so it can never stall startup. **Never omit the line and never guess a name** — `n/a` says this session answers to the human directly, while a missing line reads as "unknown".

⚡ **Do NOT end your turn on the banner.** It is a status line printed on the way into the work, not a finish line — there is no approval gate here and nobody will type "continue" for you. In the **same turn** that prints the banner, issue the first tool call of the actual task. "Starting now" with no tool call after it leaves the session idle at an empty `❯` composer with a healthy `working` signal, so no stall detector flags it (jat-ccdrs). To wait for a human, use `jat-signal needs_input` + `AskUserQuestion`, or `jat-signal waiting` — never a silent turn end.

## Credentials & Authentication

**CRITICAL: Never hardcode or invent passwords. Never reset user passwords for testing.**

When you need credentials (API keys, database URLs, service role keys, login credentials), use `jat-secret`:

```bash
jat-secret --list                          # List all available secrets
jat-secret <project>-supabase-url          # Project Supabase URL
jat-secret <project>-supabase-service-role-key  # Service role key
eval $(jat-secret --export)                # Load all as env vars
```

**For browser testing that requires login:**
- Use the stored admin credentials: `jat-secret flush-admin-email` and `jat-secret flush-admin-password`
- **NEVER** reset a real user's password via the admin API to log in for testing
- **NEVER** use `auth.admin.updateUserById()` or `PUT /auth/v1/admin/users/` to set a password for browser verification
- If the stored credentials don't work, emit `needs_input` and ask the user — do NOT reset the password

Resetting passwords to test UI is destructive — it locks real users out of their accounts.

## Asking Questions During Work

**Always emit `needs_input` signal BEFORE asking questions:**

```bash
jat-signal needs_input '{
  "taskId": "TASK_ID",
  "question": "Brief description of what you need",
  "questionType": "clarification"
}'
```

Question types: `clarification`, `decision`, `approval`, `blocker`, `duplicate_check`

After getting a response, emit `working` signal to resume.

## When You Finish Working

**Emit `review` signal BEFORE presenting results:**

```bash
jat-signal review '{
  "taskId": "TASK_ID",
  "taskTitle": "TASK_TITLE",
  "summary": ["What you accomplished", "Key changes"],
  "filesModified": [
    {"path": "src/file.ts", "changeType": "modified", "linesAdded": 50, "linesRemoved": 10}
  ]
}'
```

Then output:
```
READY FOR REVIEW: {TASK_ID}

Overseer: {OVERSEER_LABEL | n/a}

Summary:
  - [accomplishment 1]
  - [accomplishment 2]

Run /skill:jat-complete when ready to close this task.
```

Re-run `jat-overseer-for "$TASK_ID" --agent "$AGENT_NAME"` for this line rather than reusing the startup answer — a pilot or wave driver is often claimed after a worker starts. A name means that agent reviews and approves the work; `n/a` means it goes straight to the human.

## Signal Reference

| Signal | When | Required Fields |
|--------|------|-----------------|
| `starting` | After registration | agentName, sessionId, project, model, gitBranch, gitStatus, tools |
| `working` | Before coding | taskId, taskTitle, approach |
| `needs_input` | Before asking questions | taskId, question, questionType |
| `review` | When work complete | taskId, taskTitle, summary |


[View on SkillFed](https://skillfed.io/joewinke/jat/jat-start) · [View on GitHub](https://github.com/joewinke/jat)