Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .agents/skills/surla-ux-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,10 @@ Use the person's own task and participant profile when they give them.
Otherwise use the defaults:

- **Task:** build an agentic platform that lets end users buy and sell houses.
- **Participant profile:** a software developer who is comfortable with Go
and the command line and uses coding agents daily, but has never used
- **Participant profile:** an impatient, product-minded software developer who
uses coding agents daily, skims just enough of a README to get moving,
dislikes boilerplate setup questions or upfront checklists before seeing a
proposal, is comfortable with Go and the command line, and has never used
Surla, Goa, or Goa-AI.

## 1. Set up the run
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,13 @@ You are taking part in a usability study of a developer tool called
Think aloud. Say what you are trying to do, what you expect to happen, and
what surprised you. Do not hide confusion or make the tool look better than
it was. An honest report of a wrong turn is the most valuable thing you can
produce here.
produce here. Start the way an impatient real user does: skim only enough to
begin, invoke `/surla` (`$surla`) alone or with a short one-sentence summary
of what you want to build rather than pasting a full specification up front,
and call out in `THINKING` whenever Surla or its guide asks you to supply
plumbing details the tool could derive (such as Go module paths or folder
names) or conducts a chat interview instead of putting structured options on
the browser page.

Send a step report when any of these happens:

Expand Down
7 changes: 6 additions & 1 deletion .agents/skills/surla-ux-review/references/tester-brief.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,12 @@ one gets the step where it happened, what the participant did or said
- **Bug:** Surla behaves differently from its docs, or crashes.
- **Usability issue:** Surla works as documented, but the participant
misread it, hesitated, or took a wrong action because the interface,
output, or docs were unclear.
output, or docs were unclear—or Surla or its guide imposed unnecessary
user toil or upfront questioning (for example, asking the user for
derivable plumbing such as a Go module path or folder name, or conducting
a multi-question chat interview before proposing options on the Change
Card), even if documented and even if the participant complied without
hesitating.
- **Documentation gap:** the participant needed something the README does
not say or only links to.
- **Missing capability:** the participant needed a step to initialize,
Expand Down
13 changes: 8 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,11 +247,14 @@ were handed over, or to a model gateway; see
## Start a project

