gasm-sdk/AGENTS.md

AGENTS.md — gasm-devkit

Repository rules for AI agents and contributors. Read before modifying any code in this repository.

AI Contribution Policy

AI agents may assist with code, documentation, tests, and review in this repository. All AI-assisted changes must:

• Follow the code style and conventions in this file.
• Include the trailer Assisted-by: <model-name> in every commit message.
• Not commit directly to main — work on development.
• Pass the full Definition of Done before any commit.

Workflow

• Branching. development is the working branch. main is release-only: merge from development, then tag. Never commit directly to main.
• Release procedure.
  1. Bump version in justfile and cmd/gasm/main.go.
  2. Update CHANGELOG.md with a new ## [X.Y.Z] — YYYY-MM-DD section.
  3. Update README.md and docs/ARCHITECTURE.md if user-visible behaviour changed.
  4. Run the Definition of Done (below).
  5. Commit on development.
  6. git checkout main && git merge --ff-only development.
  7. git tag vX.Y.Z.
  8. git checkout development.
  9. GOBIN=~/.local/bin just install-bin.

Commit Messages

Conventional Commits, subject line only, imperative mood, lowercase after the colon:

feat(asm): add EVEX gather and scatter with VSIB addressing

Allowed types: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert.

Every commit ends with exactly one trailer, using the model that assisted with the change:

Assisted-by: <model-name>

Replace <model-name> with the actual model (e.g. DeepSeek V4 Pro).

No body, no footers, no trailing period on the subject.

Code Style

Language: Go 1.27 (toolchain go1.27rc1).

Formatter

gofmt — zero diff. Run just fmt before committing.

Linter

go vet — zero warnings. Run just build before committing.

Tests

go test -race -count=1 ./... — all green, coverage ≥ 80 % (hard gate, enforced by just test).

Dependencies

• Production code: standard library only. No third-party imports in shipped code.
• Test code: golang.org/x/arch is the sole test dependency (decode oracle for round-trip validation). It is never linked into the binary.
• No cgo, no C, no external toolchains, no JavaScript.

Error Handling

Explicit if err != nil. Wrap with fmt.Errorf("context: %w", err). No panics outside main. The one exception: the JIT trampoline's recover-guarded decoder hot path, which converts bounds panics to sentinel errors.

Assembly

Plan 9 syntax (Go's assembler dialect). Hand-written — no code generators except _gen/gen.go for instruction tables (which parses the Go toolchain source). Every instruction table is committed; no runtime dependency on the Go toolchain.

File Naming

• _amd64.s, _arm64.s, _riscv64.s, _loong64.s for architecture-specific assembly.
• _linux_amd64.go for platform-specific Go files.
• _test.go suffix for test files.

Definition of Done

A task is not complete until all of these pass:

1. just build — go vet + gofmt check, zero errors, zero warnings.
2. just test — full suite with -race, coverage ≥ 80 %.
3. just fmt — produces no diff.
4. Diagnostics — zero warnings across the project.
5. Non-trivial changes reviewed.

Licence

BSD-3-Clause. Every source file carries the SPDX header:

// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
// SPDX-License-Identifier: BSD-3-Clause