Go Service Template REST

AI-native Go REST template for solo developers who want coding agents that can work inside real Go constraints.

Generic AI-native repos are good at teaching agents how to spec, plan, and delegate. They are usually much weaker at teaching them how to operate inside idiomatic Go boundaries, preserve invariants, work with context, respect generated artifacts, reason about chi and sqlc, and ship code that survives review. go-service-template-rest is built around that exact gap.

This repository is for people who code with Codex, Claude Code, Cursor, Gemini CLI, and other LLM-assisted workflows, but do not want a generic process layer floating above the language. The workflow is agent-native. The instructions, skills, review surfaces, and validation loop are Go-native.

• Orchestrator-first: frame, delegate, synthesize, plan, implement, verify.
• Go-native guidance: the repository does not stop at language-agnostic workflow advice.
• Project-scoped agents: Codex agents live in .codex/agents/, Claude Code agents live in .claude/agents/.
• Portable skills: reusable workflow expertise lives in .agents/skills and is mirrored to compatibility/runtime directories.
• Artifact-driven for non-trivial work: master workflow-plan.md plus workflow-plans/<phase>.md separate cross-phase control from phase-local orchestration, while spec.md, design/, and tasks.md keep decisions, technical design, and executable task state distinct. Pre-code phases produce that bundle; implementation and validation consume it and do not create new workflow/process artifacts.
• First production feature path: before adding business code, use the first production feature checklist to place app types and ports, HTTP mapping, Postgres adapters, bootstrap wiring, telemetry, and tests.
• Production stack underneath: OpenAPI-first HTTP, PostgreSQL, sqlc, observability, tests, and CI gates are already wired.

Most AI-native coding today is solo. Most generic AI-native repos intentionally stay technology-independent. Most Go templates still stop at folder layout, Docker files, and a Makefile. That combination leaves a real hole:

• the workflow knows how to spec and delegate, but not how to reason in Go;
• the stack knows how to compile, but not how to guide an agent through non-trivial changes;
• the repo has commands, but no explicit ownership model for research, planning, implementation, review, and validation.

This template is built from the opposite assumption: if you want agents to be useful in a Go backend, the workflow and the language need to be wired together on purpose.

That is why this repository is opinionated in four places:

1. The workflow is explicit. Non-trivial work starts with optional idea refinement, then framing, workflow planning, research, synthesis, pre-spec challenge, specification with an autonomous clarification gate, technical design, task breakdown, coding from tasks.md, review, and validation. The loop is visible, not implied, one session normally owns one phase before coding, and session wrappers such as workflow-planning-session, research-session, specification-session, technical-design-session, planning-session, and validation-closeout-session keep those handoffs explicit.
2. The specialists are real. Subagents have narrow ownership areas like API, domain, data, reliability, performance, and security. They are not generic “helper” personas.
3. The skills are Go-native. The skill library does not stop at abstract design advice. It covers Go architecture, routing, DB/cache contracts, invariants, reliability, security, review, debugging, testing, and verification.
4. The backend substrate is real. OpenAPI, chi, PostgreSQL, sqlc, observability, tests, and CI gates are already in the template, so the workflow lands on an actual service baseline.

If you want a Go backend template that feels natural inside Codex or Claude Code and still respects how Go services are actually built, this repository is designed for that use case.

The fix is not a single block of text. It shapes the whole repository:

• Artifacts with clear jobs: specs/<feature-id>/workflow-plan.md keeps master control, specs/<feature-id>/workflow-plans/<phase>.md holds phase-local orchestration, specs/<feature-id>/spec.md keeps final decisions, specs/<feature-id>/design/ carries task-local technical design for non-trivial work, specs/<feature-id>/tasks.md owns the executable checkbox ledger, and the phase/session wrappers keep those handoffs explicit across sessions.
• Go-aware subagents: the agent portfolio is organized around real backend concerns instead of generic brainstorming personas.
• Go-native skills: the skill library gives the orchestrator and subagents concrete playbooks for Go design, implementation, review, and verification.
• Verification as a first-class rule: “done” is tied to fresh command evidence, not to confident prose from an LLM.
• A serious service template underneath: once the workflow moves into implementation, the repo already has OpenAPI-first HTTP, PostgreSQL, sqlc, telemetry, and CI guardrails.

