Imported from sputn1ck/fsmx (AGENTS.md). Install upstream with npx skills add sputn1ck/fsmx. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

Keep the finite state machine runtime anchored in the repo root. Key directories:

• fsmx.go holds the core FSM types and runtime loop.
• cmd/ exposes tooling such as the fsmx-mermaid generator.
• examples/{small,long}/ provide runnable demos used in docs.
• IMPROVEMENTS.md tracks roadmap notes and future ideas.

Build, Test, and Development Commands

Use Go tooling and provided make targets to iterate quickly.

• go build ./... compiles the library and generator.
• make demo-small, make demo-long, or make demos run smoke demos.
• make generate wraps go generate ./... for doc refresh.
• go run ./cmd/fsmx-mermaid -h surfaces CLI usage.
• go run ./examples/small (or long) executes demos without Make.

Coding Style & Naming Conventions

Adhere to Go 1.25+ idioms with formatting enforced before commits.

• Run gofmt -s or go fmt ./... on touched files; prefer go vet ./... locally.
• Exported identifiers use PascalCase; packages stay lower_snake and short (fsmx, cmd).
• Generic signatures follow State[E, Env, Eff] and Transition[E, Env, Eff].
• Generated sources end in .gen.go and include // Code generated ... DO NOT EDIT. headers.

Testing Guidelines

Favor table-driven tests near the code they validate.

• Place tests alongside sources as *_test.go (example: fsmx/state_test.go).
• Run go test ./... before PRs; demos double as smoke tests and must stay runnable.
• Cover transitions, effect dispatch, and error paths with explicit scenarios.

Commit & Pull Request Guidelines

Communicate impact succinctly and keep scopes tight.

• Commits use imperative subjects ≤72 chars and informative bodies (e.g., fsmx: add runner pool helper).
• PRs include a clear summary, linked issues, reproduction steps, and relevant demo/diagram output.
• Update README/examples when behavior changes; keep Mermaid artifacts current.

Tooling Tips

Lean on supplied generators to stay consistent.

• go run ./cmd/fsmx-mermaid -genfile=examples/small/docgen.go regenerates diagrams.
• Diagram directives live beside examples; keep them in sync with runtime changes.

Agent-Specific Instructions

Keep edits focused and idiomatic.

• Avoid broad refactors unless requested; aim for minimal, reviewable diffs.
• Use Make targets when available; do not override user-local configuration.