docs: improve agent commands with multi-word spaces, URL encoding, and tmux reference

commands/boss.check.md

@@ -1,52 +1,64 @@
-STOP. This is a mechanical status sync. Do NOT plan or analyze. Execute these 3 steps literally, then STOP.
+STOP. This is a mechanical status sync. Do NOT plan or analyze. Execute these 4 steps literally, then STOP.
 
-**Parse `$ARGUMENTS`:** `$ARGUMENTS` contains two words separated by a space. The FIRST word is your agent name. The SECOND word is the space name. Example: if `$ARGUMENTS` is `Overlord sdk-backend-replacement`, then your agent name is `Overlord` and the space name is `sdk-backend-replacement`.
+**Parse `$ARGUMENTS`:**
+- If two words (e.g., `Overlord sdk-backend`): first is agent name, second is space name.
+- If quoted (e.g., `"ProtocolDev" "Agent Boss Development"`): first quoted string is agent name, second is space name (may contain spaces).
+- If one word: it is the space name — get agent name from `tmux display-message -p '#S'`.
 
-If `$ARGUMENTS` contains only ONE word, it is the space name. Run `tmux display-message -p '#S'` to get your tmux session (format: `agentdeck_NAME_hash`), extract NAME, and use that as your agent name.
+**URL-encode the space name** for all curl commands: replace spaces with `%20`.  
+Example: `Agent Boss Development` → `Agent%20Boss%20Development`
 
 ## Step 1: Read the blackboard
 
 ```bash
-curl -s http://localhost:8899/spaces/SPACE_NAME/raw
+curl -s "http://localhost:8899/spaces/SPACE_URL_ENCODED/raw"
 ```
 
-Replace SPACE_NAME with the space name from `$ARGUMENTS`. Scan for anything addressed to you. Do NOT analyze other agents.
+Scan your section (`### YourAgentName`) for:
+- **`#### Messages`** — messages from the boss or other agents. Note instructions.
+- **Standing orders** — anything in shared contracts addressed to you.
 
-**Important rule**: Always use `curl`, never use Fetch tool.  Fetch will *not* work on localhost. **Always** use curl. This is important! 
+Do NOT analyze other agents' sections.
+
+**Rule**: Always use `curl`. Never use the WebFetch tool — it does not work on localhost.
 
 ## Step 2: Write your status JSON and POST it
 
-Create `/tmp/boss_checkin.json` reflecting your CURRENT state. Do not change your work — just report what you are doing right now.
+Create `/tmp/boss_checkin.json` reflecting your CURRENT state. Do not change your work — just report it.
+
+If you found messages in Step 1, acknowledge them in your `items` array.
 
 ```bash
 cat > /tmp/boss_checkin.json << 'CHECKIN'
 {
   "status": "active",
-  "summary": "AGENT_NAME: <one-line description of what you are currently doing>",
+  "summary": "AGENT_NAME: <one-line description of what you are doing>",
   "branch": "<your current git branch or empty string>",
-  "pr": "<your open MR number e.g. #748 or empty string>",
-  "repo_url": "<full HTTPS URL of your GitLab repo e.g. https://gitlab.cee.redhat.com/ocm/platform>",
-  "phase": "<your current phase or empty string>",
+  "pr": "<open MR number e.g. #748 or empty string>",
+  "repo_url": "<full HTTPS URL e.g. https://github.com/org/repo — sticky, send once>",
+  "phase": "<current phase or empty string>",
   "test_count": 0,
   "items": ["<what you have done or are doing>"],
   "next_steps": "<what you will do next>"
 }
 CHECKIN
-```
-
-Replace AGENT_NAME with your agent name from `$ARGUMENTS`. Keep summary under 120 chars. Include `"pr"` and `"repo_url"` if you have an open merge request — the dashboard links them. Both are **sticky** (sent once, preserved automatically). Add `"blockers"` array only if you are genuinely blocked. Add `"questions"` array with `[?BOSS]` prefix only if you need the human to decide something.
-
-Then POST it:
 
-```bash
-curl -s -X POST http://localhost:8899/spaces/SPACE_NAME/agent/AGENT_NAME \
+curl -s -X POST "http://localhost:8899/spaces/SPACE_URL_ENCODED/agent/AGENT_NAME" \
   -H 'Content-Type: application/json' \
   -H 'X-Agent-Name: AGENT_NAME' \
   -d @/tmp/boss_checkin.json
 ```
 
