alkstore/AGENTS.md

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 <glm-5.3-flash@alk.dev>). 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-<name>-spec.md / poc-<name>-findings.md follows the alkblobs precedent). A POC that needs this repo's code runs in a worktree (.worktrees/research/<task-id>/ 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.
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 <set> 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.