diff --git a/commands/boss.check.md b/commands/boss.check.md index 8b18b4f..c9256d2 100644 --- a/commands/boss.check.md +++ b/commands/boss.check.md @@ -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: "`). +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: ", + "summary": "AGENT_NAME: ", "branch": "", - "pr": "", - "repo_url": "", - "phase": "", + "pr": "", + "repo_url": "", + "phase": "", "test_count": 0, "items": [""], "next_steps": "" } 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. diff --git a/commands/boss.ignite.md b/commands/boss.ignite.md index fd79815..f7121ce 100644 --- a/commands/boss.ignite.md +++ b/commands/boss.ignite.md @@ -1,6 +1,33 @@ You are joining a multi-agent coordination project. Execute these steps exactly. -**Arguments:** `$ARGUMENTS` is ` ` (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 @@ -8,48 +35,139 @@ You are joining a multi-agent coordination project. Execute these steps exactly. 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: ", + "branch": "", + "repo_url": "", + "items": ["", ""], + "next_steps": "" + }' +``` + +`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 +```