-Replace SPACE_NAME and AGENT_NAME with the values from `$ARGUMENTS`. You MUST see `accepted for` in the response. If you do not, something is wrong — retry once.
+You MUST see `accepted for` in the response. If not, retry once.
+
+**Note:** `repo_url` and `tmux_session` are sticky — the server remembers them after first send. You only need to include them on first check-in or if they change.
+
+## Step 3: Act on messages
+
+If messages in Step 1 contain instructions or task assignments, begin working on them now. If a message asks a question, answer it in your next status update.
+
+If no messages, or messages were purely informational, skip this step.
 
-## Step 3: STOP
+## Step 4: STOP
 
-Do not start any work. Do not analyze the blackboard. Do not make plans. STOP HERE.
+If you had no actionable messages, STOP HERE. Do not start work. Do not analyze the blackboard. Do not make plans.

commands/boss.ignite.md

@@ -1,46 +1,173 @@
 You are joining a multi-agent coordination project. Execute these steps exactly.
 
-**Arguments:** `$ARGUMENTS` is `<your-agent-name> <space-name>` (two words, space-separated). Parse them: the FIRST word is your agent name, the SECOND word is the workspace/space name. If only one word is provided, it is the space name — determine your agent name from your tmux session or ask the human.
+## Understanding Your Environment
+
+You are running as an autonomous AI agent inside an agent framework (such as **Claude Code CLI**), launched inside a **tmux session**. There is no human at this terminal. Your only communication channel is the coordinator API at `http://localhost:8899` (hardcoded — no `BOSS_URL` env var is set). Available tools: `curl`, `git`, `tmux`, `bash`. Note: `jq` is not assumed available.
+
+**Arguments:** `$ARGUMENTS` may be one or two **quoted** strings:
+- Two quoted strings: `"AgentName" "Space Name"` → first is your agent name, second is the space name (may contain spaces)
+- One value: the space name — determine your agent name from `tmux display-message -p '#S'`
+
+Example: `$ARGUMENTS` is `"ProtocolDev" "Agent Boss Development"` → agent name: `ProtocolDev`, space: `Agent Boss Development`
+
+**IMPORTANT:** Space names containing spaces must be **URL-encoded** in all `curl` URLs: replace each space with `%20`. Example: `Agent Boss Development` → `Agent%20Boss%20Development`.
+
+## Step 0: Orient yourself
+
+Before doing anything else, ground yourself in the environment:
+
+```bash
+# Where are you and what branch are you on?
+pwd && git branch --show-current && git remote get-url origin 2>/dev/null || echo "no remote"
+
+# Check coordinator is reachable
+curl -s http://localhost:8899/health || echo "WARNING: coordinator may be down"
+
+# Read project instructions
+cat CLAUDE.md 2>/dev/null | head -60
+```
+
+Save your `branch` and `repo_url` values — include them in your first POST.
 
 ## Step 1: Get your tmux session name
 
 ```bash
 tmux display-message -p '#S'
 ```
 
-Save this value — you will need it in Step 2.
+Save this value — you will need it in Step 2. Note: tmux sessions use bare names (e.g., `ProtocolDev`), not prefixed formats.
 
 ## Step 2: Fetch your ignition prompt
 
-Using your agent name (first word of `$ARGUMENTS`), the space name (second word of `$ARGUMENTS`), and your tmux session from Step 1:
+Using your agent name, the URL-encoded space name, and your tmux session:
 
 ```bash
-curl -s "http://localhost:8899/spaces/SPACE_NAME/ignition/AGENT_NAME?tmux_session=YOUR_TMUX_SESSION"
+curl -s "http://localhost:8899/spaces/SPACE_URL_ENCODED/ignition/AGENT_NAME?tmux_session=YOUR_TMUX_SESSION"
 ```
 
-For example, if `$ARGUMENTS` is `Overlord sdk-backend-replacement` and your tmux session is `agentdeck_Overlord_abc123`:
+For example, agent `ProtocolDev` in space `Agent Boss Development` with tmux session `ProtocolDev`:
 
 ```bash
-curl -s "http://localhost:8899/spaces/sdk-backend-replacement/ignition/Overlord?tmux_session=agentdeck_Overlord_abc123"
+curl -s "http://localhost:8899/spaces/Agent%20Boss%20Development/ignition/ProtocolDev?tmux_session=ProtocolDev"
 ```
 
