add-mind

add-mind

$ARGUMENTS[0] = mind name. Ask if missing.

Step 1 — Determine scenario

Check if minds/$ARGUMENTS[0]/ directory exists:

• No directory → Scenario A, B, or D. Ask the user:

  • "How does this mind run?"
  • "1. Docker — runs as a container in this stack"
  • "2. Remote — runs on a different host (separate machine or VM)"
  • "3. Bare-metal — runs directly on this host outside Docker (e.g. a systemd service at a localhost port)"
  • If 1 → Scenario A
  • If 2 → Scenario B
  • If 3 → Scenario D

• Directory exists → Scenario C (re-registration). The mind folder is already there but may not be in the broker.

Collect from the user:

• name (from argument)
• gateway_url (default http://hive_mind:8420 for local, ask for remote)
• model (e.g. sonnet, gpt-oss:20b-32k)
• harness (e.g. claude_cli_claude, codex_cli_codex)

For Scenario B: verify the external gateway is reachable before proceeding:

curl -sf <gateway_url>/broker/minds > /dev/null && echo "Reachable" || echo "UNREACHABLE"

Step 2 — Create MIND.md (Scenarios A and B)

Write minds/<name>/MIND.md:

Scenario A (new local):

---
name: <name>
model: <model>
harness: <harness>
gateway_url: <gateway_url>
---

# <Name>

<Ask the user for a brief identity description to use as the soul seed>

Scenario B (remote):

---
name: <name>
model: <model>
harness: <harness>
gateway_url: <gateway_url>
remote: true
---

Scenario D (bare-metal local):

Ask the user for the port the mind is running on (e.g. 8421). Set gateway_url to http://localhost:<port>.

Confirm the service is up before proceeding:

curl -sf http://localhost:<port>/health && echo "UP" || echo "NOT RUNNING — start the service first"

If not running, stop and tell the user to start the service, then re-run /add-mind.

No MIND.md is written inside the hive_mind project — the mind project lives at its own path on the host. Skip to Step 5.

For Scenario C: MIND.md already exists — skip to Step 3.

Step 3 — Scaffold implementation.py (Scenario A only)

List available templates:

ls mind_templates/*.py

Ask the user which template matches their harness + model family. Copy it:

mkdir -p minds/<name>
cp mind_templates/<selected>.py minds/<name>/implementation.py

Replace the MIND_NAME placeholder:

sed -i 's/MIND_NAME/<name>/g' minds/<name>/implementation.py

Create minds/<name>/__init__.py (empty file).

Step 4 — Generate compose (Scenario A only)

Skip this step for Scenarios B, C, and D.

For Scenario A: check if the MIND.md has a container: block. If it does, run /generate-compose to update docker-compose.yml with the new mind's service definition, then start the container:

docker compose up -d <name>

If the mind does NOT have a container: block, it runs inside the main hive_mind container (subprocess mode) — skip this step.

Step 5 — Register with broker

curl -s -X POST http://localhost:8420/broker/minds \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","gateway_url":"<gateway_url>","model":"<model>","harness":"<harness>"}'

If the response contains an error, stop and surface it to the user.

Step 6 — Verify routability

Create a test session:

curl -s -X POST http://localhost:8420/sessions \
  -H "Content-Type: application/json" \
  -d '{"owner_type":"test","owner_ref":"add-mind-verify","client_ref":"add-mind","mind_id":"<name>"}'

Extract the session ID from the response. Send a test message:

curl -s -X POST http://localhost:8420/sessions/<session_id>/message \
  -H "Content-Type: application/json" \
  -d '{"content":"Respond with exactly: registration verified."}'

Check if the response stream contains "registration verified". Then clean up:

curl -s -X DELETE http://localhost:8420/sessions/<session_id>

If routability check fails, surface the error clearly but do NOT roll back the registration — the mind is registered, it just couldn't respond yet.

Step 7 — Report

Summarize:

• Scenario handled (A=Docker / B=Remote / C=Re-registration / D=Bare-metal)
• Files created (MIND.md, implementation.py, init.py — Scenario A only)
• Containerised (yes/no, compose updated — Scenario A only)
• Broker registration status
• Routability verification result