From cd4dadfa6ee2e84c28171b27e7743dec9ab76642 Mon Sep 17 00:00:00 2001 From: fullsend-code <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Sun, 16 Aug 2026 08:04:12 +0000 Subject: [PATCH] docs(#4334): add new-module creation conventions to scorecard AGENTS.md Add a "New Module Creation" section documenting the scaffolding conventions for new scorecard backend modules. The section covers initial version (0.0.0), changeset creation, API report generation, README requirements, config visibility annotations, and prettier formatting. These conventions were learned from fix iterations on PR #4258, where the code agent's initial commit required three human-triggered fixes for version, changeset, API report, README, and an incorrect @deepVisibility secret annotation on a non-sensitive filter field. Closes #4334 --- workspaces/scorecard/AGENTS.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/workspaces/scorecard/AGENTS.md b/workspaces/scorecard/AGENTS.md index 0b2b240c4b5..28d8eaa59a0 100644 --- a/workspaces/scorecard/AGENTS.md +++ b/workspaces/scorecard/AGENTS.md @@ -9,6 +9,17 @@ - Lint: `yarn lint:all` - Type check: `yarn tsc` +## New Module Creation + +When creating a new scorecard backend module under `plugins/`: + +1. Set `version` in `package.json` to `0.0.0` (the first changeset bumps it to `0.0.1`). +2. Create a changeset at `workspaces/scorecard/.changeset/.md` with a `patch` bump for the new package. +3. After adding public exports, generate the API report: `yarn tsc && yarn build:api-reports:only` from the scorecard workspace. +4. Create a `README.md` with: feature overview, prerequisites, installation instructions, and app-config configuration examples. +5. In `config.d.ts`, use `@visibility frontend` or `@visibility backend` for non-sensitive fields. Only use `@deepVisibility secret` for fields that contain credentials, tokens, or other genuinely sensitive values. Catalog entity filters (e.g., `kind: Component`) are not sensitive. +6. Run `yarn prettier:fix` from the scorecard workspace before committing. + ## Metric ID Naming Convention All metric IDs use `lowerCamelCase` with a `.` format: