AGENTS.md

1# AGENTS.md - Jido Guide
2 
3## Intent
4Build reliable agent systems by separating pure decision logic from runtime side-effect execution.
5 
6## Runtime Baseline
7- Elixir `~> 1.18`
8- OTP `27+` (release QA baseline)
9 
10## Commands
11- `mix test` (default alias excludes `:flaky`)
12- `mix test --include flaky` (full suite)
13- `mix test --cover` (coverage gate)
14- `mix q` or `mix quality` (`format --check-formatted`, `compile --warnings-as-errors`, `credo`, `dialyzer`)
15- `mix docs` (local docs)
16 
17## Work Management
18This project tracks work with `bw` (Beadwork), which persists plans, progress,
19and decisions to git so they survive compaction, session boundaries, and context
20loss.
21 
22- Always run `bw prime` before starting implementation work.
23- Use one Beadwork issue per branch/PR unless the issue is explicitly split.
24- Start work with `bw start <id>` and record validation, skip decisions, PR
25  links, and CI outcomes with `bw comment <id> "..."`
26- Completing a task includes committing, pushing, closing the Beadwork issue,
27  and running `bw sync`.
28- For architecture-review findings, prefer the portable helper:
29  `scripts/bw-codex-loop.sh`.
30 
31## Architecture Snapshot
32- `Jido.Agent`: pure agent module with immutable state and `cmd/2`
33- `Jido.AgentServer`: GenServer runtime for directives, lifecycle, and message flow
34- `Jido.Agent.Directive.*`: typed effect descriptors (`Emit`, `SpawnAgent`, `StopChild`, etc.)
35- `Jido.Agent.StateOp.*`: internal state transition operations applied by strategy layer
36- Plugins/sensors provide capability composition without coupling core agent logic
37 
38## Standards
39- Keep `cmd/2` pure: same input => same `{agent, directives}` output
40- Keep directives for external effects only; do not rely on directives for state mutation
41- Use **Zoi-first** schemas for new agent/plugin/signal contracts
42- Preserve tagged tuple and structured error contracts at public boundaries
43- Keep cross-agent communication on signals/directives, not ad-hoc process messages
44 
45## Testing and QA
46- Prefer pure agent tests first, then AgentServer/runtime integration tests
47- Use helpers from `test/AGENTS.md` (`JidoTest.Case`, `JidoTest.Eventually`) for async assertions
48- Avoid `Process.sleep/1` in tests; assert eventual state/event behavior
49 
50## Release Hygiene
51- Keep semver ranges stable (`~> 2.0` for Jido ecosystem peers)
52- Use Conventional Commits
53- Do not modify `CHANGELOG.md`; release notes are generated from Git history during release, so keep changes focused on proper Conventional Commits.
54 
55## References
56- `README.md`
57- `usage-rules.md`
58- `guides/`
59- `test/AGENTS.md`
60- https://hexdocs.pm/jido
61