alkgen/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.

Git Workflow

Commit and push when reasonable. When a change is complete and verified (build + lint + tests pass), commit and push to origin/main without asking. This overrides the built-in default of "only commit when explicitly asked."

The workflow:

1. Make the change
2. Verify: cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check, cargo doc --no-deps if docs changed, cargo build --target wasm32-unknown-unknown --release if dependency/wasm-relevant code changed
3. Inspect git status and git diff before staging — stage only the intended files, never secrets
4. Write a concise commit message matching the repo style (see git log --oneline -10). For multi-point changes, use a summary line plus a body with bullet points and a verification block.
5. git push origin main
6. Report the commit hash and the verification summary

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
• The change touches semver-relevant public API (this crate is headed to crates.io; once published, renames/removals/signature changes on public items are breaking — additive changes are fine)
• You'd be force-pushing, amending a published 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.2 <glm-5.2@alk.dev>). Do not change git config, skip hooks, or use git commit -i.

Project Conventions (Rust / template codegen crate)

This is a template-based codegen engine: handlebars-rust templates rendered over alktype BAST documents to produce code artifacts (binary readers/writers/validators, protocol handlers). Conventions apply to all work in src/ and tests/.

1. No comments in code unless the user explicitly asks. This is a project-wide convention. Doc comments (///, //!) are fine and expected on public API. Inline // comments only when the user asks or when a non-obvious safety/correctness constraint would otherwise be missed.

2. Error handling — thiserror for library error types. No panics in library code. No unwrap() or expect() outside tests — if you reach for unwrap, the error path wasn't specified, stop and decide what should actually happen. Template registration/render failures are data, not crashes: a malformed template or BAST input must produce a typed error, never a panic (generated code feeds alkcall, which accepts BAST from arbitrary peers).

3. No async — template rendering and codegen are synchronous, CPU-bound operations. No tokio, no async/await in the core. (If a future file-watch/rebuild service is wanted, that is an assembly- layer concern, not a lib concern.)

4. WASM-clean — the crate must compile to wasm32-unknown-unknown. No filesystem access in library code (handlebars dir_source feature is off-limits in lib code; templates come from strings or include_str!). No threads, no std::time, no platform deps. If you reach for a new dependency, first verify it is wasm-compatible and worth the cost.

5. serde_json preserve_order is load-bearing — alktype relies on it (field order in schema JSON determines packed byte order). Do not disable it and do not sort schema keys in contexts built for templates unless the template explicitly requires a sort.

6. Strict template mode — Handlebars::set_strict_mode(true) for any registry the lib renders with. A missing variable in a codegen template must be a render error, not silently-empty output (silent gaps become compile bugs in the consumer's build, far from the cause). alkminer-v1's ShaderBuilder is the precedent.

7. Templates are code — templates live as const &str (inline) or include_str! files, versioned in-repo, with render tests pinning their output. Changing a template changes generated code; treat template edits with the same care as source edits (tests must pin golden output before merging).

8. Generated-code hygiene — generated artifacts start with a "Auto-generated by alkgen. DO NOT EDIT." banner (typebox-rs precedent). Rendering must be deterministic: same BAST + same templates + same options → byte-identical output (no HashMap iteration order leaking into generated code).

9. Naming — Rust standard: snake_case for functions/variables/ modules, PascalCase for types/traits, SCREAMING_SNAKE_CASE for constants. Template registry names: lowercase kebab or snake, one name per template kind.

10. Module structure — one module per file under src/, re-exported from src/lib.rs. Public API surface is the lib.rs re-exports.

11. No unsafe — zero unsafe blocks. If a perf argument appears, the answer lives in the template/data-model layer, not in unsafe.

Verification Commands

Run these before committing. All must pass.

cargo test                                            # full suite
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo doc --no-deps                                   # if docs changed
cargo build --target wasm32-unknown-unknown --release # if deps/wasm-relevant code changed
cargo publish --dry-run --allow-dirty                 # before a release

Architecture Context

• docs/sdd_process.md — the SDD workflow (phases, roles, task format). Phase 0 (research/POC) runs before architecture; small changes may skip the ceremony per the doc's "reasonable exceptions" clause.
• docs/research/phase-0.md — the current phase-0 findings + OQ list. Read it before proposing design changes; extend it when research answers questions.
• docs/architecture/ — will exist after Phase 1; the authoritative spec once present (ADRs numbered, OQs tracked in open-questions.md).
• tasks/ — task graph after decomposition.

Reference Material (outside this repo)

• /workspace/@alkdev/alktype — the BAST engine (crates.io 0.3.0); docs/architecture/ there is the schema/layout/validation spec.
• /workspace/@alkimiadev/typebox-rs/src/codegen — older handlebars codegen precedent (simple context structs + inline templates).
• /workspace/@alkminer/reference/alkminer-v1/src/compute/kernel.rs — handlebars-as-JIT precedent (strict registry, partials, render-then- compile with cache).
• /workspace/@alkdev/alkhttp/src/adapters — from_openapi / from_jsonschema handler shapes the call-protocol codegen mirrors.
• /workspace/@alkdev/alkcall — channels consumer; generated readers/writers/validators serve its channels.
• /workspace/handlebars-rust — vendored handlebars checkout (head; crates.io 6.4.4 is the pinned stable).