• The user (or an agent via mcp__swarm__clear-session-tool) clears the session without passing new_session_instructions. The server pastes the universal nudge prompt followed by your brief.
• A fresh box boots with no task brief queued — same paste, same shape.

When a clear does carry explicit new_session_instructions, those win — the brief is the fallback for the "no idea what to do next" case, not a replacement for a concrete task brief.

Three places to set the brief. The most specific one wins.

Fallback order at paste time: per-box override → pool override → system default. A blank textarea on any layer means "fall through to the next one".

The brief is pasted verbatim into the agent's terminal as its first instruction after /clear. It has to spell out the exact ask-question-tool shape the agent should fire — there's no UI builder in between, and the agent has no context to fill in gaps. A working brief covers:

1. Use mcp__swarm__ask-question-tool to ask what to do next.
2. A use-case-appropriate title (e.g. "What's next?" for dev, "How can I help?" for an assistant).
3. 3–5 informed-guess option buttons with explicit key=... / label="..." lines.
4. A multiline free-text input ("Notes" or similar) so the user can describe something the buttons miss.
5. Tags: repo:<git-repo>, branch:<git-branch>, agent:<your-hostname>.
6. intent="new_work" (this card is the queue hook — the work-queue dispatcher only fills new_work cards).
7. Instruction to end the turn after asking — no polling, the server pastes the answer back.

Max length is 8000 chars. Avoid apostrophes in the brief body — it travels through escapeshellarg on its way into a tmux paste-buffer. If you need to write apostrophes in the question itself, tell the agent to put them in the message body (which the agent assembles on the other side, not shell-escaped).

Both the per-box and per-pool editors have an AI assist button. Type a few words describing what the box is for ("personal assistant that reads my email and calendar"), hit AI assist, and the model expands it into a complete brief in the required shape. Anything the seed doesn't cover comes back as a TODO: placeholder you can spot and fill in before saving.

Requires an OpenRouter API key on your account — set it in Integrations settings. The same model that powers inbox digests drafts the brief.

Suppose this box has MCP servers for Gmail, Google Calendar, and an inbox-digest action wired up. The default Feature/Bug/Testing prompt doesn't fit — when the user opens the PWA in the morning, they want a very different set of buttons. Paste this into the Nudge brief panel on the box (or on the pool, if you run several assistant boxes):

You are a personal assistant. The session was just cleared with no specific task brief. Before doing anything else, call mcp__swarm__ask-question-tool to ask the user how you can help.

The card must include exactly these option buttons (use these keys verbatim so answers are easy to filter later) plus one free-text input:

- key=daily_brief    label="Daily brief"      - summarise unread email + today and tomorrows calendar in one push
- key=read_email     label="Read email"       - triage the inbox, surface anything that needs a reply or action
- key=check_calendar label="Check calendar"   - what is on the agenda today, this week, or a date the user names
- key=draft_reply    label="Draft a reply"    - draft a response to a specific thread the user picks
- key=research       label="Research"         - look something up and report back
- key=notes          label="Notes"            - multiline text input, placeholder "Anything else? A person, a topic, a deadline, the goal..."

Title the card "How can I help?" and tag it with the current repo, git branch, and your agent label (e.g. repo:<git-repo>, branch:<git-branch>, agent:<your-hostname>). Pass intent="new_work" because you are idle and asking what to pick up. Avoid apostrophes in this brief because it travels through escapeshellarg on its way into a tmux paste-buffer; when you need them in your own message body, paste them there since that part is not shell-escaped.

After asking, end your turn. The server will paste the user answer back into this pane via the standard [answer] notification. On the next turn:

1. Read the answer via mcp__swarm__get-question-tool.
2. Declare working state via mcp__swarm__update-working-state-tool with is_idle: false and a one-line working_on summarising the task.
3. Run the right tool for the selected button:
   - daily_brief: fetch unread Gmail threads + today/tomorrow Google Calendar events, summarise both in one mcp__swarm__send-message-tool push titled "Daily brief", tagged daily-brief plus the usual repo/branch/agent tags.
   - read_email: list the most recent unread threads, group by sender, push a short summary plus any threads that look like they need a human reply.
   - check_calendar: pull events for the window the user named (today by default), push a single message with a markdown bullet list.
   - draft_reply: ask a follow-up clarification question (intent="clarification") for which thread, then draft the reply as a message body for the user to approve before sending.
   - research: ask a follow-up clarification question for the exact topic, then return a short writeup as a message.
4. When the work wraps, flip is_idle back to true with working_on: null and end the turn.

Same brief on every assistant box in a personal-assistant pool — set it once at the pool layer and every box in the pool inherits. If one of those boxes needs a different ask (say, a research-only box without calendar access), set its per-box override and the pool's brief stops applying to that box.

The brief fires on /clear and on boot — but a personal-assistant box probably also wants the morning brief to land without the user having to open the PWA. Pair the brief with a routine that targets the same pool and runs at 07:00 every day with a prompt like "Run the daily brief: unread email + today + tomorrow on the calendar, one push." The routine dispatcher hands it to the oldest-idle box in the pool, the agent runs it, and you wake up to one notification instead of having to ask.

The brief and the routine answer different questions — the brief covers "the session just cleared, what now?", the routine covers "it's 07:00, do the thing." Both want the same agent shape, so keep the language consistent across them.

• Saved the brief but the agent still asks Feature/Bug? The brief only fires on a fresh boot or a clear-without-instructions. Trigger a clear via the dev box show page (Helpers → Clear session) to load it.
• Agent posts the question with the wrong title / missing options? The agent only knows what the brief tells it. Re-read your brief and make sure every required button has an explicit key=... + label="..." line.
• Agent asks but never wakes when the user answers? The brief must instruct the agent to end its turn after asking and let the server's [answer] paste wake the next turn. Polling with wait-for-answer-tool on a Swarm-spawned box defeats the push.
• Shell-escape glitches in the pasted text? Strip apostrophes from the brief body — it travels through escapeshellarg on its way into the tmux paste-buffer.
• Brief exceeds 8000 chars? Trim it. The buffer is capped server-side and a too-long brief is silently truncated.

• Swarm agent operating spec — the full runtime contract the brief plugs into.
• Routines — schedule the same agent shape on a cron.
• Presets — bake the brief into a spawn template.