support: a generalist agent that does what it is asked, delegating a range's reading to the analyst
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
36ca927998
commit
7aaabfdca0
6 files changed
+275
-2
No files matched your search
@@ -0,0 +1,111 @@
|
||||
# Support agent Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** add `support`, a generalist orchestrator agent of the plugin, launched from anywhere, that does what it is asked and delegates a range's reading to the analyst; its folders live in `~/aimsight-labeling/auto/support/`.
|
||||
|
||||
**Architecture:** one prompt file `agents/support.md`; it calls the analyst by a nested `claude -p` from a root of links inside its own folder (`work/root/`), as aimsight-app does. aimsight-labeling ignores `auto/support/*/work/` and documents the folder.
|
||||
|
||||
**Tech Stack:** Markdown prompts for Claude Code agents (plugin `agents`, `--plugin-dir`); `claude -p`.
|
||||
|
||||
**Spec:** `docs/superpowers/specs/2026-11-17-support-agent-design.md`
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- Every time UTC; no rule specific to a station, a target or a date; never read `.env` nor copy `SIM_CCID`, `ip*`; `labeling/auto` only, never `labeling/manual/`.
|
||||
- The agent's rules: its agent file and the caller's `INSTRUCTIONS` only (`omitClaudeMd: true`); it names no caller.
|
||||
- Every `claude -p` runs on the subscription: prefixed by `env -u ANTHROPIC_API_KEY`.
|
||||
- Commit by path, never `git add -A` (aimsight-app writes in aimsight-labeling at the same time); messages end with an empty line then `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`; nothing is pushed.
|
||||
- English everywhere.
|
||||
|
||||
## Review Focus
|
||||
|
||||
- Launched from a folder that is not a repository (e.g. `/tmp`): its folder is still `~/aimsight-labeling/auto/support/…`, an absolute path (Task 2, step 3).
|
||||
- An `Output folder` in the request: it writes there, nothing in aimsight-labeling (Task 2, step 3).
|
||||
- A question needing a station it cannot infer: one question, then stop, no analyst launched (Task 2, step 4).
|
||||
- A follow-up to the analyst: `--resume` works only from the same root (sessions are keyed by the working directory): the command always `cd`s to `<folder>/work/root` (Task 2, step 1).
|
||||
- A product question needing no data: no root, no analyst, the knowledge base answers (Task 2, step 3).
|
||||
|
||||
---
|
||||
|
||||
### Task 1: the support folders in aimsight-labeling
|
||||
|
||||
**Files:**
|
||||
- Modify: `~/aimsight-labeling/.gitignore`
|
||||
- Modify: `~/aimsight-labeling/README.md:6` (after the `auto/analyses/` line)
|
||||
- Modify: `~/aimsight-labeling/CLAUDE.md:5` (after "The aimsight-app analyses: …")
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `auto/support/<YYYY-MM-DD>_<subject>/`, its `work/` outside git.
|
||||
|
||||
- [ ] **Step 1: Check that `work/` is not ignored yet**
|
||||
|
||||
Run: `git -C ~/aimsight-labeling check-ignore -q auto/support/x/work/y; echo $?`
|
||||
Expected: `1`
|
||||
|
||||
- [ ] **Step 2: Add `auto/support/*/work/` to `.gitignore`; in README a line `auto/support/<YYYY-MM-DD>_<subject>/`: the folders of the `support` agent (agents repository): the request, the answer, the analyst's work when it was called (`work/` outside git); in CLAUDE.md, "The support agent's folders: `auto/support/<YYYY-MM-DD>_<subject>/`."**
|
||||
|
||||
- [ ] **Step 3: Check**
|
||||
|
||||
Run: `git -C ~/aimsight-labeling check-ignore -q auto/support/x/work/y; echo $?`
|
||||
Expected: `0`
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git -C ~/aimsight-labeling commit -m "auto/support/: the folders of the support agent, work/ outside git" -m "Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>" -- .gitignore README.md CLAUDE.md
|
||||
```
|
||||
|
||||
### Task 2: the `support` agent
|
||||
|
||||
**Files:**
|
||||
- Create: `agents/support.md`
|
||||
- Modify: `README.md` (table: a `support` row; first paragraph unchanged)
|
||||
- Modify: `.claude-plugin/plugin.json` (`description`: "analyst, upgrader, validator, support")
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `auto/support/` (Task 1); the analyst's request (`agents/analyst.md`, "Your request").
|
||||
- Produces: `--agent agents:support`; request parameters `INSTRUCTIONS: <file>` and `Output folder: <folder>`, both optional.
|
||||
|
||||
- [ ] **Step 1: Write `agents/support.md`**
|
||||
|
||||
Frontmatter: `name: support`, a `description` naming its trade and its two parameters, `tools: Read, Write, Edit, Bash, Glob, Grep`, `model: inherit`, `omitClaudeMd: true`. Sections, in order, from the spec:
|
||||
- the trade (generalist: does what is asked; orchestrator; an answer to a client or to the expert);
|
||||
- its rules (this file and `INSTRUCTIONS` only; `INSTRUCTIONS` prevails over the rest except the project rules);
|
||||
- the request (`INSTRUCTIONS`, `Output folder`, else free text);
|
||||
- its folder (`~/aimsight-labeling/auto/support/<YYYY-MM-DD>_<subject>/`, `date -u +%F`; `request.md`, `answer.md`, `analyst/`, `work/`; writes nothing else, commits nothing);
|
||||
- where answers lie (the map: `data/` via `tools/GUIDE.md` and `tools/DATA.md`; `labeling/` knowledge, `auto/` labels and analyses, `families.md` "For the client" columns; `detectors/scripts/categories.py`; earlier `auto/support/` folders; `~/aimsight-libredesk/snippets/textes/` as knowledge, not rules);
|
||||
- steps 1–4 of the spec;
|
||||
- delegation to the analyst, with this exact command, run in the background:
|
||||
`cd <folder>/work/root && env -u ANTHROPIC_API_KEY claude -p "<request>" --plugin-dir ~/aimsight-agents --agent agents:analyst --output-format json --allowedTools Read,Write,Bash --permission-mode acceptEdits --add-dir ~/aimsight-data/data --add-dir ~/aimsight-labeling --add-dir ~/aimsight-tools`,
|
||||
the root's links `data -> ~/aimsight-data/data`, `labeling -> ~/aimsight-labeling`, `tools -> ~/aimsight-tools`, `detectors -> ~/aimsight-detectors`; the request with `Output folder: labeling/auto/support/<folder>/analyst/`, `DETECTORS: yes`, `Events: python3 detectors/scripts/categories.py data/<STATION>/ --from <day> --to <day>`, `INSTRUCTIONS: <absolute folder>/analyst-instructions.md`; follow-up by `--resume <session_id>` from the same root; nothing submitted to `labeling/auto/<STATION>.jsonl`;
|
||||
- an answer to a client (the trade only, as in the spec);
|
||||
- the project rules (Global Constraints, first line);
|
||||
- the answer (without instructions: the deliverable, then what it saw outside the question, a few lines).
|
||||
|
||||
- [ ] **Step 2: Check it loads and knows its trade**
|
||||
|
||||
Run: `env -u ANTHROPIC_API_KEY claude -p "In three lines: your trade, where your folder goes, how you call the analyst." --plugin-dir ~/aimsight-agents --agent agents:support --model haiku`
|
||||
Expected: a generalist that does what it is asked; `~/aimsight-labeling/auto/support/`; `claude -p` from `work/root`.
|
||||
|
||||
- [ ] **Step 3: A product question from `/tmp`, with an `Output folder`**
|
||||
|
||||
Run, from `/tmp`: `env -u ANTHROPIC_API_KEY claude -p "A client asks: does the camera keep measuring without a cloud connection? Output folder: <scratchpad>/support-check/." --plugin-dir ~/aimsight-agents --agent agents:support --model haiku --permission-mode acceptEdits --add-dir <scratchpad> --add-dir ~/aimsight-libredesk`
|
||||
Expected: `request.md` and `answer.md` in `<scratchpad>/support-check/`, no `analyst/`, nothing new in `~/aimsight-labeling/auto/support/`; the answer leads with yes or no, from the knowledge base.
|
||||
|
||||
- [ ] **Step 4: A station question without a station**
|
||||
|
||||
Run: `env -u ANTHROPIC_API_KEY claude -p "A client writes: my curves jumped last night, why? Output folder: <scratchpad>/support-check-2/." --plugin-dir ~/aimsight-agents --agent agents:support --model haiku --permission-mode acceptEdits --add-dir <scratchpad>`
|
||||
Expected: one question (which station), no `claude -p` launched.
|
||||
|
||||
- [ ] **Step 5: README row and plugin description**
|
||||
|
||||
Row: `support` | do what it is asked, as a generalist: answer a client or the expert, delegating a range's reading to the analyst | `INSTRUCTIONS: <file>`, `Output folder` (both optional; else `~/aimsight-labeling/auto/support/<date>_<subject>/`) | the user, from anywhere (`claude --plugin-dir ~/aimsight-agents --agent agents:support`).
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git commit -m "support: a generalist agent that does what it is asked, delegating to the analyst" -m "Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>" -- agents/support.md README.md .claude-plugin/plugin.json docs/superpowers/specs/2026-11-17-support-agent-design.md docs/superpowers/plans/2026-11-17-support-agent.md
|
||||
```
|
||||
|
||||
Left to the user: a real case with the analyst (minutes, on the subscription).
|
||||
@@ -0,0 +1,56 @@
|
||||
# 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).
|
||||
Reference in new issue
Block a user