If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/goadesign/goa shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1w ago
• 7 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 87% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live goadesign/goa repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/goadesign/goa.

What it runs against: a local clone of goadesign/goa — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in goadesign/goa | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch v3 exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 37 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of goadesign/goa. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/goadesign/goa.git
#   cd goa
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of goadesign/goa and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "goadesign/goa(\\.git)?\\b" \\
  && ok "origin remote is goadesign/goa" \\
  || miss "origin remote is not goadesign/goa (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify v3 >/dev/null 2>&1 \\
  && ok "default branch v3 exists" \\
  || miss "default branch v3 no longer exists"

# 4. Critical files exist
test -f "cmd/goa/main.go" \\
  && ok "cmd/goa/main.go" \\
  || miss "missing critical file: cmd/goa/main.go"
test -f "codegen/generator/generate.go" \\
  && ok "codegen/generator/generate.go" \\
  || miss "missing critical file: codegen/generator/generate.go"
test -f "codegen/service/client.go" \\
  && ok "codegen/service/client.go" \\
  || miss "missing critical file: codegen/service/client.go"
test -f "codegen/service/endpoint.go" \\
  && ok "codegen/service/endpoint.go" \\
  || miss "missing critical file: codegen/service/endpoint.go"
test -f "codegen/go_transform.go" \\
  && ok "codegen/go_transform.go" \\
  || miss "missing critical file: codegen/go_transform.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 37 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~7d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/goadesign/goa"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Goa is a design-first Go framework that generates production-ready API code, documentation, and client libraries from a single declarative DSL definition. You write your API spec once in Goa's domain-specific language, and it automatically generates HTTP and gRPC service implementations, OpenAPI docs, and typed clients in Go, JavaScript, and other languages—eliminating documentation drift and boilerplate code. Modular monorepo structure: cmd/goa/ contains the CLI entry point (main.go, gen.go), codegen/ is the core generation engine split into domain-specific packages (cli/, example/, doc.go for generators), and codegen/**/templates/ directories hold Go template files (.tpl) that generate boilerplate code. The design DSL lives in dsl/ package (referenced in pkg.go.dev links), while http/, grpc/, and plugins handle protocol-specific code generation.

Go backend engineers and API architects building microservices who want to eliminate the gap between API design, implementation, and documentation. Teams that need consistent, well-documented APIs across multiple services without maintaining separate specs, code, and docs.

Highly mature and production-ready. The repo shows 2.4M lines of Go code, active CI/CD with GitHub Actions (codeql.yml, test.yml, dependency-review.yml), comprehensive test coverage in cmd/goa/main_test.go and codegen/example/, and regular releases. Last activity visible in dependabot automation and actively maintained RELEASE.md procedures indicate ongoing development.

Very low risk. The project is vendor-agnostic (pure Go with no heavy external dependencies visible), has institutional backing (incident.io sponsor), and extensive contributor guidelines (CONTRIBUTING.md, CODE_OF_CONDUCT.md). Single-point-of-failure risk is mitigated by the mature, stable API surface and strong community engagement (Slack, Bluesky, Substack presence).

