Skip to content

nicolasfmelo/masa-skill

masa-framework

Verified

Apply the MASA (Modular Agentic Semantic Architecture) framework when writing, reviewing, or refactoring code. Use when implementing features, reviewing architecture, checking layer compliance, or setting up a new project in Python, JavaScript/TypeScript, or Go.

references/languages/go.md

View on GitHub
# MASA in Go — Language-Specific Guide

## Project Layout

Go's package system maps naturally to MASA layers. Each layer is a Go package
(or package group) with an explicit public API.

```
internal/
├── domain/
│   ├── order/
│   │   ├── order.go          # Order struct, OrderStatus type
│   │   └── id.go             # OrderID type
│   └── errors/
│       └── errors.go         # OrderNotFoundError, StorageUnavailableError, …
├── engines/
│   └── ordercalc/
│       └── calculator.go     # CalculateTotal(), ApplyDiscount()
├── services/
│   └── orderservice/
│       ├── service.go        # OrderService struct + methods
│       └── ports.go          # Repository and EmailClient interfaces
├── integrations/
│   ├── database/
│   │   └── orderrepo/
│   │       ├── repo.go       # OrderRepository implementation (PostgreSQL)
│   │       └── mapping.go    # rowToOrder(), orderToRow()
│   └── externalapis/
│       └── emailclient/
│           └── client.go     # EmailClient implementation (SMTP / SendGrid)
└── delivery/
    ├── http/
    │   └── orderhandler/
    │       └── handler.go    # HTTP handler (net/http or Gin)
    └── schemas/
        └── orderschemas/
            ├── request.go    # CreateOrderRequest + ToDomain()
            └── response.go   # CreateOrderResponse + FromDomain()
```

**Package naming rule:** Short, lowercase, domain nouns — `order`, `ordercalc`,
`orderservice`, `orderrepo`. Never `ordercontroller`, `orderhelper`, `orderutil`.

---

## Domain Models

Go structs are naturally immutable when fields are unexported or the struct is
copied on return. Use exported fields for domain models (agents can read them),
but define constructors to enforce invariants.

```go
// internal/domain/order/id.go
package order

import "github.com/google/uuid"

// OrderID is a distinct type — not interchangeable with plain string or uuid.UUID
type OrderID uuid.UUID

func NewOrderID() OrderID {
    return OrderID(uuid.New())
}

func ParseOrderID(s string) (OrderID, error) {
    u, err := uuid.Parse(s)
    if err != nil {
        return OrderID{}, err
    }
    return OrderID(u), nil
}

func (id OrderID) String() string {
    return uuid.UUID(id).String()
}


// internal/domain/order/order.go
package order

type Status string

const (
    StatusPending   Status = "pending"
    StatusConfirmed Status = "confirmed"
    StatusShipped   Status = "shipped"
    StatusCancelled Status = "cancelled"
)

type Order struct {
    ID           OrderID
    CustomerID   CustomerID
    ItemsTotal   float64
    ShippingCost float64
    Status       Status
}


// internal/domain/errors/errors.go
package domainerrors

import "fmt"

type OrderNotFoundError struct {
    ID string
}

func (e *OrderNotFoundError) Error() string {
    return fmt.Sprintf("order %s not found", e.ID)
}

type StorageUnavailableError struct {
    Msg string
}

func (e *StorageUnavailableError) Error() string {
    return e.Msg
}

type DuplicateOrderError struct {
    ID string
}

func (e *DuplicateOrderError) Error() string {
    return fmt.Sprintf("order %s already exists", e.ID)
}
```

---

## Engines (Pure Functions)

Go functions with no pointer receivers on external state, no `io.Reader`/`http.Client`
params. If it's pure, it has no side effects and can be tested with zero setup.

```go
// internal/engines/ordercalc/calculator.go
package ordercalc

import "github.com/yourorg/masa/internal/domain/order"

// CalculateTotal is a pure function — no I/O, no state.
func CalculateTotal(o order.Order) float64 {
    return o.ItemsTotal + o.ShippingCost
}

// ApplyDiscount returns a new Order — original is unchanged (Go value copy).
func ApplyDiscount(o order.Order, discountPct float64) order.Order {
    discounted := o.ItemsTotal * (1 - discountPct/100)
    o.ItemsTotal = math.Round(discounted*100) / 100
    return o // copy returned, original not mutated
}
```

---

