surla

README

Surla

An agentic software factory that builds, verifies, and evolves production services at a fraction of the token cost.

Solo coding agents—and most multi-agent "team" wrappers—still ask LLMs to hand-write every line of HTTP routing, auth middleware, workflow plumbing, and tests from scratch. That works on day one and collapses by feature three: the codebase drifts into an inconsistent maze that burns more tokens on every edit, and the agent writing the code writes tests that rubber-stamp its own bugs.

Surla pairs mixed-model agent teams (combining frontier reasoners and fast coding models across Claude, Codex, and Gemini) with a deterministic compiler stack. Because Goa generates transports, schemas, and validation at 0 LLM tokens, and Goa-AI provides built-in durable workflows, tool guardrails, and isolated evaluation, your agents only write compact contracts and pure domain logic, and a separate surla verify step checks the candidate build in an OS sandbox before you merge.

You: "Add a refund assistant to our orders service. Refunds up to $50 get
      instant store credit; anything larger waits for a manager."

Surla: Before I propose a build plan, two quick edge cases:
  1. Does "$50" mean item subtotal, or total including tax and shipping?
  2. What happens at exactly $50.00 — instant credit or manager approval?

You: "Total including tax and shipping, and $50.00 is instant."

Surla: Locked 5 acceptance checks, compiled design/orders.go (0 tokens),
       and proposed a team across model families & classes:
  • Architect (Claude Opus)     → API, auth & workflow contract
  • Builder (Claude Sonnet)     → Refund workflow & state store
  • Test Author (Gemini Pro)    → Isolated acceptance & crash suite
  • Reviewer (Codex)            → Adversarial security & code review

---

Why Engineers Use Surla

1. 0-token code generation—agents write the contract, the compiler writes the plumbing

