gophling

Go REST API scaffold for parallel coding agents, with PostgreSQL,
OpenAPI, sqlc, and reproducible checks. Each resource is an ordinary Go package.

Start a project

Use a patched supported Go release (minimum 1.26.10) and Git. Bootstrap uses
the pinned Go 1.27.3 toolchain, downloading it if needed. Docker runs the local
database.

go run github.com/y0f/gophling/cmd/forge@latest new myapp
cd myapp
go run ./cmd/dev bootstrap

The installer asks for a module path and the optional components to keep.
For automation, pass -yes -module github.com/you/myapp. Use -ref <tag-or-SHA>
to select the scaffold revision; .forge.json records the resolved revision.
For repeatable setup, pin the launcher version (cmd/forge@<release>) and use a
full commit SHA for -ref when selecting older or custom source.

If in-place initialization is interrupted while publishing files, recover from
the project root before making manual changes:

go run github.com/y0f/gophling/cmd/forge@<release> init -recover

Use the release that performed initialization. Recovery restores the saved
tracked files and preserves unrelated untracked files. Earlier tool or
generation failures leave the original project untouched.

Run and verify

go run ./cmd/dev doctor
go run ./cmd/dev check
./bin/task up

The fast check runs without a database. task up starts the API and Postgres.
On PowerShell use ./bin/task.exe; if Task is on PATH, task also works.

The API is at http://localhost:8080, the reference at /docs, and the
contract at /openapi.yaml. Read the development bearer token from the API log:

docker compose -f deployments/docker-compose.yml logs api

task down stops the stack and keeps data. task reset also deletes the
database volume.

Add a feature

go run ./cmd/forge add resource Note
./bin/task generate
go run ./cmd/dev check

The generator adds a module, migration, SQL queries, OpenAPI operations, tests,
and route wiring. Reads are public; writes require notes:write or an explicit
role grant. The logged development token has the admin role, which gets no
automatic grant for new resources. Apply the migration before serving the routes.

Alternatively, ask your coding agent to perform the same change:

Add a Note resource. Keep reads public and require notes:write for writes.
Test invalid input and denied writes. Regenerate the bindings, then run the
fast and integration checks.

Agent setup covers Claude Code, Codex, Gemini CLI, Copilot,
and Cursor instruction loading.
Parallel work assigns modules to separate
worktrees and shared changes to one coordinator.
The resource guide gives the complete workflow.

Included

Optional outbox: commit events with state changes and retry failed deliveries.
The example publisher only logs event metadata; replace it for external delivery.

Optional idempotency: replay create requests with the same caller, key, and
body; reject a changed body with 409.

Optional tracing: OTLP export with a local Collector, Tempo, and Grafana stack.

Optional admin listener: token-protected pprof and expvar on a separate port.

Production mode requires a token verifier. The local Compose stack explicitly
enables development mode and its temporary signing key.

Documentation

• Setup and commands
• Parallel worktrees
• Architecture and decisions
• Schema changes
• Authorization
• Testing

• Fit and alternatives
• Agent evaluation results and method
• Recorded resource workflow

• Contributing

Verify a release

Replace TAG with the downloaded release tag (for example, v1.3.0) and
OWNER/REPOSITORY with the GitHub repository that published it.

For gophling releases, the repository is y0f/gophling.

cosign verify-blob --bundle checksums.txt.bundle \
  --certificate-identity 'https://github.com/OWNER/REPOSITORY/.github/workflows/release.yml@refs/tags/TAG' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com checksums.txt

Then compare the SHA-256 hash of your downloaded archive with its entry in the
verified checksums.txt before extracting it.

For public GitHub.com releases, also verify the archive's build provenance.
Replace ARCHIVE with the downloaded filename.

gh attestation verify ARCHIVE --repo OWNER/REPOSITORY \
  --signer-workflow OWNER/REPOSITORY/.github/workflows/release.yml \
  --source-ref refs/tags/TAG

This verifies the artifact's association with the release workflow and source
tag. The workflow skips GitHub attestations for private repositories;
enabling them there requires a
supported GitHub Enterprise Cloud plan. See GitHub's
attestation guide
and verification options.

When the release is marked Immutable, verify GitHub's release attestation
and the downloaded asset as well:

gh release verify TAG --repo OWNER/REPOSITORY
gh release verify-asset TAG ARCHIVE --repo OWNER/REPOSITORY

This applies to uploaded release assets, not GitHub's automatically generated
source ZIP/tarballs. Immutability must be enabled for each repository and applies
to future releases; it does not protect older releases or custom branch refs.
See release operations and GitHub's
release verification guide.

MIT. See LICENSE.