signal

Signal — Mid-Work Agent Coordination

Write structured coordination signals during active work. Signals are typed journal entries that other agents check at natural breakpoints (before editing claimed files, after making architectural decisions).

Signals are NOT chat. They are structured, typed messages — four types, one purpose each. An agent should be able to read all active signals in under 200 tokens.

When to Use This Skill

• Claiming exclusive ownership of files or code areas during parallel work
• Making an architectural or design decision that affects other agents' work
• Discovering a problem that crosses into another agent's territory
• Completing a significant milestone that frees up files or changes assumptions
• Local-only coordination when a switchboard is not configured — signal is the filesystem fast path

When NOT to Use This Skill

• Completed work summaries — use /handoff instead
• Starting a session — use /pickup instead
• Progress updates nobody needs — if it doesn't affect another agent, don't signal
• Solo work with no parallel agents — signals with no readers are noise
• Distributed agents on different machines — use /coordinate with the switchboard instead

Shared Coordination Space

Signals live in the journal directory of the shared handoff space:

MAIN_WORKTREE=$(git worktree list --porcelain | head -1 | sed 's/worktree //')
HANDOFF_DIR="${MAIN_WORKTREE}/.claude/handoff"
JOURNAL_DIR="${HANDOFF_DIR}/journal/${AGENT_NAME}"

Agent identity follows the same rules as /handoff — worktree name, branch name, or timestamp fallback.

The 4 Signal Types

Every signal has a type field. There are exactly four types. Use the right one.

CLAIM — "I own this, don't touch it"

Write a CLAIM when you're about to do significant work on files that other agents might also need. Claims are advisory but respected — the pickup protocol flags conflicts with claims.

---
type: claim
agent: {agent-name}
timestamp: {ISO-8601}
---
Claiming exclusive work on {area/module}.
Files: {file1}, {file2}, {file3}
Reason: {Why concurrent edits would conflict}
Duration: {Expected — e.g., "this session", "next 2 hours"}

When: Before starting work on shared code. Check active claims first — if someone already claims your target files, coordinate before proceeding.

DECISION — "I chose X, build on this"

Write a DECISION when you make a choice that constrains future work. Other agents need to know this so they don't make conflicting choices.

---
type: decision
agent: {agent-name}
timestamp: {ISO-8601}
---
Decision: {What you decided}
Rationale: {Why — one sentence}
Affects: {What code/agents this constrains}

When: After making any non-obvious architectural, design, or implementation choice. If reversing your decision would require another agent to redo work, signal it.

PROBLEM — "This affects your work"

Write a PROBLEM when you discover something that crosses into another agent's territory or changes shared assumptions.

