go-surgeon: Scaffold Skill

You are working in a Go project that has go-surgeon scaffolding templates available. Before creating files manually, ALWAYS check if a template exists that can do it better.

The scaffold system is a workflow engine — not just a file generator. Templates emit contextual hints (task lists) that tell you exactly what to do next. You MUST read and follow these hints.

Pre-flight

# Check if templates exist
go-surgeon scaffold list-templates

# If no templates found, .surgeon-templates/ doesn't exist yet — skip scaffolding

1. Discovering Templates

List all available templates

go-surgeon scaffold list-templates

Returns all templates with their names, descriptions, and available commands.

Read documentation for a template

# All commands in a template
go-surgeon scaffold doc <template_name>

# Specific command (shows required variables, files generated, hints)
go-surgeon scaffold doc <template_name> <command_name>

Always read the doc before executing. It tells you:

• What variables are required (--set Key=Value)
• What files will be created
• What post_commands will chain automatically
• What hints will be emitted

2. Executing Scaffolding

go-surgeon scaffold execute <template> <command> --set Key=Value [--set Key2=Value2 ...]

Example workflow

# Step 1: Read what bootstrap does
go-surgeon scaffold doc hexagonal bootstrap

# Step 2: Execute with required variables
go-surgeon scaffold execute hexagonal bootstrap \
  --set AppName=catalog \
  --set ModulePath=github.com/myorg/myapp

What happens during execution

1. Pre-flight check: All destination files are checked. If ANY already exists, the entire execution aborts — no partial writes.
2. File generation: Template files are rendered with Go text/template syntax and your variables.
3. Post-command chaining: If the command has post_commands, they execute automatically in sequence. Variables are forwarded. Diamond dependencies are deduplicated (a command never runs twice in the same chain).
4. Go formatting: All generated .go files are formatted with goimports automatically.
5. Hints: After all files are created, hints are printed. READ THEM.

3. Following Hints — THIS IS CRITICAL

After every scaffold execution, hints are printed to the console. They look like:

--- bootstrap ---
Project bootstrapped. The following commands were executed in sequence.

--- add_main ---
Main created at cmd/catalog/main.go.

--- add_domain ---
Domain layer initialized at internal/catalog/domain/.
You MUST now:
1. Define your domain entities using `go-surgeon add-struct`
2. Create repositories using: go-surgeon scaffold execute hexagonal add_repository --set AppName=catalog --set EntityName=Book
3. Wire the application in cmd/catalog/main.go

You MUST follow these hints step by step. They are the template author's designed workflow. Do not improvise a different approach.

When a hint tells you to run another scaffold command, run it. When it tells you to use go-surgeon add-struct or go-surgeon update-func, switch to using those commands (see the go-surgeon-edit skill).

4. Template Variables

Variables are passed via --set Key=Value flags. They're available in templates as {{ .Key }}.

Available template functions

• {{ .AppName | lower }} — lowercase
• {{ .AppName | upper }} — UPPERCASE
• {{ .AppName | title }} — Title Case

Variables are used in:

• File content (.tmpl files)
• Destination paths (e.g., cmd/{{ .AppName }}/main.go)
• Hints (e.g., "Domain layer at internal/{{ .AppName }}/domain/")

5. Creating Your Own Templates

If no template exists for what the user wants, and they'd benefit from a reusable pattern, you can create one.

Templates live in .surgeon-templates/<name>/manifest.yaml:

name: hexagonal
description: |
  Hexagonal architecture template for Go services.

commands:
  - command: bootstrap
    description: Bootstraps a complete hexagonal project structure
    variables:
      - key: AppName
        description: folder name for the main app
      - key: ModulePath
        description: Go module path
    files:
      - source: .gitignore.tmpl
        destination: .gitignore
      - source: Makefile.tmpl
        destination: Makefile
    post_commands:
      - add_main
    hint: |
      Project bootstrapped successfully.

  - command: add_main
    description: Creates the main.go entrypoint
    variables:
      - key: AppName
        description: folder name for the main app
    files:
      - source: cmd/appname/main.go.tmpl
        destination: cmd/{{ .AppName }}/main.go
    hint: |
      Main created at cmd/{{ .AppName }}/main.go.
      Next: define domain entities and repositories.

Best practices for templates

1. Granular commands: Break into small commands (add_repository, add_usecase, add_http_handler) rather than one massive generator.
2. Actionable hints: Print task lists that guide step-by-step. LLMs read and execute these iteratively.
3. Chain with `post_commands`: Use workflow chaining so bootstrap → add_main → add_domain runs in one shot.
4. Safety: Pre-flight check prevents overwriting existing files. Always safe to run.
5. Variables in paths: Use {{ .EntityName | lower }} in destination paths for dynamic directory creation.
6. Empty files: Omit source to create an empty file (useful for .gitkeep or placeholder packages).

Template file structure

.surgeon-templates/
└── hexagonal/
    ├── manifest.yaml
    ├── .gitignore.tmpl
    ├── Makefile.tmpl
    └── cmd/
        └── appname/
            └── main.go.tmpl

Template files use Go text/template syntax:

// main.go.tmpl
package main

func main() {
    app := {{ .AppName | lower }}.NewApp()
    app.Run()
}

6. Workflow Decision Tree

When the user asks to create something in a Go project:

1. Is go-surgeon available?
   NO  → Fall back to manual file creation
   YES → Continue

2. Does the task involve creating multiple related files / architectural layers?
   NO  → Use go-surgeon edit commands directly (add-func, add-struct, etc.)
   YES → Continue

3. Run: go-surgeon scaffold list-templates
   Templates exist?
   NO  → Either create a template (if reusable) or use edit commands
   YES → Continue

4. Read: go-surgeon scaffold doc <template> <command>
   Command matches the need?
   YES → Execute it and follow hints
   NO  → Use edit commands or create a new template command

7. Common Patterns

Bootstrap a new service

go-surgeon scaffold doc hexagonal bootstrap
go-surgeon scaffold execute hexagonal bootstrap --set AppName=catalog --set ModulePath=github.com/myorg/catalog
# → Follow hints to add entities, repos, handlers

Add a new domain entity

go-surgeon scaffold doc hexagonal add_entity
go-surgeon scaffold execute hexagonal add_entity --set AppName=catalog --set EntityName=Book
# → Follow hints to define fields, create repository, wire in app

Add a repository

go-surgeon scaffold doc hexagonal add_repository
go-surgeon scaffold execute hexagonal add_repository --set AppName=catalog --set EntityName=Book
# → Follow hints to implement the adapter

Chain: the hints drive you

Each scaffold execution produces hints → you follow them → some hints say to run another scaffold → you run it → it produces more hints → repeat until the architecture is complete.

This is the power of the scaffold workflow engine: the template author designs the entire build sequence, and you just follow the hints.