This repository treats delivery as an explicit loop, not as a single long chat and not as process theater:

intake -> idea refine? -> workflow planning -> research -> synthesis -> pre-spec challenge -> specification + clarification challenge -> technical design -> planning -> coding from tasks.md -> review -> validation

• intake: frame the change, scope it, and record assumptions.
• idea refine: when the request is still a raw concept, use idea-refine to make the user, problem, success criteria, MVP, and not-doing boundary explicit before engineering framing.
• workflow planning: choose the execution shape, decide whether work stays local or fans out, set the current phase in master workflow-plan.md, write the phase-local orchestration in workflow-plans/<phase>.md, and state whether later design/, tasks.md, test-plan.md, or rollout.md artifacts will be required. Early checkpoints often use workflow-plans/workflow-planning.md or workflow-plans/research.md; later ones use files like workflow-plans/specification.md, workflow-plans/technical-design.md, or workflow-plans/planning.md. Do not optimize for a small lane count; optimize for coverage.
• research: keep simple work local or fan out only to read-only subagents, with enough lanes to cover the materially affected domains. When in doubt on a complex task, prefer more lanes over fewer.
• synthesis: compare specialist output and produce candidate decisions.
• pre-spec challenge: pressure-test candidate decisions before they harden into spec.md, and loop back to research if needed.
• specification: stabilize final decisions, constraints, and open questions in spec.md; for non-trivial work, run the autonomous spec-clarification-challenge gate through a read-only challenger before approval.
• technical design: for non-trivial work, turn approved decisions into a task-local design/ bundle. Load docs/repo-architecture.md first when stable repository boundaries or runtime flows matter.
• planning: use planning-and-task-breakdown or equivalent discipline to turn approved spec.md + design/ into small, verifiable execution slices in tasks.md; any later review or validation phase workflow files are created here before code starts only when named multi-session routing needs them, and the planning exit records implementation readiness as PASS, CONCERNS, FAIL, or WAIVED.
• implementation: change the service in the main flow, not inside research agents. New code/test files are fine when approved tasks.md requires them; new workflow/process artifacts are not. Existing tasks.md checkbox/progress state may be updated; missing required tasks.md or implementation readiness of FAIL routes back to planning or the named earlier phase instead of being invented mid-code.
• review: run targeted review agents only where the risk justifies them.
• validation: do not claim "done" without fresh command evidence, and do not create new planning/process artifacts during closeout. Existing tasks.md may be progress-updated only when it already belongs to the task.

For non-trivial work, one session = one phase by default before coding: master workflow-plan.md tracks the current phase, artifact status, next session, blockers, and links to phase workflow plans; the current workflow-plans/<phase>.md carries phase-local orchestration. Finish that phase, update both workflow-control files plus the owning phase artifacts, and stop before the next phase. Start the next phase in a new session unless an upfront direct path or lightweight local waiver was recorded. If later review or validation phase files are needed, create them before implementation begins and let post-code sessions update them rather than inventing them mid-execution.

When a task benefits from explicit session boundaries, use the phase/session wrappers that match the current checkpoint:

