Project-Kiln/AGENTS.md

Codex instructions

Authority and scope

• Start with docs/spec/00_SPEC_INDEX.md. The numbered files under docs/spec/ are the complete active specification; 99_FULL_SPEC_ARCHIVE.md is historical and is not in this repository.
• Required and Confirmed items are binding. Proposed, Deferred, Open, Optional, and Post-v1 items must not silently become implementation requirements.
• Before changing scope, architecture, compatibility, release timing, schemas, commands, or user-visible behavior, read docs/spec/01_PROJECT_FOUNDATION.md and docs/spec/07_RISKS_DECISIONS_AND_HISTORY.md and apply the cross-spec integrity rules.
• Ask the project owner when multiple plausible resolutions materially differ. Do not invent a decision merely to keep moving.

Current state

• Phases 0–3 are complete. Steam launch planning and execution is next.
• Project Kiln, kiln, and every kiln-* name are private placeholders. Do not publish, globally install, register, or expose them as stable compatibility promises.
• The workspace is private, AGPL-3.0-or-later, Rust 2024, with Rust 1.97.1 as both the minimum supported compiler and reviewed development toolchain.
• Every new provider starts with read-only fixture-driven discovery and must reuse the Phase 1 contracts before execution work begins.

Required workflow

1. Define one narrow task with exclusions, affected components, acceptance criteria, and exact verification commands.
2. Implement one vertical capability at a time. Do not spread incomplete work across providers or system layers.
3. Treat provider files, manifests, artwork, frontend descriptors, paths, and strings as hostile input. Never interpolate them into a shell command.
4. Keep ordinary discovery and launch unprivileged. Preserve per-user XDG state and do not hard-code usernames, UIDs, home directories, mounts, or the reference hardware.
5. Use exact versions for local path dependencies as well as their paths. Update and commit Cargo.lock for every dependency change.
6. Add dependency licenses only after review; do not broaden deny.toml speculatively.
7. Update ADRs, evidence, traceability, source inventory, changelog, and active spec files whenever a change materially affects them.

Verification

Run before handing work back:

make check

All compilation and auditing runs locally; Gitea is source storage only. Also run focused tests for the changed capability. Do not report a gate as passed unless it actually ran. Record blocked hardware/VM/provider checks explicitly for later local execution rather than fabricating evidence.

Repository map

• crates/kiln-core/: provider-independent contracts and logic
• crates/kiln-cli/: the single human and machine-facing CLI
• crates/kiln-adapter-steam/: read-only Steam library and app-manifest discovery
• docs/spec/: active specification
• docs/adr/: architecture decisions
• docs/phase-0/: completed baseline policies and evidence
• docs/handoff/: bounded Codex CLI task briefs
• scripts/: repository, toolchain, licensing, and placeholder gates