Ent Schema Generator

Overview

Transform requirement inputs into implementation-ready database schema plans for sphere-layout Go projects using Ent ORM. This skill focuses on decisions directly actionable in Ent schema code and downstream integration layers.

This skill is repository-specific — always prefer local scaffold conventions over generic patterns unless explicitly requested.

When to Use

Use this skill when the user mentions:

• Database schema, Ent schema, entity design, or table structure

• Adding new data models, fields, or relationships

• Database migration, schema evolution, or index planning

• Proto bindings, entpb generation, or bind/render integration

• Any prompt describing business data requirements that need database persistence

Required Reading

Always read these files in order before generating schema plans:

• references/best-practices.md — Decision rules for schema design

• references/output-template.md — Required output format

Reference these when needed:

• references/ent-schema-examples.md — Code patterns with entproto annotations

• references/go-ent-service-patterns.md — DAO/service patterns

Workflow

Follow this sequence for each schema task:

Phase 1: Analysis

• Gather evidence from prompt/docs/proto/schema/service/dao/render

• Extract candidate entities and lifecycle states

• Identify key business requirements and constraints

Phase 2: Design Decisions

• Design field-level policies (Optional/Nillable/Unique/Immutable/Default)

• Decide ID strategy — generator-managed by default

• Decide relation strategy: relation-entity > array > join table > JSON fallback

• Build query-driven index plan from list/filter/sort paths

• Plan Go implementation (weak relation IDs, batch IDIn, chunking)

Phase 3: EntProto Compliance (REQUIRED)

• Add entproto annotations to ALL schemas:

• Schema: entproto.Message() in Annotations() method

• Fields: entproto.Field(n) with sequential numbers (ID=1)

• Enums: entproto.Field(n)

• entproto.Enum(map[string]int32{...}) with values starting from 1

• Verify enum values always start from 1 (0 is reserved)

Phase 4: Integration

• Map to bind registration, WithIgnoreFields, render/dao/service

• Document post-change commands and validation steps

Phase 5: Output

• Produce final brief using references/output-template.md

Critical Requirements

EntProto Annotation Rules

ALL schemas MUST include entproto annotations — this is not optional:

Component Required Annotation

Schema entproto.Message() in Annotations()

Primary Key Field entproto.Field(1)

Regular Fields entproto.Field(n) (sequential)

Enum Fields entproto.Field(n)

• entproto.Enum(map[string]int32{...})

Enum Values Must start from 1 (0 reserved)

Import: "entgo.io/contrib/entproto"

Integration Completeness

Task is incomplete without addressing:

• Bind registration — New entities must be added to cmd/tools/bind/main.go#createFilesConf

• WithIgnoreFields — Review for timestamps and sensitive fields

• Post-generation commands — Always include: make gen/proto go test ./...

• Generation diff checklist — Verify entpb/proto/bind/map changes are consumed

Output Requirements

Use references/output-template.md as the exact output format:

• Keep all 11 sections in order

• Mark assumptions explicitly as "Assumption:"

• Add "Blocking Notes:" under any section with incomplete validation

Common Pitfalls

• Don't stop at schema-only output when integration is affected

• Don't skip WithIgnoreFields review for sensitive fields

• Don't use Optional/Nillable for entproto — prefer zero-value defaults

• Don't start enum values from 0

• Don't forget to register new entities in bind config