Getting Started

Getting Started

Prerequisites

• Go 1.23+
• golangci-lint
• Docker (for @integration tier with testcontainers-go)

---

Install the CLI

go install github.com/spannersync/gherkinforge/cmd/gforge@latest

Verify:

gforge --help

---

Clone and Run the Pilot Suite

git clone https://github.com/SpannerSync/gherkinforge.git
cd gherkinforge
go mod tidy
go test -race -count=1 -run TestFeatures ./tests/...

Expected output:

Feature: Order Management

  Scenario: Successfully creating an order emits a domain event   ... passed
  Scenario: Order creation fails when no items are provided        ... passed
  Scenario: Multi-item order total is mathematically verifiable    ... passed

3 scenarios (3 passed)
17 steps (17 passed)
--- PASS: TestFeatures

---

Lint Your Feature Files

gforge lint features/
# ✓ No violations found.

Lint checks:

1. Every .feature file has exactly one tier tag (@business, @integration, @nfr)
2. @business files use at least one DataTable or DocString
3. No forbidden implementation symbols in step text
4. No UI/DOM vocabulary in @business steps (Zero Trust Pillar 2)

---

Scaffold a New Bounded Context

gforge scaffold \
  --feature features/business/create_order.feature \
  --out pkg/context/shipment

Generates:

pkg/context/shipment/
├── domain/
│   ├── shipment.go     (aggregate root — int64 measurements)
│   └── ports.go        (repository + event interfaces)
├── usecases/
│   └── create_shipment.go
└── adapters/
    └── inmemory/
        └── repository.go

---

Full CI Pipeline

make ci
# runs: lint-go → lint-features → test