Why pay an LLM to hallucinate 3,000 lines of HTTP handlers, gRPC stubs, OpenAPI specs, MCP schemas, and JSON validators? In Surla, the Architect agent expresses your API, agent tools, and security rules in a compact, strongly typed design (design/*.go). Goa deterministically generates the transports, OpenAPI specs, MCP schemas, and validators from that design with no model inference (0 LLM tokens)—eliminating entire classes of glue-code bugs and the token spend of writing them by hand.

2. A built-in Golden Path that stays cheap and effortless to evolve

Most AI-built codebases rot after a few weeks because every prompt invents a new folder structure, a new way to call LLMs, or a new auth pattern—forcing future agents to burn tens of thousands of tokens just reverse-engineering the repo. Surla enforces an embedded Golden Path architecture:

• Predictable layout & generated agent maps: Every service follows the same clean structure and ships an auto-generated AGENTS_QUICKSTART.md map, so any coding agent can jump in months later and extend the platform with minimal context tokens.
• Production patterns by default: One HTTP/MCP edge gateway, internal gRPC services, a central LLM gateway with rate limiting and cost tracking, durable Temporal workflows, and server-injected tenant_id/user_id fields that the LLM can never spoof.

3. Mixed-model teams where the builder never grades its own homework

When configured with provider profiles (-swarm-profiles) and explicit builder path scopes, Surla proposes a team that routes each role to the right model family and class—frontier reasoning models for architecture and security review, fast coding models for scoped implementation, and a disjoint model family for test authoring. Final verification (surla verify on the CLI, or verify_change, get_verification, and list_verifications over MCP when -project or -verification-config is configured; see docs/REFERENCE.md) is independent of the builder: it builds the candidate from its exact commit inside an OS sandbox (verify/candidate) and runs an evaluator suite the builder does not control, and the reference suite starts each candidate process in its own sandbox:

• Unseen holdout tests: Hidden scenarios verify security and edge cases while Report.ForBuilders() strips holdout names, inputs, and logs from the builder's view. For those scenarios to stay unseen, builders must not be able to read the evaluator suite or its report and work directories; share only the redacted builder report with them.
• Real kill -9 crash & budget proof: The included examples/orders-eval reference suite (surla verify or go test -race -tags e2e) kills the Temporal worker mid-transaction (kill -9), restarts the API during paused approvals, and fails any scenario whose runtime LLM token use exceeds its budget (TestSeededPayloadBloatFailsTheBudget proves it with a seeded payload bloat).

4. Fast draft overrides and live role-switched testing

Instead of reading a 2,000-line diff blindly, Surla separates fast prompt tuning from compiled business rules and ships stateful dependency simulators in examples/orders-eval:

• Test across real auth boundaries: In the reference platform, trigger a \$54.00 refund as a Customer, verify that customer credentials cannot approve it (403 Forbidden), and switch to Approving Manager to approve or decline the paused workflow through the real HTTP API.
• Iterate on prompts without rebuilding: Start surla serve with -project <dir> or -verification-config, then call start_live_target with a candidate commit: surla serve builds that commit the way verification does and runs it as a live target through the evaluator suite's --live mode. draft_override (POST /sandbox/draft) then sends new prompt wording to that running target, without rebuilding Go code (see the draft_override and start_live_target reference). A project created with surla init has an evaluator suite that supports --live; after its first commit, start surla serve from the project directory with a model (-model-provider and -model-name, or -model-gateway-addr) and -project ., which reads the starter layout and pins the evaluator suite to that HEAD commit at startup. Surla refuses any attempt to override compiled Go business rules (target_kind: "compiled_rule", requires_rebuild: true). A draft lasts only as long as the live target: to keep it, edit the text into source, commit, and run surla verify on that commit for the same request_revision. The in-repository examples/orders/cmd/orders-surla host instead binds Options.TargetUpdater to edit prompts on an already-running orders deployment.
• Interactive MCP Apps checkpoint viewer (ui://surla/checkpoint): An MCP Apps host loads the viewer through MCP resources/read (text/html;profile=mcp-app) and shows each tool result in it. For a Change Card, the viewer shows a form with every open question, example, and preserved behavior, saves through confirm_intent (recovering a newer saved card with get_change, preserving only changed draft answers and examples in #surla-preserved-draft alongside the #surla-prior-revision comparison when a card is revised via revise_change or confirm_intent), and—when approve_merge has recorded promotion approval via Options.PromotionTarget—renders the Checkpoint 5 current approval summary (approval) or recorded-unverified approval notice (unverified_approval, when promotion inputs cannot currently be checked) and warns if local draft edits would supersede the approved revision. When the CP1 model also composed a decision view, the viewer renders it with OpenUI components such as a policy simulator table, ambiguity choice cards, a workflow timeline, and impact callouts. Choices made there change the same draft the form submits, and the view is labeled as a model-proposed illustration. An invalid or stale composition leaves the full form usable. Across checkpoints, the viewer retains received session state and renders a session navigation bar plus in-view actions (View Saved Verifications, Load Change Card, and Return to Change Card) so you can move back and forth between the Change Card (CP1/CP5), session-only architecture previews (CP2), structural diffs, live-target and fast-draft results (CP3), and Checkpoint 4 verification runs (verify_change, get_verification, and list_verifications; see docs/REFERENCE.md) without losing unsaved CP1 edits. In CP4, the viewer loads saved runs for the active change_id, warns when a displayed run is not included in the last loaded list or when a CP2 preview or CP4 run applies to a different request_revision or change_id than the loaded card, and keeps raw IDs and digests in expandable Details. The planned role-switcher and replay controls are described in docs/HOW_IT_WORKS.md.

Why the name "Surla"? Named after Tambdi Surla in Goa—home to the carved basalt Mahadeva temple beside the Surla River. In Surla (SOOR-lah), design/*.go is that enduring stone contract: one compiled specification every coding agent builds to, and an independent verifier checks against.

---

Try It in 60 Seconds

1. Inspect, Diff, or Scaffold a Goa-AI Project Locally (0 API Keys Needed)

Surla requires macOS (sandbox-exec isolates candidate builds and processes) and Go 1.27.3+. Before configuring an LLM key or starting a server, install the surla CLI to scaffold and preview a new starter service from anywhere (surla init and surla gen generate code, and surla preview evaluates designs, in Surla's sandbox, so no separate global goa install is needed):

# Install the Surla CLI (embeds the published module version for surla init):
go install github.com/goadesign/surla/cmd/surla@latest

# Scaffold a new Goa + Goa-AI + Model starter service and visible eval/ suite:
surla init -dir /tmp/shop -module example.com/shop

# Compile /tmp/shop/design/*.go in an OS sandbox at 0 LLM tokens and print
# its C4 containers, boundary edges, agent policies, and tool guardrails:
surla preview -dir /tmp/shop

# List all commands and flags:
surla help

Or clone this repository to inspect and diff the included examples/orders reference platform (from a checkout, you can run either the installed surla binary or go run ./cmd/surla; when running go run ./cmd/surla init from a checkout, pass -surla-version v0.0.0-20261104215521-580509970fb6):

git clone https://github.com/goadesign/surla.git
cd surla

# Preview the Orders reference platform's C4 architecture and tool guardrails at 0 LLM tokens:
surla preview -dir examples/orders

# Compare two Goa design modules structurally at 0 LLM tokens:
surla diff --old-dir examples/orders --new-dir examples/orders

After you edit a module's design/, surla gen -dir <module> regenerates its gen/ inside the same sandbox and swaps it in atomically. It needs the module to use goa.design/goa/v3 v3.35.1-0.20261103205041-35e789e8f9b1 or later, and doesn't yet support gRPC designs; see surla gen.

2. Connect Your Coding Agent to the Surla Control Plane (surla serve)

Surla organizes development around five checkpoints (CP1 Confirm Intent → CP2 Preview Architecture → CP3 Fast Draft & Sandbox → CP4 Isolated Verification → CP5 Promotion Check; see docs/HOW_IT_WORKS.md). From the surla repository checkout, start the standalone Surla control plane and connect your coding assistant over MCP to propose, confirm, and preview a feature change at CP1 and CP2 (surla serve saves Change Cards in -cards-dir, default .surla/cards, so confirmed cards survive restarts; add -project <dir> or -verification-config to enable CP4 verify_change, get_verification, and list_verifications over MCP, and add -promotion-config to bind the CP5 staged-release PromotionTarget for approve_merge; surla serve applies CP3 prompt drafts to a live target started with start_live_target when -project or -verification-config is set, and the CLI verification walkthrough covers standalone surla verify and surla approve):

# Start the Surla MCP & HTTP control plane with CP1 model analysis and multi-family swarm profiles
export SURLA_AUTH_TOKEN="dev-secret-token"
export ANTHROPIC_API_KEY="sk-ant-..."
surla serve \
  -addr 127.0.0.1:8090 \
  -principal operator@example.com \
  -model-provider anthropic \
  -model-name claude-opus-4-6 \
  -swarm-profiles ./examples/orders/swarm-profiles.example.json

Register http://127.0.0.1:8090/mcp in your coding agent. For Claude Code, save this as .mcp.json; Claude Code fills in ${SURLA_AUTH_TOKEN} from the environment it starts in:

{
  "mcpServers": {
    "surla": {
      "type": "http",
      "url": "http://127.0.0.1:8090/mcp",
      "headers": {"Authorization": "Bearer ${SURLA_AUTH_TOKEN}"}
    }
  }
}

Other clients use the client-specific configuration in Register Surla in Your MCP Client (docs/REFERENCE.md) (covering Cursor .cursor/mcp.json, Gemini CLI .gemini/settings.json with httpUrl, and Codex .codex/config.toml; see also Terminology at a Glance and -swarm-profiles configuration—examples/orders/swarm-profiles.example.json is an illustrative operator-edited profile file where "authenticated": true is an operator assertion rather than a live credential check, and setting ANTHROPIC_API_KEY for CP1 analysis does not authenticate the OpenAI or Google coding-agent CLIs).

For a project that already has a design, ask your agent to send its design/*.go files as design_source, so the analysis considers them; without it, propose_change receives no current design.

Then prompt your agent:

"Using Surla, propose a change to examples/orders so VIP customers get instant store-credit refunds up to $150, then preview the compiled C4 architecture and Chorus swarm plan for builder scope orders (internal/**)."

Your agent will create the Change Card (propose_change, using revise_change when requirements evolve on the same change_id and calling confirm_intent to answer open ambiguity questions or refine confirmed answers and examples, which returns the card's change_id and locks a SHA-256 request_revision fingerprint), compile the candidate Goa contract at 0 LLM tokens (preview_architecture over MCP, or surla preview-change from the local module directory so the agent never has to copy go.mod, go.sum, and design/*.go into tool arguments), and return the updated C4 topology, tool guardrails, and—when explicit builder scopes are supplied—a proposed cross-family Chorus roster (@builder-orders and @reviewer when builders are supplied, plus @architect when architect_paths / -architect-path are supplied and @eval-author when eval_paths / -eval-path are supplied). The preview proposes the Chorus coordination roster; it does not launch agents. From a shell, pass the confirmed card's change_id and request_revision to surla preview-change (without -builders, the command returns a solo preview of the evaluated C4 architecture, agent policies, and tool contracts with swarm.status: "unconfigured" and no missing_roles; pass -builders <file.json> and optional repeatable -architect-path / -eval-path flags as shown in Configure the Proposed Swarm Roster (docs/REFERENCE.md) to include the proposed team assignments):

# Send the local module snapshot to CP2 for the confirmed Change Card's change_id and request_revision
# (returns the evaluated C4 architecture, agent policies, and tool contracts; add -builders to plan the team roster):
surla preview-change \
  -server http://127.0.0.1:8090 \
  -change-id vip-refunds \
  -request-revision "$REQUEST_REVISION" \
  -dir examples/orders

To run the full independent verification suite (surla verify and surla approve) and compare the full operator report with the builder-redacted -builder-view report (where unseen "holdout" acceptance tests are redacted to "id": "holdout-1"), see the Orders Reference Platform Walkthrough (examples/orders/README.md).

---

Dive Deeper

• Orders Reference Platform (examples/orders/README.md) — Walk through the Golden Path orders platform, run surla verify (full vs. -builder-view), and watch TestSeededPayloadBloatFailsTheBudget catch a token regression.
• How Surla Works (docs/HOW_IT_WORKS.md) — Walk through the 5 checkpoints (CP1–CP5), the proposed cross-model team, fast draft overrides, and OS-isolated verification.
• Golden Path Architecture (docs/ARCHITECTURE_PLAYBOOK.md) — Explore the 7 Golden Path rules that keep Surla platforms maintainable and see how the Goa Design suite powers them.
• CLI, MCP & Repo Reference (docs/REFERENCE.md) — Configure MCP clients (Claude Code, Cursor, Gemini CLI, and Codex), browse the MCP tools and CLI flags, and run the examples/orders reference suite.
• Architecture Proposal (PROPOSAL.md) & Product Vision (PRESS_RELEASE.md) — Read the full system design, threat model, and Working Backwards press release.

License

Surla is released under the MIT License.

Documentation

Overview

Package surla holds the go.mod Surla was built from, so code that needs Surla's own dependency versions reads them from the binary instead of looking for a go.mod on disk.

Index

• func GoMod() string

Functions

func GoMod

func GoMod() string

GoMod returns the go.mod Surla was built from. The design evaluator (internal/designeval) reads its go directive and the Goa, Goa-AI and Model versions it requires, as the Go version and generator versions for designs that do not require them. Because the file is compiled in, the result does not depend on the working directory or on a source checkout being present.