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

112 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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).