9.1 KiB
/optimize 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: Optimizer's /optimize ANALYSIS: <folder> optimises the detectors and the reading tools from one analysis; Diagnostic-App calls it once.
Architecture: /improve is moved to /optimize, derives its inputs from the analysis folder, keeps its detectors steps, then runs agents:tool-builder as a subagent and writes one summary. The tool-builder writes only in the session folder. Diagnostic-App's optimisation becomes a single claude -p turn in Optimizer.
Tech Stack: Claude Code skills and agents (Markdown), Python 3 (Diagnostic-App server and its check.py).
Spec: docs/superpowers/specs/2026-11-16-optimize-design.md
Global Constraints
- English everywhere; every time UTC.
- Commit by path, never
git add -A; each repository on its current branch (Optimizermaster, the othersmain); nothing pushed. - Commit messages end with an empty line then
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>. - Optimizer is read-only on
data/andlabeling/; the agents never run on an API key. - Detector fix commits stay
improve: S<n>.
Review Focus
/optimizewithout inputs, or with an analysis folder lackingrequest.json: says what is missing, stops, touches neitherdetectors/nortools/(Task 2, Step 4).- An analysis whose range carries no label (
score.pyexits with an error): the detectors part stops, the tools part still runs (Task 2 skill text, Step 4 review). - An analysis that ends at midnight:
TO= the day afterend, as Diagnostic-App does today (Task 2 skill text). - The tool-builder never writes in the analysis folder (Task 1).
- Diagnostic-App with Optimizer lacking the
toolslink: a clear refusal (Task 3, Step 1).
Task 1: the tool-builder writes in its report's folder (agents)
Files:
-
Modify:
~/agents/agents/tool-builder.md(lines 3, 44-45, 65) -
Modify:
~/agents/agents/upgrader.md:3,8,~/agents/agents/validator.md:3,8,~/agents/README.md:8-10 -
Step 1: In
tool-builder.md, Check step 1:--out <the folder of your report>/work/tools/instead of<analysis>/work/tools/; Check step 2: rerun the report's commands with their--outreplaced by<the folder of your report>/work/; add "You write nothing in the analysis folder." to "What you touch"; report template "figures in /work/tools/". Description: launched by Optimizer's/optimize(Agent tool,agents:tool-builder). -
Step 2: "improve workflow" → "optimize workflow" in
upgrader.md,validator.md; README table: requests "that of theoptimizeskill", the tool-builder's caller "Optimizer (/optimize)". -
Step 3:
grep -n "work/tools\|improve workflow\|improve\skill" ~/agents -rreturns only` lines. -
Step 4: Commit in
~/agents:Optimize: the tool-builder writes in its report's folder; run by Optimizer's /optimize.
Task 2: the /optimize skill (Optimizer)
Files:
- Move:
.claude/skills/improve/SKILL.md→.claude/skills/optimize/SKILL.md(git mv) - Create: link
tools -> ~/tools(ignored or untracked, like the others) - Modify:
README.md,CLAUDE.md
Interfaces:
-
Produces: request
/optimize ANALYSIS: <analysis folder>/. OUT: sessions/<analysis>_<YYYYMMDDTHHMMZ>/. Caller's context: …; optional overridesDETECTORS,TOOLS,DATA,LABELS,FAMILIES; output<OUT>/summary.md(first line# optimize: <station>, <FROM> → <TO>, lines**Result**:and**Tools changed**:),<OUT>/tools.md. -
Step 1: Skill frontmatter
name: optimize, description: the workflow that, from one analysis, improves the detectors (upgrader, validator) and the reading tools (tool-builder). -
Step 2: Inputs section per the spec:
ANALYSIS,OUTrequired; defaultsDETECTORS: detectors/,TOOLS: tools/,DATA: data,LABELS: labeling/auto,FAMILIES: labeling/families.md; derivedSTATION,FROM,TO(day afterend), labels file, reference,CONTEXT. MissingANALYSIS/OUT, norequest.json,DETECTORSorTOOLSnot a git repository: say so, stop, change nothing. Remove theDATA+STATIONSmode and its commands. -
Step 3: Steps: "Part 1, detectors" = the current steps (unchanged; a stop in part 1 — no label on the range, an agent missing — goes to part 2, not to the end); "Part 2, tools", always: Agent tool
agents:tool-builder, requestAnalysis: <ANALYSIS>/. Tools: <TOOLS>/. Write <OUT>/tools.md., plus the caller's context; its output missing: note it. Summary: title# optimize: …, the detectors part as now,**Tools changed**:under**Result**:, section## Reading tools(copied: "Tools changed", "What I decided" of<OUT>/tools.md),## Toolsrenamed## Scripts of the agents. Answer: add the**Tools changed**line. -
Step 4: Run
env -u ANTHROPIC_API_KEY claude -p "/optimize" --plugin-dir agents --model haiku, then the same with"/optimize ANALYSIS: labeling/auto/analyses/nothing/. OUT: /tmp/x/". Expected: both say what is missing and stop;git -C detectors status --shortandgit -C tools status --shortempty. -
Step 5:
ln -s ~/tools tools; checkgit statusdoes not showtoolsas a new file to commit (add it to.gitignoreif the other links are there). -
Step 6:
README.md: scope "the detectors and the tools, from an analysis"; the steps; thetoolslink; the by-hand command/optimize ANALYSIS: labeling/auto/analyses/<analysis>/. OUT: sessions/<analysis>_<YYYYMMDDTHHMMZ>/.with--add-dir ~/tools; what a session leaves (tools.md,work/).CLAUDE.md: the same scope, link and check command. -
Step 7: Commit in Optimizer by path: the moved skill,
README.md,CLAUDE.md,.gitignoreif changed, the spec and this plan:Optimize: /optimize, the detectors and the tools from one analysis (ex /improve).
Task 3: Diagnostic-App calls /optimize once
Files:
- Modify:
~/Diagnostic-App/app/server/analysis.py(docstring 1-11,IMPROVE29-33,optimize262-268,optimize_thread275-297) - Test:
~/Diagnostic-App/app/server/check.py(check_optimization, 135-166) - Modify:
~/Diagnostic-App/CLAUDE.md:5,8,README.md:6,25,app/README.md:24,41
Interfaces:
-
Consumes: Task 2's request.
-
Step 1: the failing check. In
check_optimization: createskills/optimize/SKILL.mdinstead ofimprove; the links loop("data", "labeling", "detectors", "tools")with a refusal asserted beforetoolsexists; after the runassert len(launched) == 1;request.startswith("/optimize ANALYSIS: labeling/auto/analyses/NORDEND_a/. OUT: sessions/NORDEND_a_"),k["cwd"] == analysis.OPTIMIZER.resolve(),"--plugin-dir" in args; remove thelaunched[1]tool-builder assertions; keep the old<analysis>/tools.mdsummary assertion. -
Step 2:
cd ~/Diagnostic-App && .venv/bin/python app/server/check.py→ FAIL incheck_optimization. -
Step 3:
IMPROVE→OPTIMIZE = "/optimize ANALYSIS: labeling/auto/analyses/{name}/. OUT: sessions/{name}_{time}/. Caller's context: Diagnostic-app, through Optimizer; read-only on data/ and labeling/; commit only in detectors/ and tools/, on their current branch; do not commit OUT.";optimize()checksskills/optimize/SKILL.mdand thetoolslink;optimize_threadone turn inOPTIMIZER.resolve()with--plugin-dir AGENTS.resolve(),--add-dirdetectors (station.links() already adds tools),--allowedTools Read,Write,Edit,Bash,Agent; therequest.jsonread andTOcomputation removed (Optimizer derives them); docstrings say/optimize. -
Step 4:
.venv/bin/python app/server/check.py→ passes. -
Step 5: Docs: "Optimize the detectors" launches
/optimizeinoptimizer/on the analysis (detectors committed indetectors/, tools intools/); contract "the request of/optimize";app/README.mdthe single launch; summary path. -
Step 6: Commit in Diagnostic-App by path:
Optimize: a single /optimize call in Optimizer, the detectors and the tools.
Task 4: wording in detectors and tools
Files: ~/detectors/CLAUDE.md:3,12, ~/detectors/README.md ("Improving them"), ~/tools/README.md ("Who changes it")
- Step 1:
improveskill →optimizeskill (detectors); the tool-builder "run by Optimizer's/optimize, after each analysis optimised" (tools). History references (wf-improve,improve: S<n>) unchanged. - Step 2: Commit each repository by path:
Optimize: the skill is /optimize.
Task 5: final check
grep -rn "/improve\|improve\skill|skills/improve" ~/Optimizer --include=*.md -l | grep -v "archive/|sessions/|docs/superpowers"and the same on Diagnostic-App (outsidedocs/superpowers,node_modules`), agents, detectors, tools: nothing left.- Diagnostic-App
check.pypasses; the Task 2 haiku runs stop cleanly. - Left to the user: a real session through the app's button (it commits in
detectorsandtools).