From 2b514d77aee5146df4db5e941b0de22f9e1f9a77 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 1 May 2026 20:08:58 +0000 Subject: [PATCH 1/3] chore(agentic/commands): apply Anthropic prompt engineering best practices Aligns slash-command prompts with the official Claude Opus 4.7 prompting guide (be clear and direct, scope explicit, tell-not-tell-not, structured JSON outputs) and fixes drift against the current repo layout. - Fix stale paths: services/ and core/models/ no longer exist; metadata and implementations now live under metadata/python/{lib}.yaml and implementations/python/{lib}.py (corrects update.md throughout) - Replace legacy jet_brains_* tool aliases with canonical mcp__serena__* in prime.md and agentic.md (matches .claude/settings.json permissions) - Replace large duplicated "Codebase Structure" sections in seven planning/review/test/document commands with a single pointer to agentic/docs/project-guide.md - Make planning commands (bug/chore/feature/refactor) explicit that they produce a plan only, not an implementation - Refresh implement.md with action-default and anti-overengineering guidance straight from the Opus 4.7 prompting guide - Drop deprecated "Ultra think" wording and tighten JSON-only output steering in review.md and classify.md - Lock start.md to the actual configured Vite port (3000), add parallel-tool guidance and safety rails to commit.md and pull_request.md - Refresh date examples in planning commands to today (260501) --- agentic/commands/agentic.md | 12 ++-- agentic/commands/audit.md | 2 +- agentic/commands/audit/catalog-auditor.md | 10 +-- agentic/commands/bug.md | 32 +++------ agentic/commands/chore.md | 31 ++------- agentic/commands/classify.md | 5 +- agentic/commands/commit.md | 13 ++-- agentic/commands/document.md | 20 +----- agentic/commands/feature.md | 32 +++------ agentic/commands/implement.md | 26 ++++++-- agentic/commands/prime.md | 29 ++++---- agentic/commands/pull_request.md | 8 ++- agentic/commands/refactor.md | 32 +++------ agentic/commands/review.md | 31 +++------ agentic/commands/start.md | 30 +++++---- agentic/commands/test.md | 20 +----- agentic/commands/update.md | 80 +++++++++++------------ 17 files changed, 170 insertions(+), 243 deletions(-) diff --git a/agentic/commands/agentic.md b/agentic/commands/agentic.md index 13690f1397..70800199b5 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` @@ -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 @@ -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/catalog-auditor.md b/agentic/commands/audit/catalog-auditor.md index 5c6c15076d..1753cee8be 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`). +- **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/document.md b/agentic/commands/document.md index 4e3de97d1d..e9983a3812 100644 --- a/agentic/commands/document.md +++ b/agentic/commands/document.md @@ -53,24 +53,8 @@ documentation_screenshots_dir: $3 if provided, otherwise leave it blank ## 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 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..7bce4f766f 100644 --- a/agentic/commands/prime.md +++ b/agentic/commands/prime.md @@ -24,25 +24,26 @@ gh pr list --limit 10 2>/dev/null || echo "(gh CLI not available)" ## Serena -- Run `check_onboarding_performed` -- Run `list_memories` and read relevant ones +- Run `mcp__serena__check_onboarding_performed` +- Run `mcp__serena__list_memories` and read relevant ones -### JetBrains Tools (prefer over brute-force scanning) +### Serena MCP tools (prefer over brute-force scanning) -Use Serena's JetBrains-backed tools for code navigation — they provide semantic understanding -that grep/glob cannot: +Use Serena's symbol-aware tools for code navigation — they provide semantic understanding that grep/glob cannot. +The canonical, MCP-registered prefix is `mcp__serena__*` (matches `.claude/settings.json`). 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..506d000059 100644 --- a/agentic/commands/review.md +++ b/agentic/commands/review.md @@ -38,32 +38,17 @@ review_image_dir: `/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 "plots/{spec_id}/implementations/python/.update-preview/{library}/plot.html" ]; then + gsutil cp "plots/{spec_id}/implementations/python/.update-preview/{library}/plot.html" "${STAGING_PATH}/plot.html" gsutil acl ch -u AllUsers:R "${STAGING_PATH}/plot.html" 2>/dev/null || true fi ``` @@ -303,7 +303,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 +330,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 +339,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 +418,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 +510,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 +569,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 +592,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 +618,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 +631,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 +640,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 +689,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 From c0980bb557c74aaa5aefcb525f1b890e0537a037 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 1 May 2026 20:33:21 +0000 Subject: [PATCH 2/3] chore(agentic/commands): rename context.md to docs.md The `/context` slash command collides with Claude Code's built-in `/context` (it shows context-window usage), so the project command was unreachable. Rename the file to `docs.md` so it surfaces as `/docs`. - Rename agentic/commands/context.md -> agentic/commands/docs.md - Add a note to the renamed file explaining the migration - Update all references: prime.md (@-include), document.md (router update step + entry-format), agentic.md (TAC scope mentions), audit/agentic-auditor.md (TAC sanity reference) --- agentic/commands/agentic.md | 4 ++-- agentic/commands/audit/agentic-auditor.md | 2 +- agentic/commands/{context.md => docs.md} | 6 +++++- agentic/commands/document.md | 10 ++++++---- agentic/commands/prime.md | 2 +- 5 files changed, 15 insertions(+), 9 deletions(-) rename agentic/commands/{context.md => docs.md} (88%) diff --git a/agentic/commands/agentic.md b/agentic/commands/agentic.md index 70800199b5..172cad22f6 100644 --- a/agentic/commands/agentic.md +++ b/agentic/commands/agentic.md @@ -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` @@ -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/` 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/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 e9983a3812..d437df0869 100644 --- a/agentic/commands/document.md +++ b/agentic/commands/document.md @@ -42,14 +42,16 @@ 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 @@ -119,7 +121,7 @@ to ground the documentation you generate. ## 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/prime.md b/agentic/commands/prime.md index 7bce4f766f..31ce5fed9e 100644 --- a/agentic/commands/prime.md +++ b/agentic/commands/prime.md @@ -18,7 +18,7 @@ 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 From b872a35d35ead1a1c3dc817955be85745eef5a85 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 1 May 2026 20:56:03 +0000 Subject: [PATCH 3/3] Address Copilot review feedback on PR #5648 - catalog-auditor.md: update implementation coverage example to use `implementations/python/*.py` to match the new namespaced layout. - review.md: fix JSON-shape inconsistency (object vs array) and quote the keys in the Output Structure example so it is valid JSON, since the prompt mandates strict JSON.parse() of the response. - update.md: stop copying transient `plot.png` into `plots/{spec_id}/implementations/python/`. Process and upload the preview directly from `.update-preview/{library}/`, matching the file-containment guidance and avoiding accidental commits or cross-agent overwrites alongside source implementations. https://claude.ai/code/session_01GWQrCaJZGt4nVRz7ct2LHs --- agentic/commands/audit/catalog-auditor.md | 2 +- agentic/commands/review.md | 16 +++++++--------- agentic/commands/update.md | 23 +++++++++++++---------- 3 files changed, 21 insertions(+), 20 deletions(-) diff --git a/agentic/commands/audit/catalog-auditor.md b/agentic/commands/audit/catalog-auditor.md index 1753cee8be..6ef6bc0f23 100644 --- a/agentic/commands/audit/catalog-auditor.md +++ b/agentic/commands/audit/catalog-auditor.md @@ -23,7 +23,7 @@ You don't need to query the database or run helper scripts. The repository under ## Things worth a glance (pick whichever feel productive) -- **Implementation coverage** — specs with very few `implementations/*.py` files relative to the 9 supported libraries. +- **Implementation coverage** — specs with very few `implementations/python/*.py` files relative to the 9 supported libraries. - **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`. diff --git a/agentic/commands/review.md b/agentic/commands/review.md index 506d000059..00e628d80b 100644 --- a/agentic/commands/review.md +++ b/agentic/commands/review.md @@ -52,7 +52,7 @@ to map the diff back onto specific subsystems. ## Report -- IMPORTANT: Return results exclusively as a JSON array based on the `Output Structure` section below. +- IMPORTANT: Return results exclusively as a JSON object matching the `Output Structure` section below. - `success` should be `true` if there are NO BLOCKING issues (implementation matches spec for critical functionality) - `success` should be `false` ONLY if there are BLOCKING issues that prevent the work from being released - `review_issues` can contain issues of any severity (skippable, tech_debt, or blocker) @@ -63,22 +63,20 @@ to map the diff back onto specific subsystems. ```json { - success: "boolean - true if there are NO BLOCKING issues (can have skippable/tech_debt issues), false if there are BLOCKING issues", - review_summary: "string - 2-4 sentences describing what was built and whether it matches the spec. Written as if reporting during a standup meeting. Example: 'The natural language query feature has been implemented with drag-and-drop file upload and interactive table display. The implementation matches the spec requirements for SQL injection protection and supports both CSV and JSON formats. Minor UI improvements could be made but all core functionality is working as specified.'", - review_issues: [ + "success": "boolean - true if there are NO BLOCKING issues (can have skippable/tech_debt issues), false if there are BLOCKING issues", + "review_summary": "string - 2-4 sentences describing what was built and whether it matches the spec. Written as if reporting during a standup meeting. Example: 'The natural language query feature has been implemented with drag-and-drop file upload and interactive table display. The implementation matches the spec requirements for SQL injection protection and supports both CSV and JSON formats. Minor UI improvements could be made but all core functionality is working as specified.'", + "review_issues": [ { "review_issue_number": "number - the issue number based on the index of this issue", "screenshot_path": "string - /absolute/path/to/screenshot_that_shows_review_issue.png", "issue_description": "string - description of the issue", "issue_resolution": "string - description of the resolution", "issue_severity": "string - severity of the issue between 'skippable', 'tech_debt', 'blocker'" - }, - ... + } ], - screenshots: [ + "screenshots": [ "string - /absolute/path/to/screenshot_showcasing_functionality.png", - "string - /absolute/path/to/screenshot_showcasing_functionality.png", - "...", + "string - /absolute/path/to/screenshot_showcasing_functionality.png" ] } ``` diff --git a/agentic/commands/update.md b/agentic/commands/update.md index 46f9721d8a..4797131f05 100644 --- a/agentic/commands/update.md +++ b/agentic/commands/update.md @@ -262,34 +262,37 @@ Quality: /100 | Updated: {YYYY-MM-DD} """ ``` -#### 6d. Copy Final Images +#### 6d. Process Final Images -For each library, copy the preview images to the implementations directory for GCS upload: +For each library, optimize the preview image **in place** within the per-library `.update-preview/` +directory. Do NOT copy artifacts up to `plots/{spec_id}/implementations/python/` — that directory is +reserved for source files (`{library}.py`) and a clean transient PNG/HTML alongside source files +risks an accidental commit or overwrite by a parallel agent. ```bash -cp plots/{spec_id}/implementations/python/.update-preview/{library}/plot.png plots/{spec_id}/implementations/python/plot.png -# Process images (optimization) +# Process image (optimization) — read and write to the same staging path uv run python -m core.images process \ - plots/{spec_id}/implementations/python/plot.png \ - plots/{spec_id}/implementations/python/plot.png + plots/{spec_id}/implementations/python/.update-preview/{library}/plot.png \ + plots/{spec_id}/implementations/python/.update-preview/{library}/plot.png ``` Note: Since we process one library at a time for GCS upload, handle sequentially. #### 6e. GCS Staging Upload -For each library: +For each library, upload directly from the per-library `.update-preview/` directory: ```bash STAGING_PATH="gs://anyplot-images/staging/{spec_id}/{library}" +PREVIEW_DIR="plots/{spec_id}/implementations/python/.update-preview/{library}" # Upload PNG -gsutil cp plots/{spec_id}/implementations/python/plot.png "${STAGING_PATH}/plot.png" +gsutil cp "${PREVIEW_DIR}/plot.png" "${STAGING_PATH}/plot.png" gsutil acl ch -u AllUsers:R "${STAGING_PATH}/plot.png" 2>/dev/null || true # Upload HTML if it exists (interactive libraries: plotly, bokeh, altair, highcharts, pygal, letsplot) -if [ -f "plots/{spec_id}/implementations/python/.update-preview/{library}/plot.html" ]; then - gsutil cp "plots/{spec_id}/implementations/python/.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 ```