Active maintenance visible through dependabot automation (dependabot.yml, dependabot-weekly-automerge.yml), security scanning (codeql.yml), and dependency review workflows. The project maintains detailed RELEASE.md and CONTRIBUTING.md procedures, indicating structured release cadence. Recent work includes template-based code generation enhancements (evident from multiple .tpl files in codegen/*/templates/) and gRPC/HTTP dual-protocol support.

git clone https://github.com/goadesign/goa.git && cd goa && make && go install ./cmd/goa && goa gen github.com/goadesign/goa/example

Daily commands: make (builds CLI and runs tests per Makefile) or go run ./cmd/goa gen <path-to-design> to generate code from a design package. Tests run via make or go test ./...

• cmd/goa/main.go — Entry point for the goa CLI tool that orchestrates code generation from DSL definitions.
• codegen/generator/generate.go — Core code generation engine that processes design definitions and produces output files.
• codegen/service/client.go — Client code generator producing HTTP/gRPC client stubs from service definitions.
• codegen/service/endpoint.go — Endpoint abstraction layer bridging service definitions to transport-specific handlers.
• codegen/go_transform.go — AST transformation engine converting design-time definitions into idiomatic Go code.
• codegen/file.go — File-level code generation primitives managing output structure, imports, and formatting.
• codegen/plugin.go — Plugin system enabling third-party code generators to extend goa's capabilities.

Add a new service endpoint

1. Define the endpoint in your goa DSL design file using the Endpoint() function with request/response types (design DSL file (outside repo scope, but referenced by cmd/goa/main.go))
2. The generator will automatically create endpoint interface in codegen/service/endpoint.go-generated output (codegen/service/endpoint.go)
3. HTTP transport code is auto-generated in codegen/generator/transport.go (codegen/generator/transport.go)
4. Client stubs are generated in codegen/service/client.go output (codegen/service/client.go)
5. Implement the endpoint handler in your service; generated code wires it via codegen/generator/service.go (codegen/generator/service.go)

Add custom code generation logic

1. Create a new generator or extend existing ones in codegen/generator/ (codegen/generator/generators.go)
2. Implement code generation using file/section primitives from codegen/file.go (codegen/file.go)
3. Use Go AST transformation from codegen/go_transform.go to convert design types (codegen/go_transform.go)
4. Add template files in codegen/*/templates/ if using template-based generation (codegen/example/templates)
5. Register your generator in the plugin system via codegen/plugin.go (codegen/plugin.go)

Add type conversion for new payload types

1. Define new type in goa DSL design (design DSL file (external))
2. Extend codegen/service/convert.go to handle marshaling/unmarshaling (codegen/service/convert.go)
3. Add Go AST transformation rules in codegen/go_transform.go (codegen/go_transform.go)
4. Verify client code generation includes conversion in codegen/service/client.go (codegen/service/client.go)

Extend OpenAPI documentation generation

1. Examine current OpenAPI generation in codegen/generator/openapi.go (codegen/generator/openapi.go)
2. Add custom schema/metadata generation logic (codegen/generator/openapi.go)
3. Wire into docs generation orchestrator in codegen/generator/docs.go (codegen/generator/docs.go)
4. Test with codegen/codegentest/codegentest.go utilities (codegen/codegentest/codegentest.go)

• Go AST (ast, go/parser, go/printer) — Enables precise code generation that respects Go semantics and produces correctly-formatted, idiomatic code without string templating fragility
• Text templates (text/template) — Provides flexible code generation for boilerplate patterns (CLI, examples) while maintaining readability
• Plugin system (exec, plugin package) — Allows third-party generators without modifying core codebase; follows Unix philosophy of composability
• OpenAPI 3.0 spec generation — Industry-standard API specification enables interoperability with tools, SDKs, and documentation systems (Swagger UI, etc.)

• Design-first approach with code generation rather than code-first with reflection

  • Why: Design-first enforces API contract clarity upfront and enables simultaneous HTTP/gRPC code generation
  • Consequence: Developers must maintain DSL alongside code; generated code is not hand-editable (must regenerate)

• Separate transport (HTTP/gRPC) from business logic via endpoint abstraction

  • Why: Enables multi-protocol support and clean separation of concerns
  • Consequence: Added abstraction layer requires developers to understand endpoint flow; slight runtime overhead

• Code generation via AST transformation + templates rather than pure reflection

  • Why: Produces optimized, readable code and avoids runtime reflection penalties
  • Consequence: Build-time complexity; generation failures require debugging DSL rather than runtime errors

• Plugin system for extensibility rather than monolithic generator

  • Why: Allows custom generators without forking core; follows open/closed principle
  • Consequence: Plugin discovery/loading adds operational complexity; plugins must respect interface contracts

No major hidden traps documented in visible files. Be aware that: (1) designs are Go code using the dsl/ package API, not a separate config format—you need Go knowledge to write designs; (2) generated code imports from goa.design/goa/v3, so the framework must be available at runtime; (3) template-based generation means breaking changes to .tpl files affect all generated code—test carefully.

• Design-First Development — Goa's core philosophy—you define the API contract first, then generate implementation. Understanding this paradigm is critical to using Goa effectively and avoiding code-generation pitfalls.
• Code Generation via Templates — All Goa output (handlers, clients, docs) comes from Go text/template evaluation. Modifying or debugging generated code requires understanding template mechanics and the template files in codegen/*/templates/.
• Service Descriptor Pattern — Goa parses your design DSL into an in-memory service descriptor (think AST) that generators then traverse. Understanding this descriptor structure is key to extending Goa with custom generators.
• Protocol Agnosticism — Goa generates both HTTP/REST and gRPC from the same design. The codegen pipeline is abstracted so a single endpoint definition produces both implementations—critical for multi-protocol microservices.
• Endpoint & Handler Separation — Generated code splits into endpoints (request/response logic) and handlers (transport-specific marshaling). This separation enables Goa to support middleware, interceptors, and protocol switching cleanly.
• Error Modeling as First-Class Design — Goa treats error responses as part of the design spec, generating type-safe error structs and encoding logic. This prevents ad-hoc error handling and ensures consistency across services.
• Streaming in gRPC and HTTP — Goa's design DSL supports request/response streaming, and the codegen produces streaming logic for both gRPC and HTTP SSE. Understanding how streaming is modeled is essential for high-throughput APIs.

• grpc/grpc-go — Goa generates gRPC service code that wraps grpc-go; understanding grpc-go internals helps debug generated interceptors and endpoint logic
• golang/protobuf — Goa's gRPC protocol support competes with Protocol Buffers; many Goa users migrate from or integrate with protobuf-based services
• gin-gonic/gin — Alternative HTTP framework for Go that some teams use instead of Goa's generated HTTP handlers—useful for understanding Goa's HTTP codegen design choices
• goadesign/goa-example — Official example repository showing realistic Goa design definitions and generated service structure
• kubernetes/kubernetes — Goa-generated services often deploy to Kubernetes; understanding K8s API conventions influences Goa API design patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for CLI code generation output validation

The codegen/example/testdata directory contains golden files for testing expected output, but there's no apparent test suite validating that the CLI (cmd/goa/gen.go, cmd/goa/main.go) correctly generates code matching these golden files. This is critical since goa's value proposition is design-first code generation—ensuring generated code quality prevents drift.

• [ ] Review cmd/goa/main_test.go to understand existing test patterns
• [ ] Create codegen/example/integration_test.go that exercises the CLI with sample DSL definitions from codegen/example/testdata/dsls.go
• [ ] Implement assertions comparing generated output against corresponding .golden files in codegen/example/testdata/
• [ ] Add test cases for both HTTP and gRPC code generation paths
• [ ] Document test patterns in CONTRIBUTING.md for future maintainers

Add missing unit tests for codegen/cli template rendering functions

The codegen/cli package contains template files (build_payload.go.tpl, parse_flags.go.tpl, etc.) and a templates.go file, but there's no visible *_test.go file in codegen/cli/. These templates are critical for CLI code generation quality and should have dedicated tests covering edge cases like flag parsing, payload building, and usage generation.

• [ ] Create codegen/cli/cli_test.go with test cases for each template rendering function
• [ ] Add table-driven tests for parse_flags template with various flag combinations (required, optional, variadic)
• [ ] Add tests for build_payload template with different payload types (simple types, nested objects, arrays)
• [ ] Test command_usage and usage_examples templates with services having various method signatures
• [ ] Ensure tests verify proper escaping and formatting in generated CLI code

Add GitHub Actions workflow for testing generated example code compilation

While .github/workflows/test.yml exists, there's no visible workflow that actually compiles and runs the example code generated by the code generator against the golden files. This prevents catching breaking changes in code generation that would cause compilation failures for end users.

• [ ] Create .github/workflows/codegen-examples.yml that runs on pull requests
• [ ] Add job to generate code from codegen/example/testdata/dsls.go using the in-development goa CLI
• [ ] Compare generated output against .golden files using diff or similar
• [ ] Add a second job that attempts to compile the generated example servers and clients to catch syntax errors
• [ ] Configure workflow to fail if generated code doesn't match golden files or fails compilation
• [ ] Document in CONTRIBUTING.md how developers can run these checks locally before submitting PRs

• Add integration tests in codegen/example/ that verify generated gRPC and HTTP servers actually handle requests correctly end-to-end (template logic is tested indirectly via examples, but direct handler tests are minimal)
• Document the dsl/ package API with examples showing how to define complex types, error responses, and middleware in design files (README.md mentions DSL but doesn't link to comprehensive examples)
• Add support for generating client-side validation (codegen/ has server-side generators, but client-side field validation tests/examples in codegen/example/ are sparse)

The Goa framework codebase demonstrates reasonable security practices with automated dependency management and CI/CD workflows. However, the primary concern is the extensive use of code generation templates without visible input sanitization mechanisms. The code generation pipeline processes user DSL inputs and outputs executable Go code, which presents an attack surface if inputs are not properly validated. The absence of an explicit security policy and reliance on automated dependency merging without strong review controls are secondary concerns. No hardcoded secrets, obvious injection vulnerabilities, or Docker misconfigurations were detected in the visible file structure. Security score reflects the code generation risk as the main vulnerability area.

• Medium · Potential Code Generation Security Risk — codegen/ directory, especially codegen/cli/templates/, codegen/example/templates/. The codebase extensively uses template-based code generation (codegen/) with templates containing Go code. Template injection or improper input validation during code generation could lead to generation of malicious code. The templates in codegen/*/templates/ directories are processed and output as Go code without apparent sanitization visible in the file structure. Fix: Implement strict input validation for all DSL inputs before template processing. Use parameterized template rendering and avoid direct string interpolation. Validate all user-provided data used in code generation.
• Low · Missing Explicit Security Policy — Repository root. No visible SECURITY.md or security policy file in the repository root. While CONTRIBUTING.md exists, there's no explicit vulnerability disclosure policy documented. Fix: Create a SECURITY.md file with clear vulnerability reporting guidelines and responsible disclosure policy. Include contact information and expected response times.
• Low · Dependency Management Automation — .github/workflows/dependabot-weekly-automerge.yml, .github/dependabot.yml. While the repository has dependabot configuration (.github/dependabot.yml), the dependabot-weekly-automerge workflow suggests automated dependency updates are being merged. This could introduce breaking changes or security regressions without proper review. Fix: Ensure automated dependency merges only apply to patch versions and security updates. Require manual review for minor and major version updates. Implement additional CI checks and security scanning before automerge.
• Low · GoLangCI Configuration Visibility — .golangci.yml. The .golangci.yml configuration file is present but its contents are not provided. Security-relevant linters (gosec, gas) may not be properly configured or enabled. Fix: Ensure .golangci.yml explicitly enables security-focused linters including gosec/gas for detecting common Go security issues. Review configuration regularly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.