Two files, one repository
agentjido/jido ships 1 format across 3 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 10 | 3 | 0% |
| Commands | 0 | 6 | 6 | 0% |
| Section tags | 4 | 1 | 1 | 67% |
What each file covers
Sections
0 shared · 10 only in A · 3 only in B- − AGENTS.md - Jido Guide
- − Intent
- − Runtime Baseline
- − Commands
- − Work Management
- − Architecture Snapshot
- − Standards
- − Testing and QA
- − Release Hygiene
- − References
- + `.spec` Agent Guide
- + First Read
- + Working Rules
Commands
0 shared · 6 only in A · 6 only in B- − mix test
- − mix test --include flaky
- − mix test --cover
- − mix q
- − mix quality
- − mix docs
- + mix spec.prime --base HEAD
- + mix spec.next
- + mix spec.next --bugfix
- + mix spec.check --base ...
- + mix spec.validate --debug
- + mix spec.status
Section tags
4 shared · 1 only in A · 1 only in B- − deployment
- + agent-behaviour
- test
- code-style
- git-pr
- do-not
Line diff
agentjido/jido · AGENTS.md
@@ −1 @@
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
agentjido/jido · .spec/AGENTS.md
@@ +1 @@
1# `.spec` Agent Guide
2
3Use this folder to maintain authored Spec Led Development subjects and generated state.
4
5<!-- covers: spec.workspace.agents_present spec.workspace.agent_prime_context -->
6
7## First Read
8
91. Read `.spec/README.md`.
102. Read `.spec/decisions/README.md` and any ADRs that affect the subject you are changing.
113. Read the current `.spec/specs/*.spec.md` files before editing.
12
13## Working Rules
14
15- Keep one subject per file.
16- Put normative statements in `spec-requirements`.
17- Add `spec-scenarios` only when `given` / `when` / `then` improves clarity.
18- Add `spec-meta.decisions` only when a subject depends on a durable cross-cutting ADR.
19- Keep ADRs in `.spec/decisions/*.md` for cross-cutting policy only.
20- Prefer targeted command verifications for behavioral proof.
21- Use file-backed verifications only when the target can carry stable `covers:` markers for every covered id.
22- Keep verification targets repository-root-relative.
23- Use Git history and pull requests as the change log; keep `.spec` current-state only.
24- At session start, run `mix spec.prime --base HEAD`.
25- After code, docs, or tests change, run `mix spec.next`.
26- For bug fixes, prefer `mix spec.next --bugfix`.
27- If next says `needs subject updates`, update the named subject before you finish.
28- If next says `ready for check`, move to `mix spec.check --base ...`.
29- Use `mix spec.validate --debug` when you need low-level verifier output.
30- Run `mix spec.status` when you need coverage or weak-spot summaries.
31
@@ −1 +1 @@
1−# AGENTS.md - Jido Guide
1+# `.spec` Agent Guide
22
3−## Intent
4−Build reliable agent systems by separating pure decision logic from runtime side-effect execution.
3+Use this folder to maintain authored Spec Led Development subjects and generated state.
54
6−## Runtime Baseline
7−- Elixir `~> 1.18`
8−- OTP `27+` (release QA baseline)
5+<!-- covers: spec.workspace.agents_present spec.workspace.agent_prime_context -->
96
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)
7+## First Read
168
17−## Work Management
18−This project tracks work with `bw` (Beadwork), which persists plans, progress,
19−and decisions to git so they survive compaction, session boundaries, and context
20−loss.
9+1. Read `.spec/README.md`.
10+2. Read `.spec/decisions/README.md` and any ADRs that affect the subject you are changing.
11+3. Read the current `.spec/specs/*.spec.md` files before editing.
2112
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`.
13+## Working Rules
3014
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
15+- Keep one subject per file.
16+- Put normative statements in `spec-requirements`.
17+- Add `spec-scenarios` only when `given` / `when` / `then` improves clarity.
18+- Add `spec-meta.decisions` only when a subject depends on a durable cross-cutting ADR.
19+- Keep ADRs in `.spec/decisions/*.md` for cross-cutting policy only.
20+- Prefer targeted command verifications for behavioral proof.
21+- Use file-backed verifications only when the target can carry stable `covers:` markers for every covered id.
22+- Keep verification targets repository-root-relative.
23+- Use Git history and pull requests as the change log; keep `.spec` current-state only.
24+- At session start, run `mix spec.prime --base HEAD`.
25+- After code, docs, or tests change, run `mix spec.next`.
26+- For bug fixes, prefer `mix spec.next --bugfix`.
27+- If next says `needs subject updates`, update the named subject before you finish.
28+- If next says `ready for check`, move to `mix spec.check --base ...`.
29+- Use `mix spec.validate --debug` when you need low-level verifier output.
30+- Run `mix spec.status` when you need coverage or weak-spot summaries.
6131
