AGENTS.md

1# Symphony Elixir
2 
3This directory contains the Elixir agent orchestration service that polls Linear, creates per-issue workspaces, and runs Codex in app-server mode.
4 
5## Environment
6 
7- Elixir: `1.19.x` (OTP 28) via `mise`.
8- Install deps: `mix setup`.
9- Main quality gate: `make all` (format check, lint, coverage, dialyzer).
10 
11 
12## Codebase-Specific Conventions
13 
14- Runtime config is loaded from `WORKFLOW.md` front matter via `SymphonyElixir.Workflow` and `SymphonyElixir.Config`.
15- Keep the implementation aligned with [`../SPEC.md`](../SPEC.md) where practical.
16  - The implementation may be a superset of the spec.
17  - The implementation must not conflict with the spec.
18  - If implementation changes meaningfully alter the intended behavior, update the spec in the same
19    change where practical so the spec stays current.
20- Prefer adding config access through `SymphonyElixir.Config` instead of ad-hoc env reads.
21- Workspace safety is critical:
22  - Never run Codex turn cwd in source repo.
23  - Workspaces must stay under configured workspace root.
24- Orchestrator behavior is stateful and concurrency-sensitive; preserve retry, reconciliation, and cleanup semantics.
25- Simplicity is a project constraint: prefer the smallest coherent design with one clear owner and
26  invariant. Push back on extra abstractions, duplicated policy, and speculative flexibility.
27- For stateful changes, check startup, reload, restart, and failure recovery together before editing.
28- Follow `docs/logging.md` for logging conventions and required issue/session context fields.
29 
30## Tests and Validation
31 
32Run targeted tests while iterating, then run full gates before handoff.
33 
34- Prefer narrow tests that exercise real OTP processes and observable behavior over mock-only or
35  broad end-to-end coverage; prove health with a synchronous call or stable effect, not only a PID.
36- For non-trivial changes, use an adversarial review early to challenge complexity and try to break
37  adjacent lifecycle paths; a reproducible failure blocks landing even if other reviews are clean.
38- If tests need repeated global restarts or bespoke cleanup, first fix the shared harness or
39  ownership boundary.
40 
41```bash
42make all
43```
44 
45## Required Rules
46 
47- Public functions (`def`) in `lib/` must have an adjacent `@spec`.
48- `defp` specs are optional.
49- `@impl` callback implementations are exempt from local `@spec` requirement.
50- Evaluate proposed directions instead of agreeing reflexively; surface simpler designs and material
51  trade-offs early.
52- Keep changes narrowly scoped; avoid unrelated refactors.
53- Follow existing module/style patterns in `lib/symphony_elixir/*`.
54 
55Validation command:
56 
57```bash
58mix specs.check
59```
60 
61## PR Requirements
62 
63- PR body must follow `../.github/pull_request_template.md` exactly.
64- Validate PR body locally when needed:
65 
66```bash
67mix pr_body.check --file /path/to/pr_body.md
68```
69 
70## Docs Update Policy
71 
72If behavior/config changes, update docs in the same PR:
73 
74- `../README.md` for project concept and goals.
75- `README.md` for Elixir implementation and run instructions.
76- `WORKFLOW.md` for workflow/config contract changes.
77