Open an existing project or an empty folder in your coding agent and invoke
`/surla` (`$surla` in Codex). Tell the guide the service you want and its Go
module path, for example `example.com/shop`. In an empty folder, the guide
calls [`init_project`](docs/REFERENCE.md#init_project) with `dir: "."` to
create the starter and its first Git commit in place. Agent configuration
folders can stay; the operation refuses conflicting project files.
`/surla` (`$surla` in Codex). Describe what you want to build (if you invoke
`/surla` alone, the guide opens the page and asks what you would like to
build). In an empty folder, the guide calls
[`init_project`](docs/REFERENCE.md#init_project) with `dir: "."` to create the
starter and its first Git commit in place, deriving a default Go module path
from the folder name unless you specify one. Open product questions go onto the
Change Card for you to answer on the page. Agent configuration folders can
stay; the operation refuses conflicting project files.

The starter has a Goa and Goa-AI service, architecture diagrams declared with
[Model](https://github.com/goadesign/model), a first Story in
Expand Down
3 changes: 2 additions & 1 deletion cmd/surla/check_journey_e2e_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,8 @@ func TestCheckProjectRepairsDependenciesOnOneServer(t *testing.T) {
ConfirmIntentEndpoint: userTransport.ConfirmIntent(), StartBuildEndpoint: userTransport.StartBuild(),
}

args, err := gensurla.EncodeInitProjectPayload(&gensurla.InitProjectPayload{ModulePath: "example.com/shop"})
shopModule := "example.com/shop"
args, err := gensurla.EncodeInitProjectPayload(&gensurla.InitProjectPayload{ModulePath: &shopModule})
require.NoError(t, err)
initialized, err := gensurla.DecodeInitProjectResult(journeyCall(t, client, "init_project", args, journeyCallTimeout))
require.NoError(t, err)
Expand Down
3 changes: 2 additions & 1 deletion cmd/surla/gen_e2e_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -112,8 +112,9 @@ func TestGenOnAFreshStarterChangesNothingAndKeepsModulesApart(t *testing.T) {
&bearerDoer{client: srv.Client(), token: "test-token"},
goahttp.RequestEncoder, goahttp.ResponseDecoder, false)
client := &genmcpsurla.Client{ToolsCallEndpoint: transport.ToolsCall()}
shopModule := "example.com/shop"
args, err := gensurla.EncodeInitProjectPayload(&gensurla.InitProjectPayload{
ModulePath: "example.com/shop",
ModulePath: &shopModule,
})
require.NoError(t, err)
call := &genmcpsurla.ToolsCallPayload{Name: "init_project", Arguments: args}
Expand Down
11 changes: 5 additions & 6 deletions design/design.go
Original file line number Diff line number Diff line change
Expand Up @@ -78,15 +78,14 @@ var DeclineRevisionPayload = Type("DeclineRevisionPayload", func() {

// InitProjectPayload is the input to the init_project tool.
var InitProjectPayload = Type("InitProjectPayload", func() {
Description("Go module path and optional directory for initializing a new Surla starter project in the bound workspace.")
Attribute("module_path", String, "Go module path of the new service (for example example.com/shop).", func() {
Description("Optional Go module path and directory for initializing a new Surla starter project in the bound workspace.")
Attribute("module_path", String, "Optional Go module path of the new service (for example example.com/shop). Omit unless the user gave one: Surla derives example.com/<service> from the target folder name.", func() {
MinLength(3)
Example("example.com/shop")
})
Attribute("dir", String, "Use a direct child name, or . to initialize the bound workspace itself while preserving allowed agent configuration. When omitted or empty, defaults to the service name derived from module_path.", func() {
Example("shop")
Attribute("dir", String, "Use . to initialize the bound workspace itself while preserving allowed agent configuration, or pass a direct child name. When omitted or empty, defaults to . when module_path is omitted, or to the service name derived from module_path when module_path is given.", func() {
Example(".")
})
Required("module_path")
})

// InitProjectResult is the output of the init_project tool.
Expand Down Expand Up @@ -1065,7 +1064,7 @@ var _ = Service("surla", func() {
Error("conflict", ErrorResult, "The workspace or target directory is already initialized.")
Error("unprocessable", ErrorResult, "The module path or child directory name is invalid.")
Error("not_implemented", ErrorResult, "This control plane has no exact Surla module version configured for starter generation.")
Tool("init_project", "Initialize a new Surla starter project inside the bound workspace directory, create its initial Git commit, and switch the server's active workspace to that project. Returns the created commit ID in commit for start_live_target and verify_change.")
Tool("init_project", "Initialize a new Surla starter project inside the bound workspace directory, create its initial Git commit, and switch the server's active workspace to that project. Pass dir: \".\" and omit module_path to initialize an empty project folder in place with a module path derived from the folder name (pass module_path only when the user gave one). Returns the created commit ID in commit for start_live_target and verify_change.")
HTTP(func() {
POST("/workspace/init")
Response(StatusOK)
Expand Down
16 changes: 11 additions & 5 deletions docs/HOW_IT_WORKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,9 +117,13 @@ session if it has not discovered the integration yet.
Open your project folder in the agent and invoke `/surla` (`$surla` in
Codex). Its first Surla tool call starts or attaches to the server for that
physical folder and attaches the current session as the guide. Discovery
alone starts no server. If the folder is empty, the guide can call
alone starts no server. If you invoke `/surla` without a request yet, the
guide opens the page and asks what you would like to build. Once you state a
goal in an empty folder, the guide can call
[`init_project`](REFERENCE.md#init_project) with `dir: "."` to create the
starter and its first Git commit in place.
starter and its first Git commit in place, deriving a default Go module path
from the folder name unless you gave one, and puts open product questions on
the Change Card rather than asking a checklist in chat.

In Herdr, when the client forwards its terminal identity, Surla can adopt the
guide's existing local pane and space if their project and team labels are
Expand Down Expand Up @@ -190,10 +194,12 @@ manager approves it."
guide adds your flows to `design/story.go` in `.surla-draft`.
- In a folder with no service, the guide first creates the starter
project with [`init_project`](REFERENCE.md#init_project). It can pass
`dir: "."` to put the service, Story, test module in `eval/` and first
`dir: "."` (and omit `module_path`, so Surla derives one from the folder
name) to put the service, Story, test module in `eval/` and first
commit into the existing folder while preserving supported agent
configuration. Omitting `dir` creates a child folder named for the
service and makes it the server's active workspace.
configuration. Omitting `dir` when `module_path` is given creates a child
folder named for the service and makes it the server's active workspace;
omitting both initializes `.` in place.
- In a project made another way, the design can import the Story language
only when the draft's `go.mod` requires its module. When it does not,
the failed evaluation names the step: “`In the folder that holds that
Expand Down
27 changes: 18 additions & 9 deletions docs/REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -1159,22 +1159,31 @@ and session credential stay with the server and browser.

#### `init_project`

`POST /workspace/init`. **Input:** `module_path`, `dir?`. **Output:**
`POST /workspace/init`. **Input:** `module_path?`, `dir?`. **Output:**
`InitProjectResult` (`dir`, `module_path`, `service_name`, `commit`).

Creates the [`surla init`](#surla-init) starter and runs `go mod tidy`,
`go vet ./...` and `go test ./...` in both modules. The server saves
`Initial scaffold` with its Git identity and makes the starter its active
workspace. With an MCP `progressToken`, the server reports each phase.

Omit `dir` or pass an empty string to create a child folder named for the
service. A named child must match `^[a-zA-Z0-9][a-zA-Z0-9._-]*$` and cannot
start with `.surla`. Pass `dir: "."` to initialize the bound folder in
place. It may already contain `.claude`, `.codex`, `.cursor`, `.gemini`,
`.agents`, `.vscode`, `.mcp.json` or `.DS_Store`. Surla preserves those
entries and refuses other existing entries or collisions with generated
files in this mode. It publishes the checked starter with `.git` last and
resumes interrupted publication on restart.
Omit `module_path` to derive `example.com/<service>` from the target folder's
name (lowercased ASCII letters and non-leading digits up to 48 characters,
appending `svc`—clamped to 48 characters—for `main`, a Go keyword, a `vN`
module-version suffix or a reserved module path name, and falling back to
`example.com/app` when the name has no ASCII letter). When supplied,
`module_path` must be at least three characters (`400` when shorter) and end in
a valid service name.

Pass `dir: "."` (or omit both `module_path` and `dir`) to initialize the bound
folder in place. When `module_path` is given and `dir` is omitted or empty,
Surla creates a child folder named for the service. A named child must match
`^[a-zA-Z0-9][a-zA-Z0-9._-]*$` and cannot start with `.surla`. In-place mode
may already contain `.claude`, `.codex`, `.cursor`, `.gemini`, `.agents`,
`.vscode`, `.mcp.json` or `.DS_Store`. Surla preserves those entries and
refuses other existing entries or collisions with generated files in this mode.
It publishes the checked starter with `.git` last and resumes interrupted
publication on restart.

| Refusal | When |
| --- | --- |
Expand Down
2 changes: 1 addition & 1 deletion gen/http/cli/surla/cli.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion gen/http/openapi.json

Large diffs are not rendered by default.

12 changes: 4 additions & 8 deletions gen/http/openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3102,8 +3102,6 @@ paths:
required: true
schema:
$ref: '#/definitions/InitProjectPayload'
required:
- module_path
responses:
"200":
description: OK response.
Expand Down Expand Up @@ -7803,18 +7801,16 @@ definitions:
properties:
dir:
type: string
description: Use a direct child name, or . to initialize the bound workspace itself while preserving allowed agent configuration. When omitted or empty, defaults to the service name derived from module_path.
example: shop
description: Use . to initialize the bound workspace itself while preserving allowed agent configuration, or pass a direct child name. When omitted or empty, defaults to . when module_path is omitted, or to the service name derived from module_path when module_path is given.
example: .
module_path:
type: string
description: Go module path of the new service (for example example.com/shop).
description: 'Optional Go module path of the new service (for example example.com/shop). Omit unless the user gave one: Surla derives example.com/<service> from the target folder name.'
example: example.com/shop
minLength: 3
example:
dir: shop
dir: .
module_path: example.com/shop
required:
- module_path
InitProjectResult:
title: InitProjectResult
type: object
Expand Down
2 changes: 1 addition & 1 deletion gen/http/openapi3.2.json

Large diffs are not rendered by default.

12 changes: 5 additions & 7 deletions gen/http/openapi3.2.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -16462,7 +16462,7 @@ paths:
schema:
$ref: '#/components/schemas/InitProjectPayload'
example:
dir: shop
dir: .
module_path: example.com/shop
responses:
"200":
Expand Down Expand Up @@ -23058,19 +23058,17 @@ components:
properties:
dir:
type: string
description: Use a direct child name, or . to initialize the bound workspace itself while preserving allowed agent configuration. When omitted or empty, defaults to the service name derived from module_path.
example: shop
description: Use . to initialize the bound workspace itself while preserving allowed agent configuration, or pass a direct child name. When omitted or empty, defaults to . when module_path is omitted, or to the service name derived from module_path when module_path is given.
example: .
module_path:
type: string
description: Go module path of the new service (for example example.com/shop).
description: 'Optional Go module path of the new service (for example example.com/shop). Omit unless the user gave one: Surla derives example.com/<service> from the target folder name.'
example: example.com/shop
minLength: 3
description: Request body for init_project.
example:
dir: shop
dir: .
module_path: example.com/shop
required:
- module_path
InitProjectResult:
type: object
properties:
Expand Down
2 changes: 1 addition & 1 deletion gen/http/openapi3.json

Large diffs are not rendered by default.

12 changes: 5 additions & 7 deletions gen/http/openapi3.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -16461,7 +16461,7 @@ paths:
schema:
$ref: '#/components/schemas/InitProjectPayload'
example:
dir: shop
dir: .
module_path: example.com/shop
responses:
"200":
Expand Down Expand Up @@ -23052,19 +23052,17 @@ components:
properties:
dir:
type: string
description: Use a direct child name, or . to initialize the bound workspace itself while preserving allowed agent configuration. When omitted or empty, defaults to the service name derived from module_path.
example: shop
description: Use . to initialize the bound workspace itself while preserving allowed agent configuration, or pass a direct child name. When omitted or empty, defaults to . when module_path is omitted, or to the service name derived from module_path when module_path is given.
example: .
module_path:
type: string
description: Go module path of the new service (for example example.com/shop).
description: 'Optional Go module path of the new service (for example example.com/shop). Omit unless the user gave one: Surla derives example.com/<service> from the target folder name.'
example: example.com/shop
minLength: 3
description: Request body for init_project.
example:
dir: shop
dir: .
module_path: example.com/shop
required:
- module_path
InitProjectResult:
type: object
properties:
Expand Down
8 changes: 1 addition & 7 deletions gen/http/surla/client/cli.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 8 additions & 5 deletions gen/http/surla/client/types.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading