Reorganize plot implementations under python/ subdirectory

[MarkusNeusinger]

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

[Copilot]

Pull request overview

This PR updates the agentic command documentation to reflect a new plot directory layout where Python implementations and metadata are stored under plots/{spec_id}/implementations/python/ and plots/{spec_id}/metadata/python/, and it refreshes several command prompts for clarity and tool naming consistency.

Changes:

• Updated /update workflow documentation to use implementations/python/ and metadata/python/ paths throughout.
• Simplified multiple command docs by removing duplicated “Codebase Structure” sections in favor of agentic/docs/project-guide.md.
• Renamed the conditional docs router command to /docs (file agentic/commands/docs.md) and updated references; standardized Serena tool prefixes to mcp__serena__*.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
agentic/commands/update.md	Repoints all update-workflow path references to implementations/python/ and metadata/python/.
agentic/commands/test.md	Removes duplicated repo layout block; points to agentic/docs/project-guide.md.
agentic/commands/start.md	Clarifies running dev servers “in background” via tooling semantics and adds verification guidance.
agentic/commands/review.md	Tightens JSON-output constraints and trims duplicated layout docs (but introduces/retains JSON-shape inconsistencies).
agentic/commands/refactor.md	Clarifies “plan-only” behavior and standardizes plan path/date guidance.
agentic/commands/pull_request.md	Adds guardrails for PR creation workflow (parallel pre-checks; avoid force/no-verify).
agentic/commands/prime.md	Updates docs router reference and standardizes Serena MCP tool naming guidance.
agentic/commands/implement.md	Strengthens execution/scope/validation guidance for implementing a plan.
agentic/commands/feature.md	Clarifies plan-only behavior and standardizes plan path/date guidance.
agentic/commands/document.md	Updates conditional docs router reference to agentic/commands/docs.md.
agentic/commands/docs.md	Adds header note explaining /docs rename from context.md.
agentic/commands/commit.md	Adds safer staging/commit guidance to avoid accidentally committing sensitive/unrelated files.
agentic/commands/classify.md	Clarifies one-line JSON-only output requirements and schema.
agentic/commands/chore.md	Clarifies plan-only behavior and standardizes plan path/date guidance.
agentic/commands/bug.md	Clarifies plan-only behavior and standardizes plan path/date guidance.
agentic/commands/audit/catalog-auditor.md	Updates metadata path examples to metadata/python/ (one implementation path reference remains outdated).
agentic/commands/audit/agentic-auditor.md	Updates wording to reflect /docs routing.
agentic/commands/audit.md	Updates Serena tool prefix guidance to prefer mcp__serena__*.
agentic/commands/agentic.md	Standardizes Serena tool naming and updates docs router references to /docs.

Comments suppressed due to low confidence (1)

agentic/commands/review.md:56

• In this template the JSON-return requirements are internally inconsistent: the instructions say to return a single JSON object, but the Report section still says to return a JSON array. Downstream parsing/validation will be ambiguous; please make both sections agree on the same top-level shape (object vs array).

- IMPORTANT: Return ONLY the JSON object specified in the `Report` section below.
  - IMPORTANT: Do not include any preamble, explanation, or markdown formatting around the JSON.
  - We'll immediately run JSON.parse() on the output, so make sure it's valid JSON.
  - Match the schema exactly — extra keys or missing required keys will fail downstream parsing.
- Reason carefully through the review. Focus on critical functionality paths and the user experience. Do not
  report issues that are not material to the feature — inflated issue lists are noise, not signal.

## Codebase Structure

For the full project layout, conventions, and tech stack, see `agentic/docs/project-guide.md`. Read it only if you need
to map the diff back onto specific subsystems.

## Report

- IMPORTANT: Return results exclusively as a JSON array based on the `Output Structure` section below.
- `success` should be `true` if there are NO BLOCKING issues (implementation matches spec for critical functionality)

[Copilot]

This still refers to implementations as implementations/*.py, but plot implementations are now namespaced under implementations/python/*.py. Updating this example will keep the audit guidance aligned with the new directory structure.

Suggested change

	- **Implementation coverage** — specs with very few `implementations/*.py` files relative to the 9 supported libraries.
	- **Implementation coverage** — specs with very few `implementations/python/*.py` files relative to the 9 supported libraries.

[Copilot]

The shipping steps create a temporary plots/{spec_id}/implementations/python/plot.png in the implementations directory. This conflicts with the earlier “never create files in implementations/python/ directly” guidance and increases the risk of accidentally committing/overwriting artifacts. Prefer processing/uploading directly from the per-library .update-preview/{library}/plot.png (or write to a dedicated temp/staging path under .update-preview/) so no extra files are created alongside source implementations.

[Copilot]

These instructions emphasize strict JSON.parse() parsing and exact schema matching, but the Output Structure example further down in this file is not valid JSON (e.g., unquoted keys). Please update the example to valid JSON so the prompt doesn't encourage outputs that will fail parsing.