Skip to content

AUTO-MAS-Project/AUTO-MAS / .agents/skills/mas-schema-naming

mas-schema-naming

Verified

Define canonical naming for future backend schema domains. Use when creating new specialized schema models or extending Pydantic contracts in app/models/schema.py, standardizing shared Info/Data/Notify/Run semantics, and avoiding new naming drift without forcing retroactive changes on legacy modules.

MAS Schema Naming

Objective

Standardize naming for future specialized backend schema implementations.

This skill constrains new domain work by default. It does not require retroactive renaming of existing legacy modules unless explicitly requested.

Global Constraints

Apply these constraints while using this skill.

  1. Make minimal necessary changes first; avoid broad refactors unless explicitly requested.
  2. Align with current code style and existing project conventions in the touched module.
  3. Avoid over-engineering, over-abstraction, and defensive programming that does not match existing code patterns.
  4. Study similar existing implementations deeply before coding and follow established local patterns.

Apply Workflow

  1. Determine whether the field is shared semantic or domain-specific semantic.
  2. For shared semantic, use the canonical name from this skill.
  3. For domain-specific semantic, keep naming local to the domain block.
  4. Keep public config-model field style consistent: PascalCase.
  5. When touching legacy modules, prefer compatibility-first edits and avoid broad rename-only refactors.

Canonical Structure For New Domains

Use this top-level structure for new script/user schema models.

class XxxConfig(BaseModel):
    Info: XxxConfig_Info | None
    Run: XxxConfig_Run | None
    Emulator: XxxConfig_Emulator | None  # only if emulator semantics exist


class XxxUserConfig(BaseModel):
    Info: XxxUserConfig_Info | None
    Data: XxxUserConfig_Data | None
    Notify: XxxUserConfig_Notify | None
    # optional domain blocks, e.g. Task/Stage/Game

Shared Naming Matrix

Use these names when semantics are the same.

SemanticCanonical nameBlock
Script display nameNameInfo
Script runtime pathPathInfo
Emulator idIdEmulator
Emulator indexIndexEmulator
Transition strategyTaskTransitionMethodRun
Daily proxy limitProxyTimesLimitRun
Retry limitRunTimesLimitRun
Runtime timeoutRunTimeLimitRun
User display nameNameUser.Info
User idIdUser.Info
User enabled statusStatusUser.Info
Remaining day budgetRemainedDayUser.Info
User noteNotesUser.Info
User tag payloadTagUser.Info
Last proxy dateLastProxyDateUser.Data
Proxy run countProxyTimesUser.Data
Manual-check resultIfPassCheckUser.Data
Notify enabledEnabledUser.Notify
Send statisticIfSendStatisticUser.Notify
Send mailIfSendMailUser.Notify
Mail receiverToAddressUser.Notify
ServerChan enabledIfServerChanUser.Notify
ServerChan keyServerChanKeyUser.Notify

Boundary For Domain-Specific Names

  1. Keep domain-specific semantics inside dedicated domain blocks.
  2. Do not force shared naming when semantics differ.
  3. Do not add synonym fields for the same semantic in one block.

Drift To Avoid In New Work

  1. Same semantic, different names (Path vs RootPath).
  2. Same semantic, different block placement (Data vs Info).
  3. Same semantic, mixed boolean style in the same block.

Compatibility Rule

When canonicalizing an existing public field:

  1. Keep read compatibility for legacy payloads during migration.
  2. Prefer writing canonical names in new responses.
  3. Remove legacy names only after consumer migration is complete.

PR Checklist

  1. New specialized schema models follow this canonical matrix for shared semantics.
  2. Domain-specific fields stay in domain-specific blocks.
  3. No new synonym names are introduced for existing shared semantics.
  4. Legacy modules are not renamed in bulk unless explicitly in scope.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall