From b6a95b72851b8009867057202b508152ecf01407 Mon Sep 17 00:00:00 2001 From: vmarcella Date: Sat, 21 Mar 2026 16:53:40 -0700 Subject: [PATCH 1/4] [add] initial AGENTS.md --- AGENTS.md | 225 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..d45e3e73 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,225 @@ +# Repository Guidelines + +## Project Structure & Module Organization + +Lambda is organised as a Cargo workspace with multiple crates. + +* Core engine code lives in `crates/lambda-rs` +* Platform & dependency abstractions in `crates/lambda-rs-platform` +* CLI parsing utilities in `crates/lambda-rs-args` +* Logging in `crates/lambda-rs-logging`. + +Shared tooling sits under `lambda-sh/` and `scripts/`, + +* Shader and logo assets are versioned in `crates/lambda-rs/assets/` +* Integration tests run from `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 you iterate. + +## Project Architecture & structure + +### General architecture rules + +* `lambda-rs` is the primary API exposed to end users and should not leak any +internal platform or dependency details. +* `lambda-rs-platform` is where lower level abstractions and dependency wrappers +should be designed to support the needs of the higher level framework. +* Use the builder pattern to expose resources provided by our APIs where +necessary (I.E. for creating a window, gpu, shaders, audio streams, etc). +* In libraries exposed by this repository, avoid using panic unless absolutely +necessary and allow for the user handle errors whenever possible. +* Errors should be as actionable & descriptive as possible, providing context +on what caused the error to occur. + +### lambda-rs + +This module 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 anything that utilizes GPU resources. + +* Do not expose dependency code to the end user unless absolutely necessary. All +lower level dependency/vendor code should be abstracted in `lambda-rs-platform` +and then those abstractions should be imported into this library. + +### lambda-rs-platform + +This module located in `crates/lambda-rs-platform` is our platform and +dependency abstraction layer. This library provides wrappers for all of our +dependency code for our primary API, `lambda-rs`, allowing users to only focus +on the high level abstractions. + +* While APIs here should aim to provide more stable interfaces for our +`lambda-rs`, this should be treated more as an internal API that is meant to +to support the needs of our primary framework, even if it means making non-backwards +compatible changes. + +## Coding Practices, Styles, & 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 stay snake_case. +* Public types use UpperCamelCase. +* constants 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/semicolons instead of tightly packed tokens. +* Add comprehensive documentation to all code & tests. +* Add documentation to any pieces of code that are not immediately clear/are +very complex. +* Rustdoc requirements for new/changed code: + * All public functions, methods, and types MUST have Rustdoc comments. + * Non-trivial private helper functions SHOULD have Rustdoc comments. + * Rustdoc 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 you removed code where the code used to be. + +* Feature flags and documentation (brief) + * Non‑essential code with production runtime cost (e.g., validation, 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 (e.g., rendering validation features live in `lambda-rs`). Prefer narrowly scoped flags over broad umbrellas; umbrella bundles MAY exist for convenience but MUST NOT be enabled by default. + * Umbrella Cargo features (for example, `render-validation`, `render-validation-strict`, `render-validation-all`) MUST only compose granular feature flags. Code and documentation MUST gate behavior using granular feature names (for example, `render-validation-encoder`, `render-validation-instancing`) plus `debug_assertions`, never umbrella names. + * Every granular feature that toggles behavior MUST be included in at least one umbrella feature for discoverability and consistency. + * Do not leak platform/vendor details into public `lambda-rs` features; 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, and the same PR MUST update `docs/features.md` with: name, owning crate, default state (debug/release), summary, and expected runtime cost. + * Do not include perf‑impacting features in a crate’s `default` feature set. + +## Testing Guidelines + +Unit tests reside alongside code; integration tests live in `crates/lambda-rs/tests/runnables.rs`. Add focused tests for new render paths or platform shims, grouping by feature. Run `cargo test -p lambda-rs -- --nocapture` when debugging rendering output, and keep coverage steady by updating or extending the runnable scenarios and examples. Document non-trivial manual verification steps in the PR body. + +## Commit & Pull Request Guidelines + +We follow the `[scope] message` style seen in `git log` (e.g. `[add] logging crate to packages.`). Each commit should remain narrowly scoped and buildable. Pull requests must describe intent, list test commands, and link any tracking issues. Include screenshots or clips if the change affects visuals, and mention required platform checks so reviewers can reproduce confidently. + +## Setup & Tooling Tips + +New contributors should enable the bundled pre-commit hooks via `pre-commit install` after running `scripts/setup.sh`. 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 Metadata & Authoring + +To keep long‑lived docs consistent and traceable, include a metadata header (YAML front matter) at the top of all roadmap/spec/guide docs and follow the structure rules below. + +Metadata schema (paste at the top of a doc): + +--- + +title: "" +document_id: "" +status: "draft" # draft | living | frozen | deprecated +created: "" # e.g., 2025-09-24T00:00:00Z +last_updated: "" +version: "0.x.y" +engine_workspace_version: "2023.1.30" +wgpu_version: "26.0.1" +shader_backend_default: "naga" +winit_version: "0.29.10" +repo_commit: "" +owners: ["lambda-sh"] +reviewers: ["engine", "rendering"] +tags: ["roadmap", "games", "2d", "3d", "desktop"] +--- + +Authoring guidance: + +* Keep sections short and scannable; prefer bullets and code snippets. +* Include ASCII diagrams where helpful; avoid embedded binaries in repo. +* When proposing APIs, mirror existing builder/command patterns and show concise Rust sketches. +* Update `last_updated`, `version`, and `repo_commit` when making material changes; append a “Changelog” section. +* Prefer ISO‑8601 UTC timestamps. Use semantic versioning for the doc `version`. +* Create new specifications by copying `docs/specs/_spec-template.md` and + completing the placeholders; do not start from an existing spec. +* Always create a table of contents for specs & tutorials. + +### Documentation Tone & Style (Required) + +All specs, and long‑lived docs must adopt a professional, precise tone: + +* Voice and register + * Use clear, direct, neutral language. Prefer active voice and present tense. + * Avoid conversational phrasing, rhetorical questions, or tutorial chatter. + * Do not use first‑person pronouns (“I”, “we”) or address the reader (“you”) unless the context requires an instruction; prefer “the API”, “the engine”, or “this document”. + * Do not include meta commentary (e.g., “this aims to…”, “we want to…”). State requirements and behavior plainly. + +* Normative language + * Use RFC‑2119 keywords where appropriate: MUST, SHOULD, MAY, MUST NOT, SHOULD NOT. + * When explaining decisions, use a short “Rationale” sub‑bullet rather than “Why” prose. + +* Terminology and consistency + * Define acronyms on first use in each document (e.g., “uniform buffer object (UBO)”), then use the acronym. Acronyms are permitted in docs (not in code). + * Use consistent technical terms: `GPU`, `CPU`, `wgpu`, “bind group”, “pipeline layout”. Refer to code identifiers with backticks (e.g., `BindGroupLayout`). + * Prefer American English spelling (e.g., “behavior”, “color”). + * When describing implementation areas, refer to crates by name (for example, `lambda-rs`, `lambda-rs-platform`) instead of generic labels like “engine layer” or “platform layer”. + +* Structure and formatting + * Keep headings stable and diff‑friendly; avoid frequent renames. + * Keep bullets to one line when possible; avoid filler sentences. + * Include only minimal, buildable code snippets; match repository style. + * Avoid marketing claims, subjective adjectives, and speculation. + +* Metadata and changelog discipline + * Update `last_updated`, bump `version` semantically, and set `repo_commit` to the current `HEAD` when making substantive edits. + * Changelog entries use ISO‑8601 date, version, and a concise imperative summary of the changes (content, not process). + +* Prohibitions + * No emojis, exclamation marks for emphasis, or informal asides. + * No references to AI authorship or generation. + * No unscoped promises like “we will add…” without a linked tracking issue. + * Do not add commentary about what you MUST or SHOULD do in the guidelines + within specs or tutorials based on the AGENTS.md file. + +### Tutorials Authoring (Required) + +Tutorials are step‑by‑step instructional documents that teach a discrete task using the engine. They MUST follow the same metadata schema and tone rules as other docs, with the additions below. + +* Location and naming + * Place tutorials under `docs/tutorials/`. + * Use kebab‑case filenames (e.g., `uniform-buffers.md`). + * Include the `tutorial` tag in the metadata `tags` array. + +* Tone and voice + * Follow “Documentation Tone & Style (Required)” while adopting a book‑like instructional narrative. + * Explain intent before each code block: what is about to be done and why it is necessary. + * After each code block, include a short narrative paragraph that describes the outcome and what has been achieved. + * Include a final Conclusion section that summarizes what was built and what outcomes were achieved across the tutorial. + * Imperative instructions are preferred; limited second‑person (“you”) MAY be used to guide the reader when clarity improves. + * Define acronyms on first use (e.g., “uniform buffer object (UBO)”) and then use the acronym consistently. + +* Standard section structure + * Goals: clearly state what will be built and what will be learned. + * Overview: one short paragraph defining the task and constraints. + * Prerequisites: version assumptions, build commands, and paths to examples. + * Implementation Steps: numbered, with an explanation of intent and rationale preceding each code block, followed by a narrative paragraph after each code block that summarizes the resulting state and why it matters. + * Validation: exact commands to build/run and expected visible behavior. + * Notes: normative requirements and pitfalls using RFC‑2119 terms (MUST/SHOULD/MAY). + * Conclusion: concise summary of accomplishments and the final state of the system built in the tutorial. + * Exercises: 5–7 focused extensions that reuse concepts from the tutorial. + * Changelog: ISO‑8601 date, version, and concise changes. + +* Code and snippets + * Match repository style: 2‑space indentation, line width ≈ 80, explicit `return` statements, and no abbreviations or acronyms in code identifiers. + * Prefer minimal, buildable snippets; avoid large, redundant code blocks. + * Reference files via workspace‑relative paths (e.g., `crates/lambda-rs/examples/uniform_buffer_triangle.rs`). + * Use ASCII diagrams only; do not embed binaries. + +* Metadata discipline + * Update `last_updated`, bump `version` semantically, and set `repo_commit` to the current `HEAD` when making substantive edits. + * Keep `document_id` stable across revisions; use semantic versioning in `version`. + +* Consistency + * Keep headings stable and diff‑friendly across tutorial revisions. + * Use consistent terminology: `bind group`, `pipeline layout`, `GPU`, `CPU`, `wgpu`. + +* Scope and process isolation + * Do not reference internal process documents (e.g., this file) or include commentary about guideline updates within tutorials or specs. From 4404d5638dd5c7aeb6f6f72cb32f3cc3371d128b Mon Sep 17 00:00:00 2001 From: vmarcella Date: Sat, 21 Mar 2026 18:48:26 -0700 Subject: [PATCH 2/4] [update] formatting --- AGENTS.md | 499 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 307 insertions(+), 192 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d45e3e73..f2ce3f38 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,123 +2,174 @@ ## Project Structure & Module Organization -Lambda is organised as a Cargo workspace with multiple crates. - -* Core engine code lives in `crates/lambda-rs` -* Platform & dependency abstractions in `crates/lambda-rs-platform` -* CLI parsing utilities in `crates/lambda-rs-args` -* Logging in `crates/lambda-rs-logging`. - -Shared tooling sits under `lambda-sh/` and `scripts/`, - -* Shader and logo assets are versioned in `crates/lambda-rs/assets/` -* Integration tests run from `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 you iterate. - -## Project Architecture & structure - -### General architecture rules - -* `lambda-rs` is the primary API exposed to end users and should not leak any -internal platform or dependency details. -* `lambda-rs-platform` is where lower level abstractions and dependency wrappers -should be designed to support the needs of the higher level framework. -* Use the builder pattern to expose resources provided by our APIs where -necessary (I.E. for creating a window, gpu, shaders, audio streams, etc). -* In libraries exposed by this repository, avoid using panic unless absolutely -necessary and allow for the user handle errors whenever possible. -* Errors should be as actionable & descriptive as possible, providing context -on what caused the error to occur. - -### lambda-rs - -This module 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 anything that utilizes GPU resources. - -* Do not expose dependency code to the end user unless absolutely necessary. All -lower level dependency/vendor code should be abstracted in `lambda-rs-platform` -and then those abstractions should be imported into this library. - -### lambda-rs-platform - -This module located in `crates/lambda-rs-platform` is our platform and -dependency abstraction layer. This library provides wrappers for all of our -dependency code for our primary API, `lambda-rs`, allowing users to only focus -on the high level abstractions. - -* While APIs here should aim to provide more stable interfaces for our -`lambda-rs`, this should be treated more as an internal API that is meant to -to support the needs of our primary framework, even if it means making non-backwards -compatible changes. - -## Coding Practices, Styles, & 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 stay snake_case. -* Public types use UpperCamelCase. -* constants 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/semicolons instead of tightly packed tokens. -* Add comprehensive documentation to all code & tests. -* Add documentation to any pieces of code that are not immediately clear/are -very complex. -* Rustdoc requirements for new/changed code: - * All public functions, methods, and types MUST have Rustdoc comments. - * Non-trivial private helper functions SHOULD have Rustdoc comments. - * Rustdoc 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 you removed code where the code used to be. - -* Feature flags and documentation (brief) - * Non‑essential code with production runtime cost (e.g., validation, 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 (e.g., rendering validation features live in `lambda-rs`). Prefer narrowly scoped flags over broad umbrellas; umbrella bundles MAY exist for convenience but MUST NOT be enabled by default. - * Umbrella Cargo features (for example, `render-validation`, `render-validation-strict`, `render-validation-all`) MUST only compose granular feature flags. Code and documentation MUST gate behavior using granular feature names (for example, `render-validation-encoder`, `render-validation-instancing`) plus `debug_assertions`, never umbrella names. - * Every granular feature that toggles behavior MUST be included in at least one umbrella feature for discoverability and consistency. - * Do not leak platform/vendor details into public `lambda-rs` features; 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, and the same PR MUST update `docs/features.md` with: name, owning crate, default state (debug/release), summary, and expected runtime cost. - * Do not include perf‑impacting features in a crate’s `default` feature set. +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 reside alongside code; integration tests live in `crates/lambda-rs/tests/runnables.rs`. Add focused tests for new render paths or platform shims, grouping by feature. Run `cargo test -p lambda-rs -- --nocapture` when debugging rendering output, and keep coverage steady by updating or extending the runnable scenarios and examples. Document non-trivial manual verification steps in the PR body. +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 -We follow the `[scope] message` style seen in `git log` (e.g. `[add] logging crate to packages.`). Each commit should remain narrowly scoped and buildable. Pull requests must describe intent, list test commands, and link any tracking issues. Include screenshots or clips if the change affects visuals, and mention required platform checks so reviewers can reproduce confidently. +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 -New contributors should enable the bundled pre-commit hooks via `pre-commit install` after running `scripts/setup.sh`. 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. +- 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 Metadata & Authoring -To keep long‑lived docs consistent and traceable, include a metadata header (YAML front matter) at the top of all roadmap/spec/guide docs and follow the structure rules below. +Long-lived docs MUST include a metadata header with YAML front matter. Apply +this to roadmaps, specifications, guides, tutorials, and similar durable +documents. -Metadata schema (paste at the top of a doc): +Metadata schema: +```yaml --- - title: "" document_id: "" status: "draft" # draft | living | frozen | deprecated -created: "" # e.g., 2025-09-24T00:00:00Z +created: "" # e.g., 2025-09-24T00:00:00Z last_updated: "" version: "0.x.y" engine_workspace_version: "2023.1.30" @@ -130,96 +181,160 @@ owners: ["lambda-sh"] reviewers: ["engine", "rendering"] tags: ["roadmap", "games", "2d", "3d", "desktop"] --- - -Authoring guidance: - -* Keep sections short and scannable; prefer bullets and code snippets. -* Include ASCII diagrams where helpful; avoid embedded binaries in repo. -* When proposing APIs, mirror existing builder/command patterns and show concise Rust sketches. -* Update `last_updated`, `version`, and `repo_commit` when making material changes; append a “Changelog” section. -* Prefer ISO‑8601 UTC timestamps. Use semantic versioning for the doc `version`. -* Create new specifications by copying `docs/specs/_spec-template.md` and - completing the placeholders; do not start from an existing spec. -* Always create a table of contents for specs & tutorials. - -### Documentation Tone & Style (Required) - -All specs, and long‑lived docs must adopt a professional, precise tone: - -* Voice and register - * Use clear, direct, neutral language. Prefer active voice and present tense. - * Avoid conversational phrasing, rhetorical questions, or tutorial chatter. - * Do not use first‑person pronouns (“I”, “we”) or address the reader (“you”) unless the context requires an instruction; prefer “the API”, “the engine”, or “this document”. - * Do not include meta commentary (e.g., “this aims to…”, “we want to…”). State requirements and behavior plainly. - -* Normative language - * Use RFC‑2119 keywords where appropriate: MUST, SHOULD, MAY, MUST NOT, SHOULD NOT. - * When explaining decisions, use a short “Rationale” sub‑bullet rather than “Why” prose. - -* Terminology and consistency - * Define acronyms on first use in each document (e.g., “uniform buffer object (UBO)”), then use the acronym. Acronyms are permitted in docs (not in code). - * Use consistent technical terms: `GPU`, `CPU`, `wgpu`, “bind group”, “pipeline layout”. Refer to code identifiers with backticks (e.g., `BindGroupLayout`). - * Prefer American English spelling (e.g., “behavior”, “color”). - * When describing implementation areas, refer to crates by name (for example, `lambda-rs`, `lambda-rs-platform`) instead of generic labels like “engine layer” or “platform layer”. - -* Structure and formatting - * Keep headings stable and diff‑friendly; avoid frequent renames. - * Keep bullets to one line when possible; avoid filler sentences. - * Include only minimal, buildable code snippets; match repository style. - * Avoid marketing claims, subjective adjectives, and speculation. - -* Metadata and changelog discipline - * Update `last_updated`, bump `version` semantically, and set `repo_commit` to the current `HEAD` when making substantive edits. - * Changelog entries use ISO‑8601 date, version, and a concise imperative summary of the changes (content, not process). - -* Prohibitions - * No emojis, exclamation marks for emphasis, or informal asides. - * No references to AI authorship or generation. - * No unscoped promises like “we will add…” without a linked tracking issue. - * Do not add commentary about what you MUST or SHOULD do in the guidelines - within specs or tutorials based on the AGENTS.md file. - -### Tutorials Authoring (Required) - -Tutorials are step‑by‑step instructional documents that teach a discrete task using the engine. They MUST follow the same metadata schema and tone rules as other docs, with the additions below. - -* Location and naming - * Place tutorials under `docs/tutorials/`. - * Use kebab‑case filenames (e.g., `uniform-buffers.md`). - * Include the `tutorial` tag in the metadata `tags` array. - -* Tone and voice - * Follow “Documentation Tone & Style (Required)” while adopting a book‑like instructional narrative. - * Explain intent before each code block: what is about to be done and why it is necessary. - * After each code block, include a short narrative paragraph that describes the outcome and what has been achieved. - * Include a final Conclusion section that summarizes what was built and what outcomes were achieved across the tutorial. - * Imperative instructions are preferred; limited second‑person (“you”) MAY be used to guide the reader when clarity improves. - * Define acronyms on first use (e.g., “uniform buffer object (UBO)”) and then use the acronym consistently. - -* Standard section structure - * Goals: clearly state what will be built and what will be learned. - * Overview: one short paragraph defining the task and constraints. - * Prerequisites: version assumptions, build commands, and paths to examples. - * Implementation Steps: numbered, with an explanation of intent and rationale preceding each code block, followed by a narrative paragraph after each code block that summarizes the resulting state and why it matters. - * Validation: exact commands to build/run and expected visible behavior. - * Notes: normative requirements and pitfalls using RFC‑2119 terms (MUST/SHOULD/MAY). - * Conclusion: concise summary of accomplishments and the final state of the system built in the tutorial. - * Exercises: 5–7 focused extensions that reuse concepts from the tutorial. - * Changelog: ISO‑8601 date, version, and concise changes. - -* Code and snippets - * Match repository style: 2‑space indentation, line width ≈ 80, explicit `return` statements, and no abbreviations or acronyms in code identifiers. - * Prefer minimal, buildable snippets; avoid large, redundant code blocks. - * Reference files via workspace‑relative paths (e.g., `crates/lambda-rs/examples/uniform_buffer_triangle.rs`). - * Use ASCII diagrams only; do not embed binaries. - -* Metadata discipline - * Update `last_updated`, bump `version` semantically, and set `repo_commit` to the current `HEAD` when making substantive edits. - * Keep `document_id` stable across revisions; use semantic versioning in `version`. - -* Consistency - * Keep headings stable and diff‑friendly across tutorial revisions. - * Use consistent terminology: `bind group`, `pipeline layout`, `GPU`, `CPU`, `wgpu`. - -* Scope and process isolation - * Do not reference internal process documents (e.g., this file) or include commentary about guideline updates within tutorials or specs. +``` + +### Authoring Guidance + +- Keep sections short and scannable. +- Prefer bullets and concise code snippets. +- Include ASCII diagrams where helpful. +- Do not commit embedded binaries to the repository. +- When proposing APIs, mirror existing builder or command patterns and show + concise Rust sketches. +- Update `last_updated`, `version`, and `repo_commit` when making material + changes. +- Append a `Changelog` section for material updates. +- Prefer ISO-8601 UTC timestamps. +- Use semantic versioning for the document `version`. +- Create new specifications by copying `docs/specs/_spec-template.md` and + completing the placeholders. Do not start from an existing specification. +- Always include a table of contents for specifications and tutorials. + +### Documentation Tone & Style + +All specifications and long-lived docs MUST adopt a professional and precise +tone. + +#### Voice & Register + +- Use clear, direct, neutral language. +- Prefer active voice and present tense. +- Avoid conversational phrasing, rhetorical questions, and tutorial chatter. +- Avoid first-person pronouns such as `I` and `we`. +- Do not address the reader directly unless the context requires an + instruction. Prefer terms such as "the API", "the engine", or + "this document". +- Do not include meta commentary, such as "this aims to" or "we want to". + State requirements and behavior directly. + +#### Normative Language + +- Use RFC-2119 keywords where appropriate: MUST, SHOULD, MAY, MUST NOT, and + SHOULD NOT. +- When explaining decisions, use a short `Rationale` sub-bullet instead of a + "Why" paragraph. + +#### Terminology & Consistency + +- Define acronyms on first use in each document, such as + "uniform buffer object (UBO)", then use the acronym consistently. +- Acronyms are permitted in documentation but not in code identifiers. +- Use consistent technical terms such as `GPU`, `CPU`, `wgpu`, "bind group", + and "pipeline layout". +- Refer to code identifiers with backticks, such as `BindGroupLayout`. +- Prefer American English spelling, such as "behavior" and "color". +- When describing implementation areas, refer to crates by name, such as + `lambda-rs` and `lambda-rs-platform`, rather than generic labels like + "engine layer" or "platform layer". + +#### Structure & Formatting + +- Keep headings stable and diff-friendly. +- Avoid frequent heading renames. +- Keep bullets to one line when practical. +- Avoid filler sentences. +- Include only minimal, buildable code snippets. +- Match repository style in all examples. +- Avoid marketing claims, subjective adjectives, and speculation. + +#### Metadata & Changelog Discipline + +- Update `last_updated`, bump `version` semantically, and set `repo_commit` to + the current `HEAD` when making substantive edits. +- Changelog entries MUST use an ISO-8601 date, the document version, and a + concise imperative summary of the content change. + +#### Prohibitions + +- Do not use emojis, exclamation marks for emphasis, or informal asides. +- Do not reference AI authorship or generation. +- Do not make unscoped promises such as "we will add" without a linked + tracking issue. +- Do not add commentary in specifications or tutorials about what must or + should be done because of this `AGENTS.md` file. + +## Tutorials Authoring + +Tutorials are step-by-step instructional documents that teach a discrete task +using the engine. They MUST follow the same metadata schema and tone rules as +other docs, with the additions below. + +### Location & Naming + +- Place tutorials under `docs/tutorials/`. +- Use kebab-case filenames, such as `uniform-buffers.md`. +- Include the `tutorial` tag in the metadata `tags` array. + +### Tone & Voice + +- Follow the Documentation Tone & Style rules while using a book-like + instructional narrative. +- Explain intent before each code block, including what is about to be done + and why it is necessary. +- After each code block, include a short narrative paragraph describing the + outcome and what was achieved. +- Include a final `Conclusion` section summarizing what was built and what the + tutorial accomplished. +- Imperative instructions are preferred. Limited second-person language MAY be + used when it materially improves clarity. +- Define acronyms on first use, such as "uniform buffer object (UBO)", and + use them consistently. + +### Standard Section Structure + +- `Goals`: clearly state what will be built and what will be learned. +- `Overview`: provide a short paragraph defining the task and constraints. +- `Prerequisites`: list version assumptions, build commands, and paths to + examples. +- `Implementation Steps`: use numbered steps. Each step MUST explain intent + and rationale before the code block and include a short narrative paragraph + afterward describing the resulting state and why it matters. +- `Validation`: provide exact commands to build and run, plus the expected + visible behavior. +- `Notes`: capture normative requirements and pitfalls using MUST, SHOULD, and + MAY. +- `Conclusion`: summarize the final system and what was accomplished. +- `Exercises`: include 5 to 7 focused extensions that reuse concepts from the + tutorial. +- `Changelog`: record the ISO-8601 date, version, and concise change summary. + +### Code & Snippets + +- Match repository style: 2-space indentation, line width near 80 columns, + explicit return statements, and no abbreviations or acronyms in code + identifiers. +- Prefer minimal, buildable snippets. +- Avoid large, redundant code blocks. +- Reference files with workspace-relative paths, such as + `crates/lambda-rs/examples/uniform_buffer_triangle.rs`. +- Use ASCII diagrams only. +- Do not embed binaries. + +### Metadata Discipline + +- Update `last_updated`, bump `version` semantically, and set `repo_commit` to + the current `HEAD` when making substantive edits. +- Keep `document_id` stable across revisions. +- Use semantic versioning for the document `version`. + +### Consistency + +- Keep headings stable and diff-friendly across tutorial revisions. +- Use consistent terminology such as `bind group`, `pipeline layout`, `GPU`, + `CPU`, and `wgpu`. + +### Scope & Process Isolation + +- Do not reference internal process documents, such as this file. +- Do not include commentary about guideline updates within tutorials or + specifications. From 76667a6953e042b535d5ba611f7ca5e90b099ad0 Mon Sep 17 00:00:00 2001 From: vmarcella Date: Sun, 22 Mar 2026 16:01:52 -0700 Subject: [PATCH 3/4] [add] skills for authoring docs & tutorials --- .codex/environments/environment.toml | 6 ++ .../skills/long-lived-docs-authoring/SKILL.md | 69 +++++++++++++++++ .../agents/openai.yaml | 4 + .codex/skills/tutorial-authoring/SKILL.md | 74 +++++++++++++++++++ .../tutorial-authoring/agents/openai.yaml | 4 + 5 files changed, 157 insertions(+) create mode 100644 .codex/environments/environment.toml create mode 100644 .codex/skills/long-lived-docs-authoring/SKILL.md create mode 100644 .codex/skills/long-lived-docs-authoring/agents/openai.yaml create mode 100644 .codex/skills/tutorial-authoring/SKILL.md create mode 100644 .codex/skills/tutorial-authoring/agents/openai.yaml 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." From 943298d86707bc979e110df00ce8a37851ef8a00 Mon Sep 17 00:00:00 2001 From: vmarcella Date: Sun, 22 Mar 2026 16:03:08 -0700 Subject: [PATCH 4/4] [update] AGENTS file to no longer include sections now broken off into skills --- AGENTS.md | 210 ++++++++---------------------------------------------- 1 file changed, 28 insertions(+), 182 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f2ce3f38..e676b6d1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -156,185 +156,31 @@ Pull requests MUST: options exposed by `lambda-sh/lambda.sh` for consistent builds. - Store large assets through `git-lfs` to keep history lean. -## Documentation Metadata & Authoring - -Long-lived docs MUST include a metadata header with YAML front matter. Apply -this to roadmaps, specifications, guides, tutorials, and similar durable -documents. - -Metadata schema: - -```yaml ---- -title: "" -document_id: "" -status: "draft" # draft | living | frozen | deprecated -created: "" # e.g., 2025-09-24T00:00:00Z -last_updated: "" -version: "0.x.y" -engine_workspace_version: "2023.1.30" -wgpu_version: "26.0.1" -shader_backend_default: "naga" -winit_version: "0.29.10" -repo_commit: "" -owners: ["lambda-sh"] -reviewers: ["engine", "rendering"] -tags: ["roadmap", "games", "2d", "3d", "desktop"] ---- -``` - -### Authoring Guidance - -- Keep sections short and scannable. -- Prefer bullets and concise code snippets. -- Include ASCII diagrams where helpful. -- Do not commit embedded binaries to the repository. -- When proposing APIs, mirror existing builder or command patterns and show - concise Rust sketches. -- Update `last_updated`, `version`, and `repo_commit` when making material - changes. -- Append a `Changelog` section for material updates. -- Prefer ISO-8601 UTC timestamps. -- Use semantic versioning for the document `version`. -- Create new specifications by copying `docs/specs/_spec-template.md` and - completing the placeholders. Do not start from an existing specification. -- Always include a table of contents for specifications and tutorials. - -### Documentation Tone & Style - -All specifications and long-lived docs MUST adopt a professional and precise -tone. - -#### Voice & Register - -- Use clear, direct, neutral language. -- Prefer active voice and present tense. -- Avoid conversational phrasing, rhetorical questions, and tutorial chatter. -- Avoid first-person pronouns such as `I` and `we`. -- Do not address the reader directly unless the context requires an - instruction. Prefer terms such as "the API", "the engine", or - "this document". -- Do not include meta commentary, such as "this aims to" or "we want to". - State requirements and behavior directly. - -#### Normative Language - -- Use RFC-2119 keywords where appropriate: MUST, SHOULD, MAY, MUST NOT, and - SHOULD NOT. -- When explaining decisions, use a short `Rationale` sub-bullet instead of a - "Why" paragraph. - -#### Terminology & Consistency - -- Define acronyms on first use in each document, such as - "uniform buffer object (UBO)", then use the acronym consistently. -- Acronyms are permitted in documentation but not in code identifiers. -- Use consistent technical terms such as `GPU`, `CPU`, `wgpu`, "bind group", - and "pipeline layout". -- Refer to code identifiers with backticks, such as `BindGroupLayout`. -- Prefer American English spelling, such as "behavior" and "color". -- When describing implementation areas, refer to crates by name, such as - `lambda-rs` and `lambda-rs-platform`, rather than generic labels like - "engine layer" or "platform layer". - -#### Structure & Formatting - -- Keep headings stable and diff-friendly. -- Avoid frequent heading renames. -- Keep bullets to one line when practical. -- Avoid filler sentences. -- Include only minimal, buildable code snippets. -- Match repository style in all examples. -- Avoid marketing claims, subjective adjectives, and speculation. - -#### Metadata & Changelog Discipline - -- Update `last_updated`, bump `version` semantically, and set `repo_commit` to - the current `HEAD` when making substantive edits. -- Changelog entries MUST use an ISO-8601 date, the document version, and a - concise imperative summary of the content change. - -#### Prohibitions - -- Do not use emojis, exclamation marks for emphasis, or informal asides. -- Do not reference AI authorship or generation. -- Do not make unscoped promises such as "we will add" without a linked - tracking issue. -- Do not add commentary in specifications or tutorials about what must or - should be done because of this `AGENTS.md` file. - -## Tutorials Authoring - -Tutorials are step-by-step instructional documents that teach a discrete task -using the engine. They MUST follow the same metadata schema and tone rules as -other docs, with the additions below. - -### Location & Naming - -- Place tutorials under `docs/tutorials/`. -- Use kebab-case filenames, such as `uniform-buffers.md`. -- Include the `tutorial` tag in the metadata `tags` array. - -### Tone & Voice - -- Follow the Documentation Tone & Style rules while using a book-like - instructional narrative. -- Explain intent before each code block, including what is about to be done - and why it is necessary. -- After each code block, include a short narrative paragraph describing the - outcome and what was achieved. -- Include a final `Conclusion` section summarizing what was built and what the - tutorial accomplished. -- Imperative instructions are preferred. Limited second-person language MAY be - used when it materially improves clarity. -- Define acronyms on first use, such as "uniform buffer object (UBO)", and - use them consistently. - -### Standard Section Structure - -- `Goals`: clearly state what will be built and what will be learned. -- `Overview`: provide a short paragraph defining the task and constraints. -- `Prerequisites`: list version assumptions, build commands, and paths to - examples. -- `Implementation Steps`: use numbered steps. Each step MUST explain intent - and rationale before the code block and include a short narrative paragraph - afterward describing the resulting state and why it matters. -- `Validation`: provide exact commands to build and run, plus the expected - visible behavior. -- `Notes`: capture normative requirements and pitfalls using MUST, SHOULD, and - MAY. -- `Conclusion`: summarize the final system and what was accomplished. -- `Exercises`: include 5 to 7 focused extensions that reuse concepts from the - tutorial. -- `Changelog`: record the ISO-8601 date, version, and concise change summary. - -### Code & Snippets - -- Match repository style: 2-space indentation, line width near 80 columns, - explicit return statements, and no abbreviations or acronyms in code - identifiers. -- Prefer minimal, buildable snippets. -- Avoid large, redundant code blocks. -- Reference files with workspace-relative paths, such as - `crates/lambda-rs/examples/uniform_buffer_triangle.rs`. -- Use ASCII diagrams only. -- Do not embed binaries. - -### Metadata Discipline - -- Update `last_updated`, bump `version` semantically, and set `repo_commit` to - the current `HEAD` when making substantive edits. -- Keep `document_id` stable across revisions. -- Use semantic versioning for the document `version`. - -### Consistency - -- Keep headings stable and diff-friendly across tutorial revisions. -- Use consistent terminology such as `bind group`, `pipeline layout`, `GPU`, - `CPU`, and `wgpu`. - -### Scope & Process Isolation - -- Do not reference internal process documents, such as this file. -- Do not include commentary about guideline updates within tutorials or - specifications. +## 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`.