diff --git a/.codex/environments/environment.toml b/.codex/environments/environment.toml new file mode 100644 index 00000000..250e153b --- /dev/null +++ b/.codex/environments/environment.toml @@ -0,0 +1,6 @@ +# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY +version = 1 +name = "lambda-rs" + +[setup] +script = "./scripts/setup.sh" diff --git a/.codex/skills/long-lived-docs-authoring/SKILL.md b/.codex/skills/long-lived-docs-authoring/SKILL.md new file mode 100644 index 00000000..cf22ad37 --- /dev/null +++ b/.codex/skills/long-lived-docs-authoring/SKILL.md @@ -0,0 +1,69 @@ +--- +name: long-lived-docs-authoring +description: Use when drafting or revising long-lived repository documentation such as specs, roadmaps, guides, feature docs, or planning docs that need Lambda's required metadata, structure, and documentation style. Do not use for tutorials; use `tutorial-authoring` instead. +--- + +# Long Lived Docs Authoring + +Use this skill for durable Markdown documents that are meant to stay in the +repository and be maintained over time. The goal is to apply Lambda's +documentation metadata, tone, and maintenance rules without keeping those +details in the main task prompt. + +## When To Use + +- New or updated specifications in `docs/specs/`. +- Roadmaps, plans, feature documents, and other durable docs in `docs/`. +- Documentation changes that need YAML front matter, changelog discipline, + and repository-specific style constraints. +- Do not use this skill for tutorials in `docs/tutorials/`. +- Do not use this skill for Rustdoc-only work. + +## Workflow + +1. Identify the document type and location. + Use `docs/specs/_spec-template.md` for new specifications instead of + starting from another spec. +2. Add or preserve the metadata header. + Long-lived docs require YAML front matter with these fields: + `title`, `document_id`, `status`, `created`, `last_updated`, `version`, + `engine_workspace_version`, `wgpu_version`, `shader_backend_default`, + `winit_version`, `repo_commit`, `owners`, `reviewers`, and `tags`. +3. Structure the document for maintenance. + Keep sections short, scannable, and diff-friendly. Specifications should + include a table of contents. Use stable headings and avoid unnecessary + renames. +4. Apply repository documentation style. + Use clear, direct, neutral language in active voice. Prefer present tense. + Avoid conversational phrasing, rhetorical questions, marketing language, + speculation, emojis, exclamation-based emphasis, and AI authorship + references. +5. Use consistent technical terminology. + Define acronyms on first use in each document. Prefer American English. + Refer to crates by name, such as `lambda-rs` and `lambda-rs-platform`. + Wrap code identifiers in backticks. +6. Keep examples minimal and buildable. + Use concise Rust sketches when proposing APIs. Mirror the repository's + existing builder and command patterns. Use ASCII diagrams only and do not + embed binaries. +7. Update maintenance metadata on substantive edits. + Update `last_updated`, bump `version` semantically, set `repo_commit` to + `HEAD`, and append or update the `Changelog` section. + +## Required Style Rules + +- Use RFC-2119 keywords when the content is normative. +- Prefer `Rationale` bullets instead of long "Why" paragraphs. +- Keep bullets short when possible. +- Avoid filler sentences and meta commentary such as "this aims to". +- Do not make unscoped promises such as "we will add" without a linked issue. + +## Validation Checklist + +- Metadata header is present and complete. +- The file uses stable headings and short sections. +- The tone is professional, direct, and repository-aligned. +- Acronyms are defined on first use. +- Code snippets are minimal and stylistically consistent with the repository. +- `last_updated`, `version`, `repo_commit`, and `Changelog` are updated for + substantive edits. diff --git a/.codex/skills/long-lived-docs-authoring/agents/openai.yaml b/.codex/skills/long-lived-docs-authoring/agents/openai.yaml new file mode 100644 index 00000000..a60ca74d --- /dev/null +++ b/.codex/skills/long-lived-docs-authoring/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Long-Lived Docs" + short_description: "Author specs, guides, and durable docs" + default_prompt: "Use $long-lived-docs-authoring to draft or revise a spec, roadmap, or guide for this repository." diff --git a/.codex/skills/tutorial-authoring/SKILL.md b/.codex/skills/tutorial-authoring/SKILL.md new file mode 100644 index 00000000..feacbb38 --- /dev/null +++ b/.codex/skills/tutorial-authoring/SKILL.md @@ -0,0 +1,74 @@ +--- +name: tutorial-authoring +description: Use when creating or revising step-by-step tutorials in `docs/tutorials/`. This skill applies Lambda's required metadata, instructional structure, tone, code-snippet rules, and validation expectations for tutorial documents. +--- + +# Tutorial Authoring + +Use this skill for tutorial documents that teach a discrete task in the +repository. It includes the long-lived documentation rules that tutorials +inherit, plus the additional section and narrative requirements specific to +`docs/tutorials/`. + +## When To Use + +- New tutorials in `docs/tutorials/`. +- Revisions to existing tutorials that change structure, examples, or prose. +- Documentation tasks that teach a step-by-step workflow with validation and + exercises. +- Do not use this skill for generic guides, specs, or roadmaps outside + `docs/tutorials/`. + +## Workflow + +1. Place the file correctly. + Tutorials belong in `docs/tutorials/` and should use kebab-case file names. + Include the `tutorial` tag in the metadata. +2. Add the required metadata header. + Tutorials use the same YAML front matter fields as other long-lived docs: + `title`, `document_id`, `status`, `created`, `last_updated`, `version`, + `engine_workspace_version`, `wgpu_version`, `shader_backend_default`, + `winit_version`, `repo_commit`, `owners`, `reviewers`, and `tags`. +3. Build the required section layout. + Tutorials should include a table of contents and these sections: + `Goals`, `Overview`, `Prerequisites`, `Implementation Steps`, + `Validation`, `Notes`, `Conclusion`, `Exercises`, and `Changelog`. +4. Write each implementation step as instruction plus outcome. + Explain intent and rationale before each code block. After each code block, + include a short paragraph describing the resulting state and why it matters. +5. Keep the instructional tone precise. + Use a book-like instructional narrative while staying professional and + direct. Imperative phrasing is preferred. Limited second-person phrasing is + acceptable when it clearly improves the instruction. +6. Keep terminology and examples consistent. + Define acronyms on first use, use terms such as `GPU`, `CPU`, `wgpu`, + `bind group`, and `pipeline layout` consistently, and refer to identifiers + with backticks. +7. Keep code snippets minimal and repository-aligned. + Match repository style: 2-space indentation, line width near 80 columns, + explicit return statements, and no abbreviations or acronyms in code + identifiers. Prefer workspace-relative file paths in prose and examples. +8. Update maintenance metadata on substantive edits. + Update `last_updated`, bump `version` semantically, set `repo_commit` to + `HEAD`, and maintain the `Changelog`. + +## Required Style Rules + +- Use clear, direct, neutral language. +- Prefer active voice and present tense. +- Avoid conversational filler, rhetorical questions, emojis, marketing claims, + speculation, and AI authorship references. +- Use RFC-2119 keywords in `Notes` when the content is normative. +- Do not include commentary about internal process documents or guideline + updates. + +## Validation Checklist + +- The tutorial lives under `docs/tutorials/` with a kebab-case file name. +- Metadata header and `tutorial` tag are present. +- A table of contents is present. +- All required sections are present and ordered clearly. +- Each implementation step includes intent before the code and outcome after it. +- Code snippets are minimal, buildable, and repository-aligned. +- `Validation` contains exact commands and expected behavior. +- `Exercises` contains 5 to 7 focused follow-up tasks. diff --git a/.codex/skills/tutorial-authoring/agents/openai.yaml b/.codex/skills/tutorial-authoring/agents/openai.yaml new file mode 100644 index 00000000..ae89fc8a --- /dev/null +++ b/.codex/skills/tutorial-authoring/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Tutorial Authoring" + short_description: "Write repository tutorials with the required structure" + default_prompt: "Use $tutorial-authoring to create or revise a tutorial for this repository." diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..e676b6d1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,186 @@ +# Repository Guidelines + +## Project Structure & Module Organization + +Lambda is organized as a Cargo workspace with multiple crates. + +- Core engine code lives in `crates/lambda-rs`. +- Platform and dependency abstractions live in + `crates/lambda-rs-platform`. +- CLI parsing utilities live in `crates/lambda-rs-args`. +- Logging utilities live in `crates/lambda-rs-logging`. + +Shared tooling lives under `lambda-sh/` and `scripts/`. + +- Shader and logo assets are versioned in `crates/lambda-rs/assets/`. +- Integration tests live in `crates/lambda-rs/tests/`. + +Run `scripts/setup.sh` once to install git hooks and `git-lfs`. +Use `cargo build --workspace` for a full Rust build and +`cargo test --workspace` to exercise unit and integration suites. +Example binaries can be launched with `cargo run --example minimal` +while iterating. + +## Project Architecture & Structure + +### General Architecture Rules + +- `lambda-rs` is the primary API exposed to end users and MUST NOT leak + internal platform or dependency details. +- `lambda-rs-platform` contains lower-level abstractions and dependency + wrappers and SHOULD be designed to support the needs of the higher-level + framework. +- Use the builder pattern where appropriate to expose resources provided by + the APIs, such as windows, GPUs, shaders, and audio streams. +- In libraries exposed by this repository, avoid panics unless absolutely + necessary and allow the caller to handle errors whenever possible. +- Errors SHOULD be actionable and descriptive, including context about the + cause of the failure. + +### `lambda-rs` + +`lambda-rs`, located in `crates/lambda-rs`, is the primary API offered by +this repository. It is a high-level framework for building desktop +applications, games, and other GPU-backed software. + +- Do not expose dependency code to end users unless absolutely necessary. + Lower-level dependency or vendor code SHOULD be abstracted in + `lambda-rs-platform` and consumed from there. + +### `lambda-rs-platform` + +`lambda-rs-platform`, located in `crates/lambda-rs-platform`, is the +platform and dependency abstraction layer. This library provides wrappers +around dependency code used by `lambda-rs`, allowing the primary API to stay +focused on higher-level abstractions. + +- APIs in this crate SHOULD aim for stable interfaces for `lambda-rs`, but + this crate is still treated as an internal support layer. + Non-backward-compatible changes are acceptable when they are required to + support the primary framework. + +## Coding Practices, Style, & Naming Conventions + +- Follow Rust 2021 idioms with 2-space indentation and `max_width = 80`, + as enforced by `rustfmt.toml`. +- Always run `cargo +nightly fmt --all` and + `cargo clippy --workspace --all-targets -- -D warnings` before sending + changes. +- Module and file names MUST remain `snake_case`. +- Public types MUST use `UpperCamelCase`. +- Constants MUST use `SCREAMING_SNAKE_CASE`. +- Use explicit return statements. +- Do not use abbreviations or acronyms for variable names. +- Maintain readable spacing in new statements: keep spaces after keywords, + around operators, and after commas and semicolons instead of tightly packed + tokens. +- Add comprehensive documentation to all code and tests. +- Add documentation to code that is complex or not immediately clear. + +### Rustdoc Requirements + +- All public functions, methods, and types MUST have Rustdoc comments. +- Non-trivial private helper functions SHOULD have Rustdoc comments. +- Rustdoc for new or changed APIs MUST follow this structure: + - One-line summary sentence describing behavior. + - Optional paragraph describing nuances, constraints, or invariants. + - `# Arguments` section documenting each parameter. + - `# Returns` section describing the return value. + - `# Errors` section for `Result`-returning APIs describing failure cases. + - `# Panics` section only if the implementation can panic. Prefer avoiding + panics in library code. + - `# Safety` section for `unsafe` APIs describing required invariants. + +- Do not add comments explaining why code was removed where that code used to + be. + +### Feature Flags & Documentation + +- Non-essential code with production runtime cost, such as validation or + extra logging, MUST be disabled by default in release builds and guarded + behind explicit Cargo features. Debug builds MAY enable such checks via + `debug_assertions`. +- Add features in the crate that owns the behavior. For example, rendering + validation features belong in `lambda-rs`. +- Prefer narrowly scoped feature flags over broad umbrella flags. Umbrella + bundles MAY exist for convenience but MUST NOT be enabled by default. +- Umbrella Cargo features, such as `render-validation`, + `render-validation-strict`, and `render-validation-all`, MUST only compose + granular feature flags. +- Code and documentation MUST gate behavior using granular feature names, such + as `render-validation-encoder` and `render-validation-instancing`, together + with `debug_assertions`, never umbrella names. +- Every granular feature that toggles behavior MUST be included in at least + one umbrella feature for discoverability and consistency. +- Public `lambda-rs` features MUST NOT leak platform or vendor details. Map + high-level features to `lambda-rs-platform` internals as needed. +- Specifications that add or change behavior MUST list the exact Cargo + features they introduce or rely on. The same change MUST also update + `docs/features.md` with the feature name, owning crate, default state + (debug or release), summary, and expected runtime cost. +- Do not include performance-impacting features in a crate's `default` + feature set. + +## Testing Guidelines + +Unit tests live alongside the code. Integration test coverage lives under +`crates/lambda-rs/tests/`, with runnable scenarios defined in +`crates/lambda-rs/tests/runnables.rs`. + +- Add focused tests for new render paths or platform shims, grouped by + feature. +- Run `cargo test -p lambda-rs -- --nocapture` when debugging rendering + output. +- Maintain coverage by updating or extending runnable scenarios and examples. +- Document non-trivial manual verification steps in the pull request body. + +## Commit & Pull Request Guidelines + +Commit messages follow the `[scope] message` style used in `git log`, such as +`[add] logging crate to packages.` Each commit SHOULD remain narrowly scoped +and buildable. + +Pull requests MUST: + +- Describe the intent of the change. +- List the test commands that were run. +- Link any tracking issues. +- Include screenshots or clips for visual changes. +- Note any required platform checks so reviewers can reproduce the change. + +## Setup & Tooling Tips + +- Run `scripts/setup.sh`, then enable the bundled hooks with + `pre-commit install`. +- When working with the C++ engine archive, respect the `lambda_args_*` + options exposed by `lambda-sh/lambda.sh` for consistent builds. +- Store large assets through `git-lfs` to keep history lean. + +## Documentation Skills + +Use the repo-local Codex skills for detailed documentation workflows. + +- Use `.codex/skills/long-lived-docs-authoring/SKILL.md` for specs, roadmaps, + guides, plans, and other long-lived Markdown documents. +- Use `.codex/skills/tutorial-authoring/SKILL.md` for step-by-step tutorials + in `docs/tutorials/`. +- Keep repo-wide policy in this file and keep detailed documentation authoring + workflow in those skills. + +## Documentation Requirements + +- Long-lived docs MUST include YAML front matter with `title`, + `document_id`, `status`, `created`, `last_updated`, `version`, + `engine_workspace_version`, `wgpu_version`, `shader_backend_default`, + `winit_version`, `repo_commit`, `owners`, `reviewers`, and `tags`. +- New specifications MUST be created from `docs/specs/_spec-template.md`. +- Specifications and tutorials MUST include a table of contents. +- Substantive documentation edits MUST update `last_updated`, `version`, + `repo_commit`, and the `Changelog`. +- Long-lived docs MUST use a professional, precise tone with active voice, + consistent terminology, American English spelling, and RFC-2119 keywords + where appropriate. +- Tutorials MUST live in `docs/tutorials/`, use kebab-case filenames, include + the `tutorial` tag, and include `Goals`, `Overview`, `Prerequisites`, + `Implementation Steps`, `Validation`, `Notes`, `Conclusion`, `Exercises`, + and `Changelog`.