---
type: problem
agent: {agent-name}
timestamp: {ISO-8601}
affects: {agent-name or "all"}
---
Problem: {What you found}
Impact: {How it affects the other agent's work}
Suggestion: {Optional — what they should do about it}

When: You find a bug, design flaw, or constraint that another agent needs to know about. Don't signal problems that only affect your own work.

COMPLETE — "Area is free, assumptions may have changed"

Write a COMPLETE when you finish a significant chunk of work. This releases any claims you had and notifies others that the codebase state has changed in your area.

---
type: complete
agent: {agent-name}
timestamp: {ISO-8601}
---
Completed: {What you finished}
Released: {Files/areas no longer claimed}
Changed assumptions: {What other agents should re-check, if anything}

When: After completing a milestone, merging, or finishing work on claimed files. Always pair with releasing your claims.

The 3 Steps (MANDATORY)

Step 1: Check Before Signaling (REQUIRED)

Before writing a signal, check existing signals to avoid duplicates or conflicts:

# Read recent signals from all agents
for agent_dir in "${HANDOFF_DIR}/journal/"*/; do
  AGENT=$(basename "$agent_dir")
  LATEST=$(ls "$agent_dir" 2>/dev/null | sort -n | tail -3)
  for f in $LATEST; do
    echo "=== ${AGENT}/${f} ==="
    cat "${agent_dir}/${f}" 2>/dev/null
  done
done

For CLAIM signals: Verify no one else has already claimed the same files. For DECISION signals: Verify no conflicting decision has been made.

Gate: You've read recent signals and confirmed no conflicts.

Step 2: Write the Signal (REQUIRED)

Determine the next sequence number and write the signal:

LAST=$(ls "${JOURNAL_DIR}/" 2>/dev/null | sort -n | tail -1 | sed 's/\.md//')
NEXT=$(printf "%04d" $(( ${LAST:-0} + 1 )))

Write to ${JOURNAL_DIR}/${NEXT}.md using the appropriate type template above.

Gate: Signal file is written with correct type, frontmatter, and structured content.

Step 3: Update Presence (REQUIRED)

If you wrote a CLAIM, update your presence file's touching array to include the claimed files:

# Update presence file with new claims
cat > "${HANDOFF_DIR}/active/${AGENT_NAME}.json" << EOF
{
  "agent": "${AGENT_NAME}",
  "branch": "$(git branch --show-current)",
  "started": "{original-start-time}",
  "heartbeat": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "task": "{current-task}",
  "touching": ["{all-claimed-files}"],
  "status": "working"
}
EOF

If you wrote a COMPLETE, remove the completed files from your touching array.

Gate: Presence file reflects your current claims.

When to Check Signals (Protocol for Consumers)

Agents should check signals at these natural breakpoints:

• Before editing a file — check if it's claimed by another agent
• After making a decision — check for conflicting decisions
• Before starting a new task — read recent signals for context changes
• Periodically during long work — update your heartbeat and scan for problems

Quick check command:

# Find signals from the last hour across all agents
find "${HANDOFF_DIR}/journal/" -name "*.md" -newer /tmp/signal-check-marker 2>/dev/null | while read f; do head -8 "$f"; echo "---"; done
touch /tmp/signal-check-marker

Relationship to /coordinate

Signal and coordinate serve the same purpose — agent coordination — via different transports:

	/signal	/coordinate
Transport	Filesystem (project repo)	Git (switchboard repo)
Speed	Instant (file read)	Git push/pull cycle
Scope	Same machine only	Cross-machine
Best for	2-4 local agents	Distributed teams

If a switchboard is configured in ~/.claude/coordination.json, prefer /coordinate. Use /signal as the fast path when all agents share a filesystem, or as the fallback when the switchboard is unreachable.

Red Flags - STOP

If you catch yourself:

• ❌ Writing a signal that only affects yourself — signals are for OTHER agents
• ❌ Writing paragraphs of explanation — signals are structured data, not prose
• ❌ Signaling trivially ("I edited line 42") — signal meaningful coordination events
• ❌ Claiming files you won't touch for hours — claims have implicit duration. Release what you're not actively working on.
• ❌ Not checking existing claims before editing shared files — check first, edit second

STOP. If it doesn't help another agent make a better decision, it's noise, not signal.

Verification Checklist

Before considering the signal complete:

• Checked existing signals for conflicts
• Signal has correct type (claim/decision/problem/complete)
• Signal has valid frontmatter with type, agent, timestamp
• Content is structured (not prose paragraphs)
• Presence file updated to reflect current claims
• Signal only contains information relevant to other agents

Best Practices

1. Signal at decision boundaries, not activity boundaries — "I chose JWT over session tokens" is a signal. "I'm writing code" is not.
2. Claims are temporary — always include expected duration. Release claims when done.
3. PROBLEM signals should suggest, not demand — the affected agent has their own context. Suggest, don't prescribe.
4. COMPLETE signals are the inverse of CLAIM — every claim should eventually have a matching complete.
5. When in doubt, don't signal — noise is worse than silence. The handoff captures everything at the end.

Related Skills

• /handoff — End-of-work memory transfer. Signals are mid-work; handoffs are post-work.
• /pickup — Reads signals as part of context reconstruction. Your signals are consumed here.
• /repo-ingest — Updates the coordination protocol from external repos.

After Using This Skill

MANDATORY NEXT STEPS:

• Continue working — signals are fire-and-forget

OPTIONAL NEXT STEPS:

• Check for responses/conflicts after other agents have had time to read your signal

Changelog

v1.1.0 (2026-04-11)

• Clarified relationship with /coordinate: signal is the local fast path, coordinate is distributed
• Added transport comparison table
• Added "switchboard unreachable" as fallback use case

v1.0.0 (2026-04-11)

• Initial skill creation
• Four signal types: CLAIM, DECISION, PROBLEM, COMPLETE
• Shared journal space via main worktree
• Consumer protocol for checking signals at natural breakpoints