• workflow-planning-session: own the pre-research routing pass only.
• research-session: own evidence gathering and optional preserved research/*.md only.
• specification-session: own spec.md approval, the clarification gate, and workflow-plans/specification.md only.
• technical-design-session: own the task-local design/ bundle and workflow-plans/technical-design.md only.
• planning-session: own tasks.md, optional test-plan.md or rollout.md, any later review or validation phase workflow files already required, and workflow-plans/planning.md only.
• validation-closeout-session: own fresh proof, spec.md closeout updates, and existing validation-phase routing only.

Think of the workflow-control artifacts as complementary, not competing:

• workflow-plan.md: master cross-phase routing, artifact status, blockers, and next-session handoff.
• workflow-plans/<phase>.md: one phase only, with local orchestration, completion marker, stop rule, and next action.
• tasks.md: executable task ledger with markdown checkboxes, stable IDs such as T001, phase labels, optional [P] only for safe parallel work, dependency markers when needed, concrete file/package surfaces, and proof expectations.
• Implementation readiness: a planning-phase gate. PASS allows implementation, CONCERNS requires named accepted risks and proof obligations, FAIL routes earlier, and WAIVED stays limited to explicit tiny/direct-path/prototype scope.

Use workflow-status when you only need a compact read-only status or next-action check from existing artifacts. It reports state; it does not repair artifacts, approve readiness, or replace the workflow-control files.

pre-spec challenge is a risk-driven checkpoint inside the synthesis boundary, not a separate approval authority. spec-clarification-challenge is a required non-trivial approval gate inside specification: a read-only challenger surfaces high-impact questions for the orchestrator to answer from evidence, route to targeted research, accept as risk, defer with rationale, or mark requires_user_decision without inventing an answer. For tiny or direct-path fixes, several of these stages can collapse into one short local pass instead of turning into mandatory ceremony. Write-capable delegate agents are out of policy for this workflow; if a tool surface cannot reliably stay read-only, keep that track in the main flow instead of delegating it.

The full contract lives in AGENTS.md and the supporting workflow doc lives in docs/spec-first-workflow.md.

This repository distinguishes between two different things:

• Subagents are read-only specialists you fan out to for focused research or review.
• Skills are portable workflow playbooks loaded on demand by the orchestrator or a subagent.

The repository ships with project-scoped, read-only subagents for focused reasoning and review. Codex agent instructions live in .codex/agents/*.toml and are loaded through .codex/config.toml; this registry layer uses Codex-supported agents.<name>.config_file entries while keeping each agent as a standalone custom-agent file. Claude Code mirrors live in .claude/agents/ and are generated from the Codex source with make agents-sync; verify them with make agents-check. Shared subagent invariants live in docs/subagent-contract.md, and reusable lane prompts start from docs/subagent-brief-template.md. Click an agent name to open its Codex instruction file.

All of these agents stay advisory and read-only. Write-capable delegates are not part of this subagent model. Final decisions always stay with the orchestrator in the main flow. Agent files own scope, mode routing, and handoff. If a lane uses a skill, the skill owns the procedure and exact output shape; the agent fallback return shape applies only when the chosen skill does not define one. delivery-agent, distributed-agent, and observability-agent now have dedicated review skills (go-devops-review, go-distributed-review, and go-observability-review) for targeted review of their owned surfaces; routine application-code diff review still belongs to the matching code-domain reviewer.

Codex

Codex loads the project agent registry from .codex/config.toml. In practice, you ask the orchestrator to fan out by agent name:

Use `architecture-agent` and `api-agent` to evaluate the new async export flow.
Synthesize the result into `specs/export-flow/spec.md`.
Do not start coding until the `tasks.md` handoff and implementation readiness are explicit.

Claude Code

Claude Code project agents live in .claude/agents. You can select them directly with --agent:

claude -p --agent architecture-agent -- "Review boundary ownership for adding async webhook retries in this repository."
claude -p --agent qa-agent -- "List the minimum regression obligations for changing the order status flow."

• New endpoint or contract change: api-agent + domain-agent + qa-agent
• Pre-spec pressure-test on ambiguous work: challenger-agent + the specialist whose decision still feels under-evidenced
• Spec approval clarification: challenger-agent with exactly one skill, spec-clarification-challenge
• Storage, cache, or migration change: data-agent + reliability-agent
• Cross-service or async workflow: architecture-agent + distributed-agent + security-agent
• Pre-merge cleanup on a larger diff: quality-agent + the domain reviewer that matches the risk

.agents/skills is the canonical repository skill set. These skills are procedural building blocks, not autonomous owners of the workflow. Click a skill name to open its canonical instruction file.

The catalog has two layers:

• phase/session wrappers that keep one session bounded to one checkpoint and update workflow-plan.md plus the matching workflow-plans/<phase>.md
• deeper skills that do framing, design, planning, implementation, review, or validation work inside those boundaries when needed

These repository-native skill locations keep the workflow portable:

• .agents/skills
• .claude/skills
• .cursor/skills
• .gemini/skills
• .github/skills
• .opencode/skills

The source of truth stays in .agents/skills, so you do not have to hand-maintain separate skill instructions per tool. Refresh the runtime mirrors with bash ./scripts/dev/sync-skills.sh or make skills-sync, and verify them with bash ./scripts/dev/sync-skills.sh --check or make skills-check.

Agent mirrors follow the same hygiene: .codex/agents is canonical for project subagents, .claude/agents is generated, make agents-sync refreshes it, and make agents-check is a CI-backed drift check.

The repository is designed so the main agent acts like an orchestrator, not like a single monolithic coder.

• The orchestrator owns framing, scope, synthesis, planning, implementation, reconciliation, and validation.
• Subagents own narrow research or review tracks only.
• Skills are tools, not the workflow itself.
• spec.md is the canonical decisions artifact.
• workflow-plan.md is the master control artifact for the whole task.
• workflow-plans/<phase>.md is the phase workflow artifact for one phase only.
• design/ is the task-local technical design bundle for non-trivial work.
• tasks.md is the executable task ledger and final pre-code handoff, not a second spec or second design bundle.
• Implementation readiness is the planning exit gate, not a phase. It is recorded in workflow-plan.md, with the result and stop or handoff rule in workflow-plans/planning.md.
• research/*.md is optional supporting evidence, not a competing source of truth.

For non-trivial implementation work, the artifact shape is intentionally simple:

specs/<feature-id>/
  workflow-plan.md
  workflow-plans/
  spec.md
  design/
  tasks.md
  research/

If you want the short version: frame first, keep cross-phase control in workflow-plan.md, keep current-phase orchestration in workflow-plans/<phase>.md, use the session wrappers when a checkpoint needs a dedicated session, keep approved decisions in spec.md, write task-local technical design in design/, track executable work in tasks.md, and move into coding from that ledger. For tiny fixes, keep it lighter and skip the extra artifacts when the change is obviously local and the waiver is explicit.

make bootstrap
make template-init   # run this when you create a new repo from the template
make check
make run

Before adding production feature code, start with the placement guide in Project Structure & Module Organization. It gives the short path for app-only behavior, strict-server endpoints, Postgres-backed features, workers, bootstrap wiring, and test placement.

Recommended flow:

1. Create a new empty GitHub repository under your account or organization. It may be private or public, but do not initialize it with README, .gitignore, or LICENSE.
2. Clone this template into the directory you want to use for the new service.
3. Rename the template remote to upstream and point origin to your repository.
4. Run template initialization before the first push.

git clone https://github.com/Dankosik/go-service-template-rest.git my-service
cd my-service

git remote rename origin upstream
git remote add origin git@github.com:<your-user>/<your-repo>.git
# or: git remote add origin https://github.com/<your-user>/<your-repo>.git

git remote -v

make bootstrap
make template-init
make check

git add .
git commit -m "chore: initialize service from template"
git push -u origin main

What this does:

• origin becomes your repository, so normal git push goes to your project.
• upstream keeps a reference to the original template repository in case you want to compare or pull template updates later.
• make template-init rewires the Go module path, CODEOWNERS, and skill mirrors for the new repository.
• git push -u origin main publishes the first main branch to your repository and makes future plain git push / git pull work against origin/main.

If git push says Everything up-to-date but your GitHub repository is still empty, your local branch is probably still tracking the template branch instead of your own repository. Check:

git remote -v
git branch -vv

Expected state:

• origin points to your repository.
• upstream points to go-service-template-rest.
• main tracks origin/main, not upstream/main.

If needed, publish the branch explicitly:

git push -u origin main

If SSH push fails with Permission denied (publickey), either configure your GitHub SSH key or switch origin to HTTPS:

git remote set-url origin https://github.com/<your-user>/<your-repo>.git
git push -u origin main

If you use GitHub's Use this template button instead of the manual clone flow, clone your generated repository normally and still run:

make bootstrap
make template-init

For production-style GitHub setup after the first push:

gh auth login
make gh-protect BRANCH=main

Typical next steps:

1. Copy env/.env.example to .env if make bootstrap did not already do it.
2. Run make template-init after cloning into a new service repository to rewire module path, CODEOWNERS, and skill mirrors.
3. Use make check-full before larger changes or before opening a PR.

1. Open the repository in Codex or Claude Code.
2. Read AGENTS.md. Claude-facing compatibility is mirrored in CLAUDE.md.
3. For non-trivial or agent-backed work, open docs/spec-first-workflow.md before workflow planning or subagent fan-out.
4. If the task reaches technical design, load docs/repo-architecture.md before writing task-local design/.
5. For feature code, use the placement guide in Project Structure & Module Organization before choosing packages or tests.
6. Start with an artifact-driven, phase-bounded prompt, not with direct code generation.

Example kickoff prompt:

Use `workflow-planning-session` if this is non-trivial enough to need dedicated workflow control.
Use `idea-refine` only if the request is still too raw.
Frame a change to add tenant-aware export jobs.
Fan out to `architecture-agent`, `data-agent`, and `qa-agent` only if needed.
Run `challenger-agent` before `specification-session` if material assumptions remain.
During `specification-session`, run `challenger-agent` with `spec-clarification-challenge` before approving non-trivial `spec.md`.
Load `docs/repo-architecture.md` before `technical-design-session` if repository boundaries matter.
Write master control to `specs/tenant-export-jobs/workflow-plan.md`.
Start the current checkpoint in `specs/tenant-export-jobs/workflow-plans/workflow-planning.md`, then advance one session-bounded phase at a time through `research.md`, `specification.md`, `technical-design.md`, `planning.md`, and any needed review or validation phase files.
Write decisions to `specs/tenant-export-jobs/spec.md`, task-local technical design to `specs/tenant-export-jobs/design/`, and the executable task ledger to `specs/tenant-export-jobs/tasks.md` before coding.

Start feature work with the placement guide in Project Structure & Module Organization; it covers the short path for HTTP endpoints, Postgres-backed features, and workers without duplicating the workflow rules here.

• cmd/service - service entrypoint and bootstrap lifecycle orchestration
• internal/app - use-case layer
• internal/domain - domain contracts and types
• internal/infra - HTTP, Postgres, telemetry, and other infrastructure adapters
• api/openapi/service.yaml - REST API source of truth
• internal/api - generated OpenAPI artifacts
• env/migrations - SQL migrations for the local PostgreSQL environment
• internal/infra/postgres/sqlcgen - generated sqlc artifacts
• specs/ - spec-first decision records and implementation history
• .agents/skills - canonical skill definitions

More detail: docs/project-structure-and-module-organization.md, plus the stable architecture baseline in docs/repo-architecture.md

Workflow comes first, but this is still a serious Go backend template.

• Go 1.26
• chi for HTTP routing
• kin-openapi and oapi-codegen for contract-first API work
• PostgreSQL 17, pgx/v5, and sqlc for SQL-first data access
• koanf for configuration
• Prometheus and OpenTelemetry for observability
• testcontainers-go, go.uber.org/mock, and goleak for testing
• Docker multi-stage builds and distroless runtime images
• GitHub Actions for CI, nightly checks, and CD

For the full dependency graph, see go.mod and go.sum.

Local entry points:

• make check - quick local checks
• make docker-check - quick checks through pinned Docker tooling
• BASE_REF=origin/main HEAD_REF=HEAD make check-full - full local pre-push baseline with docs-drift comparison
• make ci-local - native CI-style flow
• BASE_REF=origin/main HEAD_REF=HEAD make docker-ci - closest Docker-based CI parity flow with pinned tooling images
• make openapi-check - OpenAPI generation, drift, runtime contract, lint, and schema validation checks
• BASE_OPENAPI=<base> make openapi-breaking - OpenAPI breaking-change compatibility check
• make sqlc-check - generated SQL artifact drift checks
• make migration-validate / make docker-migration-validate - migration rehearsal for changed migrations
• make test-integration - integration tests
• make gh-protect BRANCH=main - branch protection setup helper

Migration rehearsal targets may skip when no MIGRATION_DSN is provided and Docker is unavailable; skip output is not migration proof. For the full local-vs-GitHub parity matrix and CD caveats, see Build, Test, and Development Commands.

Repository and CI guardrails include:

• formatting and module integrity checks
• golangci-lint
• unit tests, race tests, and coverage thresholds
• OpenAPI generation drift, validation, lint, and breaking-change checks
• sqlc generation drift checks
• docs, agent mirror, and skills mirror drift checks
• govulncheck, gosec, and gitleaks
• container image scanning with Trivy
• GHCR publishing, CycloneDX SBOM generation, and Cosign signing in release flows

See .github/workflows/ and Makefile for the exact pipeline steps.