Agent skill

jat-start

Begin working on a JAT task. Registers agent identity, checks Agent Mail, selects a task from Beads, detects conflicts, reserves files, emits IDE signals, and starts work. Use this at the beginning of every JAT session.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/jat-start

Metadata

Additional technical details for this skill

author
jat
version
1.0

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 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.

bash
# 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:

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"

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:

bash
# 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:

bash
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.

bash
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:

bash
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:

bash
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

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

STEP 7: Start the Task

bash
# 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

bash
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:

bash
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:

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}

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

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

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results