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

8.1 KiB
Raw Blame 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 cds 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
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
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).