From fbf547a690ccfdc27a42f5e0b7a1958ad8a67429 Mon Sep 17 00:00:00 2001 From: Markus Neusinger <2921697+MarkusNeusinger@users.noreply.github.com> Date: Tue, 9 Jun 2026 20:30:23 +0200 Subject: [PATCH 1/2] chore: remove serena leftovers (hooks, permissions, docs, templates) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Serena MCP was removed from the project, but config and docs still referenced it — the SessionStart hook failed every session with "serena-hooks: not found". - .claude/settings.json: drop serena-hooks hooks (PreToolUse, SessionStart, Stop) and the mcp__serena__* permission - .serena/: delete tracked project files and memories - CLAUDE.md: drop the Serena tool section, keep Context7 - agentic/commands/: replace serena tool references with built-in Glob/Grep/Read/Edit equivalents in the audit/prime/agentic templates Co-Authored-By: Claude Fable 5 --- .claude/settings.json | 45 ------ .serena/.gitignore | 1 - .serena/memories/code_style.md | 64 -------- .serena/memories/commands.md | 87 ----------- .serena/memories/project_overview.md | 128 ---------------- .serena/memories/style_guide.md | 102 ------------- .serena/memories/task_completion.md | 42 ------ .serena/project.yml | 141 ------------------ CLAUDE.md | 14 +- agentic/commands/agentic.md | 30 ++-- agentic/commands/audit.md | 6 +- agentic/commands/audit/agentic-auditor.md | 6 +- agentic/commands/audit/audit.workflow.js | 2 +- agentic/commands/audit/backend-auditor.md | 14 +- agentic/commands/audit/catalog-auditor.md | 4 +- agentic/commands/audit/db-auditor.md | 8 +- agentic/commands/audit/design-auditor.md | 8 +- agentic/commands/audit/frontend-auditor.md | 10 +- agentic/commands/audit/infra-auditor.md | 12 +- .../commands/audit/llm-pipeline-auditor.md | 10 +- .../commands/audit/observability-auditor.md | 8 +- agentic/commands/audit/quality-auditor.md | 10 +- agentic/commands/audit/security-auditor.md | 6 +- agentic/commands/prime-deep.md | 30 ++-- agentic/commands/prime.md | 14 +- 25 files changed, 87 insertions(+), 715 deletions(-) delete mode 100644 .serena/.gitignore delete mode 100644 .serena/memories/code_style.md delete mode 100644 .serena/memories/commands.md delete mode 100644 .serena/memories/project_overview.md delete mode 100644 .serena/memories/style_guide.md delete mode 100644 .serena/memories/task_completion.md delete mode 100644 .serena/project.yml diff --git a/.claude/settings.json b/.claude/settings.json index 1d5266f21c..f6e2a5f4c5 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -8,7 +8,6 @@ "Read(/tmp/*)", "mcp__plugin_context7_context7__*", "mcp__plugin_playwright_playwright__*", - "mcp__serena__*", "Bash(git commit *)", "Bash(git push *)" ], @@ -17,49 +16,5 @@ }, "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" - }, - "hooks": { - "PreToolUse": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "serena-hooks remind --client=claude-code" - } - ] - }, - { - "matcher": "mcp__serena__*", - "hooks": [ - { - "type": "command", - "command": "serena-hooks auto-approve --client=claude-code" - } - ] - } - ], - "SessionStart": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "serena-hooks activate --client=claude-code" - } - ] - } - ], - "Stop": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "serena-hooks cleanup --client=claude-code" - } - ] - } - ] } } \ No newline at end of file diff --git a/.serena/.gitignore b/.serena/.gitignore deleted file mode 100644 index 14d86ad623..0000000000 --- a/.serena/.gitignore +++ /dev/null @@ -1 +0,0 @@ -/cache diff --git a/.serena/memories/code_style.md b/.serena/memories/code_style.md deleted file mode 100644 index fa3db364bd..0000000000 --- a/.serena/memories/code_style.md +++ /dev/null @@ -1,64 +0,0 @@ -# Code Style and Conventions - -## Python (API, Core, Tests) -- **Linter/Formatter**: Ruff (line-length=120, target=py314) -- **Rules**: E, F, W, I, C, B (ignores E501, C901, B008) -- **Excludes**: plots/, scripts/, .git, .venv, __pycache__, dist, temp -- **Type Hints**: Required for all functions -- **Docstrings**: Google style for public functions -- **Import Order**: stdlib → third-party → local (enforced by ruff I) -- **Async**: SQLAlchemy async, pytest-asyncio (auto mode) - -## TypeScript (Frontend) -- **Linter**: ESLint 10 with typescript-eslint -- **Strict mode**: Enabled in tsconfig -- **Target**: ES2020, bundler module resolution -- **Path alias**: `@/` → `./src/` -- **Components**: PascalCase files (e.g., `PlotCard.tsx`), function components only -- **Hooks**: camelCase with `use` prefix (e.g., `useSpecs.ts`) -- **Utils/Types**: camelCase files (e.g., `api.ts`) -- **Exports**: Named exports (no default exports) -- **Styling**: MUI `sx` prop + theme tokens from `app/src/theme/index.ts`. No hardcoded hex colors — use `colors.*`, `semanticColors.*`, `fontSize.*`, `typography.fontFamily` imports. See Serena memory `style_guide` for full token reference. -- **State**: Local state + custom hooks (no Redux/Zustand). Avoid `setState` inside `useEffect` for prop resets — use render-time ref pattern instead. -- **API calls**: Plain `fetch()` in `utils/api.ts` - -## Agentic Layer Conventions -- **Script headers**: uv inline script metadata (dependencies declared in-file) -- **CLI**: Click for all workflow scripts -- **Console output**: Rich library, stderr for UI, stdout for state JSON -- **State**: `WorkflowState` persisted at `agentic/runs/{run_id}/state.json` -- **Templates**: `agentic/commands/*.md` with `$1`, `$2`, `$ARGUMENTS` placeholders -- **Execution**: `prompt_claude_code_with_retry()` in `agent.py` -- **Data types**: `TestResult`, `ReviewResult`, `ReviewIssue` in `agent.py` -- **JSON parsing**: `parse_json()` handles markdown-fenced JSON from LLM output - -## Plot Implementation Style (KISS) -```python -""" -spec-id: Plot Title -Library: library-name -""" -import matplotlib.pyplot as plt -import numpy as np - -# Data -np.random.seed(42) -x = np.random.randn(100) - -# Plot -fig, ax = plt.subplots(figsize=(16, 9)) -ax.scatter(x, y) -ax.set_title('Title') -plt.tight_layout() -plt.savefig('plot.png', dpi=300, bbox_inches='tight') -``` -- No functions, no classes, no `if __name__` -- No type hints or docstrings in plot code -- Flow: imports → data → plot → save - -## Naming Conventions -- **Spec IDs**: `{plot-type}-{variant}-{modifier}` (lowercase, hyphens) -- **Implementation files**: `{library}.py` -- **Metadata files**: `{library}.yaml` -- **Test naming**: `test_{what_it_does}` -- **All output**: English only (comments, commits, docs, PRs) diff --git a/.serena/memories/commands.md b/.serena/memories/commands.md deleted file mode 100644 index 6eb80b77df..0000000000 --- a/.serena/memories/commands.md +++ /dev/null @@ -1,87 +0,0 @@ -# Commands Reference - -## Development Setup -```bash -uv sync --all-extras # Install Python dependencies -cd app && yarn install # Install frontend dependencies -uv run alembic upgrade head # Run DB migrations -``` - -## Running Services -```bash -uv run uvicorn api.main:app --reload --port 8000 # Backend API -cd app && yarn dev # Frontend dev server -docker-compose up # All services -``` - -## Code Quality (REQUIRED before commits) -```bash -uv run ruff check # Lint check -uv run ruff check --fix # Auto-fix lint -uv run ruff format # Format code -cd app && yarn lint # Frontend lint -``` - -## Testing -```bash -uv run pytest # All tests -uv run pytest tests/unit # Unit tests only -uv run pytest tests/integration # Integration tests -uv run pytest --cov=. --cov-report=html # With coverage -uv run pytest tests/unit/api/test_routers.py::test_name # Specific test -``` - -## Database -```bash -uv run alembic upgrade head # Apply migrations -uv run alembic revision --autogenerate -m "description" # Create migration -uv run alembic current # Check current revision -``` - -## Frontend -```bash -cd app && yarn dev # Dev server -cd app && yarn build # Production build (tsc + vite) -cd app && yarn preview # Preview prod build -cd app && yarn lint # ESLint check -cd app && yarn type-check # TypeScript type check only -cd app && yarn test # Run vitest -cd app && yarn test:watch # Watch mode tests -``` - -## Agentic Workflows -```bash -# Individual phases (all use Click CLI) -uv run agentic/workflows/plan.py --spec-id --library -uv run agentic/workflows/build.py --run-id -uv run agentic/workflows/test.py --run-id -uv run agentic/workflows/review.py --run-id - -# Orchestrators -uv run agentic/workflows/plan_build.py --spec-id --library -uv run agentic/workflows/plan_build_test.py --spec-id --library -uv run agentic/workflows/plan_build_test_review.py --spec-id --library -``` - -## GitHub Actions (via gh CLI) -```bash -# Spec workflow -gh issue create --title "Plot Name" --label "spec-request" --body "Description" -# After review: add 'approved' label to ISSUE (not PR!) - -# Implementation workflow -gh workflow run bulk-generate.yml -f specification_id= -f library=all - -# Monitor -gh run list --workflow=impl-generate.yml -gh run list --workflow=impl-review.yml -gh run list --workflow=impl-merge.yml - -# Sync to DB -gh workflow run sync-postgres.yml -``` - -## Important Notes -- Use `uv run` for all Python commands (no system python) -- Use `yarn` (not npm) for frontend -- Never manually merge impl PRs - let `impl-merge.yml` handle it diff --git a/.serena/memories/project_overview.md b/.serena/memories/project_overview.md deleted file mode 100644 index 047b5a786d..0000000000 --- a/.serena/memories/project_overview.md +++ /dev/null @@ -1,128 +0,0 @@ -# anyplot - Project Overview - -## Purpose -**anyplot** is an AI-powered platform for Python data visualization that automatically discovers, generates, tests, and maintains plotting examples across 9 major libraries. Community proposes plot ideas via GitHub Issues → AI generates code → AI quality review → Deployed. - -## Supported Libraries (9) -matplotlib, seaborn, plotly, bokeh, altair, plotnine, pygal, highcharts, lets-plot - -## Tech Stack -- **Backend**: Python 3.13+, FastAPI, SQLAlchemy async, asyncpg, PostgreSQL -- **Frontend**: React 19, Vite 8, TypeScript 6, MUI 9, Emotion CSS-in-JS -- **Package Managers**: uv (Python), yarn (frontend) -- **Infrastructure**: Google Cloud Run, Cloud SQL, Cloud Storage (GCS) -- **AI**: Claude (code generation, quality review, spec creation) -- **CI/CD**: GitHub Actions (13 workflows, label-driven triggers) - -## Directory Structure -``` -anyplot/ -├── api/ # FastAPI backend -│ ├── main.py # App factory, CORS, lifespan -│ ├── routers/ # health, specs, libraries, images, plots, stats, -│ │ # download, proxy, seo, og_images, debug (11 routers) -│ ├── mcp/ # MCP server (server.py) -│ ├── schemas.py # Pydantic response models -│ ├── dependencies.py # DB session injection -│ ├── exceptions.py # HTTP error handlers -│ ├── cache.py # Caching layer -│ └── analytics.py # Analytics tracking -├── core/ # Shared business logic -│ ├── config.py # Settings (pydantic-settings) -│ ├── constants.py # SUPPORTED_LIBRARIES, quality thresholds -│ ├── images.py # GCS image handling -│ ├── utils.py # Shared utilities -│ ├── database/ -│ │ ├── connection.py # Async SQLAlchemy engine -│ │ ├── models.py # ORM models (Spec, Implementation, Tag) -│ │ ├── repositories.py # Data access layer -│ │ └── types.py # Custom types (PostgreSQL + SQLite compat) -│ └── generators/ -│ └── plot_generator.py # Plot code generation logic -├── app/ # React frontend -│ └── src/ -│ ├── components/ # 16 components (Breadcrumb, ErrorBoundary, FilterBar, -│ │ # Footer, Header, ImageCard, ImagesGrid, Layout, -│ │ # LibraryPills, LoaderSpinner, SpecDetailView, -│ │ # SpecOverview, SpecTabs, ToolbarActions) -│ ├── pages/ # 7 pages (CatalogPage, DebugPage, HomePage, -│ │ # InteractivePage, LegalPage, McpPage, SpecPage) -│ ├── hooks/ # 10 hooks (useAnalytics, useCodeFetch, useCopyCode, -│ │ # useFilterFetch, useFilterState, useInfiniteScroll, -│ │ # useLayoutContext, useLocalStorage, useUrlSync) -│ ├── types/ # TypeScript interfaces -│ ├── utils/ # api.ts (fetch-based API client), filters.ts, fuzzySearch.ts -│ └── theme/ # MUI theme config -├── agentic/ # AI workflow layer -│ ├── workflows/ # Composable phase scripts (Click CLI, uv inline headers) -│ │ ├── plan.py, build.py, test.py, review.py # Individual phases -│ │ ├── document.py, patch.py, prompt.py, ship.py # Additional phases -│ │ ├── plan_build.py, plan_build_test.py # Orchestrators -│ │ ├── plan_build_test_review.py # Full review pipeline -│ │ ├── plan_build_test_review_document.py # + documentation -│ │ ├── plan_build_test_review_document_ship.py # + shipping -│ │ └── modules/ # agent.py (execution, types), state.py (persistence), -│ │ # orchestrator.py, template.py -│ ├── commands/ # 17 .md prompt templates ($1, $2, $ARGUMENTS vars) -│ │ # agentic, audit, bug, chore, classify, commit, context, -│ │ # dokument, feature, implement, prime, pull_request, -│ │ # refactor, review, start, test, update -│ ├── specs/ # Task specification files -│ ├── context/ # Context documentation for specific changes -│ ├── docs/ # project-guide.md -│ └── runs/ # Runtime state (gitignored) -├── automation/ # CI/CD helper scripts -│ └── scripts/ # workflow_cli.py, label_manager.py, sync_to_postgres.py, workflow_utils.py -├── plots/ # ~259 specifications (plot-centric design) -│ └── {spec-id}/ -│ ├── specification.md # Library-agnostic description -│ ├── specification.yaml # Tags, metadata -│ ├── implementations/ # {library}.py files -│ └── metadata/ # {library}.yaml files -├── prompts/ # AI prompt files -│ ├── plot-generator.md, quality-*.md, spec-*.md, impl-tags-generator.md -│ ├── default-style-guide.md # Default visual style rules -│ ├── library/ # 9 library-specific rule files -│ ├── templates/ # spec/metadata YAML/MD templates -│ └── workflow-prompts/ # ai-quality-review.md, impl-generate-claude.md, -│ # impl-repair-claude.md, report-analysis.md -├── tests/ # pytest suite -│ ├── conftest.py # Shared fixtures -│ ├── unit/ -│ │ ├── api/ # test_routers, test_cache, test_analytics, test_proxy, mcp/ -│ │ ├── core/ # test_config, test_constants, test_images, test_types, test_utils -│ │ ├── agentic/ # test_state, test_template, test_agent_*, test_orchestrator* -│ │ ├── automation/ # test_label_manager, test_sync_to_postgres, test_workflow_* -│ │ ├── workflows/ # test_workflows -│ │ └── prompts/ # test_prompts -│ ├── integration/ # test_repositories, api/test_api_endpoints -│ └── e2e/ # test_api_postgres (requires DATABASE_URL) -├── docs/ # contributing, development, reference/, workflows/, concepts/ -├── alembic/ # DB migrations (async engine) -├── .github/workflows/ # 13 GitHub Actions workflows -└── docker-compose.yml # API + PostgreSQL + frontend -``` - -## GitHub Actions Workflows (13) -| Workflow | Purpose | -|----------|---------| -| `spec-create.yml` | Creates specs from issues labeled `spec-request` | -| `impl-generate.yml` | Generates implementation for one spec+library | -| `impl-review.yml` | AI quality review of implementations | -| `impl-repair.yml` | Fixes rejected implementations (max 3 attempts) | -| `impl-merge.yml` | Merges approved PRs, creates metadata, promotes GCS | -| `bulk-generate.yml` | Batch generation for multiple specs/libraries | -| `report-validate.yml` | Validates user-submitted issue reports | -| `sync-postgres.yml` | Syncs filesystem specs/impls to PostgreSQL | -| `sync-labels.yml` | Auto-syncs labels after manual PR merges | -| `ci-lint.yml` | Ruff linting on PRs | -| `ci-tests.yml` | Unit tests on PRs | -| `notify-deployment.yml` | Deployment notifications | -| `util-claude.yml` | Claude utility workflow | - -## Data Flow -1. GitHub Issue + `spec-request` → `spec-create.yml` generates spec PR -2. `approved` label on Issue → spec merges, gets `spec-ready` label -3. `bulk-generate.yml` → `impl-generate.yml` → `impl-review.yml` → `impl-merge.yml` -4. `sync-postgres.yml` syncs filesystem to PostgreSQL on push to main -5. FastAPI serves data, React frontend displays gallery at anyplot.ai diff --git a/.serena/memories/style_guide.md b/.serena/memories/style_guide.md deleted file mode 100644 index d0784184e4..0000000000 --- a/.serena/memories/style_guide.md +++ /dev/null @@ -1,102 +0,0 @@ -# anyplot Design System - -Canonical source: `docs/reference/style-guide.md` (brand · frontend · plots in one doc). -Frontend tokens: `app/src/theme/index.ts` + `app/src/main.tsx` (MUI theme). - -## Aesthetic anchor -`arXiv paper` × `tmux/lazygit` — **the site is the neutral frame; the plots are the content.** Three layers: Brand (identity/voice), Frontend (visual language), Plots (color palette across all 9 libraries). - -## Typography — MonoLisa only, one face + two voices -- **Roman (upright MonoLisa)** — default for everything: body, UI, nav, buttons, code, logo, display. -- **Script (italic MonoLisa + `ss02`)** — editorial accent, semantic emphasis only (hero sub-headlines, section titles, `your`, taglines). -- `ss02` is enabled globally on `html`: `font-feature-settings: "ss02";` — it only affects `font-style: italic`. -- **No second font.** Fraunces, Inter, Space Grotesk, Poppins are all out. The anti-pattern "reaching for a serif for warmth" explicitly forbidden. -- CSS vars `--serif`, `--sans`, `--mono` all resolve to the same MonoLisa stack (aliased for compatibility). -- **Exception**: ErrorBoundary uses raw `'monospace'` (crash-safe fallback). -- `fontSize.micro` (0.5rem) and `fontSize.xxs` (0.625rem) restricted to data-dense pages (StatsPage, DebugPage). Public pages: `fontSize.xs` (0.75rem) minimum. - -## Color — imprint palette -Colourblind-safe categorical palette (8 hues, hybrid-v3 sort) plus 3 semantic anchors outside the pool. All 8 categorical slots stay fixed across themes; the neutral and muted anchors flip per theme. Full rationale: `docs/reference/palette-variants/v3/decision-rationale.md`. - -``` -slot 0 #009E73 brand green ★ first series — logo, primary CTAs -slot 1 #C475FD lavender (creative / artistic) PLOT-ONLY -slot 2 #4467A3 blue (info links, footnotes) -slot 3 #BD8233 ochre (hover accent, earth / commodity) -slot 4 #AE3030 matte red (errors, destructive — deferred semantic anchor) -slot 5 #2ABCCD cyan (sky / tech-cool) PLOT-ONLY -slot 6 #954477 rose (wellness / health) PLOT-ONLY -slot 7 #99B314 lime (growth / nature) PLOT-ONLY - -semantic anchors (outside the categorical pool): - amber #DDCC77 warning / caution (fixed) - neutral #1A1A17 / #F0EFE8 totals / baseline / outline (theme-adaptive) - muted #6B6A63 / #A8A79F other / rest / disabled (theme-adaptive) -``` - -**Brand green `#009E73` appears in UI ONLY in 8 contexts:** logo dot, italic accent words in headlines, hero terminal cursor, active nav item (dot prefix + underline), code-action button hover, code-block syntax (comments), palette strip, small status indicators. -**Never**: backgrounds, regular card borders, body text emphasis, non-logo icons, static decorative dots. - -**Plot-only colours** (lavender, cyan, rose, lime) must never appear in UI chrome — they are reserved for data marks so categorical plots retain visual impact. - -## Surfaces — warm, not clinical -Pure `#FFFFFF` is out — makes saturated palette colors look harsh. - -| Token | Light | Dark | -|----------------|-----------|-----------| -| `--bg-page` | `#F5F3EC` | `#121210` | -| `--bg-surface` | `#FAF8F1` | `#1A1A17` | -| `--bg-elevated`| `#FFFDF6` | `#242420` | - -## Warm-tinted grayscale (reddish-brown undertone, not blue-gray) -| Token | Light | Dark | Role | -|----------------|-----------|-----------|------------------| -| `--ink` | `#1A1A17` | `#F0EFE8` | Primary text | -| `--ink-soft` | `#4A4A44` | `#B8B7B0` | Secondary text | -| `--ink-muted` | `#8A8A82` | `#6E6D66` | Tertiary, meta | -| `--rule` | rgba(26,26,23,.10) | rgba(240,239,232,.10) | Borders/dividers | - -## WCAG rule -`colors.gray[400]` (#9ca3af) and lighter **must never be used for text or icons**. Minimum text color = `semanticColors.mutedText` (#6b7280, 4.6:1). - -## Frontend imports (MUI theme) -```ts -import { typography, colors, semanticColors, fontSize, spacing } from '../theme'; -import { headingStyle, subheadingStyle, textStyle, codeBlockStyle, tableStyle, labelStyle, monoText } from '../theme'; -``` -Semantic text tokens: `labelText` 7.0:1, `subtleText` 5.8:1, `mutedText` 4.6:1. -Highlight treatments: `colors.highlight.bg`/`colors.highlight.text`, `colors.tooltipLight` — never hardcode highlight hex. - -## Layout — three tiers -- **paper** 1240px — landing hero, About, Methodology, Blog, Legal -- **catalog** 2200px — plot catalog, search results, library/spec pages -- **hero-flank** 100vw — ultrawide-only (`≥1600px`) vertical plot stacks -- Gutter: 24px mobile → 96px wide. Section padding: 80px vertical desktop. Card padding: 24–28px. - -## Section-header pattern (shell-prompt prefixes) -- `❯` navigation/categorical · `$` action/list · `~/path/` hierarchical/about -- Title in italic + ss02 (script), `--imprint-green`, underlined with 1px `--rule`. - -## Buttons — method-call doctrine -- **Action** (primary affordance): `.copy()`, `.open()`, `.download()` — `::before { content: "." }`, hover flips to `--imprint-green`. -- **Hero CTA** (filled, landing only): dark pill, 4px radius, hover → green. -- **Ghost** (rare): transparent, `--rule` border. - -## Logo `any.plot()` -MonoLisa Bold, letters `--ink`, `.` `--imprint-green` scaled 1.3× (circle), `()` `--ink` weight 400 at 45% opacity. Favicon reduces to `a.p`. Clear space `1em`. - -## Voice -Precise · understated · curious · respectful · slightly playful · code-native · AI-honest. -Avoid: sales-y ("unlock", "supercharge"), corporate ("solutions", "leverage"), breathless, AI-hype ("AI-powered", "intelligent"), emoji-heavy. -Default: **lowercase**. Oxford comma always. Em-dashes with spaces (European style). -AI pipeline framing: humans submit ideas + approve specs + tune rules; AI drafts specs, generates code, reviews. Never patch generated code by hand. - -## Anti-patterns -Gradients (esp. purple-blue SaaS), glass/backdrop-blur, isometric illustrations, parallax/hero videos, badge-heavy UI, pure `#FFF`/`#000` backgrounds, branded spinners, stock imagery, **second typeface**, categorical palettes on continuous data. - -## Plot defaults -- First series **always** `#009E73`. -- Neutral (pos 8) reserved for aggregates/residuals/reference lines. -- 5 lighter members (lavender, ochre, cyan, lime, amber) fall under WCAG 3:1 on cream bg. Add a 1px ink stroke on affected series when the chart is small or accessibility-strict — see outline pattern in `docs/reference/palette-variants/v3/decision-rationale.md`. -- Non-categorical: sequential → `imprint_seq` (green→blue); diverging → `imprint_div` (red↔theme-adaptive-midpoint↔blue). Never substitute viridis/cividis/BrBG/jet/hsv/rainbow — palette identity is part of the brand. -- Plot-internal typography (ticks/labels/legends): MonoLisa, 10–13px. diff --git a/.serena/memories/task_completion.md b/.serena/memories/task_completion.md deleted file mode 100644 index 88ef547b60..0000000000 --- a/.serena/memories/task_completion.md +++ /dev/null @@ -1,42 +0,0 @@ -# Task Completion Checklist - -## Before Completing Any Task - -### 1. Code Quality (REQUIRED) -```bash -# Python changes -uv run ruff check && uv run ruff format - -# Frontend changes -cd app && yarn lint -``` - -### 2. Run Tests (if applicable) -```bash -uv run pytest tests/unit # For backend changes -uv run pytest tests/integration # For DB/API changes -cd app && yarn build # For frontend (catches TS errors) -cd app && yarn test # Frontend unit tests (vitest) -``` - -### 3. Documentation -Check if related docs need updating: -- `docs/reference/plausible.md` - analytics events -- `docs/workflows/` - workflow changes -- `docs/contributing.md` - user-facing changes -- `agentic/docs/project-guide.md` - architecture/agentic changes - -## Critical Rules - -### NEVER do: -- Commit or push in interactive sessions (let user do it) -- Manually create `plots/{spec-id}/` directories or `specification.md` files -- Manually merge implementation PRs -- Upload images to GCS manually -- Add `approved` label to PRs (add to ISSUES instead) - -### ALWAYS do: -- Use GitHub Actions pipeline for specs and implementations -- Write everything in English -- Let `impl-merge.yml` handle PR merging -- Update docs when changing features or workflows diff --git a/.serena/project.yml b/.serena/project.yml deleted file mode 100644 index 4f7cb19597..0000000000 --- a/.serena/project.yml +++ /dev/null @@ -1,141 +0,0 @@ - - -# list of languages for which language servers are started; choose from: -# al angular ansible bash clojure -# cpp cpp_ccls crystal csharp csharp_omnisharp -# dart elixir elm erlang fortran -# fsharp go groovy haskell haxe -# hlsl html java json julia -# kotlin lean4 lua luau markdown -# matlab msl nix ocaml pascal -# perl php php_phpactor powershell python -# python_jedi python_ty r rego ruby -# ruby_solargraph rust scala scss solidity -# swift systemverilog terraform toml typescript -# typescript_vts vue yaml zig -# (This list may be outdated. For the current list, see values of Language enum here: -# https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py -# For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.) -# Note: -# - For C, use cpp -# - For JavaScript, use typescript -# - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root) -# - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three) -# - For Free Pascal/Lazarus, use pascal -# Special requirements: -# Some languages require additional setup/installations. -# See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers -# When using multiple languages, the first language server that supports a given file will be used for that file. -# The first language is the default language and the respective language server will be used as a fallback. -# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored. -languages: -- python -- typescript - -# the encoding used by text files in the project -# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings -encoding: "utf-8" - -# whether to use project's .gitignore files to ignore files -ignore_all_files_in_gitignore: true - -# list of additional paths to ignore in this project. -# Same syntax as gitignore, so you can use * and **. -# Note: global ignored_paths from serena_config.yml are also applied additively. -ignored_paths: [] - -# whether the project is in read-only mode -# If set to true, all editing tools will be disabled and attempts to use them will result in an error -# Added on 2025-04-18 -read_only: false - -# list of tool names to exclude. -# This extends the existing exclusions (e.g. from the global configuration) -# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html -excluded_tools: [] - -# initial prompt for the project. It will always be given to the LLM upon activating the project -# (contrary to the memories, which are loaded on demand). -initial_prompt: "" -# the name by which the project can be referenced within Serena -project_name: "anyplot" - -# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default). -# This extends the existing inclusions (e.g. from the global configuration). -# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html -included_optional_tools: [] - -# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools. -# This cannot be combined with non-empty excluded_tools or included_optional_tools. -# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html -fixed_tools: [] - -# list of mode names to that are always to be included in the set of active modes -# The full set of modes to be activated is base_modes + default_modes. -# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply. -# Otherwise, this setting overrides the global configuration. -# Set this to [] to disable base modes for this project. -# Set this to a list of mode names to always include the respective modes for this project. -base_modes: - -# list of mode names that are to be activated by default, overriding the setting in the global configuration. -# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes. -# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply. -# Otherwise, this overrides the setting from the global configuration (serena_config.yml). -# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply -# for this project. -# This setting can, in turn, be overridden by CLI parameters (--mode). -# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes -default_modes: - -# time budget (seconds) per tool call for the retrieval of additional symbol information -# such as docstrings or parameter information. -# This overrides the corresponding setting in the global configuration; see the documentation there. -# If null or missing, use the setting from the global configuration. -symbol_info_budget: - -# The language backend to use for this project. -# If not set, the global setting from serena_config.yml is used. -# Valid values: LSP, JetBrains -# Note: the backend is fixed at startup. If a project with a different backend -# is activated post-init, an error will be returned. -language_backend: - -# list of regex patterns which, when matched, mark a memory entry as read‑only. -# Extends the list from the global configuration, merging the two lists. -read_only_memory_patterns: [] - -# line ending convention to use when writing source files. -# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default) -# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings. -line_ending: - -# list of regex patterns for memories to completely ignore. -# Matching memories will not appear in list_memories or activate_project output -# and cannot be accessed via read_memory or write_memory. -# To access ignored memory files, use the read_file tool on the raw file path. -# Extends the list from the global configuration, merging the two lists. -# Example: ["_archive/.*", "_episodes/.*"] -ignored_memory_patterns: [] - -# advanced configuration option allowing to configure language server-specific options. -# Maps the language key to the options. -# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available. -# No documentation on options means no options are available. -ls_specific_settings: {} - -# list of mode names to be activated additionally for this project, e.g. ["query-projects"] -# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes. -# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes -added_modes: - -# list of additional workspace folder paths for cross-package reference support (e.g. in monorepos). -# Paths can be absolute or relative to the project root. -# Each folder is registered as an LSP workspace folder, enabling language servers to discover -# symbols and references across package boundaries. -# Currently supported for: TypeScript. -# Example: -# additional_workspace_folders: -# - ../sibling-package -# - ../shared-lib -additional_workspace_folders: [] diff --git a/CLAUDE.md b/CLAUDE.md index 2679d77688..54c8fb887b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,22 +31,12 @@ After opening a PR, the work is **not** complete. Stay with the PR until both th This rule applies to every PR Claude opens, including small fixes and follow-ups. -## MCP Tools (Serena & Context7) - -**Serena** - Prefer for Python/TypeScript code navigation and editing (canonical MCP-prefix is `mcp__serena__*`): -- `mcp__serena__jet_brains_find_symbol` / `mcp__serena__jet_brains_get_symbols_overview` - Find classes, functions, methods -- `mcp__serena__jet_brains_find_referencing_symbols` - Find all usages of a symbol -- `mcp__serena__replace_symbol_body` / `mcp__serena__insert_after_symbol` - Edit entire functions/classes -- `mcp__serena__replace_content` (regex) - Small inline edits -- `mcp__serena__search_for_pattern` / `mcp__serena__list_dir` / `mcp__serena__find_file` - Non-code files, directory exploration +## MCP Tools (Context7) **Context7** - Use for up-to-date library documentation: - `resolve-library-id` -> `query-docs` - Get current API docs, code examples - Use when working with external libraries (matplotlib, FastAPI, SQLAlchemy, React, etc.) - -**When to use:** -- Serena: Understanding codebase structure, refactoring, finding usages, editing code -- Context7: Checking correct API usage, finding library-specific patterns, debugging library issues +- When to use: checking correct API usage, finding library-specific patterns, debugging library issues ## Development Workflow diff --git a/agentic/commands/agentic.md b/agentic/commands/agentic.md index 172cad22f6..0396b21a50 100644 --- a/agentic/commands/agentic.md +++ b/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** (`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 +- Use **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` @@ -278,13 +278,13 @@ You are the **core-auditor** on the agentic-audit team. Analyze leverage points - Are tools documented (parameters, return values)? **How to work:** -1. Use `list_dir` to explore directories listed above -2. Use `mcp__serena__get_symbols_overview` on key files -3. Use `search_for_pattern` for patterns like `CLAUDE.md`, model references, `mcp`, `prompt` +1. Use Glob to explore directories listed above +2. Read key files (or Grep them for `class |def ` declarations for a structural overview) +3. Use Grep for patterns like `CLAUDE.md`, model references, `mcp`, `prompt` 4. Use Read to examine prompt files and configuration -5. Use `mcp__serena__find_symbol` with `depth=1` to inspect MCP tools and CLI commands +5. Grep for the definitions of MCP tools and CLI commands to inspect them 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 +7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Glob/Grep/Read tools instead 8. You MAY use Bash for: `uv run python -c "..."` to inspect tool registrations **Report format:** Send findings to `agentic-lead` via `SendMessage`. Structure each finding as: @@ -423,13 +423,13 @@ You are the **environment-auditor** on the agentic-audit team. Analyze leverage - Are naming conventions consistent (snake_case Python, camelCase TS, kebab-case files)? **How to work:** -1. Use `list_dir` with `recursive=false` to map top-level and sub-directory structure -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`) +1. Use Glob to map top-level and sub-directory structure +2. Read key files to check type annotations +3. Use Grep 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 6. Compare `tests/` structure with `api/`, `core/`, `automation/` structure -7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Serena/Glob/Grep/Read tools instead +7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Glob/Grep/Read tools instead 8. You MAY use Bash for: `uv run ruff check api/ core/ --select ANN 2>&1 | tail -20` **Report format:** Same as core-auditor — send findings to `agentic-lead` via `SendMessage` using the `LEVERAGE_POINT` / `POSITIVE` format. @@ -551,13 +551,13 @@ You are the **workflow-auditor** on the agentic-audit team. Analyze leverage poi - Do workflows run successfully AFK (without human checking in)? **How to work:** -1. Use `list_dir` to explore `tests/`, `agentic/specs/`, `agentic/workflows/`, `agentic/commands/`, `prompts/` -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 +1. Use Glob to explore `tests/`, `agentic/specs/`, `agentic/workflows/`, `agentic/commands/`, `prompts/` +2. Read workflow scripts and test files (or Grep them for `class |def ` declarations for an overview) +3. Grep for the definitions of 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` +5. Use Grep 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 -7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Serena/Glob/Grep/Read tools instead +7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Glob/Grep/Read tools instead 8. You MAY use Bash for: `uv run pytest tests/ --co -q 2>&1 | tail -20` or `uv run ruff check . 2>&1 | tail -5` **Report format:** Same as core-auditor — send findings to `agentic-lead` via `SendMessage` using the `LEVERAGE_POINT` / `POSITIVE` format. diff --git a/agentic/commands/audit.md b/agentic/commands/audit.md index d48c636d2c..41427eecba 100644 --- a/agentic/commands/audit.md +++ b/agentic/commands/audit.md @@ -27,7 +27,7 @@ You are the **audit-lead**. Your job is to coordinate a team of specialist audit - Empty / `all` → spawn all 16 auditors - Single keyword → spawn only that auditor (see Scope Table) - Directory path → Lead determines which auditor(s) cover that path - - Optional `since=` (e.g. `since=main`, `since=HEAD~10`) → **Incremental mode**: Lead computes the changed file list once via `git diff --name-only ...HEAD` and passes the relevant subset to each auditor. Auditors must restrict their analysis to those files (plus their direct importers if a quick `mcp__serena__find_referencing_symbols` lookup is cheap). If `since=` is omitted, auditors run a full sweep of their scope. The five external-system auditors (`gcloud`, `github`, `plausible`, `pagespeed`, `seo`) ignore `since=` because their scope is live systems, not files. + - Optional `since=` (e.g. `since=main`, `since=HEAD~10`) → **Incremental mode**: Lead computes the changed file list once via `git diff --name-only ...HEAD` and passes the relevant subset to each auditor. Auditors must restrict their analysis to those files (plus their direct importers if a quick Grep lookup is cheap). If `since=` is omitted, auditors run a full sweep of their scope. The five external-system auditors (`gcloud`, `github`, `plausible`, `pagespeed`, `seo`) ignore `since=` because their scope is live systems, not files. 2. **Run baseline measurements** (these are the ONLY Bash commands the Lead runs in this phase): ```bash @@ -113,8 +113,8 @@ Both mechanisms use the **same** active set, Shared Rules, Findings Schema, Dime ### Phase 2: Parallel Analysis Each specialist receives a focused prompt loaded from `agentic/commands/audit/-auditor.md` (see the Specialist Prompts index below), prepended with the Shared Rules. 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`). 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 +- Use **Glob/Grep/Read** for code analysis +- Pause and consolidate findings 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 - Tag every finding with exactly one **dimension** (see Dimension Taxonomy) and emit it per the **Findings Schema** diff --git a/agentic/commands/audit/agentic-auditor.md b/agentic/commands/audit/agentic-auditor.md index 39e283b718..97398a457b 100644 --- a/agentic/commands/audit/agentic-auditor.md +++ b/agentic/commands/audit/agentic-auditor.md @@ -11,13 +11,13 @@ You are the **agentic-auditor** on the audit team. Your scope is the **agent erg - 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 +1. Glob the directories above 2. Read `CLAUDE.md` end-to-end and any nested `CLAUDE.md` files -3. `mcp__serena__get_symbols_overview` is mostly not useful here (markdown); rely on Read + Grep + Glob +3. This scope is mostly markdown — rely on Read + Grep + Glob 4. Glob for `agentic/commands/*.md`, `prompts/**/*.md`, `.claude/**/*.json` 5. Cross-check `@`-references in CLAUDE.md and command files against the actual file paths 6. Grep for inline prompt strings inside `agentic/workflows/`, `automation/scripts/`, and `scripts/` that look like they should live in `prompts/` (note: the old `core/generators/` package was removed — don't look for it) -7. `think_about_collected_information` after the docs+commands sweep +7. Pause and consolidate findings after the docs+commands sweep 8. **Do NOT use Bash** for file discovery 9. You MAY skip `/agentic`-style numerical scoring — this is an audit, not a TAC scorecard. Surface findings, not a score. diff --git a/agentic/commands/audit/audit.workflow.js b/agentic/commands/audit/audit.workflow.js index 128b3d957e..a1465d7dcd 100644 --- a/agentic/commands/audit/audit.workflow.js +++ b/agentic/commands/audit/audit.workflow.js @@ -72,7 +72,7 @@ function verifyPrompt(finding, auditorName, partnerHint) { return [ `You are a rigorous ${partnerHint} reviewer peer-reviewing a finding raised by the ${auditorName}.`, `Bring your own domain expertise and independently check it against the actual repo / live system`, - `(use Read / Grep / Serena / read-only Bash as needed). Do NOT just re-read the original auditor's reasoning.`, + `(use Read / Grep / read-only Bash as needed). Do NOT just re-read the original auditor's reasoning.`, ``, `FINDING: ${finding.title}`, `IMPORTANCE: ${finding.importance}`, diff --git a/agentic/commands/audit/backend-auditor.md b/agentic/commands/audit/backend-auditor.md index bb57701de8..a44098fab9 100644 --- a/agentic/commands/audit/backend-auditor.md +++ b/agentic/commands/audit/backend-auditor.md @@ -13,13 +13,13 @@ You are the **backend-auditor** on the audit team. Analyze `api/`, `core/`, and - **Import hygiene**: Unused imports, circular imports, import order **How to work:** -1. Use `list_dir` to understand directory structure of `api/`, `core/`, `automation/` -2. Use `mcp__serena__get_symbols_overview` on key files to understand architecture -3. Use `mcp__serena__find_symbol` with `depth=1` to inspect classes and their methods -4. Use `search_for_pattern` to find anti-patterns (e.g. `bare except`, `type: ignore`, `Any`, `TODO`, `FIXME`) -5. Use `mcp__serena__find_referencing_symbols` to check if code is actually used -6. Use `think_about_collected_information` after research sequences -7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Serena/Glob/Grep/Read tools instead +1. Use Glob (`api/**`, `core/**`, `automation/**`) to understand directory structure +2. Read key files (or Grep them for `class |def ` declarations) to understand architecture +3. Grep for class definitions and read their methods to inspect classes +4. Use Grep to find anti-patterns (e.g. `bare except`, `type: ignore`, `Any`, `TODO`, `FIXME`) +5. Grep for symbol names to find usages and check if code is actually used +6. Pause and consolidate findings after research sequences +7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Glob/Grep/Read tools instead 8. You MAY use Bash for: `uv run ruff check api/ core/ automation/` or `uv run pytest tests/unit -x -q` **Report format:** Emit findings per the **Findings Schema** in the orchestrator (`audit.md`). Every finding carries `DIMENSION` (one of `security | speed | looks | modern | correctness | maintainability`) in addition to importance/effort/auto-fix. Backend findings are usually `correctness`, `speed`, or `maintainability` — tag the single best fit. Also surface any high-value **exemplary gap** (something a best-in-class backend would have that anyplot lacks), rated like any other finding. In team mode, send findings to `audit-lead` via `SendMessage`, starting with one `COVERAGE: full | partial` line, then one block per finding: diff --git a/agentic/commands/audit/catalog-auditor.md b/agentic/commands/audit/catalog-auditor.md index 6ef6bc0f23..2841a8cd44 100644 --- a/agentic/commands/audit/catalog-auditor.md +++ b/agentic/commands/audit/catalog-auditor.md @@ -16,7 +16,7 @@ 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). +- Start with 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/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. @@ -41,7 +41,7 @@ These are **suggestions**. Skip any that don't yield signal and lean into whiche ## Tool budget -~30 calls. One pass over `plots/` via `list_dir` / Glob, then targeted reads on a handful of specs. Don't open every spec. +~30 calls. One pass over `plots/` via Glob, then targeted reads on a handful of specs. Don't open every spec. ## Report format diff --git a/agentic/commands/audit/db-auditor.md b/agentic/commands/audit/db-auditor.md index 75b2eac5e0..261565f06e 100644 --- a/agentic/commands/audit/db-auditor.md +++ b/agentic/commands/audit/db-auditor.md @@ -11,12 +11,12 @@ You are the **db-auditor** on the audit team. Analyze `alembic/`, `core/database - **Migration ↔ model drift**: Models declare columns/indexes that aren't in any migration, or vice versa **How to work:** -1. `list_dir` on `alembic/versions/` and `core/database/` -2. `mcp__serena__get_symbols_overview` on `core/database/models.py` and each repository file +1. Glob `alembic/versions/**` and `core/database/**` +2. Read `core/database/models.py` and each repository file 3. Read each migration file (they're typically small — Read the whole list); flag missing `downgrade()` or `op.execute(...)` raw-SQL without a parameterization story 4. Grep for: `op\.drop_`, `op\.alter_column`, `pass\s*$` inside `def downgrade`, `lazy=`, `selectinload`, `joinedload`, raw `text("...")` in repositories, `await .* commit\(\)` -5. `mcp__serena__find_referencing_symbols` on each model class to find query call sites (N+1 hunting) -6. `think_about_collected_information` after the migration sweep +5. Grep for each model class name to find query call sites (N+1 hunting) +6. Pause and consolidate findings after the migration sweep 7. **Do NOT use Bash** for file discovery 8. You MAY use Bash for: `uv run alembic check` (catches model↔migration drift) and `uv run alembic history --indicate-current 2>&1 | tail -20` diff --git a/agentic/commands/audit/design-auditor.md b/agentic/commands/audit/design-auditor.md index 19342e6931..4bd26e6907 100644 --- a/agentic/commands/audit/design-auditor.md +++ b/agentic/commands/audit/design-auditor.md @@ -15,14 +15,14 @@ Almost every finding you emit is `DIMENSION: looks`. Tag the rare exception accu - **Exemplary gap**: what would a best-in-class product site have here that anyplot lacks (a polished design system, motion/micro-interactions, a cohesive empty-state language)? Emit high-value gaps as `looks` findings. **How to work:** -1. `list_dir` on `app/src/theme/`, `app/src/components/`, `app/src/pages/`, `app/src/styles/` +1. Glob `app/src/theme/**`, `app/src/components/**`, `app/src/pages/**`, `app/src/styles/**` 2. Read the theme definition(s) and `useThemeMode` to learn the token system and how light/dark are derived 3. Grep for hardcoded visual values that bypass the theme: `#[0-9a-fA-F]{3,8}`, `rgb\(`, `style=\{\{`, `px`-literal sizing in `sx`, `color:\s*['"]`, `backgroundColor` -4. `mcp__serena__get_symbols_overview` on a representative set of pages/components to see how consistently theme tokens vs. literals are used +4. Read a representative set of pages/components to see how consistently theme tokens vs. literals are used 5. Sample a handful of pages end-to-end (landing, catalog, a spec detail, the palette page) and reason about both themes from the code 6. Look for missing/undesigned empty-loading-error states and removed focus outlines (`outline:\s*none`, `:focus` overrides) -7. `think_about_collected_information` after the design sweep -8. **Do NOT use Bash** for file discovery — use Serena/Glob/Grep/Read +7. Pause and consolidate findings after the design sweep +8. **Do NOT use Bash** for file discovery — use Glob/Grep/Read 9. You MAY use Bash for: `cd app && yarn build 2>&1 | tail -20` (confirm the styled bundle builds) — optional, skip if budget-tight **Tool budget:** ~30 calls. If insufficient, set `COVERAGE: partial` and prioritize dark-mode contrast correctness first, design-system token drift second. diff --git a/agentic/commands/audit/frontend-auditor.md b/agentic/commands/audit/frontend-auditor.md index 7e98e498b9..fa5bf047f2 100644 --- a/agentic/commands/audit/frontend-auditor.md +++ b/agentic/commands/audit/frontend-auditor.md @@ -15,13 +15,13 @@ You are the **frontend-auditor** on the audit team. Analyze the `app/src/` direc - **Consistency**: Naming conventions, file organization, export patterns **How to work:** -1. Use `list_dir` to understand `app/src/` structure +1. Use Glob `app/src/**` to understand `app/src/` structure 2. Use Glob to find all `.tsx` and `.ts` files: `**/*.tsx`, `**/*.ts` in `app/src/` -3. Use `mcp__serena__get_symbols_overview` on key components +3. Read key components 4. Use Grep to search for anti-patterns (e.g. `: any`, `eslint-disable`, `@ts-ignore`, `console.log`) -5. Use `search_for_pattern` for cross-file patterns -6. Use `think_about_collected_information` after research sequences -7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Serena/Glob/Grep/Read tools instead +5. Use Grep for cross-file patterns +6. Pause and consolidate findings after research sequences +7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Glob/Grep/Read tools instead 8. You MAY use Bash for: `cd app && yarn type-check 2>&1 | tail -20` **Report format:** Same as backend-auditor — send findings to `audit-lead` via `SendMessage`. diff --git a/agentic/commands/audit/infra-auditor.md b/agentic/commands/audit/infra-auditor.md index 05f0e6ad25..2fd3bdc76e 100644 --- a/agentic/commands/audit/infra-auditor.md +++ b/agentic/commands/audit/infra-auditor.md @@ -11,12 +11,12 @@ You are the **infra-auditor** on the audit team. Analyze `.github/workflows/`, ` - **Config drift**: Mismatches between workflow configs and actual project structure **How to work:** -1. Use `list_dir` to find all workflow files, prompt files, Docker files, config files -2. Use `find_file` with masks like `*.yml`, `*.yaml`, `Dockerfile*`, `*.toml`, `*.json` -3. Use Read to examine workflow files (they're YAML, not code — Serena symbols won't help) -4. Use `search_for_pattern` to find patterns across workflows (e.g. inconsistent action versions, missing `concurrency:`) +1. Use Glob to find all workflow files, prompt files, Docker files, config files +2. Use Glob with masks like `**/*.yml`, `**/*.yaml`, `**/Dockerfile*`, `**/*.toml`, `**/*.json` +3. Use Read to examine workflow files (they're YAML, not code — read them end-to-end) +4. Use Grep to find patterns across workflows (e.g. inconsistent action versions, missing `concurrency:`) 5. Use Grep to check for security anti-patterns (e.g. `${{ github.event`, `pull_request_target`, insecure permissions) -6. Use `think_about_collected_information` after research sequences -7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Serena/Glob/Grep/Read tools instead +6. Pause and consolidate findings after research sequences +7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Glob/Grep/Read tools instead **Report format:** Same as backend-auditor — send findings to `audit-lead` via `SendMessage`. diff --git a/agentic/commands/audit/llm-pipeline-auditor.md b/agentic/commands/audit/llm-pipeline-auditor.md index 36bfed71fd..dd3241149d 100644 --- a/agentic/commands/audit/llm-pipeline-auditor.md +++ b/agentic/commands/audit/llm-pipeline-auditor.md @@ -14,13 +14,13 @@ You are the **llm-pipeline-auditor** on the audit team. anyplot's core is a spec - **Workflow ↔ code drift**: Do workflow inputs/outputs match what the SDK call sites in `scripts/` and `agentic/workflows/modules/` expect? **How to work:** -1. `list_dir` on `prompts/`, `scripts/`, `agentic/workflows/` -2. `mcp__serena__get_symbols_overview` on `scripts/evaluate-plot.py` -3. `mcp__serena__find_symbol` on the `Anthropic` / `client.messages.create` call sites +1. Glob `prompts/**`, `scripts/**`, `agentic/workflows/**` +2. Read `scripts/evaluate-plot.py` +3. Grep for the `Anthropic` / `client.messages.create` call sites 4. Grep for: `anthropic\.`, `messages.create`, `max_tokens`, `cache_control`, hardcoded model strings (`claude-`, `sonnet`, `haiku`, `opus`), bare `except` around SDK calls 5. Read each prompt file at least skim-depth; look for placeholder mismatches and library references -6. `mcp__serena__find_referencing_symbols` on each prompt-loader function to see who consumes which prompt -7. `think_about_collected_information` after the SDK + prompt scan +6. Grep for each prompt-loader function's name to see who consumes which prompt +7. Pause and consolidate findings after the SDK + prompt scan 8. **Do NOT use Bash** for file discovery 9. You MAY use Bash for: `uv run python -c "from core.config import settings; print(settings.claude_model, settings.claude_max_tokens)"` to confirm runtime config diff --git a/agentic/commands/audit/observability-auditor.md b/agentic/commands/audit/observability-auditor.md index 94a9af1246..0f54535836 100644 --- a/agentic/commands/audit/observability-auditor.md +++ b/agentic/commands/audit/observability-auditor.md @@ -12,12 +12,12 @@ You are the **observability-auditor** on the audit team. anyplot uses Plausible - **Tracing / metrics**: No Sentry or OpenTelemetry detected — flag this as a known gap (Importance 3) only if logging coverage is also weak; otherwise note as Positive Pattern that the team has chosen logs-only **How to work:** -1. `list_dir` on `app/src/analytics/`, plus Read `api/analytics.py`, `api/cache.py`, `docs/reference/plausible.md` -2. `mcp__serena__find_symbol` on the Plausible event-emitting functions in both backend and frontend -3. `mcp__serena__find_referencing_symbols` on each event-emitter to count call sites and check naming +1. Glob `app/src/analytics/**`, plus Read `api/analytics.py`, `api/cache.py`, `docs/reference/plausible.md` +2. Grep for the definitions of the Plausible event-emitting functions in both backend and frontend +3. Grep for each event-emitter's name to count call sites and check naming 4. Grep for: `print\(`, `logging\.`, `logger\.`, `plausible`, `track`, `event\(`, around the Anthropic SDK call sites 5. Read `docs/reference/plausible.md` and cross-check every documented event against actual emit sites; flag mismatches in both directions -6. `think_about_collected_information` after the analytics + logging scan +6. Pause and consolidate findings after the analytics + logging scan 7. **Do NOT use Bash** for file discovery 8. You MAY use Bash for: `cd app && yarn build 2>&1 | tail -20` to check that the analytics bundle builds cleanly diff --git a/agentic/commands/audit/quality-auditor.md b/agentic/commands/audit/quality-auditor.md index bcfe73745e..ed508b4524 100644 --- a/agentic/commands/audit/quality-auditor.md +++ b/agentic/commands/audit/quality-auditor.md @@ -13,13 +13,13 @@ You are the **quality-auditor** on the audit team. Analyze `tests/`, `docs/`, `a - **Repo-health / exemplary baseline** (`maintainability`, mostly Importance 3): a top-tier public repo has the full community-health set. anyplot already has `LICENSE`, `SECURITY.md`, `.github/ISSUE_TEMPLATE/`, `.github/dependabot.yml`. Flag *missing* high-value pieces as exemplary-gap findings: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, a PR template (`.github/pull_request_template.md`), `.editorconfig`, a `CHANGELOG.md` (or release notes), and CI/coverage/license badges in the README. Don't over-flag — only the ones that would visibly raise the repo's polish. A single rolled-up finding listing the missing files is better than one finding each. **How to work:** -1. Use `list_dir` to map `tests/` structure and compare with `api/`, `core/`, `automation/` structure -2. Use `mcp__serena__get_symbols_overview` on test files to check test method quality -3. Use `search_for_pattern` to find test anti-patterns (e.g. `assert True`, `pass`, empty test bodies) +1. Use Glob to map `tests/` structure and compare with `api/`, `core/`, `automation/` structure +2. Read test files (or Grep them for `def test_` declarations) to check test method quality +3. Use Grep to find test anti-patterns (e.g. `assert True`, `pass`, empty test bodies) 4. Use Glob to find all `.md` docs files, then Read key ones to check staleness 5. Use Grep to verify cross-references (e.g. file paths mentioned in docs actually exist) -6. Use `think_about_collected_information` after research sequences -7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Serena/Glob/Grep/Read tools instead +6. Pause and consolidate findings after research sequences +7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Glob/Grep/Read tools instead 8. You MAY use Bash for: `uv run pytest tests/ --co -q 2>&1 | tail -20` (list collected tests) **Report format:** Same as backend-auditor — send findings to `audit-lead` via `SendMessage`. diff --git a/agentic/commands/audit/security-auditor.md b/agentic/commands/audit/security-auditor.md index c20af44ef3..3071a6f38f 100644 --- a/agentic/commands/audit/security-auditor.md +++ b/agentic/commands/audit/security-auditor.md @@ -12,11 +12,11 @@ You are the **security-auditor** on the audit team. anyplot has a public, unauth - **CSP / security headers**: Frontend response headers (if served from FastAPI), iframe restrictions for og-image endpoints **How to work:** -1. `list_dir` on `.github/workflows/` and `api/routers/` +1. Glob `.github/workflows/**` and `api/routers/**` 2. Grep across the repo for: `os\.getenv`, `os\.environ`, `\${{\s*github\.event\.`, `pull_request_target`, `permissions:`, `actions/checkout@`, `f"\s*SELECT`, `f"\s*INSERT`, `f"\s*UPDATE`, `\.format\(.*SELECT`, `eval\(`, `exec\(`, `subprocess\.`, `shell=True` -3. `mcp__serena__find_symbol` on each FastAPI router function to see what it accepts and reflects +3. Grep for each FastAPI router function's definition to see what it accepts and reflects 4. Read every workflow file that triggers on `pull_request_target`, `issue_comment`, or `workflow_dispatch` end-to-end -5. `think_about_collected_information` after the workflow + API scan +5. Pause and consolidate findings after the workflow + API scan 6. **Do NOT use Bash** for file discovery 7. You MAY use Bash for: `uv run --with pip-audit pip-audit 2>&1 | tail -30` (ephemeral install — `pip-audit` is intentionally NOT a project dep) and `cd app && yarn audit --level high --groups dependencies 2>&1 | tail -30` (Yarn 1.22 syntax, matches `packageManager` in `app/package.json`) diff --git a/agentic/commands/prime-deep.md b/agentic/commands/prime-deep.md index 56740bbfe3..92fa1e7868 100644 --- a/agentic/commands/prime-deep.md +++ b/agentic/commands/prime-deep.md @@ -22,27 +22,21 @@ gh pr list --limit 10 2>/dev/null || echo "(gh CLI not available)" @docs/concepts/vision.md @pyproject.toml -## Serena +## Tools -- Run `mcp__serena__check_onboarding_performed` -- Run `mcp__serena__list_memories` and read relevant ones +### Code navigation (prefer targeted lookups over brute-force scanning) -### Serena MCP tools (prefer over brute-force scanning) +Use the built-in Glob/Grep/Read tools for code navigation — targeted searches beat reading whole directories. -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`). +- Read — read a file to understand it before diving deeper. For a quick structural overview (classes, functions, variables), Grep the file for `class |def ` declarations. +- Grep for a symbol's definition (e.g. `class MyClass`, `def my_method`) — find where it's defined across the codebase. Use context flags (`-A`/`-B`/`-C`) to see signatures and docstrings. +- Grep for a symbol's name — find all usages (who calls this function? who imports this class?). Essential for understanding impact of changes. +- Glob — locate files by pattern (e.g. `core/database/**`, `**/*.tsx`) when you know the shape of the path but not the exact file. -- `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 -### Editing via Serena +For code edits, use the built-in tools: -For structural edits, prefer Serena's symbol-aware tools over raw text replacement: - -- `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) +- Edit — exact string replacement in a file (e.g. replace a function/class body, insert code relative to a symbol) +- Write — create a new file or fully rewrite an existing one +- Grep — regex search across the codebase (fast, flexible) diff --git a/agentic/commands/prime.md b/agentic/commands/prime.md index 0596b32026..4408ccf8dc 100644 --- a/agentic/commands/prime.md +++ b/agentic/commands/prime.md @@ -10,14 +10,12 @@ git log --oneline -5 gh pr list --limit 5 2>/dev/null || echo "(gh CLI not available)" ``` -## 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 symbol-aware tools over grep/glob for code navigation and edits: - - `mcp__serena__get_symbols_overview` / `mcp__serena__find_symbol` — semantic lookup - - `mcp__serena__find_referencing_symbols` — impact analysis before edits - - `mcp__serena__replace_symbol_body` / `mcp__serena__insert_after_symbol` — structural edits +## Tools + +- Use the built-in Glob/Grep/Read/Edit tools for code navigation and edits: + - Read a file, or Grep for `class |def ` declarations — structural overview and symbol lookup + - Grep for a symbol name to find its usages/call sites — impact analysis before edits + - Edit / Write — code edits - See `/prime-deep` for the full tool catalog. ## What this project is From 07b36691f2dffdf3bc1c3e2688a142818566ef2c Mon Sep 17 00:00:00 2001 From: Markus Neusinger <2921697+MarkusNeusinger@users.noreply.github.com> Date: Tue, 9 Jun 2026 20:37:21 +0200 Subject: [PATCH 2/2] fix(prime-deep): drop dangling @agentic/commands/context.md include The file was deleted in #5648; the include has been a silent no-op since. Flagged by Copilot review on #8518. Co-Authored-By: Claude Fable 5 --- agentic/commands/prime-deep.md | 1 - 1 file changed, 1 deletion(-) diff --git a/agentic/commands/prime-deep.md b/agentic/commands/prime-deep.md index 92fa1e7868..e6281208eb 100644 --- a/agentic/commands/prime-deep.md +++ b/agentic/commands/prime-deep.md @@ -18,7 +18,6 @@ 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