65 lines
3.1 KiB
Markdown
65 lines
3.1 KiB
Markdown
# 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:
|
||
|
||
```sh
|
||
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
|