## Services — Ports (Interfaces) in the Service Package

In Go, interfaces are defined by the consumer, not the implementor. Define repository
and client interfaces in `services/orderservice/ports.go`. Implement them in
`integrations/`. This is idiomatic Go and maps directly to MASA's Static Dependency
Tracing rule.

```go
// internal/services/orderservice/ports.go
package orderservice

import "github.com/yourorg/masa/internal/domain/order"

// OrderRepository — implemented by integrations/database/orderrepo
type OrderRepository interface {
    Save(o order.Order) (order.Order, error)
    FindByID(id order.OrderID) (order.Order, error)
}

// EmailClient — implemented by integrations/externalapis/emailclient
type EmailClient interface {
    SendConfirmation(o order.Order) error
}


// internal/services/orderservice/service.go
package orderservice

import "github.com/yourorg/masa/internal/domain/order"

type OrderService struct {
    repo        OrderRepository
    emailClient EmailClient
}

// NewOrderService is the constructor — full dependency declaration in one function.
func NewOrderService(repo OrderRepository, emailClient EmailClient) *OrderService {
    return &OrderService{repo: repo, emailClient: emailClient}
}

func (s *OrderService) Create(o order.Order) (order.Order, error) {
    saved, err := s.repo.Save(o)
    if err != nil {
        return order.Order{}, err
    }
    if err := s.emailClient.SendConfirmation(saved); err != nil {
        // decide: fail or log? for now, log and continue
        return saved, nil
    }
    return saved, nil
}

func (s *OrderService) Get(id order.OrderID) (order.Order, error) {
    return s.repo.FindByID(id)
}
```

---

## Integrations — Repository Implementation

```go
// internal/integrations/database/orderrepo/repo.go
package orderrepo

import (
    "database/sql"
    "errors"

    "github.com/yourorg/masa/internal/domain/order"
    domainerrors "github.com/yourorg/masa/internal/domain/errors"
)

type orderRow struct {
    ID           string
    CustomerID   string
    ItemsTotal   float64
    ShippingCost float64
    Status       string
}

func rowToOrder(r orderRow) (order.Order, error) {
    id, err := order.ParseOrderID(r.ID)
    if err != nil {
        return order.Order{}, err
    }
    custID, err := order.ParseCustomerID(r.CustomerID)
    if err != nil {
        return order.Order{}, err
    }
    return order.Order{
        ID:           id,
        CustomerID:   custID,
        ItemsTotal:   r.ItemsTotal,
        ShippingCost: r.ShippingCost,
        Status:       order.Status(r.Status),
    }, nil
}

type OrderRepository struct {
    db *sql.DB
}

func New(db *sql.DB) *OrderRepository {
    return &OrderRepository{db: db}
}

func (r *OrderRepository) FindByID(id order.OrderID) (order.Order, error) {
    row := r.db.QueryRow(
        "SELECT id, customer_id, items_total, shipping_cost, status FROM orders WHERE id = $1",
        id.String(),
    )
    var or orderRow
    if err := row.Scan(&or.ID, &or.CustomerID, &or.ItemsTotal, &or.ShippingCost, &or.Status); err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return order.Order{}, &domainerrors.OrderNotFoundError{ID: id.String()}
        }
        return order.Order{}, &domainerrors.StorageUnavailableError{Msg: err.Error()}
    }
    return rowToOrder(or)
}

func (r *OrderRepository) Save(o order.Order) (order.Order, error) {
    _, err := r.db.Exec(
        "INSERT INTO orders (id, customer_id, items_total, shipping_cost, status) VALUES ($1,$2,$3,$4,$5)",
        o.ID.String(), o.CustomerID.String(), o.ItemsTotal, o.ShippingCost, string(o.Status),
    )
    if err != nil {
        return order.Order{}, &domainerrors.StorageUnavailableError{Msg: err.Error()}
    }
    return o, nil
}
```

---

## Delivery — net/http Handler

