Jat Start

/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 Mail
2. Check Agent Mail - Read messages before starting
3. Select task - From parameter or show recommendations
4. Review prior tasks - Check for duplicates and related work
5. Start work - Reserve files, update Beads, announce
6. Emit signals - IDE tracks state through jat-signal

Step-by-Step Instructions

STEP 1: Parse Arguments

Check what was passed: $ARGUMENTS may contain agent-name, task-id, both, or nothing.

# Test if a param is a valid task ID
bd show "$PARAM" --json >/dev/null 2>&1 && echo "task-id" || echo "agent-name"

STEP 2: Get/Create Agent Identity

2A: Check for IDE Pre-Registration

If spawned by the IDE, your identity file already exists:

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"

If found, use that name and skip to Step 3.

2B: Register Manually (CLI only)

If no pre-registration file exists, pick a name and register:

# Generate or use provided name
am-register --name "$AGENT_NAME" --program pi --model "$MODEL_ID"
tmux rename-session "jat-${AGENT_NAME}" 2>/dev/null

2C: Write Session Identity

For manual sessions, write the identity file so the IDE can track you:

mkdir -p .claude/sessions
echo "$AGENT_NAME" > ".claude/sessions/agent-${SESSION_ID}.txt"

STEP 3: Check Agent Mail

Always check mail before selecting a task.

am-inbox "$AGENT_NAME" --unread

Read each message. Reply if needed with am-reply. Acknowledge with am-ack.

STEP 4: Select Task

If a task-id was provided, use it. Otherwise, show available work:

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

If no task-id provided, display recommendations and stop here.

STEP 5: Review Prior Tasks

Search for related or duplicate work from the last 7 days:

DATE_7D=$(date -d '7 days ago' +%Y-%m-%d 2>/dev/null || date -v-7d +%Y-%m-%d)
bd search "$SEARCH_TERM" --updated-after "$DATE_7D" --limit 20 --json

Look for:

• Duplicates (closed tasks with nearly identical titles) - ask user before proceeding
• Related work (same files/features) - note for context
• In-progress by other agents - coordinate via Agent Mail

If a potential duplicate is found, ask the user before proceeding.

STEP 6: Conflict Detection

am-reservations --json          # Check file locks
git diff-index --quiet HEAD --  # Check uncommitted changes

STEP 7: Start the Task

# Update task status
bd update "$TASK_ID" --status in_progress --assignee "$AGENT_NAME"

# Reserve files you'll edit
am-reserve "relevant/files/**" --agent "$AGENT_NAME" --ttl 3600 --reason "$TASK_ID"

# Announce to other agents
am-send "[$TASK_ID] Starting: $TASK_TITLE" "Starting work" \
  --from "$AGENT_NAME" --to @active --thread "$TASK_ID"

STEP 8: Emit Signals

Both signals are required before starting actual work.

8A: Starting Signal

jat-signal starting '{
  "agentName": "AGENT_NAME",
  "sessionId": "SESSION_ID",
  "taskId": "TASK_ID",
  "taskTitle": "TASK_TITLE",
  "project": "PROJECT",
  "model": "MODEL_ID",
  "tools": ["bash", "read", "write", "edit"],
  "gitBranch": "BRANCH",
  "gitStatus": "clean",
  "uncommittedFiles": []
}'

8B: Working Signal

After reading the task and planning your approach:

jat-signal working '{
  "taskId": "TASK_ID",
  "taskTitle": "TASK_TITLE",
  "approach": "Brief description of implementation plan",
  "expectedFiles": ["src/**/*.ts"],
  "baselineCommit": "COMMIT_HASH"
}'

8C: Output Banner

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

Agent: {AGENT_NAME}
Task: {TASK_TITLE}
Priority: P{X}

Approach:
  {YOUR_APPROACH_DESCRIPTION}

Asking Questions During Work

Always emit needs_input signal BEFORE asking questions:

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:

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}

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

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

Signal Reference