Contributing

Project Structure

Total: ~3,200 LOC of Go across a 5-layer architecture.

Build & Test

just recipes are canonical. Raw Go equivalents work but lack version ldflags and pre-commit ordering.

# Full pre-commit check (fmt → vet → test → build)
just check

# Individual recipes
just build       # build to ./bin/z2e-terminal with version ldflags
just fmt          # gofmt -w ./cmd ./internal
just vet          # go vet ./cmd/... ./internal/...
just test         # go test ./cmd/... ./internal/...

Note: gofmt scope is ./cmd ./internal, not ./....

Pre-commit Checklist

1. just fmt — Format code (gofmt -w ./cmd ./internal)
2. just vet — Static analysis
3. just test — Run tests
4. just build — Ensure compilation
5. just run — Manual smoke test

Code Style

• gofmt only — do not hand-align spacing
• Error handling: early returns, wrap errors with %w
• Prefer typed structs over map[string]any for internal logic
• Use JSON tags only on serialized payloads
• Bubble Tea: Model struct with Init(), Update(), View() pattern
• Agent runtime: explicit step loop with guard checks, no goroutine races
• Never leak AI_GATEWAY_API_KEY, Authorization headers, or raw tokens into traces or observations

Key Design Decisions

• Pure pass-through policy: No deny-list, no allowlist. The system prompt guides behavior.
• SSE streaming: LLM responses streamed through a 6-stage pipeline to the terminal.
• No goroutine sharing: All mutable state flows through Bubble Tea's Cmd/Msg channel.
• Single executor path: bash -lc is the only audited shell-crossing point.

Tests

Two test files currently exist:

• internal/config/gateway_test.go
• internal/llm/gateway/client_test.go

Tests should be deterministic (no timing-sensitive flakes) and placed alongside the package they cover. Use table-driven tests with t.Parallel() for independent cases.

Version Sync

When bumping the version, update all of these in the same commit:

• VERSION (plain text, e.g. v0.2.4)
• internal/ui/model.go — the appVersion constant (shown in TUI title bar)
• README.md — the "Current version" section

Use short, one-line commit messages for version bumps.

Documentation

• Update docs in www/content/docs/ (this Fumadocs site)
• AGENTS.md in the repo root documents architecture, guards, and conventions for agentic contributors

Contact

• GitHub: Z2E-Agent