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

Phase 0 is complete. Phase 1 contracts are 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, MSRV 1.85, with the reviewed development toolchain pinned to Rust 1.97.1.
No real provider implementation starts until the relevant Phase 1 contracts and mock adapter tests pass.

Required workflow

Define one narrow task with exclusions, affected components, acceptance criteria, and exact verification commands.
Implement one vertical capability at a time. Do not spread incomplete work across providers or system layers.
Treat provider files, manifests, artwork, frontend descriptors, paths, and strings as hostile input. Never interpolate them into a shell command.
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.
Use exact versions for local path dependencies as well as their paths. Update and commit Cargo.lock for every dependency change.
Add dependency licenses only after review; do not broaden deny.toml speculatively.
Update ADRs, evidence, traceability, source inventory, changelog, and active spec files whenever a change materially affects them.

Verification

Run before handing work back:

make verify
make audit

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
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

2.8 KiB Raw Blame History