Session Coordinator Skill v3.0.1 — Main Process Never Blocks#

Core Principle#

Main process = dialog + dispatch. Never block.

The main goal is responsiveness — the main process must never be blocked, stalled, or made unresponsive. This is not "never execute." It is "never block."

A blocked main process shows as: typing indicator disappears, user cannot get a response, session appears frozen.

Decision Framework#

Spawn when (blocks or uncertain):#

• Remote operations (SSH, remote API calls)
• git push/pull/clone operations
• Any operation involving network I/O
• Operations with unknown duration
• Operations that need isolation (fail without affecting main session)
• State-modifying operations: file write, git commit, package publish, deploy, or any operation that changes persistent state on disk or remote
• Anything requiring waiting for external result
• Spawn must always include a label parameter (see Spawn Label Convention below)

Execute directly when (fast, non-blocking AND same topic):#

• Local scripts that run in <1 second
• Reading files, writing docs, writing code
• Dialog, judgment, approval, reasoning
• Quick system calls (RAM, disk, process status)
• Must NOT involve network I/O (SSH, HTTP, remote calls)
• Must be same topic as current conversation

Self-check signal:#

"If my typing indicator disappeared, am I being blocked right now?"

If a question or request is on a DIFFERENT topic, spawn it — do not handle it directly even if it seems fast. Different topic = different subagent.

---

Spawn Mode v3 — Default: session thread#

Default spawn mode is mode="session" with thread=true.

• Use mode="session", thread=true for most tasks (interactive, multi-step, or uncertain duration)
• Use mode="one-shot" only when explicitly instructed or when the task is trivial and guaranteed single-turn
• Never assume mode="run" (run = detached, no result push = unreliable)

python

# ✅ Default: session thread (most tasks)
spawn(task="task-description", mode="session", thread=true, label="task-label")

# ✅ Explicit one-shot: only when scope is trivially bounded
spawn(task="task-description", mode="one-shot", label="task-label")

# ❌ Don't use run unless you explicitly need detached/no-result
spawn(task="task-description", mode="run")

---

Timeout Guidelines#

Use these as a guide to set runtime when spawning:

TierDurationExamplesfast~5 minfile ops, single API call, config check, quick testmedium~15 mingit operations, moderate build, moderate data processinglong60 min+large clones, heavy builds, multi-step deployments, data migrationpython

# Fast task — 5 min timeout
spawn(task="check service status", runtime="fast", label="service-status-check")

# Medium task — 15 min timeout
spawn(task="clone repository and run tests", runtime="medium", label="repo-test")

# Long task — 60 min timeout
spawn(task="full deployment pipeline", runtime="long", label="deploy-pipeline")

---

Spawn Label Convention#

When spawning a subagent, always include a descriptive label parameter:

• Use dashes, not spaces (e.g., project-config-sync not project config sync)
• Use generic, descriptive names only — never specific project names, IPs, hostnames, or user names
• Label should reflect the actual task category or action

Generic placeholder examples:

• project-name → repo-name or project-alfa
• 192.168.x.x → remote-host or node-alpha
• user@host → admin-user or service-account

python

# ✅ Good: generic, dashes, descriptive
spawn(task="sync config to remote node", label="config-sync")
spawn(task="run test suite for module", label="test-suite")
spawn(task="deploy service to environment", label="service-deploy")

# ❌ Bad: spaces, specific names, cryptic
spawn(task="...", label="proj1")           # too short, no dashes
spawn(task="...", label="192-168-1-1")     # specific IP — not allowed
spawn(task="...", label="johns-task")      # specific user name — not allowed
spawn(task="...", label="foo-bar-v2")      # specific project codename — not allowed

When the user says "stop that thing", look at subagents list and match the label to find the right subagent to stop.

---

Lifecycle Management#

Auto-Timeout#

• Subagents run with a defined runtime timeout (fast/medium/long)
• If the subagent exceeds its timeout without a result, it is considered stalled
• Do NOT manually extend timeouts unless user explicitly asks

Done Signals#

A subagent can be safely let timeout (or can terminate early) when:

1. user says "done" — user has indicated the task is complete or no longer needed
2. Context switches — user has moved to a different topic or task; the previous subagent is no longer relevant
3. Explicit cancel — user says "stop", "cancel", "forget it"

What to do when done signal fires:#

• Do NOT try to salvage a timed-out subagent
• Do NOT restart the same task unless user explicitly asks
• Acknowledge the signal and move on

---

Result Writing#

Important results → MEMORY.md#

After a subagent completes, if the result is significant (decision made, lesson learned, important output, state change), write it to MEMORY.md in the main session.

markdown

## [Date] Task Result
- Task: task-description
- Outcome: what happened
- Key decision/learning: ...

Daily logs → memory/YYYY-MM-DD.md#

Routine subagent work should be logged in the daily memory file:

bash

# Create/update daily log
memory/2026-04-06.md

Include: task label, what was done, key result. Keep it concise.

---

Spawn Is Transparent#

Do not announce to user when you are spawning a subagent.

• Do NOT say "I'm spawning a subagent to handle this..."
• Do NOT say "Let me dispatch this to a background agent..."
• Just spawn it and continue the dialog naturally

user does not need to know the execution architecture. The subagent handles the work; you handle the conversation.

---

Role Definition#

ResponsibilityMain ProcessSubagentUser dialog✅❌Task dispatch✅❌Result production❌✅Result delivery to user✅❌Decision making✅❌Status coordination✅❌Fast local operations✅❌Blocking operations❌✅

---

Execution Model#

Blocked = Wrong#

If the main process blocks, the pattern has failed — regardless of whether the task eventually completes.

Spawn and Continue#

python

# ❌ Wrong — blocks main process, typing disappears
exec("ssh remote-host ...")
subprocess.run(...)

# ✅ Correct — non-blocking, typing stays active
spawn(task="remote operation description", runtime="medium", mode="session", thread=true, label="remote-task")

After spawning: continue dialog with user. Do NOT wait. Results arrive via push event.

Fire-and-Forget#

• Spawn with full task description and runtime estimate
• Do NOT estimate how long it takes
• Do NOT poll for status
• Continue dialog
• Report result when delivered

---

Multi-Node Coordination#

Each node runs its own subagents. Nodes do not delegate to each other's subagents. Coordination between nodes goes through whatever inter-node protocol is configured for that setup.

---

Anti-Patterns#

Anti-PatternWhy WrongCorrect"Let me check..." + exec in mainBlocks typingSpawn subagentWaiting for subagent result before respondingBlocks dialogContinue, report laterDirect remote operations in main processBlocksSpawnSpawning to avoid doing work (not to avoid blocking)Misuse of patternExecute directly if fastAll work spawn, nothing directOver-interpretationFast ops = directAnnouncing the spawn to userNoise, breaks flowSpawn silently, continueUsing specific IPs/hostnames in labelsPrivacy leakUse generic names

---

Workflow Summary#

1. User request arrives
2. Assess: will this block? (slow / uncertain / remote = spawn; fast / local / dialog = direct)
3. If spawn → spawn with session thread + appropriate runtime + generic label
4. If direct → execute and respond now
5. Result arrives via push → report to user
6. If result is significant → write to MEMORY.md or daily log
7. Self-check: is typing indicator still showing?

---

Key Insight#

"Never block" is the rule. "Never execute" is a misreading of the rule — fast operations should be direct because they do not block. The typing indicator is the visible signal: if it disappears, something is blocking.

---

Privacy Notes#

All examples in this skill use generic placeholders only. No specific project names, IPs, hostnames, user names, service names, or AI names appear in any example. This protects both operational security and privacy.