1# Working Agreement for zot
2
3This file defines how automated coding assistants should work in this repository. Treat it as a practical operating manual, not a substitute for reading the code.
4
5## Product intent
6
7zot is a compact Go coding-agent harness. Changes should preserve its defining properties:
8
9- one portable binary
10- a provider-neutral agent engine
11- a terminal UI without a framework dependency
12- extensions that communicate through subprocess JSON-RPC
13- predictable behavior on macOS, Linux, and Windows
14- a small dependency and operational footprint
15
16Prefer a narrow, explicit implementation over a generalized subsystem. New abstractions must earn their cost through a real boundary or repeated use.
17
18## Starting a task
19
20Build context before editing:
21
221. Inspect `git status --short`. Existing modifications may belong to the user or another agent.
232. Locate and read every `AGENTS.md` that governs the target path.
243. Read the owning implementation, nearby tests, and any user-facing documentation for the behavior.
254. Reproduce reported failures when feasible. Record expected behavior separately from observed behavior.
265. For GitHub work, inspect the issue or pull request with `gh` if it is available. Do not change branches merely to review a pull request.
27
28Do not use a search result or one function as a complete model of a feature. Follow calls across package boundaries and inspect persisted or streamed representations when relevant.
29
30## Code ownership map
31
32Put behavior in the package that owns the concern:
33
34| Area | Responsibility |
35|---|---|
36| `packages/core` | Agent loop, messages, tool contracts, events, confirmation, sessions, compaction |
37| `packages/provider` | Provider clients, wire formats, streaming, retries, model metadata and discovery |
38| `packages/provider/auth` | Login flows, credential lookup, refresh, and storage |
39| `packages/agent` | CLI configuration, model selection, runtime assembly, RPC, and zotfiles |
40| `packages/agent/modes` | Interactive, print, JSON, dialog, bot, and Telegram interfaces |
41| `packages/agent/extensions` | Extension process lifecycle and host integration |
42| `packages/agent/extproto` | Extension wire protocol |
43| `packages/agent/ext` | Public extension SDK |
44| `packages/agent/skills` | Skill discovery and loading |
45| `packages/agent/swarm` | Background-agent state, supervision, and persistence |
46| `packages/agent/tools` | Built-in tools, permission checks, and jail behavior |
47| `packages/tui` | Terminal input, layout, rendering, markdown, themes, and images |
48| `packages/ignore` | Ignore-pattern matching |
49
50Provider quirks must not leak into `packages/core`. Terminal escape handling and visual layout belong in `packages/tui`. Avoid making the interactive mode a catch-all when a focused package can own the behavior.
51
52## Correctness contracts
53
54Some parts of zot require extra care because small mistakes corrupt state or weaken user protections.
55
56### Agent events and sessions
57
58- Keep streamed events and stored transcripts structurally valid.
59- Preserve tool-call and tool-result pairing, including cancellation and error paths.
60- Maintain compatibility with existing session files unless a migration is explicitly part of the task.
61- Validate replay, resume, fork, import, and export paths when changing shared session structures.
62
63### Providers
64
65- Keep request construction, response parsing, streaming state, and retry classification inside `packages/provider`.
66- Never assume two OpenAI-compatible services have identical edge behavior.
67- When changing model metadata, verify provider ID, model ID, context size, output limit, reasoning support, routing, and pricing independently.
68- Tests must use local servers or fixtures. Do not make paid or credentialed API calls.
69
70### Credentials and private data
71
72- Treat API keys, OAuth tokens, session text, extension payloads, and local state as sensitive.
73- Never include secrets in logs, fixtures, snapshots, errors, or commits.
74- Credential files must retain restrictive permissions where the platform supports them.
75- Test authentication with synthetic values and isolated temporary directories.
76
77### Tools and confinement
78
79- Permission checks must fail closed.
80- Resolve path and symlink behavior before allowing filesystem access.
81- Jail mode is an accident-prevention guardrail, not a security sandbox. Documentation and errors must not claim stronger isolation.
82- Preserve confirmation semantics across every mode. A convenient fallback must not silently grant access.
83
84### Extensions and RPC
85
86- Existing JSON-RPC and extension clients are compatibility surfaces.
87- Add fields in a backward-compatible way and tolerate peers that do not send newly introduced fields.
88- Keep stdout machine-readable where it carries protocol data. Diagnostics belong on stderr or in the established event channel.
89- Ensure child processes are cleaned up on normal exit, cancellation, and startup failure.
90
91### Terminal behavior
92
93- Rendering code must account for ANSI sequences, Unicode display width, wrapping, narrow terminals, and partial streamed content.
94- Avoid tests that depend on a developer's terminal capabilities.
95- Changes involving input, resize, clipboard, process control, paths, shells, or signals require inspection of build-tagged counterparts.
96
97## Implementation approach
98
99For fixes, locate the earliest broken invariant and test there. A UI symptom may originate in provider parsing, event construction, or session replay. Repair the owning layer rather than masking the symptom downstream.
100
101For features, identify all public surfaces before coding: flags, configuration, slash commands, SDK, RPC, extensions, persisted state, provider behavior, and docs. Implement only the surfaces required for a complete first version.
102
103While editing:
104
105- Preserve unrelated working-tree changes.
106- Use idiomatic Go and standard-library facilities when they are sufficient.
107- Keep functions and interfaces focused. Do not introduce an interface solely to mock one call unless it improves the production boundary.
108- Return errors with enough context to identify the failed operation, without exposing private data.
109- Thread `context.Context` through blocking work and honor cancellation.
110- Avoid time-based synchronization in tests. Prefer channels, explicit hooks, or polling with a deadline.
111- Use `t.TempDir()` and `t.Setenv()` for isolated tests. Restore package globals in cleanup.
112- Do not perform opportunistic refactors outside the requested change.
113
114If intentional behavior appears removable or requirements conflict materially, ask the user before proceeding.
115
116## Validation ladder
117
118Match validation effort to the change, then finish with repository-wide checks when code changed.
119
1201. Add or update a regression test in the owning package.
1212. During iteration, run the smallest relevant test, for example:
122
123   ```sh
124   go test ./packages/provider -run TestName
125   ```
126
1273. Format every changed Go file with `gofmt`.
1284. Run the complete suite:
129
130   ```sh
131   go test ./...
132   ```
133
134   `make test` additionally enables the race detector and is preferred for concurrency-sensitive work.
135
1365. Run `go vet ./...` for changes involving concurrency, interfaces, formatting calls, unsafe behavior, process lifecycle, or broad runtime wiring.
1376. Before reporting completion, inspect:
138
139   ```sh
140   git diff --check
141   git status --short
142   git diff
143   ```
144
145Do not hide failures, weaken assertions, or claim validation that was not run. If a check cannot run, state the command and the reason.
146
147Documentation-only changes do not require the Go test suite unless they alter generated or executable examples. They still require diff and status review.
148
149## Documentation duties
150
151Update documentation in the same change whenever users, integrators, or extension authors would observe different behavior. Relevant locations include `README.md`, `docs/rpc.md`, `docs/extensions.md`, `docs/skills.md`, `docs/themes.md`, and `docs/zotfiles.md`.
152
153Examples must match real flags and schemas. State limitations plainly, especially around sandboxing, provider support, compatibility, and platform differences.
154
155## Dependency policy
156
157zot's single-binary design and small footprint are product requirements.
158
159- Prefer the standard library or existing dependencies.
160- Explain why a new dependency is necessary before adding it.
161- Review transitive dependencies and platform implications.
162- Do not add a TUI framework for behavior the current renderer can support.
163- Keep `go.mod` and `go.sum` changes limited to the requested work.
164
165## Source-control safety
166
167The working directory may contain changes from other people or agents.
168
169Allowed inspection commands include `git status`, `git diff`, `git log`, `git show`, and `git blame`. Avoid destructive or broad commands such as `git reset --hard`, `git clean`, `git checkout .`, and blanket staging.
170
171Do not commit, create or switch branches, rebase, push, tag, or open a pull request unless the user explicitly requests that operation. Permission to edit files is not permission to commit them.
172
173When a commit is requested:
174
175- include only files changed for the current task
176- stage paths explicitly
177- review the staged diff before committing
178- use a concise imperative subject that describes the behavior
179- never bypass hooks without explicit approval
180
181When a pull request is requested, run the full validation suite first, summarize compatibility and user-visible effects, and mention any failed or skipped checks.
182
183## Completion report
184
185A final response should be brief and factual. Include:
186
187- what changed and where
188- which checks were run and their results
189- any unresolved risk, skipped validation, or follow-up needed
190
191Do not report success while tests are failing. Do not include unrelated cleanup suggestions unless they materially affect the requested work.