111 lines
8.1 KiB
Markdown
111 lines
8.1 KiB
Markdown
# 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).
|