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:

1. references/best-practices.md — Decision rules for schema design
2. 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

1. Gather evidence from prompt/docs/proto/schema/service/dao/render
2. Extract candidate entities and lifecycle states
3. Identify key business requirements and constraints

Phase 2: Design Decisions

4. Design field-level policies (Optional/Nillable/Unique/Immutable/Default)
5. Decide ID strategy — generator-managed by default
6. Decide relation strategy: relation-entity > array > join table > JSON fallback
7. Build query-driven index plan from list/filter/sort paths
8. Plan Go implementation (weak relation IDs, batch IDIn, chunking)

Phase 3: EntProto Compliance (REQUIRED)

9. 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
10. Verify enum values always start from 1 (0 is reserved)

Phase 4: Integration

11. Map to bind registration, WithIgnoreFields, render/dao/service
12. Document post-change commands and validation steps

Phase 5: Output

13. 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:

1. Bind registration — New entities must be added to cmd/tools/bind/main.go#createFilesConf
2. WithIgnoreFields — Review for timestamps and sensitive fields
3. Post-generation commands — Always include:

   make gen/proto
   go test ./...
   

4. 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