```go
// internal/delivery/schemas/orderschemas/request.go
package orderschemas

import (
    "encoding/json"
    "net/http"

    "github.com/yourorg/masa/internal/domain/order"
)

type CreateOrderRequest struct {
    CustomerID   string  `json:"customer_id"`
    ItemsTotal   float64 `json:"items_total"`
    ShippingCost float64 `json:"shipping_cost"`
}

func DecodeCreateOrder(r *http.Request) (CreateOrderRequest, error) {
    var req CreateOrderRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        return CreateOrderRequest{}, err
    }
    return req, nil
}

func (req CreateOrderRequest) ToDomain() (order.Order, error) {
    custID, err := order.ParseCustomerID(req.CustomerID)
    if err != nil {
        return order.Order{}, err
    }
    return order.Order{
        ID:           order.NewOrderID(),
        CustomerID:   custID,
        ItemsTotal:   req.ItemsTotal,
        ShippingCost: req.ShippingCost,
        Status:       order.StatusPending,
    }, nil
}


// internal/delivery/schemas/orderschemas/response.go
package orderschemas

import "github.com/yourorg/masa/internal/domain/order"

type CreateOrderResponse struct {
    ID     string `json:"id"`
    Status string `json:"status"`
}

func FromDomain(o order.Order) CreateOrderResponse {
    return CreateOrderResponse{ID: o.ID.String(), Status: string(o.Status)}
}


// internal/delivery/http/orderhandler/handler.go
package orderhandler

import (
    "encoding/json"
    "net/http"

    domainerrors "github.com/yourorg/masa/internal/domain/errors"
    "github.com/yourorg/masa/internal/delivery/schemas/orderschemas"
    "github.com/yourorg/masa/internal/services/orderservice"
)

type OrderHandler struct {
    service *orderservice.OrderService
}

func New(service *orderservice.OrderService) *OrderHandler {
    return &OrderHandler{service: service}
}

func (h *OrderHandler) Create(w http.ResponseWriter, r *http.Request) {
    // 1. Validate
    req, err := orderschemas.DecodeCreateOrder(r)
    if err != nil {
        http.Error(w, "invalid request body", http.StatusBadRequest)
        return
    }
    domainOrder, err := req.ToDomain()
    if err != nil {
        http.Error(w, "invalid fields", http.StatusBadRequest)
        return
    }
    // 2. Dispatch
    created, err := h.service.Create(domainOrder)
    if err != nil {
        handleDomainError(w, err)
        return
    }
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(orderschemas.FromDomain(created))
}

func handleDomainError(w http.ResponseWriter, err error) {
    var notFound *domainerrors.OrderNotFoundError
    if errors.As(err, &notFound) {
        http.Error(w, notFound.Error(), http.StatusNotFound)
        return
    }
    http.Error(w, "internal error", http.StatusInternalServerError)
}
```

---

## Wiring (main.go)

```go
// cmd/api/main.go
package main

import (
    "database/sql"
    "net/http"

    "github.com/yourorg/masa/internal/delivery/http/orderhandler"
    "github.com/yourorg/masa/internal/integrations/database/orderrepo"
    "github.com/yourorg/masa/internal/integrations/externalapis/emailclient"
    "github.com/yourorg/masa/internal/services/orderservice"
)

func main() {
    db, _ := sql.Open("postgres", "...")

    // Compose dependency graph explicitly — MASA Static Dependency Tracing
    repo    := orderrepo.New(db)
    email   := emailclient.New("smtp.example.com")
    service := orderservice.NewOrderService(repo, email)
    handler := orderhandler.New(service)

    mux := http.NewServeMux()
    mux.HandleFunc("POST /orders", handler.Create)
    http.ListenAndServe(":8080", mux)
}
```

The dependency graph is fully readable from `main.go` alone. No magic, no reflection.

---

## Tooling

### Layer boundary enforcement — depguard (golangci-lint)

```yaml
# .golangci.yml
linters-settings:
  depguard:
    rules:
      engines-cannot-import-integrations:
        files: ["**/engines/**/*.go"]
        deny:
          - pkg: "github.com/yourorg/masa/internal/integrations"
            desc: "engines must not import integrations"
      delivery-cannot-import-engines:
        files: ["**/delivery/**/*.go"]
        deny:
          - pkg: "github.com/yourorg/masa/internal/engines"
            desc: "delivery must access engines through services only"
```

### Testing layout

```
tests/
├── unit/
│   └── engines/        # table-driven pure function tests (zero setup)
└── integration/
    ├── repos/          # testcontainers-go for real PostgreSQL
    └── services/       # mock interfaces with testify/mock
```

### Interface mocking

```go
// Use mockery or testify/mock to generate mocks from service ports:
// go install github.com/vektra/mockery/v2@latest
// mockery --name=OrderRepository --dir=internal/services/orderservice --output=tests/mocks
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall