# AGENTS.md Operating instructions for opencode agents working in this repo. opencode auto-loads this file as instructions, overriding the built-in defaults for this project. Custom agents in `.opencode/agents/` inherit these rules unless their own prompts say otherwise. ## Repo posture This repo is in **Phase 0 (Exploration)** per `docs/sdd_process.md`. There is no crate yet — no `Cargo.toml`, no `src/`, no README (the README gets written just before first publish, so it can be honest about what shipped). What exists is `docs/research/phase-0.md` (the Phase 0 document: vision, prior art, open questions, POC register), the SDD process (`docs/sdd_process.md`), and the agent defs (`.opencode/agents/`). Do not scaffold implementation code from this posture unless a task or the user asks for a POC. Do not treat `docs/research/phase-0.md` as settled architecture — it is a working research document whose open questions are genuinely open. The hedging rules of `docs/sdd_process.md` (no circular deferrals, no "resolved with escape hatches") still apply to it. ## Git Workflow **Commit and push when reasonable.** When a change is complete and verified, commit and push to `origin/main` without asking. This overrides the built-in default of "only commit when explicitly asked." In Phase 0 "verified" means the doc checks below — there is no build gate yet. Exceptions — **do not** commit or push without asking: - The change is exploratory / speculative (you're not sure the user wants it kept) - The user is actively reviewing the diff and may ask for changes - You'd be force-pushing, amending a pushed commit, creating an empty commit, or skipping hooks Never commit secrets, keys, or credentials. If a commit fails or hooks reject it, fix the issue and create a new commit — do not amend the failed one. Git identity is preconfigured (`glm-5.3-flash `). Do not change `git config`, skip hooks, or use `git commit -i`. ## Phase 0 conventions 1. **Findings land in `docs/research/`.** Research notes, POC specifications, and POC findings all go there, named consistently (`poc--spec.md` / `poc--findings.md` follows the alkblobs precedent). A POC that needs this repo's code runs in a worktree (`.worktrees/research//` per the SDD process); a self-contained POC (like the alkblobs ones) runs as a standalone crate in the global workspace. Findings land in this repo either way. 2. **Open questions get OQ-ST-NN IDs** and live in the register in `docs/research/phase-0.md` until Phase 1 promotes them to `docs/architecture/open-questions.md`. Numbering is stable — never renumber; append. POCs live in the register there too (numbered, spec'd under `docs/research/poc--spec.md`, findings in `poc--findings.md`). 3. **Cite reference checkouts by path and revision.** The external references for this crate (`/workspace/honker` @ f4e53c6, `/workspace/pgboss-rs` @ 98f7d9e) are reference checkouts of third-party projects — read freely, but never wire the checkout itself into our code. Use the published version unless we vendor or fork it (alksocks' fast-socks5 precedent); if a fork is warranted, forking is normal work. Note the checkout state when your findings depend on code specifics; licenses and provenance get recorded when we adopt code, not while only reading. 4. **POC code stays out of this repo** until Phase 1 adopts it. A POC crate proves the hypothesis and reports findings; it does not pre-scaffold the real crate layout. 5. **No mock/main-repo documentation.** No README, no CHANGELOG, no crate-level docs until the shape exists. Docs that describe a thing that doesn't exist are exactly the kind of dishonest artifact we write docs to avoid. 6. **No comments in code** (when POC crates get written) unless the user explicitly asks. Doc comments (`///`, `//!`) are fine on public API. Inline `//` comments only when a non-obvious safety/correctness constraint would otherwise be missed, or the user asks. ## Conventions that will apply once the crate exists These are family-standard and pre-committed; they'll be duplicated into task prompts and tightened by Phase 1 ADRs: - Rust crate, `tokio` async runtime, `thiserror` error types, no panics in library code, no `unwrap()`/`expect()` outside tests. - No comments in code (see 6 above). - Module-per-file under `src/`, re-exported from `src/lib.rs`; public API surface is the lib re-exports. - Optional dependencies (the postgres engine likely being the first) are feature-gated; the base crate compiles lean; both `cargo test --features ` and default-feature builds pass when features exist. - Categorical estimates (`scope`, `risk`, `impact`, `level`) in every task file — per `docs/sdd_process.md` these are structurally required, not optional metadata. ## Verification Commands Phase 0 — none (no code yet). The doc conventions above are checked by reading. When the crate appears, this section gets the standard Rust gates (`cargo test`, `cargo clippy --all-targets -- -D warnings`, `cargo fmt --check`, and the fuzz corpus replay if fuzzing is adopted — the alksocks/alktty/alktunnels pattern) and becomes the merge gate the coordinator runs. ## Architecture Context - `docs/research/phase-0.md` — the Phase 0 document: vision, prior art, open questions (OQ-ST-01..NN), the POC register, and (eventually) the converged recommendation. Read it before any non-trivial work in this repo. - `docs/research/consumer-inventory.md` — the per-feature scope synthesis answering OQ-ST-01 from the paused consumers' documents. New consumer needs get a row there *before* any scope decision assumes them. - `docs/sdd_process.md` — the SDD process. Phase 0 in progress; `docs/architecture/` does not exist yet. - The SDD process and agent defs were copied from downstream projects (alkblobs) in the workspace; project-specific stale references were cleaned at Phase 0 setup (2026-10-03). If you find a section that assumes another crate's machinery, fix it rather than working around it — same discipline as stale TODOs. - If a TODO or doc reference cites a design direction that a later ADR or Phase 0 decision rejected, the reference is stale — remove it and align; do not implement the rejected design.