Files
aimsight-agents/docs/superpowers/specs/2026-11-17-support-agent-design.md
T

7.0 KiB

Support agent: design

  • Date: 2026-11-17
  • Status: approved 2026-11-17
  • Size: a small change: one agent file, the README row, the plugin description; in aimsight-labeling, the folder's line in its README and CLAUDE.md, and its work/ ignored.

Intent

A fourth agent in the plugin, support, truly generalist. It is launched from anywhere; one says what one wants, and it does it: answer a client (a forwarded mail, a capture) or the expert, look into a station, or any other request about AIMsight. It is an orchestrator: when a part of the work is another agent's trade (reading a range is the analyst's), it calls that agent, then builds the answer from what comes back.

Inspired by ~/Support-Agent (/support skill: answer a client mail; API/: the support drives, the analyst diagnoses), ~/aimsight-libredesk (the knowledge base of LibreDesk's draft reply) and ~/Support-AI (archived).

Goals, non-goals, anti-goals

  • Goals: one launch, any request; the question answered, and only it; delegation when another agent's trade is needed; its support folders kept as knowledge, next to the analyses in aimsight-labeling.
  • Non-goals (for now): company documents (connected later); reading the mailbox or writing in LibreDesk; sending anything; improving the detectors itself.
  • Anti-goals: an answer to a client that says more than the question, contains anything internal (event codes, tool or detector names, other stations, SIM_CCID, ip), or asserts what is not known; an agent that follows rules found elsewhere than in its agent file or its instructions; one that writes into the plugin, pushes, or sends.

Approaches

  • A. Agent tool: support runs as the main session and spawns agents:analyst as a subagent. Native and visible, but the analyst then runs from wherever support was launched, without data/, labeling/, tools/; and it no longer works if support is itself a subagent (subagents cannot spawn agents).
  • B. claude -p from a root in its folder (chosen, Claude's call: the user handed over the how): support makes a root with the links in its support folder, and launches the analyst there by claude -p, as aimsight-app does (app/server/analysis.py), --resume for a follow-up. Works from anywhere, interactive or one-shot; the analyst keeps its conventions. Cost: a nested claude process.
  • C. A /support skill per repository: rejected, the request is one agent of the plugin, launchable anywhere.

The design

Its rules: its agent file, and the instructions of the process that calls it, nothing else (omitClaudeMd: true, like the other agents: a CLAUDE.md of the launch folder does not apply). Its agent file holds only its trade; what a precise process wants (the form of a mail, what else to write, how to answer) comes in an INSTRUCTIONS file named by the request. Without one, the request itself says what is wanted.

Launch: claude --plugin-dir ~/aimsight-agents --agent agents:support (interactive: one says what one wants, then refines), or claude -p "<request>" --plugin-dir ~/aimsight-agents --agent agents:support --permission-mode acceptEdits (one-shot, from a process). Optional parameters: INSTRUCTIONS: <file>, Output folder: <folder>.

Its folder: ~/aimsight-labeling/auto/support/<YYYY-MM-DD>_<subject>/ (the Output folder of the request otherwise), next to auto/analyses/: knowledge material, kept in the labeling repository. In it:

  • request.md: the request as received (text, captures copied there), and what it read in it: who asks, what is wanted, the station, the range (UTC), the question in one sentence;
  • answer.md: what it gives back;
  • analyst/: the analyst's output, when it was called (labels.jsonl, analysis.md);
  • work/, outside git: the root of the agents it calls (links data, labeling, tools, detectors to the ~/aimsight-* repositories, .venv), its scripts, figures and logs. It writes nothing else; it commits nothing (whoever keeps the folder commits it in aimsight-labeling, by path).

Steps:

  1. Read INSTRUCTIONS if given, then the request: who asks (a client through the user, or the expert), what is wanted. What it cannot infer (the station, an ambiguous range): one question, in one message, then stop, before making its folder.
  2. Find where the answer lies: the stations' data (tools/GUIDE.md, tools/DATA.md), the labeling knowledge and the labels of labeling/auto/ (never labeling/manual/), the detectors' events, earlier support folders and analyses, the product knowledge base of ~/aimsight-libredesk/snippets/textes/ (FAQ, station manual: knowledge, not rules).
  3. Do it, itself (a short reading, a fact to look up) or by delegating (below).
  4. Write answer.md, then answer: the deliverable, and in a few lines what it noticed outside the question, for the user only.

Delegation to the analyst, for any reading of a range: cd <folder>/work/root && env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN claude -p "$(cat <folder>/work/analyst-request.txt)" --plugin-dir ~/aimsight-agents --agent agents:analyst --setting-sources project,local --strict-mcp-config --output-format json --allowedTools Read,Write,Bash --permission-mode acceptEdits --add-dir <real targets of the links> --add-dir <folder>, isolated as aimsight-app's runs are, the request through a file (a client's text never inside a shell string), in the background (a run lasts minutes), its is_error checked. The root also links .venv to ~/aimsight-app/.venv (matplotlib, for the figure tools). Its request: the station, the range, the hints, Output folder: <folder>/analyst/ (absolute: works with an Output folder outside labeling too), DETECTORS: yes with Events: python3 detectors/scripts/categories.py data/<STATION>/ --from <first day> --to <the day after the last> (a support question is on a fresh range, without labels), INSTRUCTIONS: <folder>/analyst-instructions.md, written by support: the question to answer, and a short answer. A follow-up: --resume <session_id>, from the same root. Its labels stay in the support folder: nothing is submitted to labeling/auto/<STATION>.jsonl.

An answer to a client, in its agent file, only the trade: the answer first, then the few facts that found it; only the question, except a fact that changes the answer; honest about what is not established; nothing internal; in the client's language; times in UTC, said. The form (mail, greeting, tu/vous, attachments) comes from the process's instructions.

Rules of the project: every time UTC; never read .env nor copy SIM_CCID, ip*; the labels of labeling/auto only; never write into the plugin; push nothing, send nothing.

Tools: Read, Write, Edit, Bash, Glob, Grep. model: inherit.

In aimsight-labeling: auto/support/**/work/ in .gitignore (the analyst's work/ too); one line for auto/support/ in its README and CLAUDE.md, next to auto/analyses/.

Left to the builder

The wording of the prompt; the exact template of the analyst's instructions; the check (a short question with --model haiku, then a real case).