Igor Development Guide

Prerequisites

Required Tools

Go 1.25+

Igor requires Go 1.25 or later. Check your version:

go version

Install or update Go from: https://go.dev/dl/

TinyGo (for building agents)

Required for compiling agents to WASM:

# macOS
brew tap tinygo-org/tools
brew install tinygo

# Linux
wget https://github.com/tinygo-org/tinygo/releases/download/v0.40.1/tinygo_0.40.1_amd64.deb
sudo dpkg -i tinygo_0.40.1_amd64.deb

Verify installation:

tinygo version

Recommended Tools

golangci-lint (code quality)

Install linter:

# macOS
brew install golangci-lint

# Linux
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | \
  sh -s -- -b $(go env GOPATH)/bin

Verify installation:

golangci-lint --version

goimports (import formatting)

Install import formatter:

go install golang.org/x/tools/cmd/goimports@latest

Ensure $(go env GOPATH)/bin is in your PATH.

Development Workflow

Initial Setup

After cloning the repository, install Git hooks:

./scripts/install-hooks.sh

This installs pre-commit hooks that enforce code quality before each commit.

Local Quality Gates

Pre-commit hooks automatically run:

Code formatting check (make fmt-check)
Static analysis (make vet)
Linting (make lint)
Tests (make test)

If any check fails, the commit is rejected. Fix issues before committing.

To bypass hooks (not recommended):

git commit --no-verify

Only bypass for work-in-progress commits on feature branches.

Building Igor

Build the node runtime:

make build

Output: bin/igord

Building Agents

Build the example agent:

make agent

Output: agents/research/example/agent.wasm

Running Locally

Run an agent with default budget:

make run-agent

Or manually:

./bin/igord --run-agent agents/research/example/agent.wasm --budget 10.0

Code Quality

Format code:

make fmt

Check formatting without modifying:

make fmt-check

Run linters:

make lint

Run go vet:

make vet

Run all checks:

make check

Testing

Run tests:

make test

Run tests with coverage:

go test -cover ./...

Cleaning Build Artifacts

Remove binaries and checkpoints:

make clean

Makefile Targets

Run make help to see all available targets:

make help

Output:

Igor v0 Development Commands

Usage:
  make <target>

Targets:
  help         Show this help message
  build        Build igord binary
  clean        Remove build artifacts
  test         Run tests
  lint         Run golangci-lint
  vet          Run go vet
  fmt          Format code with gofmt and goimports
  fmt-check    Check if code is formatted correctly
  tidy         Tidy go.mod and go.sum
  agent        Build example agent WASM
  run-agent    Build and run example agent locally
  check        Run all checks (formatting, vet, lint)
  all          Clean, build, test, and run all checks

Code Style Guidelines

Formatting

Igor uses standard Go formatting:

gofmt for code formatting
goimports for import organization
80-character line length preferred (not enforced)

Run make fmt before committing.

Linting

Igor uses golangci-lint with the following enabled linters:

govet - Official Go static analysis
staticcheck - Advanced correctness checks
errcheck - Unchecked error detection
ineffassign - Ineffectual assignment detection
gosimple - Code simplification suggestions
unused - Unused code detection
revive - General code quality
gocyclo - Cyclomatic complexity (max: 20)

Run make lint to check code quality.

Error Handling

Always check errors
Use fmt.Errorf with %w for error wrapping
Log errors with context
Fail loudly on invariant violations

Logging

Use structured logging with slog:

logger.Info("Operation completed",
    "agent_id", agentID,
    "duration_ms", elapsed.Milliseconds(),
)

Comments

Document exported functions and types
Explain non-obvious logic
Avoid redundant comments
Use godoc conventions

Project Structure

igor/
├── cmd/igord/           # Node runtime entry point
├── internal/            # Internal packages (not importable)
│   ├── agent/          # Agent instance management
│   ├── authority/      # Lease-based authority epochs
│   ├── config/         # Configuration
│   ├── eventlog/       # Per-tick observation event log
│   ├── hostcall/       # igor host module (clock, rand, log, wallet)
│   ├── inspector/      # Checkpoint inspector
│   ├── logging/        # Structured logging
│   ├── migration/      # Migration coordination
│   ├── p2p/            # P2P networking
│   ├── pricing/        # Price feed and node pricing
│   ├── registry/       # Agent registry
│   ├── replay/         # Deterministic replay verification
│   ├── runner/         # Tick loop runner and escalation
│   ├── runtime/        # WASM execution engine (wazero)
│   ├── settlement/     # Payment settlement
│   ├── simulator/      # Local single-process simulator
│   ├── storage/        # Checkpoint storage
│   ├── timeline/       # Timeline utilities
│   └── wasmutil/       # Shared WASM capture/resume helpers
├── pkg/                 # Public packages (importable)
│   ├── budget/         # Budget types and conversions
│   ├── identity/       # Agent Ed25519 keypair management
│   ├── lineage/        # Signed checkpoint lineage
│   ├── manifest/       # Agent manifest schema
│   ├── protocol/       # P2P message types
│   └── receipt/        # Payment receipt signing
├── sdk/igor/            # Agent SDK (lifecycle, hostcall wrappers)
├── agents/
│   ├── example/        # Survivor example agent
│   └── reconciliation/ # Bridge reconciliation demo agent
├── docs/               # Documentation
└── bin/                # Compiled binaries (gitignored)

Package Organization

internal/ - Private implementation packages. Cannot be imported by external code.