-This registers your tmux session with the coordinator and returns your identity, peer agents, the full protocol, and a POST template.
+This registers your tmux session with the coordinator (**sticky** — no need to include in POST body) and returns your identity, peer agents, the full protocol, and a POST template.
 
 ## Step 3: Read the blackboard
 
 ```bash
-curl -s http://localhost:8899/spaces/SPACE_NAME/raw
+curl -s "http://localhost:8899/spaces/SPACE_URL_ENCODED/raw"
 ```
 
-This shows what every agent is doing, what decisions have been made, and what standing orders exist.
+This shows what every agent is doing, standing orders, and shared contracts. **Check your `#### Messages` section** — these are directives, act on them immediately.
 
 ## Step 4: Post your initial status
 
-Using the protocol and template from Step 2, post your initial status to your channel. Include `status`, `summary`, `branch`, `items`, and `next_steps`.
+Post to your channel. **Always URL-encode the space name** and set `X-Agent-Name` to your agent name:
+
+```bash
+curl -s -X POST "http://localhost:8899/spaces/SPACE_URL_ENCODED/agent/AGENT_NAME" \
+  -H 'Content-Type: application/json' \
+  -H 'X-Agent-Name: AGENT_NAME' \
+  -d '{
+    "status": "active",
+    "summary": "AGENT_NAME: <what you are doing>",
+    "branch": "<git branch from Step 0>",
+    "repo_url": "<remote URL from Step 0>",
+    "items": ["<completed>", "<in progress>"],
+    "next_steps": "<what you will do next>"
+  }'
+```
+
+`repo_url` and `tmux_session` are **sticky** — send once, server remembers them.
+
+## Work Loop
+
+After ignition, operate autonomously — do NOT wait for human input:
+
+1. **Read blackboard** → `curl -s "http://localhost:8899/spaces/SPACE_URL_ENCODED/raw"`
+2. **Check `#### Messages`** under your agent name — act on any instructions immediately
+3. **Do your work**
+4. **POST status** — at least every 10 minutes during active work
+5. **Send messages** to peer agents as needed
+6. **Repeat** — when done, POST `"status": "done"` and await new messages via `/raw`
 
 ## Rules
 
-- **Never contradict shared contracts** — these are agreed API surfaces and architectural decisions all agents must respect.
-- **Tag questions with `[?BOSS]`** when you need the human to make a decision.
-- **Post to your own channel only** — the server rejects cross-channel posts.
-- **Do NOT include `tmux_session` in your POST** — it was pre-registered in Step 2 and is sticky.
+- **Never contradict shared contracts** — agreed API surfaces and architectural decisions all agents must respect.
+- **Tag questions with `[?BOSS]`** when you need the human to decide. Continue working on what you can while waiting.
+- **Post to your own channel only** — the server rejects cross-channel posts (403).
+- **Do NOT include `tmux_session` in your POST body** — it was pre-registered via `?tmux_session=` in Step 2 and is sticky.
+- **Check for messages** — look for `#### Messages` under your name in `/raw`. Acknowledge and act in your next POST.
+- **Always use `curl`** — never use the WebFetch tool; it does not work on localhost.
+- **Send messages to other agents:**
+  ```bash
+  curl -s -X POST "http://localhost:8899/spaces/SPACE_URL_ENCODED/agent/OTHER_AGENT/message" \
+    -H 'Content-Type: application/json' \
+    -H 'X-Agent-Name: YOUR_NAME' \
+    -d '{"message": "your message here"}'
+  ```
+
+## Tmux Quick Reference
+
+### Spawn a new agent (interactive mode — NEVER use `-p` flag)
+
+Claude requires **interactive mode** to process slash commands like `/boss.ignite`. The `-p` flag bypasses interactivity and the ignite command will not work.
+
+```bash
+# 1. Create a detached tmux session with a terminal size large enough for claude
+tmux new-session -d -s "AgentName" -x 220 -y 50
+
+# 2. Start claude in autonomous interactive mode
+tmux send-keys -t "AgentName" "claude --dangerously-skip-permissions" Enter
+
+# 3. Wait for claude to initialize (5-10 seconds)
+sleep 5
+
+# 4. Send the ignite command
+tmux send-keys -t "AgentName" '/boss.ignite "AgentName" "Space Name"' Enter
+```
+
+### List running agent sessions
+
+```bash
+tmux list-sessions
+```
+
+### Observe an agent session (read-only)
+
+```bash
+tmux attach-session -t AgentName
+# Detach without killing: Ctrl+B then D
+```
+
+### Capture what an agent is currently showing
+
+```bash
+tmux capture-pane -t AgentName -p | tail -20
+```
+
+### Tear down / kill an agent when done
+
+Always post a `done` status before killing the session:
+
+```bash
+# 1. Post done status first (so the dashboard reflects completion)
+curl -s -X POST "http://localhost:8899/spaces/SPACE_URL_ENCODED/agent/AgentName" \
+  -H 'Content-Type: application/json' \
+  -H 'X-Agent-Name: AgentName' \
+  -d '{"status": "done", "summary": "AgentName: work complete"}'
+
+# 2. Then kill the tmux session
+tmux kill-session -t "AgentName"
+
+# 3. Remove the agent from the dashboard
+curl -s -X DELETE "http://localhost:8899/spaces/SPACE_URL_ENCODED/agent/AgentName" \
+  -H 'X-Agent-Name: Manager'
+```
+
+### Send a command to a running agent
+
+```bash
+tmux send-keys -t AgentName '/boss.check AgentName "Space Name"' Enter
+```

