Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
87 lines (68 loc) · 2.74 KB

CONTRIBUTING.md

File metadata and controls

87 lines (68 loc) · 2.74 KB

Contributing to Fizeau

Development Setup

git clone https://github.com/easel/fizeau.git
cd agent
lefthook install
make install-quality-tools
make build    # build the binary
make test     # run unit tests
make check    # fmt + vet + lint + test

Requirements

Running Tests

make test                    # unit tests
make lint                    # golangci-lint
make ci-checks               # matches the Go-side CI gate (the `test` job)
make adapter-pytest          # matches the `adapter-pytest` CI job
make ci                      # runs every CI job locally (ci-checks + adapter-pytest)
lefthook run pre-push --force # run the hook sequence on demand
go test -tags=integration .  # integration tests (requires LM Studio)

Integration tests auto-discover LM Studio on localhost:1234, vidar:1234, or bragi:1234. Override with LMSTUDIO_URL and LMSTUDIO_MODEL.

Code Style

  • gofmt is non-negotiable — CI enforces zero diff
  • go vet must pass
  • Errors must be wrapped with context: fmt.Errorf("context: %w", err)
  • Pass context.Context as the first parameter for I/O functions
  • Interfaces defined in the consuming package

Making Changes

  1. Create a branch or worktree (wt switch -c my-feature)
  2. Write tests first (TDD)
  3. Implement the minimum to make tests pass
  4. Run make check
  5. Commit with a descriptive message
  6. Push and open a PR

Project Structure

agent.go                  # Public API: Run(), Request, Result, interfaces
loop.go                   # Agent loop implementation
prompt/                   # System prompt composition
provider/openai/          # OpenAI-compatible provider (LM Studio, Ollama, etc.)
provider/anthropic/       # Anthropic Claude provider
provider/virtual/         # Dictionary replay for testing
tool/                     # Built-in tools: read, write, edit, bash
session/                  # JSONL logging, replay, cost tracking
cmd/fiz/            # Standalone CLI
website/                  # Hugo/Hextra microsite
demos/                    # Demo scripts and session fixtures

CLI Documentation

The Hugo CLI reference under website/content/docs/cli/ is generated from the live Cobra command tree. After changing fiz subcommands or flags, regenerate the pages:

make docs-cli

Commit the regenerated files alongside your code change. The generator (cmd/docgen-cli) is deterministic — re-running it without source changes produces byte-identical output.

License

By contributing, you agree that your contributions will be licensed under the MIT License.