pkg/ - Public API packages. Can be imported by agents or external tools.

cmd/ - Entry points for binaries.

Development Best Practices

Before Committing

Run quality checks:

make check

This runs:

make fmt-check - Verify formatting
make vet - Run static analysis
make lint - Run linters

Fix any issues before committing.

Commit Messages

Follow conventional commits format:

<type>(<scope>): <subject>

<body>

Types:

feat - New feature
fix - Bug fix
docs - Documentation only
chore - Tooling, dependencies
refactor - Code restructuring
test - Test additions

Examples:

feat(migration): add multi-hop migration support
fix(agent): correct budget calculation rounding
docs(architecture): clarify checkpoint format
chore(deps): update libp2p to v0.48

Testing

Write tests for:

Core logic in internal/ packages
Protocol message encoding/decoding
Storage provider implementations
Migration flows

Place tests alongside code:

internal/agent/
  instance.go
  instance_test.go

Run tests before committing:

make test

Troubleshooting

golangci-lint errors

If linter fails:

Check which linter reported the issue
Read the error message carefully
Fix the issue or suppress if false positive
Re-run make lint

Suppress false positives with //nolint comments:

//nolint:errcheck // Intentionally ignoring error
_ = stream.Close()

goimports issues

If imports are not organizing correctly:

# Manual fix
goimports -w .

Build failures

If build fails after pulling changes:

make clean
make tidy
make build

Agent compilation issues

If TinyGo compilation fails:

# Check TinyGo version
tinygo version

# Clean and rebuild
cd agents/example
make clean
make build

Editor Integration

VS Code

Install Go extension:

code --install-extension golang.go

Configure settings (.vscode/settings.json):

{
  "go.lintTool": "golangci-lint",
  "go.lintOnSave": "workspace",
  "editor.formatOnSave": true,
  "go.formatTool": "goimports"
}

Vim/Neovim

Use vim-go plugin with:

let g:go_fmt_command = "goimports"
let g:go_metalinter_command = "golangci-lint"

GoLand/IntelliJ

Preferences → Tools → File Watchers
Add goimports file watcher
Enable golangci-lint inspection

Performance Profiling

Profile CPU usage:

go test -cpuprofile=cpu.prof -bench=.
go tool pprof cpu.prof

Profile memory:

go test -memprofile=mem.prof -bench=.
go tool pprof mem.prof

Debugging

Runtime Debugging

Use delve debugger:

# Install
go install github.com/go-delve/delve/cmd/dlv@latest

# Debug igord
dlv exec ./bin/igord -- --run-agent agents/research/example/agent.wasm

Agent Debugging

Add debug output in agent code:

import "fmt"

func agent_tick() {
    fmt.Printf("[debug] Counter: %d\n", state.Counter)
    // ...
}

Output appears in igord logs.

GitHub CLI Usage

Igor provides scripts for repository management using GitHub CLI (gh).

Authentication

Check authentication status:

make gh-check
# Or: ./scripts/verify-gh-auth.sh

Authenticate if needed:

gh auth login

Repository Metadata

Configure repository description and topics (once pushed to GitHub):

make gh-metadata
# Or: ./scripts/configure-repo-metadata.sh

This sets:

Repository description
Topic tags (autonomous-agents, wasm-runtime, libp2p, etc.)
Discoverability metadata

Branch Protection

View recommended branch protection settings:

./scripts/suggest-branch-protection.sh

Prints suggested gh commands without applying them automatically.

Creating Releases

Prepare a draft release:

make gh-release VERSION=v0.1.0-genesis
# Or: ./scripts/prepare-release.sh v0.1.0-genesis

This creates a draft GitHub release with:

Release notes from template
Marked as pre-release
Ready for review and publication

Common gh Commands

# View repository
gh repo view

# View in browser
gh repo view --web

# List releases
gh release list

# View issues
gh issue list

# Create issue
gh issue create

See gh help for complete command reference.

Contributing

Pull Request Checklist

Before submitting PR:

Code Review Focus

Reviews focus on:

Correctness - Does it work as intended?
Invariants - Are system guarantees maintained?
Clarity - Is code understandable?
Testing - Is it adequately tested?

Performance optimization is secondary to correctness.

Additional Resources

docs/philosophy/OVERVIEW.md - Project overview and design philosophy
docs/runtime/ARCHITECTURE.md - Technical architecture
docs/runtime/AGENT_LIFECYCLE.md - Agent development guide
TASKS.md - Development roadmap

FilesExpand file tree

DEVELOPMENT.md

Latest commit

History

DEVELOPMENT.md

File metadata and controls

Igor Development Guide

Prerequisites

Required Tools

Recommended Tools

Development Workflow

Initial Setup

Local Quality Gates

Building Igor

Building Agents

Running Locally

Code Quality

Testing

Cleaning Build Artifacts

Makefile Targets

Code Style Guidelines

Formatting

Linting

Error Handling

Logging

Comments

Project Structure

Package Organization

Development Best Practices

Before Committing

Commit Messages

Testing

Troubleshooting

golangci-lint errors

goimports issues

Build failures

Agent compilation issues

Editor Integration

VS Code

Vim/Neovim

GoLand/IntelliJ

Performance Profiling

Debugging

Runtime Debugging

Agent Debugging

GitHub CLI Usage

Authentication

Repository Metadata

Branch Protection

Creating Releases

Common gh Commands

Contributing

Pull Request Checklist

Code Review Focus

Additional Resources