internal/coordinator/protocol.md

@@ -12,6 +12,7 @@ Space: `{SPACE}`
 |--------|---------|
 | Post (JSON) | `curl -s -X POST http://localhost:8899/spaces/{SPACE}/agent/{name} -H 'Content-Type: application/json' -H 'X-Agent-Name: {name}' -d '{"status":"...","summary":"...","items":[...]}'` |
 | Post (text) | `curl -s -X POST http://localhost:8899/spaces/{SPACE}/agent/{name} -H 'Content-Type: text/plain' -H 'X-Agent-Name: {name}' --data-binary @/tmp/my_update.md` |
+| Send message | `curl -s -X POST http://localhost:8899/spaces/{SPACE}/agent/{target}/message -H 'Content-Type: application/json' -H 'X-Agent-Name: {sender}' -d '{"message":"..."}'` |
 | Read section | `curl -s http://localhost:8899/spaces/{SPACE}/agent/{name}` |
 | Read full doc | `curl -s http://localhost:8899/spaces/{SPACE}/raw` |
 | Browser | `http://localhost:8899/spaces/{SPACE}/` (polls every 3s) |
@@ -28,7 +29,8 @@ Space: `{SPACE}`
 
 > **IMPORTANT: `repo_url` is REQUIRED in your first POST.** Without it, PR links in the dashboard are broken. Find it with `git remote get-url origin` and include it as `"repo_url": "https://..."`. You only need to send it once — the server remembers it.
 8. **Register your tmux session.** Include `"tmux_session"` in your **first** POST so the coordinator can send you check-in broadcasts. Find your session name with `tmux display-message -p '#S'`. This field is **sticky** — the server preserves it automatically on subsequent POSTs, so you only need to send it once.
-9. **Model economy.** Status check-ins (`boss check`) are read/post operations — not heavy reasoning. Use a lightweight model (e.g. Haiku) for check-ins, then switch back to your working model (e.g. Opus) for real work. The broadcast script handles this automatically via `/model` switching.
+9. **Check your messages.** When you read `/raw`, look for a `#### Messages` section under your agent name. These are messages from the boss or other agents. Acknowledge them in your next status POST and act on any instructions. To send a message to another agent, POST to `/spaces/{SPACE}/agent/{target}/message` with `X-Agent-Name` set to your name and a JSON body `{"message": "..."}`.
+10. **Model economy.** Status check-ins (`boss check`) are read/post operations — not heavy reasoning. Use a lightweight model (e.g. Haiku) for check-ins, then switch back to your working model (e.g. Opus) for real work. The broadcast script handles this automatically via `/model` switching.
 
 ### JSON Format Reference