diff --git a/agentic/commands/agentic.md b/agentic/commands/agentic.md index 13690f1397..172cad22f6 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** (`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 diff --git a/agentic/commands/audit.md b/agentic/commands/audit.md index 38989af6e9..a7ec9258bc 100644 --- a/agentic/commands/audit.md +++ b/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/-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 diff --git a/agentic/commands/audit/agentic-auditor.md b/agentic/commands/audit/agentic-auditor.md index fbfe4fd05f..22e17b3a9d 100644 --- a/agentic/commands/audit/agentic-auditor.md +++ b/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 diff --git a/agentic/commands/audit/catalog-auditor.md b/agentic/commands/audit/catalog-auditor.md index 5c6c15076d..6ef6bc0f23 100644 --- a/agentic/commands/audit/catalog-auditor.md +++ b/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. diff --git a/agentic/commands/bug.md b/agentic/commands/bug.md index a8f1ec4cb2..20932c872b 100644 --- a/agentic/commands/bug.md +++ b/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 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 `` in the `Plan Format` with the requested value. Keep it specific and actionable — + vague plans produce vague fixes. ## Plan Format diff --git a/agentic/commands/chore.md b/agentic/commands/chore.md index 21abcacfac..33531ebd4c 100644 --- a/agentic/commands/chore.md +++ b/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 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 `` in the `Plan Format` with the requested value. ## Plan Format diff --git a/agentic/commands/classify.md b/agentic/commands/classify.md index be5848f600..1065b44e70 100644 --- a/agentic/commands/classify.md +++ b/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"} diff --git a/agentic/commands/commit.md b/agentic/commands/commit.md index 69c737565e..d7a0ad7f1a 100644 --- a/agentic/commands/commit.md +++ b/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 ""` 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 ` — never use `git add -A` or `git add .`, which can pull in + `.env`, credentials, or large binaries by accident. +4. Run `git commit -m ""` 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 diff --git a/agentic/commands/context.md b/agentic/commands/docs.md similarity index 88% rename from agentic/commands/context.md rename to agentic/commands/docs.md index 24f51e2253..c4129cc507 100644 --- a/agentic/commands/context.md +++ b/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 diff --git a/agentic/commands/document.md b/agentic/commands/document.md index 4e3de97d1d..d437df0869 100644 --- a/agentic/commands/document.md +++ b/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/.md diff --git a/agentic/commands/feature.md b/agentic/commands/feature.md index b357455dce..b233ba28b4 100644 --- a/agentic/commands/feature.md +++ b/agentic/commands/feature.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. -- Understand the feature requirements from the `prompt` -- Research existing patterns in the codebase to ensure consistency -- Create the plan in the `agentic/specs/` directory with filename: `{YYMMDD}-{descriptive-name}.md` - - Use today's date as YYMMDD prefix (e.g., "260207-add-plot-export.md") -- Research the codebase starting with `README.md` -- Replace every 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 +- Understand the feature requirements from the `prompt` and research existing patterns in the codebase to ensure + consistency. This command produces a **plan only** — do NOT implement the feature here. +- Create the plan at `agentic/specs/{YYMMDD}-{descriptive-name}.md` using today's UTC date (e.g., + `260501-add-plot-export.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 `` in the `Plan Format` with the requested value. Be specific about API shapes, + component names, and file paths so a downstream agent can implement without guessing. ## Plan Format diff --git a/agentic/commands/implement.md b/agentic/commands/implement.md index d2bf88d78f..5ea18b54cd 100644 --- a/agentic/commands/implement.md +++ b/agentic/commands/implement.md @@ -1,12 +1,30 @@ # Implement the following plan -Follow the `Instructions` to implement the `Plan` then `Report` the completed work. + +Execute the plan below end-to-end, then report what changed. ## Instructions -- Read the plan, think hard about the plan and implement the plan. + +- Read the entire plan first. Reason through it carefully before touching any code so the steps stay coherent. +- Implement every step in the order given. Do not skip steps or reorder unless the plan turns out to be wrong — in + that case, stop and explain rather than improvising. +- Default to action: make the changes the plan describes (file edits, new files, scripts) rather than only + suggesting them. Use parallel tool calls for independent reads/edits. +- Stay within scope. Only change what the plan requires: + - No drive-by refactors, no extra abstractions, no speculative configurability, no defensive code for impossible + states. A bug fix doesn't need surrounding cleanup; a feature doesn't need extra knobs. + - No new comments, docstrings, or type hints on code you didn't touch. +- Run the plan's `Validation Commands` after the implementation steps and fix any failures before finishing. +- If you create temporary helper files or scratch scripts, delete them once the task is done. +- If a step is genuinely blocked (missing context, conflicting requirement, failing tests you didn't introduce), + stop and ask — do NOT use `--no-verify`, mock data, or hard-coded test values to push through. ## Plan + $ARGUMENTS ## Report -- Summarize the work you've just done in a concise bullet point list. -- Report the files and total lines changed with `git diff --stat` \ No newline at end of file + +- One concise bullet list of what was implemented (one bullet per plan step actually executed). +- Output of `git diff --stat` to show files and total lines changed. +- Validation commands run and their pass/fail status. +- Any plan steps that were skipped or deviated from, with a one-line reason. diff --git a/agentic/commands/prime.md b/agentic/commands/prime.md index c88b9ee8b3..31ce5fed9e 100644 --- a/agentic/commands/prime.md +++ b/agentic/commands/prime.md @@ -18,31 +18,32 @@ gh pr list --limit 10 2>/dev/null || echo "(gh CLI not available)" ## Read @agentic/docs/project-guide.md -@agentic/commands/context.md +@agentic/commands/docs.md @docs/concepts/vision.md @pyproject.toml ## 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`). Older repo docs may +still mention `jet_brains_*` aliases — treat them as the same tools and prefer the `mcp__serena__*` form below. -- `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` — top-level symbols in a file (classes, functions, variables). Use `depth: 1` + to also see methods of classes. Start here 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 signatures. +- `mcp__serena__find_referencing_symbols` — find all usages of a symbol (who calls this function? who imports this + class?). Essential for understanding the impact of changes. ### 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) diff --git a/agentic/commands/pull_request.md b/agentic/commands/pull_request.md index d5ceb06d0c..79119b21c1 100644 --- a/agentic/commands/pull_request.md +++ b/agentic/commands/pull_request.md @@ -21,11 +21,15 @@ plan_file: $2 ## Run +Run steps 1-3 in parallel; analyze the full output before drafting the PR body. Only push (step 4) once the +branch state matches what the PR description claims. + 1. Run `git diff origin/main...HEAD --stat` to see changed files summary 2. Run `git log origin/main..HEAD --oneline` to see commits in this branch 3. Run `git branch --show-current` to get the current branch name -4. Run `git push -u origin $(git branch --show-current)` to push the branch -5. Create the PR: +4. Run `git push -u origin $(git branch --show-current)` to push the branch (do NOT use `--force` or + `--no-verify` unless the user explicitly asks for it) +5. Create the PR — non-draft, ready for review: ``` gh pr create --title "" --body "$(cat <<'EOF' diff --git a/agentic/commands/refactor.md b/agentic/commands/refactor.md index 27f1fc8daf..83f2f068cd 100644 --- a/agentic/commands/refactor.md +++ b/agentic/commands/refactor.md @@ -11,31 +11,15 @@ prompt: $2 ## Instructions - If the run_id or prompt is not provided, stop and ask the user to provide them. -- Understand the refactoring goal from the `prompt` +- Understand the refactoring goal from the `prompt`. This command produces a **plan only** — do NOT execute the + refactor here. - IMPORTANT: A refactor changes structure while preserving behavior. No functional changes allowed. -- Establish a test baseline BEFORE planning any changes — all tests must pass before and after -- Create the plan in the `agentic/specs/` directory with filename: `{YYMMDD}-{descriptive-name}.md` - - Use today's date as YYMMDD prefix (e.g., "260207-extract-services.md") -- Research the codebase starting with `README.md` -- Replace every 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 +- Establish a test baseline BEFORE planning any changes — all tests must pass before and after. +- Create the plan at `agentic/specs/{YYMMDD}-{descriptive-name}.md` using today's UTC date (e.g., + `260501-extract-services.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 `` in the `Plan Format` with the requested value. ## Plan Format diff --git a/agentic/commands/review.md b/agentic/commands/review.md index 0825e55808..00e628d80b 100644 --- a/agentic/commands/review.md +++ b/agentic/commands/review.md @@ -38,36 +38,21 @@ review_image_dir: `/agentic/runs///agentic/runs///dev/null || true # Upload HTML if it exists (interactive libraries: plotly, bokeh, altair, highcharts, pygal, letsplot) -if [ -f "plots/{spec_id}/implementations/.update-preview/{library}/plot.html" ]; then - gsutil cp "plots/{spec_id}/implementations/.update-preview/{library}/plot.html" "${STAGING_PATH}/plot.html" +if [ -f "${PREVIEW_DIR}/plot.html" ]; then + gsutil cp "${PREVIEW_DIR}/plot.html" "${STAGING_PATH}/plot.html" gsutil acl ch -u AllUsers:R "${STAGING_PATH}/plot.html" 2>/dev/null || true fi ``` @@ -303,7 +306,7 @@ GCS files from staging to production on merge): #### 6f. Clean Up Preview Directory ```bash -rm -rf plots/{spec_id}/implementations/.update-preview +rm -rf plots/{spec_id}/implementations/python/.update-preview ``` #### 6g. Per-Library Branches, PRs & Reviews @@ -330,8 +333,8 @@ WORKTREE=".worktrees/{spec_id}-{library}" git worktree add -b implementation/{spec_id}/{library} "$WORKTREE" main # Copy only this library's changed files into the worktree -cp plots/{spec_id}/implementations/{library}.py "$WORKTREE/plots/{spec_id}/implementations/{library}.py" -cp plots/{spec_id}/metadata/{library}.yaml "$WORKTREE/plots/{spec_id}/metadata/{library}.yaml" +cp plots/{spec_id}/implementations/python/{library}.py "$WORKTREE/plots/{spec_id}/implementations/python/{library}.py" +cp plots/{spec_id}/metadata/python/{library}.yaml "$WORKTREE/plots/{spec_id}/metadata/python/{library}.yaml" # If spec was changed (only for the first library): cp plots/{spec_id}/specification.md "$WORKTREE/plots/{spec_id}/specification.md" cp plots/{spec_id}/specification.yaml "$WORKTREE/plots/{spec_id}/specification.yaml" @@ -339,8 +342,8 @@ cp plots/{spec_id}/specification.yaml "$WORKTREE/plots/{spec_id}/specification.y # Commit and push from the worktree cd "$WORKTREE" -git add plots/{spec_id}/implementations/{library}.py -git add plots/{spec_id}/metadata/{library}.yaml +git add plots/{spec_id}/implementations/python/{library}.py +git add plots/{spec_id}/metadata/python/{library}.yaml # If spec was changed (only in first library branch): git add plots/{spec_id}/specification.md git add plots/{spec_id}/specification.yaml @@ -418,7 +421,7 @@ Immediately after Phase 6 completes: 3. `TeamDelete` to clean up the team 4. Clean up preview directory: ```bash - rm -rf plots/{spec_id}/implementations/.update-preview + rm -rf plots/{spec_id}/implementations/python/.update-preview ``` #### 7b. Poll PR Status @@ -510,8 +513,8 @@ You are **{LIBRARY}** on the `update-{SPEC_ID}` team. Your job is to update the Read these files to understand what you're working with: 1. `plots/{SPEC_ID}/specification.md` — the specification (what the plot should show) -2. `plots/{SPEC_ID}/implementations/{LIBRARY}.py` — current implementation to update -3. `plots/{SPEC_ID}/metadata/{LIBRARY}.yaml` — review feedback from last review: +2. `plots/{SPEC_ID}/implementations/python/{LIBRARY}.py` — current implementation to update +3. `plots/{SPEC_ID}/metadata/python/{LIBRARY}.yaml` — review feedback from last review: - `review.strengths` — PRESERVE these (don't break what works) - `review.weaknesses` — FIX these - `review.criteria_checklist` — items with `passed: false` need fixing @@ -569,7 +572,7 @@ Then go idle and wait for the lead to relay the user's decision. Only proceed on ### Step 3: Modify Implementation -Edit `plots/{SPEC_ID}/implementations/{LIBRARY}.py`: +Edit `plots/{SPEC_ID}/implementations/python/{LIBRARY}.py`: - Follow all rules from `prompts/plot-generator.md` and `prompts/library/{LIBRARY}.md` - KISS structure: imports → data → plot → save @@ -592,20 +595,20 @@ explain what you changed and why. Do not edit the spec just for the sake of chan Run the implementation to generate the plot image. **IMPORTANT**: Each agent MUST run in its own isolated preview directory to avoid race conditions with other parallel agents. All agents write `plot.png` — running in the shared -`implementations/` directory causes file conflicts. +`implementations/python/` directory causes file conflicts. **FILE CONTAINMENT RULES — CRITICAL:** - You may ONLY write files to these locations: - - `plots/{SPEC_ID}/implementations/{LIBRARY}.py` (the implementation itself) - - `plots/{SPEC_ID}/implementations/.update-preview/{LIBRARY}/` (preview output directory) + - `plots/{SPEC_ID}/implementations/python/{LIBRARY}.py` (the implementation itself) + - `plots/{SPEC_ID}/implementations/python/.update-preview/{LIBRARY}/` (preview output directory) - `plots/{SPEC_ID}/specification.md` (only if spec changes are needed) -- **NEVER** create files in the project root, the `implementations/` directory directly, or any other location. +- **NEVER** create files in the project root, the `implementations/python/` directory directly, or any other location. - **NEVER** download or save images outside `.update-preview/{LIBRARY}/`. If you need to view the current preview from GCS, use the URL directly with `WebFetch` or `Read` — do not download it to a local file. ```bash -mkdir -p plots/{SPEC_ID}/implementations/.update-preview/{LIBRARY} -cd plots/{SPEC_ID}/implementations/.update-preview/{LIBRARY} && MPLBACKEND=Agg uv run python ../../{LIBRARY}.py +mkdir -p plots/{SPEC_ID}/implementations/python/.update-preview/{LIBRARY} +cd plots/{SPEC_ID}/implementations/python/.update-preview/{LIBRARY} && MPLBACKEND=Agg uv run python ../../{LIBRARY}.py ``` This runs `{LIBRARY}.py` from the isolated `.update-preview/{LIBRARY}/` directory, so `plot.png` and `plot.html` land @@ -618,8 +621,8 @@ If the script fails, read the error, fix the implementation, and retry. **Up to Run ruff to format and fix lint issues in the implementation before proceeding: ```bash -uv run ruff format plots/{SPEC_ID}/implementations/{LIBRARY}.py -uv run ruff check --fix plots/{SPEC_ID}/implementations/{LIBRARY}.py +uv run ruff format plots/{SPEC_ID}/implementations/python/{LIBRARY}.py +uv run ruff check --fix plots/{SPEC_ID}/implementations/python/{LIBRARY}.py ``` If `ruff check` reports unfixable errors (exit code 1), read the error output and fix the code manually, then re-run. @@ -631,8 +634,8 @@ Generate thumbnail and optimize: ```bash uv run python -m core.images process \ - plots/{SPEC_ID}/implementations/.update-preview/{LIBRARY}/plot.png \ - plots/{SPEC_ID}/implementations/.update-preview/{LIBRARY}/plot.png + plots/{SPEC_ID}/implementations/python/.update-preview/{LIBRARY}/plot.png \ + plots/{SPEC_ID}/implementations/python/.update-preview/{LIBRARY}/plot.png ``` ### Step 7: Quality Evaluation & Local Repair Loop @@ -640,7 +643,7 @@ uv run python -m core.images process \ Before shipping, formally evaluate your implementation against the same criteria CI uses. This catches issues locally (cheaper) instead of triggering expensive remote repair cycles. -**7a. View the generated image** at `plots/{SPEC_ID}/implementations/.update-preview/{LIBRARY}/plot.png`. +**7a. View the generated image** at `plots/{SPEC_ID}/implementations/python/.update-preview/{LIBRARY}/plot.png`. **7b. Score against all 6 quality categories** using the criteria from `prompts/quality-criteria.md` (read in Step 1). Produce category totals only (no per-criterion notes needed): @@ -689,7 +692,7 @@ CHANGES: - {bullet point 2} - ... -IMAGE: {absolute path to plots/{SPEC_ID}/implementations/.update-preview/{LIBRARY}/plot.png — use pwd to resolve} +IMAGE: {absolute path to plots/{SPEC_ID}/implementations/python/.update-preview/{LIBRARY}/plot.png — use pwd to resolve} QUALITY: {total}/100 (after {N} local repair iterations, 0 = passed first evaluation) VQ: {vq}/30 | DE: {de}/20 | SC: {sc}/15