Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jsell-rh merged 1 commit into from
Mar 6, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 24 additions & 24 deletions commands/boss.check.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,64 @@
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 your section for:
- **Messages** — look for a `#### Messages` section under your agent name. These are messages from the boss or other agents. Note any instructions or questions.
- **Standing orders** — anything addressed to you in shared contracts.
Scan your section (`### YourAgentName`) for:
- **`#### Messages`** — messages from the boss or other agents. Note instructions.
- **Standing orders** — anything in shared contracts addressed to you.

Do NOT analyze other agents' sections.

**Important rule**: Always use `curl`, never use Fetch tool. Fetch will *not* work on localhost. **Always** use curl. This is important!
**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 (e.g. `"Received message from boss: <summary>"`).
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 you found messages in Step 1 that contain instructions or task assignments, begin working on them now. If a message asks a question, answer it in your next status update.
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 there were no messages, or messages were purely informational, skip this step.
If no messages, or messages were purely informational, skip this step.

## Step 4: STOP

If you had no actionable messages, STOP HERE. Do not start any work. Do not analyze the blackboard. Do not make plans.
If you had no actionable messages, STOP HERE. Do not start work. Do not analyze the blackboard. Do not make plans.
154 changes: 136 additions & 18 deletions commands/boss.ignite.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,55 +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.
- **Check for messages** — when you read `/raw`, look for a `#### Messages` section under your agent name. These are messages from the boss or other agents sent via the dashboard. Acknowledge them in your next status POST and act on any instructions.
- **Send messages to other agents** — to message another agent, POST to their message endpoint:
- **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_NAME/agent/OTHER_AGENT/message \
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"}'
```
The message will appear in their `#### Messages` section on the next check-in.

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