Skill: Add Game Subsystem

Scaffold a complete new game subsystem end-to-end: models, service, router, schemas, migrations, OpenAPI spec, and tests.

When to Use

Use this skill when adding a major new game feature that spans multiple layers (database, service, API, tests). Examples: a crafting system, an auction house, a reputation system, a quest system.

Instructions

1. Design the domain model

Before writing code, identify:

• Entities: What new database tables are needed?
• Relationships: How do they relate to existing entities (Player, Entity, Party)?
• Determinism: Does any logic need seeded randomness?
• State machines: What status transitions exist (e.g., active → completed → expired)?

2. Create database models

Add SQLAlchemy models to server/app/core/models.py or a new entity file:

class MySubsystemRecord(Base):
    __tablename__ = "my_subsystem_records"

    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    entity_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("entities.id"), nullable=False)
    status: Mapped[str] = mapped_column(String, nullable=False, default="active")
    version: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())

    entity: Mapped["Entity"] = relationship(back_populates="subsystem_records")

Always include: id (UUID), version (optimistic concurrency), created_at.

3. Generate database migration

make docker-up
make docker-migrate-revision m="add_my_subsystem_tables"
make docker-migrate

Review the generated migration in server/migrations/versions/.

4. Create Pydantic schemas

Add request/response models to server/app/core/models.py (response models) and server/app/core/schemas.py (request validation):

# Response model
class MySubsystemResponse(BaseModel):
    id: str
    entity_id: str
    status: str
    created_at: datetime

    model_config = ConfigDict(from_attributes=True)

# Request model
class CreateMySubsystemRequest(BaseModel):
    entity_id: str
    parameters: dict[str, Any] = Field(default_factory=dict)

5. Create the service

Create server/app/core/my_subsystem_service.py:

class MySubsystemService:
    def __init__(self, session: Session) -> None:
        self._session = session

    def create(self, entity: Entity, *, player: Player, seed: int | None = None) -> MySubsystemRecord:
        if entity.player_id != player.id:
            raise DomainForbidden()
        record = MySubsystemRecord(entity_id=entity.id, ...)
        self._session.add(record)
        self._session.flush()
        return record

For complex subsystems, use a subdirectory: server/app/core/my_subsystem/.

6. Add the dependency provider

In server/app/api/dependencies.py:

def get_my_subsystem_service(session: Session = Depends(get_db_session)) -> MySubsystemService:
    return MySubsystemService(session)

7. Create the router

Create server/app/api/my_subsystem.py:

router = APIRouter(prefix="/my-subsystem", tags=["my-subsystem"])

@router.post("/", response_model=MySubsystemResponse, status_code=201)
def create_record(
    *,
    payload: CreateMySubsystemRequest,
    service: MySubsystemService = Depends(get_my_subsystem_service),
    session: Session = Depends(get_db_session),
    player: Player = Depends(get_current_player),
) -> MySubsystemResponse:
    entity = session.get(Entity, payload.entity_id)
    if entity is None:
        raise DomainNotFound("Entity not found")
    result = service.create(entity, player=player)
    telemetry_emit("my_subsystem.created", player_id=str(player.id))
    return MySubsystemResponse.model_validate(result)

8. Register the router

In server/app/main.py:

1. Import the router
2. Add to _ROUTERS list

In server/app/api/__init__.py:

1. Export the router

9. Update OpenAPI spec

Add all new paths and schemas to server/openapi/openapi.yaml. Validate:

make docker-openapi-validate

10. Write comprehensive tests

Create tests/test_my_subsystem.py:

• Unit tests (@pytest.mark.unit) for pure service logic
• Integration tests (@pytest.mark.integration) for API endpoints
• Determinism tests (same seed = same output) if applicable
• Error case tests (404, 403, 409)
• Edge case tests (empty inputs, boundary values)
• Property-based tests (Hypothesis) for complex logic

11. Validate everything

make docker-lint
make docker-test
make docker-openapi-validate

Coverage must remain at 99%.

12. Document

• Update docs/DOMAIN_MODEL.md if the subsystem introduces new domain concepts
• Update docs/API_COVERAGE_ANALYSIS.md with new endpoint status
• Add subsystem-specific docs in docs/agents/ if the subsystem is complex