@codeam/shared 2.61.75 → 2.61.76

package/dist/index.mjs

@@ -2043,11 +2043,110 @@ var specDrivenDevelopmentSkill = {
   }
 };
 
+// src/skills/code-naming.ts
+var CODE_NAMING_BODY = `Use this skill when NAMING or RENAMING code \u2014 variables, functions, classes,
+interfaces, types, files, modules, components, hooks, constants \u2014 while writing
+new code, refactoring, or reviewing a diff. A name should reveal intent and
+domain meaning so a reader understands the code without translating it in their
+head, and so it needs fewer comments.
+
+## The five core rules (name the concept, not the implementation)
+
+1. **Don't abbreviate, and don't use single letters for meaningful values.**
+   \`usr\`/\`cfg\`/\`authReq\` \u2192 \`user\`/\`config\`/\`authRequest\`; \`u\`/\`p\` \u2192 \`user\`/\`project\`.
+   Abbreviations rely on context the next reader may not have. Allowed: standard
+   acronyms the domain already uses (API, URL, HTTP, ID, UUID, CLI, SDK, PR, OAuth),
+   loop indices \`i\`/\`j\`, coordinates \`x\`/\`y\`, and generic type params \`T\`/\`K\`/\`V\`.
+
+2. **Don't put the data TYPE in a variable name.** \`userList\` \u2192 \`users\`,
+   \`nameString\` \u2192 \`displayName\`, \`isActiveBool\` \u2192 \`isActive\`, \`invoiceMap\` \u2192
+   \`invoicesById\`. The type system and editor already show the type; the name
+   should carry the meaning.
+
+3. **Include the UNIT when a number has one** (unless the type makes it
+   unmistakable). \`timeout\` \u2192 \`timeoutMs\`, \`delay\` \u2192 \`retryDelaySeconds\`,
+   \`size\` \u2192 \`fileSizeBytes\`, \`price\` \u2192 \`priceUsd\`. Especially time, distance,
+   money, bytes, rates, percentages, token/rate limits.
+
+4. **Don't put the type CONSTRUCT in a type's name.** \`UserClass\` \u2192 \`User\`,
+   \`PaymentInterface\`/\`IPayment\` \u2192 \`Payment\` (or a role like \`PaymentGateway\`),
+   \`ConfigType\` \u2192 \`Config\`, \`StatusEnum\` \u2192 \`Status\`. Name the concept, not
+   "what kind of programming thing it is."
+
+5. **Refactor when you're reaching for \`Utils\`/\`Helpers\`/\`Common\`.** A generic
+   bucket usually hides a missing concept. Group by domain instead:
+   \`utils/parseCookie\` \u2192 a \`cookies/\` module or a \`CookieStore\`/\`CookieJar\` class;
+   \`utils/formatDate\` \u2192 \`dates/\` or a \`DateRangeFormatter\`. Same for vague
+   \`Base\`/\`Abstract\`/\`Manager\`/\`Helper\` class names \u2014 prefer the role
+   (\`Repository\`, \`BillingService\`, \`UserProvisioner\`) unless the project
+   convention explicitly requires \`Base\`/\`Abstract\`.
+
+## Shape rules
+
+- **Functions are verbs / verb phrases:** \`createInvoice()\`, \`sendPasswordResetEmail()\`,
+  \`findRepositoryById()\`. Booleans read like a question in an \`if\`:
+  \`isActive\`, \`hasAccess\`, \`canDeploy\`, \`shouldRetry\` (prefix \`is/has/can/should/needs\`).
+- **Classes / interfaces / types are nouns or roles:** \`Invoice\`, \`PaymentGateway\`,
+  \`AgentSession\` \u2014 not \`InvoiceData\`, \`SubscriptionThing\`, \`AgentSessionType\`.
+- **Collections are plural, or \`\u2026ById\`/\`\u2026ByX\` when indexed:** \`users\`,
+  \`activeSessions\`, \`invoicesByCustomerId\`.
+- **Don't encode a temporary implementation in a name that may change:**
+  \`postgresUserRepository\` \u2192 \`userRepository\`, \`redisCache\` \u2192 \`cache\` \u2014 unless the
+  implementation IS the meaningful distinction. Name the role, not today's backend.
+- **Follow the project's existing conventions** (casing, file naming, \`useX\`
+  hooks, \`handleX\` handlers). Match the surrounding code; don't introduce a new
+  style without a strong reason.
+
+## Words to distrust (infer the real role, then name it)
+
+\`data\`, \`info\`, \`item\`, \`obj\`, \`temp\`, \`result\`, \`value\`, \`thing\`, \`stuff\`,
+\`manager\`, \`helper\`, \`utils\`, \`common\`, \`base\`, \`abstract\`, \`processor\`,
+\`handler\`, \`payload\`. They're acceptable only when the surrounding context makes
+them precise (e.g. \`config\` inside one \`DatabaseConnection\`); vague when passed
+across many layers.
+
+## Guardrails \u2014 this is a review/refactor guide, NOT a mass-rename mandate
+
+- Names that are already clear and idiomatic are DONE \u2014 leave them.
+- Before renaming: read how the identifier is used and infer the real domain
+  concept. Prefer the **smallest** clear rename.
+- Do NOT do large unrelated renames, and do NOT rename purely for personal
+  preference. Stay inside the change you were asked to make.
+- Preserve public API / exported names unless the task explicitly allows a break;
+  when you do rename, update every reference, tests, and docs in the same change.
+- No clever names, jokes, or metaphors in production code; don't make names
+  needlessly long either.
+
+When reviewing, raise a naming issue only when a clearer name would materially
+help a reader \u2014 one suggestion per finding: \`current \u2192 suggested \u2014 why\`.`;
+var CODE_NAMING_INSTRUCTION = `When naming or renaming code, name the domain concept, not the implementation:
+no abbreviations or single-letter names for meaningful values (standard acronyms
+like API/URL/ID/OAuth are fine); don't put the data type in a variable name
+(userList \u2192 users); include the unit when a number has one (timeout \u2192 timeoutMs);
+don't put the type construct in a type's name (IPayment \u2192 Payment); and refactor
+generic Utils/Helper/Manager/Base buckets into a domain module or a role-named
+class. Functions are verbs (createInvoice), booleans read like questions
+(isActive/hasAccess), classes/types are nouns/roles, collections are plural or
+\u2026ById. This is a review/refactor guide, not a mandate to mass-rename: leave
+already-clear names alone, prefer the smallest clear rename, don't rename
+unrelated code, and preserve public/exported names unless the task allows a break.`;
+var codeNamingSkill = {
+  id: "code-naming",
+  name: "Code Naming",
+  description: `Naming review & refactor: name the domain concept, not the implementation \u2014 no abbreviations, no type-in-name, units when they matter, no Utils/Manager/Base buckets; rename minimally, never mass-rename.`,
+  source: "curated",
+  delivery: {
+    skillFile: { body: CODE_NAMING_BODY },
+    instruction: { body: CODE_NAMING_INSTRUCTION }
+  }
+};
+
 // src/skills/registry.ts
 var SKILL_REGISTRY = {
   "code-review": codeReviewSkill,
   "resolve-conflicts": resolveConflictsSkill,
-  "spec-driven-development": specDrivenDevelopmentSkill
+  "spec-driven-development": specDrivenDevelopmentSkill,
+  "code-naming": codeNamingSkill
 };
 function isSkillId(id) {
   return Object.prototype.hasOwnProperty.call(SKILL_REGISTRY, id);