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

111 lines
8.1 KiB
Markdown
Raw Normal View History

# 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).