Reorganize plot implementations under python/ subdirectory (#5648)

## Summary

This PR reorganizes the plot implementation directory structure to
explicitly namespace implementations by language. All Python plot
implementations are now stored under
`plots/{spec_id}/implementations/python/` instead of directly under
`plots/{spec_id}/implementations/`, and corresponding metadata files are
moved to `plots/{spec_id}/metadata/python/`.

## Key Changes

- **Update command documentation** (`agentic/commands/update.md`):
Updated all path references to reflect the new `implementations/python/`
and `metadata/python/` structure throughout the update workflow,
including:
  - Default library scanning paths
  - Preview image generation and comparison paths
  - Ruff formatting and linting commands
  - Metadata YAML file locations
  - GCS upload and staging paths
  - Per-library branch and worktree setup
  - Agent instruction paths

- **Simplify planning command documentation**
(`agentic/commands/bug.md`, `feature.md`, `refactor.md`, `chore.md`):
Removed redundant "Codebase Structure" sections from each planning
command and consolidated guidance to reference
`agentic/docs/project-guide.md` as the single source of truth for
project layout. Clarified that these commands produce plans only and
should not execute implementation.

- **Update agent infrastructure** (`agentic/commands/agentic.md`,
`audit.md`, `audit/agentic-auditor.md`, `audit/catalog-auditor.md`):
Updated Serena tool references from `jet_brains_*` aliases to the
canonical `mcp__serena__*` prefix to match `.claude/settings.json`
registration.

- **Improve command clarity** (`agentic/commands/start.md`,
`implement.md`, `test.md`, `commit.md`, `pull_request.md`, `review.md`,
`document.md`): Enhanced instructions with more specific guidance on
execution order, error handling, scope boundaries, and output format
requirements. Removed duplicate "Codebase Structure" sections in favor
of referencing the project guide.

- **Rename documentation router** (`agentic/commands/docs.md`, formerly
`context.md`): Renamed to avoid collision with Claude Code's built-in
`/context` command. Updated all references across the codebase.

- **Clarify JSON output requirements** (`agentic/commands/classify.md`,
`review.md`): Emphasized that JSON responses must be on a single line
with no preamble or markdown formatting, as they are parsed directly by
downstream code.

## Implementation Details

The directory structure change is comprehensive and affects:
- Agent workflow paths for reading and writing implementation files
- GCS staging and upload paths for plot images and HTML
- Metadata file locations for storing review feedback and quality scores
- Preview image generation and comparison workflows
- Per-library branch creation and file staging

All path updates maintain consistency across the update workflow
documentation to ensure agents and the lead coordinator work with the
correct directory structure.

https://claude.ai/code/session_01GWQrCaJZGt4nVRz7ct2LHs

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: MarkusNeusinger

agentic/commands/agentic.md

@@ -86,7 +86,7 @@ When routing to a single leverage point, include the point number in the task de
 ### Phase 2: Parallel Analysis
 
 Each specialist receives a focused prompt (see below). They:
-- Use **Serena tools** (`jet_brains_get_symbols_overview`, `jet_brains_find_symbol`, `search_for_pattern`, `list_dir`, `find_file`, `jet_brains_find_referencing_symbols`) and **Glob/Grep/Read** for code analysis
+- Use **Serena tools** (`mcp__serena__get_symbols_overview`, `mcp__serena__find_symbol`, `search_for_pattern`, `list_dir`, `find_file`, `mcp__serena__find_referencing_symbols`) and **Glob/Grep/Read** for code analysis
 - Do **NOT** use Bash for file discovery or code searching — only for `uv run ruff`, `uv run pytest`, or similar shell-native commands
 - Send findings to `agentic-lead` via `SendMessage` when done
 - Mark their task completed via `TaskUpdate`
@@ -192,7 +192,7 @@ You are the **core-auditor** on the agentic-audit team. Analyze leverage points
 **Where to look:**
 - `CLAUDE.md` — primary agent-facing context
 - `.claude/` — tool configuration, settings
-- `agentic/commands/context.md` — conditional documentation routing
+- `agentic/commands/docs.md` — conditional documentation routing (`/docs` slash command)
 - `agentic/docs/` — project guides
 - `agentic/context/` — feature-specific context documents
 - `README.md`, `.github/copilot-instructions.md`
@@ -279,10 +279,10 @@ You are the **core-auditor** on the agentic-audit team. Analyze leverage points
 
 **How to work:**
 1. Use `list_dir` to explore directories listed above
-2. Use `jet_brains_get_symbols_overview` on key files
+2. Use `mcp__serena__get_symbols_overview` on key files
 3. Use `search_for_pattern` for patterns like `CLAUDE.md`, model references, `mcp`, `prompt`
 4. Use Read to examine prompt files and configuration
-5. Use `jet_brains_find_symbol` with `depth=1` to inspect MCP tools and CLI commands
+5. Use `mcp__serena__find_symbol` with `depth=1` to inspect MCP tools and CLI commands
 6. Use Grep to count lines in large files: check for >1000-line files as context bloat risk
 7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Serena/Glob/Grep/Read tools instead
 8. You MAY use Bash for: `uv run python -c "..."` to inspect tool registrations
@@ -379,7 +379,7 @@ You are the **environment-auditor** on the agentic-audit team. Analyze leverage
 
 **Where to look:**
 - `agentic/docs/` — agent-facing documentation
-- `agentic/commands/context.md` — conditional documentation router
+- `agentic/commands/docs.md` — conditional documentation router (`/docs` slash command)
 - `agentic/context/` — feature-specific context documents
 - `docs/` — general documentation
 - `docs/concepts/`, `docs/reference/`, `docs/workflows/`
@@ -424,7 +424,7 @@ You are the **environment-auditor** on the agentic-audit team. Analyze leverage
 
 **How to work:**
 1. Use `list_dir` with `recursive=false` to map top-level and sub-directory structure
-2. Use `jet_brains_get_symbols_overview` on key files to check type annotations
+2. Use `mcp__serena__get_symbols_overview` on key files to check type annotations
 3. Use `search_for_pattern` for anti-patterns (e.g., `Any`, `# type: ignore`, `print(`, `: any`, `console.log`)
 4. Use Read to examine config files (`tsconfig.json`, `pyproject.toml` type sections)
 5. Use Grep to find logging, error handling, and type annotation patterns
@@ -552,8 +552,8 @@ You are the **workflow-auditor** on the agentic-audit team. Analyze leverage poi
 
 **How to work:**
 1. Use `list_dir` to explore `tests/`, `agentic/specs/`, `agentic/workflows/`, `agentic/commands/`, `prompts/`
-2. Use `jet_brains_get_symbols_overview` on workflow scripts and test files
-3. Use `jet_brains_find_symbol` to inspect workflow classes, fixtures, orchestrators
+2. Use `mcp__serena__get_symbols_overview` on workflow scripts and test files
+3. Use `mcp__serena__find_symbol` to inspect workflow classes, fixtures, orchestrators
 4. Use Read to examine spec files, templates, and workflow configurations
 5. Use `search_for_pattern` for patterns like `prompt_claude_code`, `WorkflowState`, `@pytest.fixture`, `$ARGUMENTS`
 6. Use Glob to find all test files (`**/*test*.py`, `**/*.test.ts`) and template files

agentic/commands/audit.md

@@ -87,7 +87,7 @@ You are the **audit-lead**. Your job is to coordinate a team of specialist audit
 ### Phase 2: Parallel Analysis
 
 Each specialist receives a focused prompt loaded from `agentic/commands/audit/<name>-auditor.md` (see the Specialist Prompts index below). They:
-- Use **Serena tools** (`mcp__serena__get_symbols_overview`, `mcp__serena__find_symbol`, `search_for_pattern`, `list_dir`, `find_file`, `mcp__serena__find_referencing_symbols`) and **Glob/Grep/Read** for code analysis. **Tool-naming note:** `mcp__serena__*` is the canonical MCP-registered prefix that matches `.claude/settings.json` (`mcp__serena__*` is in `permissions.allow`); some other repo docs (`CLAUDE.md`, `.serena/project.yml`, `agentic/commands/prime.md`) still reference legacy aliases like `jet_brains_*` or unprefixed names — treat those as the same tools and prefer the `mcp__serena__*` form here.
+- Use **Serena tools** (`mcp__serena__get_symbols_overview`, `mcp__serena__find_symbol`, `search_for_pattern`, `list_dir`, `find_file`, `mcp__serena__find_referencing_symbols`) and **Glob/Grep/Read** for code analysis. **Tool-naming note:** `mcp__serena__*` is the canonical MCP-registered prefix that matches `.claude/settings.json` (`mcp__serena__*` is in `permissions.allow`). A few external configs (`CLAUDE.md`, `.serena/project.yml`) may still reference legacy `jet_brains_*` aliases — treat those as the same tools and use the `mcp__serena__*` form here.
 - Use `think_about_collected_information` after non-trivial research sequences
 - Do **NOT** use Bash for file discovery or code searching — only for the per-auditor whitelisted shell commands
 - Stay within the tool budget (~30 calls); set `COVERAGE: partial` if forced to stop early

agentic/commands/audit/agentic-auditor.md

@@ -8,7 +8,7 @@ You are the **agentic-auditor** on the audit team. Your scope is the **agent erg
 - `prompts/`: same drift checks the llm-pipeline-auditor does at the SDK layer, but at the *prompt-management* layer — versioning, ownership, where prompts are loaded from, whether inline prompts in code should have moved to files
 - `.claude/`: settings sanity (`settings.json`, `settings.local.json`), permission/hook configuration, MCP server registration consistency
 - `agentic/workflows/`, `agentic/audits/`, `agentic/scripts/`, `agentic/docs/`: directory hygiene, naming conventions, abandoned subdirectories, docs that contradict CLAUDE.md
-- TAC-style sanity (only flag what's actually weak): conditional docs (`/context`-style), model routing per task, self-validation loops, ADWs, context-window discipline (commands that load way more than they need)
+- TAC-style sanity (only flag what's actually weak): conditional docs (`/docs`-style routing), model routing per task, self-validation loops, ADWs, context-window discipline (commands that load way more than they need)
 
 **How to work:**
 1. `list_dir` on the directories above

agentic/commands/audit/catalog-auditor.md

@@ -17,19 +17,19 @@ You don't need to query the database or run helper scripts. The repository under
 ## How to look
 
 - Start with `list_dir` / Glob on `plots/` to get a feel for the size and shape (how many specs, how many implementations each).
-- Pick a handful of specs to actually open — mix old and new, big and small, well-covered and sparse. Read their `specification.md`, glance at `specification.yaml`, peek at one or two `metadata/{library}.yaml` files.
+- Pick a handful of specs to actually open — mix old and new, big and small, well-covered and sparse. Read their `specification.md`, glance at `specification.yaml`, peek at one or two `metadata/python/{library}.yaml` files.
 - Follow your nose. If something looks off (missing file, suspiciously empty metadata, weird tag, mismatched fields), pull on that thread.
 - Stop when you have enough material for a few real findings. You are not building a coverage report.
 
 ## Things worth a glance (pick whichever feel productive)
 
-- **Implementation coverage** — specs with very few `implementations/*.py` files relative to the 9 supported libraries.
-- **Quality score health** — `metadata/{library}.yaml` files with `quality_score: null` (review never ran) or low scores that have been sitting around.
-- **Missing metadata files** — implementation `.py` exists but no matching `metadata/{library}.yaml` (suggests a manual merge bypassed `impl-merge.yml`).
+- **Implementation coverage** — specs with very few `implementations/python/*.py` files relative to the 9 supported libraries.
+- **Quality score health** — `metadata/python/{library}.yaml` files with `quality_score: null` (review never ran) or low scores that have been sitting around.
+- **Missing metadata files** — implementation `.py` exists but no matching `metadata/python/{library}.yaml` (suggests a manual merge bypassed `impl-merge.yml`).
 - **Spec-side rot** — specs missing `updated`, missing `tags`, missing one of the required `specification.md` sections (Description / Applications / Data / Notes), or older than the current `prompts/templates/spec.md`.
 - **Tag hygiene** — tags that look like typos (used by exactly one spec), or the same concept tagged differently across specs.
-- **GCS preview integrity** — for a small sample of `metadata/{library}.yaml` files, `HEAD` the `preview_url` and flag 404 / wrong content-type / 403.
-- **Library-version drift** — `library_version` in `metadata/{library}.yaml` vs. the floor in `pyproject.toml` `lib-{library}` extras; flag obvious staleness.
+- **GCS preview integrity** — for a small sample of `metadata/python/{library}.yaml` files, `HEAD` the `preview_url` and flag 404 / wrong content-type / 403.
+- **Library-version drift** — `library_version` in `metadata/python/{library}.yaml` vs. the floor in `pyproject.toml` `lib-{library}` extras; flag obvious staleness.
 - **Duplicate-looking specs** — descriptions that read almost identically; group them as candidates, false positives are fine.
 
 These are **suggestions**. Skip any that don't yield signal and lean into whichever turn up real findings.

agentic/commands/bug.md

@@ -11,30 +11,14 @@ prompt: $2
 ## Instructions
 
 - If the run_id or prompt is not provided, stop and ask the user to provide them.
-- Investigate the bug described in the `prompt`
-- Identify the root cause before planning the fix
-- Create the plan in the `agentic/specs/` directory with filename: `{YYMMDD}-{descriptive-name}.md`
-    - Use today's date as YYMMDD prefix (e.g., "260207-fix-api-timeout.md")
-- Research the codebase starting with `README.md`
-- Replace every <placeholder> in the `Plan Format` with the requested value
-
-## Codebase Structure
-
-- `README.md` - Project overview and instructions (start here)
-- `api/` - FastAPI backend
-  - `main.py` - App entry point
-  - `routers/` - API route handlers
-- `app/` - React frontend (Vite + TypeScript)
-  - `src/` - Source code
-- `core/` - Shared Python modules
-  - `config.py` - Configuration
-  - `database/` - Database utilities, models, and repositories
-- `plots/` - Plot specifications and implementations
-- `tests/` - Test suites
-- `agentic/` - Agentic Layer
-  - `commands/` - Prompt templates
-  - `workflows/` - Workflow scripts (`uv run`)
-  - `specs/` - Generated plans
+- Investigate the bug described in the `prompt` — identify the root cause before planning the fix.
+- This command produces a **plan only** — do NOT implement the fix here.
+- Create the plan at `agentic/specs/{YYMMDD}-{descriptive-name}.md` using today's UTC date (e.g.,
+  `260501-fix-api-timeout.md`). Run `date -u +%y%m%d` if unsure.
+- Research the codebase before writing the plan. For project layout, conventions, and tech stack, see
+  `agentic/docs/project-guide.md` and read it only if needed.
+- Replace every `<placeholder>` in the `Plan Format` with the requested value. Keep it specific and actionable —
+  vague plans produce vague fixes.
 
 ## Plan Format
 

agentic/commands/chore.md

@@ -11,30 +11,13 @@ prompt: $2
 ## Instructions
 
 - If the run_id or prompt is not provided, stop and ask the user to provide them.
-- Create a plan to complete the chore described in the `prompt`
-- The plan should be simple, thorough, and precise
-- Create the plan in the `agentic/specs/` directory with filename: `{YYMMDD}-{descriptive-name}.md`
-    - Use today's date as YYMMDD prefix (e.g., "260207-update-readme.md")
-- Research the codebase starting with `README.md`
-- Replace every <placeholder> in the `Plan Format` with the requested value
-
-## Codebase Structure
-
-- `README.md` - Project overview and instructions (start here)
-- `api/` - FastAPI backend
-  - `main.py` - App entry point
-  - `routers/` - API route handlers
-- `app/` - React frontend (Vite + TypeScript)
-  - `src/` - Source code
-- `core/` - Shared Python modules
-  - `config.py` - Configuration
-  - `database/` - Database utilities, models, and repositories
-- `plots/` - Plot specifications and implementations
-- `tests/` - Test suites
-- `agentic/` - Agentic Layer
-  - `commands/` - Prompt templates
-  - `workflows/` - Workflow scripts (`uv run`)
-  - `specs/` - Generated plans
+- Plan the chore described in the `prompt`. This command produces a **plan only** — do NOT execute the chore here.
+- Keep the plan simple, thorough, and precise. Avoid over-scoping (no extra modes or speculative steps).
+- Create the plan at `agentic/specs/{YYMMDD}-{descriptive-name}.md` using today's UTC date (e.g.,
+  `260501-update-readme.md`). Run `date -u +%y%m%d` if unsure.
+- Research the codebase before writing the plan. For project layout, conventions, and tech stack, see
+  `agentic/docs/project-guide.md` and read it only if needed.
+- Replace every `<placeholder>` in the `Plan Format` with the requested value.
 
 ## Plan Format
 

agentic/commands/classify.md

@@ -17,6 +17,9 @@ Analyze the task and classify it:
 
 ## Response
 
-Respond with ONLY a JSON object on a single line. No explanation, no markdown, no code fences:
+Respond with ONLY a JSON object on a single line. No preamble, no explanation, no markdown, no code fences. The
+response will be passed directly to `JSON.parse()`, so any extra text breaks the caller.
+
+Schema (one of `bug`, `feature`, `chore`, `refactor`):
 
 {"type": "bug", "reason": "one sentence explaining why"}

agentic/commands/commit.md

@@ -30,10 +30,15 @@ task_type: $2
 
 ## Run
 
-1. Run `git diff HEAD` to understand what changes have been made
-2. Run `git status` to see which files are modified/untracked
-3. Stage changes with `git add` — prefer adding specific files over `git add -A`
-4. Run `git commit -m "<generated_commit_message>"` to create the commit
+Run steps 1 and 2 in parallel; only proceed to staging once you have read the full diff.
+
+1. Run `git diff HEAD` to read every change that will be committed.
+2. Run `git status` to confirm the set of modified/untracked files.
+3. Stage changes with `git add <specific files>` — never use `git add -A` or `git add .`, which can pull in
+   `.env`, credentials, or large binaries by accident.
+4. Run `git commit -m "<generated_commit_message>"` to create the commit. Do not pass `--no-verify`; if a
+   pre-commit hook fails, fix the underlying issue and create a new commit (do NOT amend the previous one,
+   since the failed commit was never written).
 
 ## Report
 

agentic/commands/context.md agentic/commands/docs.mdagentic/commands/context.md renamed to agentic/commands/docs.md

@@ -1,6 +1,10 @@
 # Conditional Documentation Guide
 
-This prompt helps you determine what documentation you should read based on the specific changes you need to make in the codebase. Review the conditions below and read the relevant documentation before proceeding with your task.
+> Slash command: `/docs`. Renamed from `context.md` so the project command does not collide with Claude Code's
+> built-in `/context` command.
+
+This prompt helps you determine what documentation you should read based on the specific changes you need to make
+in the codebase. Review the conditions below and read the relevant documentation before proceeding with your task.
 
 ## Instructions
 

agentic/commands/document.md

@@ -42,35 +42,21 @@ documentation_screenshots_dir: $3 if provided, otherwise leave it blank
   - How to use it (user perspective)
   - Any configuration or setup required
 
-### 5. Update Context Documentation
-- After creating the documentation file, read `agentic/commands/context.md`
+### 5. Update Conditional Documentation Router
+- After creating the documentation file, read `agentic/commands/docs.md` (the `/docs` slash command, formerly
+  `context.md`)
 - Add an entry for the new documentation file with appropriate conditions
 - The entry should help future developers know when to read this documentation
 - Format the entry following the existing pattern in the file
 
 ### 6. Final Output
-- When you finish writing the documentation and updating context.md, return exclusively the path to the documentation file created and nothing else
+- When you finish writing the documentation and updating `agentic/commands/docs.md`, return exclusively the path to
+  the documentation file created and nothing else
 
 ## Codebase Structure
 
-- `README.md` - Project overview (start here)
-- `api/` - FastAPI backend
-  - `main.py` - App entry point
-  - `routers/` - API route handlers
-  - `services/` - Business logic
-- `app/` - React frontend (Vite + TypeScript)
-  - `src/` - Source code
-- `core/` - Shared Python modules
-  - `models/` - Pydantic models
-  - `database/` - Database utilities
-- `plots/` - Plot specifications and implementations
-- `tests/` - Test suites
-- `agentic/` - Agentic Layer
-  - `commands/` - Prompt templates
-  - `workflows/` - Workflow scripts (`uv run`)
-  - `specs/` - Plans (what to do)
-  - `context/` - Feature docs (what was done)
-  - `docs/` - Static project documentation
+For the full project layout, conventions, and tech stack, see `agentic/docs/project-guide.md`. Read it only if needed
+to ground the documentation you generate.
 
 ## Documentation Format
 
@@ -135,7 +121,7 @@ documentation_screenshots_dir: $3 if provided, otherwise leave it blank
 
 ## Context Entry Format
 
-After creating the documentation, add this entry to `agentic/commands/context.md`:
+After creating the documentation, add this entry to `agentic/commands/docs.md`:
 
 ```md
 - agentic/context/<your_documentation_file>.md