Sphere Feature Workflow

Overview

Implement merge-ready feature changes in

go-sphere

scaffold projects while keeping

proto

schema

service

, and

render

layers synchronized.

This skill is scaffold-specific. Prefer repository conventions over generic architecture patterns unless the user explicitly requests otherwise.

Required Reading Order

Read these references before making edits:

references/workflow-matrix.md
references/source-of-truth-and-generated-boundaries.md
references/change-checklist.md

Scope

Use this skill when the task involves one or more of the following:

HTTP/API contract changes in
```
proto/**
```
Ent schema updates in
```
internal/pkg/database/schema/**
```
Bind/map registration updates in
```
cmd/tools/bind/main.go
```
Service/DAO/render behavior updates that must stay generation-safe
Cross-layer refactors that require protocol-first consistency

Workflow Selection

Classify the task first, then run the matching workflow:

```
Contract-first
```

Start from
```
proto/**
```
Use when adding or changing service methods, HTTP annotations, errors, or validation

```
Schema-first
```

Start from
```
internal/pkg/database/schema/**
```
Use when adding/changing entities, fields, indexes, or relationships

```
Service-only
```

Start from
```
internal/service/**
```
and
```
internal/pkg/dao/**
```
Use when behavior changes without contract/schema changes

```
Cross-layer
```

Use
```
Contract-first
```
or
```
Schema-first
```
as entrypoint, then complete all impacted layers

If classification is unclear, follow the preflight checks in references/workflow-matrix.md.

Reuse-First Policy

Before implementing new framework-level capability, check existing Sphere packages first. Do not duplicate behavior already covered by:

Lifecycle and bootstrapping:
```
core/boot
```
HTTP transport and error flow:
```
server/httpz
```
Auth and authorization:
```
server/auth/*
```
,
```
server/middleware/auth
```

Common middleware:

server/middleware/cors

ratelimiter

selector

Infrastructure adapters and shared runtime packages:
```
cache/*
```
,
```
storage/*
```
,
```
log/*
```
,
```
utils/*
```
,
```
infra/*
```

When overlap exists, reuse existing packages and document the decision.

Execution Workflows

Contract-first Workflow

Edit
```
proto/**
```
(service/method, HTTP annotation, validation, errors).
Run
```
make gen/proto
```
.
Resolve compile and behavior impacts in:

```
internal/service/**
```
```
internal/pkg/dao/**
```
```
internal/pkg/render/**
```
non-generated files

If contract-facing docs or SDK are impacted, run
```
make gen/docs
```
and/or
```
make gen/dts
```
.
Run tests and ensure generated diffs are consumed by manual code.

Schema-first Workflow

Edit
```
internal/pkg/database/schema/**
```
(field policy, relation, index strategy).
Verify bind/map registration impact in
```
cmd/tools/bind/main.go#createFilesConf
```
.
Review
```
WithIgnoreFields
```
for system-managed and sensitive fields.
Run
```
make gen/proto
```
.
Resolve compile and behavior impacts across service/dao/render.
Run tests and verify query paths align with index intent.

Service-only Workflow

Edit only non-generated business code:

```
internal/service/**
```
```
internal/pkg/dao/**
```
```
internal/pkg/render/**
```
non-generated files
optional shared orchestration in
```
internal/biz/**
```

Keep contract/schema stable unless explicitly requested.
Run targeted or full tests and confirm no API behavior regression.

Hard Rules

Edit source-of-truth files only; never patch generated files directly.
Run
```
make gen/proto
```
after any proto/schema change.
Run
```
make gen/docs
```
when HTTP contract output changes.
Run
```
make gen/wire
```
when dependency wiring signatures change.
New entity exposure must be reviewed in
```
cmd/tools/bind/main.go#createFilesConf
```
.
```
WithIgnoreFields
```
must cover system-managed and sensitive fields.
Keep service-specific business errors in the owning service proto unless explicitly shared.
Block delivery on route conflicts, cross-layer drift, or unconsumed generated changes.

Never manually edit

internal/pkg/render/entbind/**

internal/pkg/render/entmap/**

Standard Commands

bash

# ent + proto + bind/map generation chain
make gen/proto

# openapi/swagger generation
make gen/docs

# dependency injection generation
make gen/wire

# validation
go test ./...

Failure Conditions

Do not mark the task complete if any of the following is true:

Workflow type is not explicitly classified.
Required generation commands were skipped.
Generated diffs exist but are not reflected in service/dao/render logic.
Generated files were manually edited.
Bind/map or ignore-field policy impact was missed for schema-affecting changes.
Compatibility impact and residual risks were not reported.

When a failure condition is hit, output

Blocking Issues

first, then a fix plan.

Final Output Contract

Use this exact section order when reporting completion:

```
Scope
```
```
Workflow Selection
```
```
Reuse Decision
```
```
Source-of-Truth Files
```
```
Generation Commands
```
```
Behavior/Compatibility Notes
```
```
Validation
```
```
Blocking Issues
```
(only when applicable)

sphere-feature-workflow

NPX Install

Tags

SKILL.md Content