From 8dd1f4e919958da764415cb9821299d9165983b9 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 2 May 2026 20:58:36 +0000 Subject: [PATCH 1/3] chore(commands): split prime into lightweight and deep variants Reduce per-session token overhead by making /prime self-contained (~330 tokens) with project basics, top-level dirs, and the GitHub pipeline summary. Move the full architecture tour (project-guide.md + vision.md + pyproject.toml) to /prime-deep for when it's actually needed. --- agentic/commands/prime-deep.md | 48 ++++++++++++++++++++++++++++ agentic/commands/prime.md | 58 ++++++++++++++++------------------ 2 files changed, 76 insertions(+), 30 deletions(-) create mode 100644 agentic/commands/prime-deep.md diff --git a/agentic/commands/prime-deep.md b/agentic/commands/prime-deep.md new file mode 100644 index 0000000000..618d57a02f --- /dev/null +++ b/agentic/commands/prime-deep.md @@ -0,0 +1,48 @@ +# Prime (Deep) + +> Full project orientation. Use when starting architecture work, refactors, or when unsure about the codebase. For quick starts, use `/prime` instead. + +## Run + +```bash +# Current state: branch, uncommitted changes, stashes +git status --short --branch + +# Recent activity: what's been worked on +git log --oneline --graph -15 + +# Open PRs: what's in flight +gh pr list --limit 10 2>/dev/null || echo "(gh CLI not available)" +``` + +## Read + +@agentic/docs/project-guide.md +@agentic/commands/context.md +@docs/concepts/vision.md +@pyproject.toml + +## Serena + +- Run `check_onboarding_performed` +- Run `list_memories` and read relevant ones + +### JetBrains Tools (prefer over brute-force scanning) + +Use Serena's JetBrains-backed tools for code navigation — they provide semantic understanding +that grep/glob cannot: + +- `jet_brains_get_symbols_overview` — get top-level symbols in a file (classes, functions, variables). Use with `depth: 1` to also see methods of classes. Start here to understand a file before diving deeper. +- `jet_brains_find_symbol` — search for a symbol by name across the codebase. Supports name path patterns like `MyClass/my_method`. Use `include_body: true` to read source code, `include_info: true` for docstrings/signatures. +- `jet_brains_find_referencing_symbols` — find all usages of a symbol (who calls this function? who imports this class?). Essential for understanding impact of changes. +- `jet_brains_find_declaration` — jump to where a symbol is defined. +- `jet_brains_find_implementations` — find implementations of an interface/abstract class. +- `jet_brains_type_hierarchy` — understand class inheritance chains. + +### Editing via Serena + +For structural edits, prefer Serena's symbol-aware tools over raw text replacement: + +- `replace_symbol_body` — replace an entire function/class body +- `insert_after_symbol` / `insert_before_symbol` — add code relative to a symbol +- `search_for_pattern` — regex search across the codebase (fast, flexible) diff --git a/agentic/commands/prime.md b/agentic/commands/prime.md index c88b9ee8b3..684aac85c8 100644 --- a/agentic/commands/prime.md +++ b/agentic/commands/prime.md @@ -1,48 +1,46 @@ # Prime -> Execute the following sections to understand the codebase then summarize your understanding. +> Lightweight orientation for everyday work. For deep architecture context, use `/prime-deep`. CLAUDE.md is auto-loaded — critical rules are already in context. ## Run ```bash -# Current state: branch, uncommitted changes, stashes git status --short --branch - -# Recent activity: what's been worked on -git log --oneline --graph -15 - -# Open PRs: what's in flight -gh pr list --limit 10 2>/dev/null || echo "(gh CLI not available)" +git log --oneline -5 +gh pr list --limit 5 2>/dev/null || true ``` -## Read +## What this project is -@agentic/docs/project-guide.md -@agentic/commands/context.md -@docs/concepts/vision.md -@pyproject.toml +**anyplot**: AI-powered platform that generates Python data-viz examples for 9 libraries (matplotlib, seaborn, plotly, bokeh, altair, plotnine, pygal, highcharts, lets-plot). Spec-driven: every plot starts as a library-agnostic Markdown spec, then AI generates implementations per library. -## Serena +## Where things live -- Run `check_onboarding_performed` -- Run `list_memories` and read relevant ones +- `plots/{spec-id}/` — spec + per-library metadata + implementations (one dir per plot) +- `core/` — shared business logic (DB, repositories, config) +- `api/` — FastAPI backend +- `app/` — React frontend (Vite + TS + MUI) +- `agentic/` — AI workflow layer (commands in `agentic/commands/`, docs in `agentic/docs/`) +- `prompts/` — AI prompts for generation/review/tagging +- `automation/` — CI/CD helper scripts +- `.github/workflows/` — GitHub Actions pipelines -### JetBrains Tools (prefer over brute-force scanning) +Stack: Python 3.13+ (uv), PostgreSQL, GCP (Cloud Run + Cloud SQL + GCS). -Use Serena's JetBrains-backed tools for code navigation — they provide semantic understanding -that grep/glob cannot: +## GitHub pipeline (don't bypass it) -- `jet_brains_get_symbols_overview` — get top-level symbols in a file (classes, functions, variables). Use with `depth: 1` to also see methods of classes. Start here to understand a file before diving deeper. -- `jet_brains_find_symbol` — search for a symbol by name across the codebase. Supports name path patterns like `MyClass/my_method`. Use `include_body: true` to read source code, `include_info: true` for docstrings/signatures. -- `jet_brains_find_referencing_symbols` — find all usages of a symbol (who calls this function? who imports this class?). Essential for understanding impact of changes. -- `jet_brains_find_declaration` — jump to where a symbol is defined. -- `jet_brains_find_implementations` — find implementations of an interface/abstract class. -- `jet_brains_type_hierarchy` — understand class inheritance chains. +**New spec:** +1. Create issue (descriptive title, no spec-id) + add `spec-request` label +2. `spec-create.yml` runs → opens PR +3. Add `approved` label to the **issue** (not PR) → auto-merges → `spec-ready` -### Editing via Serena +**Generate implementations:** +1. `gh workflow run bulk-generate.yml -f specification_id= -f library=all` +2. Pipeline: `impl-generate` → `impl-review` → (`impl-repair` if needed) → `impl-merge` +3. **Never manually merge impl PRs** — `impl-merge.yml` handles metadata + GCS promotion -For structural edits, prefer Serena's symbol-aware tools over raw text replacement: +## Need more? -- `replace_symbol_body` — replace an entire function/class body -- `insert_after_symbol` / `insert_before_symbol` — add code relative to a symbol -- `search_for_pattern` — regex search across the codebase (fast, flexible) +- `/prime-deep` — full architecture, metadata schemas, all workflows, deployment +- `agentic/docs/project-guide.md` — comprehensive reference +- `docs/` — contributing, workflows, API, DB schema From 752683c79990fefb04c08dfd92c9b6d0bc99b317 Mon Sep 17 00:00:00 2001 From: Markus Neusinger <2921697+MarkusNeusinger@users.noreply.github.com> Date: Sat, 2 May 2026 23:16:00 +0200 Subject: [PATCH 2/3] feat: add Serena activation and JetBrains tool usage instructions - Activate the project with `mcp__serena__activate_project` if not already active - Run `mcp__serena__check_onboarding_performed` once per session - Prefer JetBrains-backed tools for code navigation and edits - See `/prime-deep` for the full tool catalog --- agentic/commands/prime.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/agentic/commands/prime.md b/agentic/commands/prime.md index 684aac85c8..3423b4e99f 100644 --- a/agentic/commands/prime.md +++ b/agentic/commands/prime.md @@ -10,6 +10,17 @@ git log --oneline -5 gh pr list --limit 5 2>/dev/null || true ``` +## Serena (activate + use) + +- Activate the project with `mcp__serena__activate_project` (param: `anyplot`) if not already active. +- Run `mcp__serena__check_onboarding_performed` once per session. +- Prefer Serena's JetBrains-backed tools over grep/glob for code navigation and edits: + - `mcp__serena__jet_brains_get_symbols_overview` / `mcp__serena__jet_brains_find_symbol` — semantic lookup + - `mcp__serena__jet_brains_find_referencing_symbols` — impact analysis before edits + - `mcp__serena__jet_brains_rename` / `mcp__serena__jet_brains_move` / `mcp__serena__jet_brains_inline_symbol` / `mcp__serena__jet_brains_safe_delete` — safe refactors + - `mcp__serena__replace_symbol_body` / `mcp__serena__insert_after_symbol` — structural edits +- See `/prime-deep` for the full tool catalog. + ## What this project is **anyplot**: AI-powered platform that generates Python data-viz examples for 9 libraries (matplotlib, seaborn, plotly, bokeh, altair, plotnine, pygal, highcharts, lets-plot). Spec-driven: every plot starts as a library-agnostic Markdown spec, then AI generates implementations per library. From ac3c4cf4223cf746caae17fd63682c2216302bc1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 2 May 2026 21:18:06 +0000 Subject: [PATCH 3/3] fix(commands): update prime-deep to use canonical mcp__serena__* tool names Co-authored-by: MarkusNeusinger <2921697+MarkusNeusinger@users.noreply.github.com> --- agentic/commands/prime-deep.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/agentic/commands/prime-deep.md b/agentic/commands/prime-deep.md index 618d57a02f..56740bbfe3 100644 --- a/agentic/commands/prime-deep.md +++ b/agentic/commands/prime-deep.md @@ -24,25 +24,25 @@ gh pr list --limit 10 2>/dev/null || echo "(gh CLI not available)" ## Serena -- Run `check_onboarding_performed` -- Run `list_memories` and read relevant ones +- Run `mcp__serena__check_onboarding_performed` +- Run `mcp__serena__list_memories` and read relevant ones -### JetBrains Tools (prefer over brute-force scanning) +### Serena MCP tools (prefer over brute-force scanning) -Use Serena's JetBrains-backed tools for code navigation — they provide semantic understanding -that grep/glob cannot: +Use Serena's symbol-aware tools for code navigation — they provide semantic understanding that grep/glob cannot. +The canonical, MCP-registered prefix is `mcp__serena__*` (matches `.claude/settings.json`). -- `jet_brains_get_symbols_overview` — get top-level symbols in a file (classes, functions, variables). Use with `depth: 1` to also see methods of classes. Start here to understand a file before diving deeper. -- `jet_brains_find_symbol` — search for a symbol by name across the codebase. Supports name path patterns like `MyClass/my_method`. Use `include_body: true` to read source code, `include_info: true` for docstrings/signatures. -- `jet_brains_find_referencing_symbols` — find all usages of a symbol (who calls this function? who imports this class?). Essential for understanding impact of changes. -- `jet_brains_find_declaration` — jump to where a symbol is defined. -- `jet_brains_find_implementations` — find implementations of an interface/abstract class. -- `jet_brains_type_hierarchy` — understand class inheritance chains. +- `mcp__serena__get_symbols_overview` — get top-level symbols in a file (classes, functions, variables). Use with `depth: 1` to also see methods of classes. Start here to understand a file before diving deeper. +- `mcp__serena__find_symbol` — search for a symbol by name across the codebase. Supports name-path patterns like `MyClass/my_method`. Use `include_body: true` to read source code, `include_info: true` for docstrings/signatures. +- `mcp__serena__find_referencing_symbols` — find all usages of a symbol (who calls this function? who imports this class?). Essential for understanding impact of changes. +- `mcp__serena__find_declaration` — jump to where a symbol is defined. +- `mcp__serena__find_implementations` — find implementations of an interface/abstract class. +- `mcp__serena__type_hierarchy` — understand class inheritance chains. ### Editing via Serena For structural edits, prefer Serena's symbol-aware tools over raw text replacement: -- `replace_symbol_body` — replace an entire function/class body -- `insert_after_symbol` / `insert_before_symbol` — add code relative to a symbol -- `search_for_pattern` — regex search across the codebase (fast, flexible) +- `mcp__serena__replace_symbol_body` — replace an entire function/class body +- `mcp__serena__insert_after_symbol` / `mcp__serena__insert_before_symbol` — add code relative to a symbol +- `mcp__serena__search_for_pattern` — regex search across the codebase (fast, flexible)