Skip to content

Commit f3c56aa

Browse files
vmarcellavmarcella
authored
chore(repo): Add agents file alongside a few skills (#196)
## Summary This branch adds repository-level Codex guidance and repo-local authoring skills. The final outcome is an `AGENTS.md` file for always-on repository policy, a Codex environment file, and two dedicated skills that handle long-lived documentation and tutorial authoring workflows. ## Related Issues None linked. ## Changes - Added `AGENTS.md` with repository guidance for structure, architecture, coding practices, testing, pull requests, and documentation requirements. - Added `.codex/environments/environment.toml` to define the workspace setup script for Codex. - Added the `long-lived-docs-authoring` skill and its `agents/openai.yaml` metadata for specs, plans, guides, and other durable Markdown docs. - Added the `tutorial-authoring` skill and its `agents/openai.yaml` metadata for step-by-step tutorials in `docs/tutorials/`. - Kept the final `AGENTS.md` focused on repo-wide policy while pointing documentation-heavy workflows at the new skills. ## Type of Change - [x] Feature (non-breaking change that adds functionality) - [x] Documentation (updates to docs, specs, tutorials, or comments) - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Refactor (code change that neither fixes a bug nor adds a feature) - [ ] Performance (change that improves performance) - [ ] Test (adding or updating tests) - [ ] Build/CI (changes to build process or CI configuration) ## Affected Crates - [ ] `lambda-rs` - [ ] `lambda-rs-platform` - [ ] `lambda-rs-args` - [ ] `lambda-rs-logging` - [x] Other: repository tooling / Codex workspace metadata ## Checklist - [ ] Code follows the repository style guidelines (`cargo +nightly fmt --all`) - [ ] Code passes clippy (`cargo clippy --workspace --all-targets -- -D warnings`) - [ ] Tests pass (`cargo test --workspace`) - [x] New code includes appropriate documentation - [ ] Public API changes are documented - [ ] Breaking changes are noted in this PR description ## Testing **Manual verification steps (if applicable):** N/A ## Screenshots/Recordings Not applicable. ## Platform Testing - [ ] macOS - [ ] Windows - [ ] Linux ## Additional Notes - This branch changes repository guidance and Codex-specific tooling only. - No Rust crates or public APIs are modified.
2 parents c84c44d + 943298d commit f3c56aa

6 files changed

Lines changed: 343 additions & 0 deletions

File tree

‎.codex/environments/environment.toml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
2+
version = 1
3+
name = "lambda-rs"
4+
5+
[setup]
6+
script = "./scripts/setup.sh"

‎.codex/skills/long-lived-docs-authoring/SKILL.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
name: long-lived-docs-authoring
3+
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.
4+
---
5+
6+
# Long Lived Docs Authoring
7+
8+
Use this skill for durable Markdown documents that are meant to stay in the
9+
repository and be maintained over time. The goal is to apply Lambda's
10+
documentation metadata, tone, and maintenance rules without keeping those
11+
details in the main task prompt.
12+
13+
## When To Use
14+
15+
- New or updated specifications in `docs/specs/`.
16+
- Roadmaps, plans, feature documents, and other durable docs in `docs/`.
17+
- Documentation changes that need YAML front matter, changelog discipline,
18+
and repository-specific style constraints.
19+
- Do not use this skill for tutorials in `docs/tutorials/`.
20+
- Do not use this skill for Rustdoc-only work.
21+
22+
## Workflow
23+
24+
1. Identify the document type and location.
25+
Use `docs/specs/_spec-template.md` for new specifications instead of
26+
starting from another spec.
27+
2. Add or preserve the metadata header.
28+
Long-lived docs require YAML front matter with these fields:
29+
`title`, `document_id`, `status`, `created`, `last_updated`, `version`,
30+
`engine_workspace_version`, `wgpu_version`, `shader_backend_default`,
31+
`winit_version`, `repo_commit`, `owners`, `reviewers`, and `tags`.
32+
3. Structure the document for maintenance.
33+
Keep sections short, scannable, and diff-friendly. Specifications should
34+
include a table of contents. Use stable headings and avoid unnecessary
35+
renames.
36+
4. Apply repository documentation style.
37+
Use clear, direct, neutral language in active voice. Prefer present tense.
38+
Avoid conversational phrasing, rhetorical questions, marketing language,
39+
speculation, emojis, exclamation-based emphasis, and AI authorship
40+
references.
41+
5. Use consistent technical terminology.
42+
Define acronyms on first use in each document. Prefer American English.
43+
Refer to crates by name, such as `lambda-rs` and `lambda-rs-platform`.
44+
Wrap code identifiers in backticks.
45+
6. Keep examples minimal and buildable.
46+
Use concise Rust sketches when proposing APIs. Mirror the repository's
47+
existing builder and command patterns. Use ASCII diagrams only and do not
48+
embed binaries.
49+
7. Update maintenance metadata on substantive edits.
50+
Update `last_updated`, bump `version` semantically, set `repo_commit` to
51+
`HEAD`, and append or update the `Changelog` section.
52+
53+
## Required Style Rules
54+
55+
- Use RFC-2119 keywords when the content is normative.
56+
- Prefer `Rationale` bullets instead of long "Why" paragraphs.
57+
- Keep bullets short when possible.
58+
- Avoid filler sentences and meta commentary such as "this aims to".
59+
- Do not make unscoped promises such as "we will add" without a linked issue.
60+
61+
## Validation Checklist
62+
63+
- Metadata header is present and complete.
64+
- The file uses stable headings and short sections.
65+
- The tone is professional, direct, and repository-aligned.
66+
- Acronyms are defined on first use.
67+
- Code snippets are minimal and stylistically consistent with the repository.
68+
- `last_updated`, `version`, `repo_commit`, and `Changelog` are updated for
69+
substantive edits.

‎.codex/skills/long-lived-docs-authoring/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Long-Lived Docs"
3+
short_description: "Author specs, guides, and durable docs"
4+
default_prompt: "Use $long-lived-docs-authoring to draft or revise a spec, roadmap, or guide for this repository."

‎.codex/skills/tutorial-authoring/SKILL.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
name: tutorial-authoring
3+
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.
4+
---
5+
6+
# Tutorial Authoring
7+
8+
Use this skill for tutorial documents that teach a discrete task in the
9+
repository. It includes the long-lived documentation rules that tutorials
10+
inherit, plus the additional section and narrative requirements specific to
11+
`docs/tutorials/`.
12+
13+
## When To Use
14+
15+
- New tutorials in `docs/tutorials/`.
16+
- Revisions to existing tutorials that change structure, examples, or prose.
17+
- Documentation tasks that teach a step-by-step workflow with validation and
18+
exercises.
19+
- Do not use this skill for generic guides, specs, or roadmaps outside
20+
`docs/tutorials/`.
21+
22+
## Workflow
23+
24+
1. Place the file correctly.
25+
Tutorials belong in `docs/tutorials/` and should use kebab-case file names.
26+
Include the `tutorial` tag in the metadata.
27+
2. Add the required metadata header.
28+
Tutorials use the same YAML front matter fields as other long-lived docs:
29+
`title`, `document_id`, `status`, `created`, `last_updated`, `version`,
30+
`engine_workspace_version`, `wgpu_version`, `shader_backend_default`,
31+
`winit_version`, `repo_commit`, `owners`, `reviewers`, and `tags`.
32+
3. Build the required section layout.
33+
Tutorials should include a table of contents and these sections:
34+
`Goals`, `Overview`, `Prerequisites`, `Implementation Steps`,
35+
`Validation`, `Notes`, `Conclusion`, `Exercises`, and `Changelog`.
36+
4. Write each implementation step as instruction plus outcome.
37+
Explain intent and rationale before each code block. After each code block,
38+
include a short paragraph describing the resulting state and why it matters.
39+
5. Keep the instructional tone precise.
40+
Use a book-like instructional narrative while staying professional and
41+
direct. Imperative phrasing is preferred. Limited second-person phrasing is
42+
acceptable when it clearly improves the instruction.
43+
6. Keep terminology and examples consistent.
44+
Define acronyms on first use, use terms such as `GPU`, `CPU`, `wgpu`,
45+
`bind group`, and `pipeline layout` consistently, and refer to identifiers
46+
with backticks.
47+
7. Keep code snippets minimal and repository-aligned.
48+
Match repository style: 2-space indentation, line width near 80 columns,
49+
explicit return statements, and no abbreviations or acronyms in code
50+
identifiers. Prefer workspace-relative file paths in prose and examples.
51+
8. Update maintenance metadata on substantive edits.
52+
Update `last_updated`, bump `version` semantically, set `repo_commit` to
53+
`HEAD`, and maintain the `Changelog`.
54+
55+
## Required Style Rules
56+
57+
- Use clear, direct, neutral language.
58+
- Prefer active voice and present tense.
59+
- Avoid conversational filler, rhetorical questions, emojis, marketing claims,
60+
speculation, and AI authorship references.
61+
- Use RFC-2119 keywords in `Notes` when the content is normative.
62+
- Do not include commentary about internal process documents or guideline
63+
updates.
64+
65+
## Validation Checklist
66+
67+
- The tutorial lives under `docs/tutorials/` with a kebab-case file name.
68+
- Metadata header and `tutorial` tag are present.
69+
- A table of contents is present.
70+
- All required sections are present and ordered clearly.
71+
- Each implementation step includes intent before the code and outcome after it.
72+
- Code snippets are minimal, buildable, and repository-aligned.
73+
- `Validation` contains exact commands and expected behavior.
74+
- `Exercises` contains 5 to 7 focused follow-up tasks.

‎.codex/skills/tutorial-authoring/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Tutorial Authoring"
3+
short_description: "Write repository tutorials with the required structure"
4+
default_prompt: "Use $tutorial-authoring to create or revise a tutorial for this repository."

‎AGENTS.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Repository Guidelines
2+
3+
## Project Structure & Module Organization
4+
5+
Lambda is organized as a Cargo workspace with multiple crates.
6+
7+
- Core engine code lives in `crates/lambda-rs`.
8+
- Platform and dependency abstractions live in
9+
`crates/lambda-rs-platform`.
10+
- CLI parsing utilities live in `crates/lambda-rs-args`.
11+
- Logging utilities live in `crates/lambda-rs-logging`.
12+
13+
Shared tooling lives under `lambda-sh/` and `scripts/`.
14+
15+
- Shader and logo assets are versioned in `crates/lambda-rs/assets/`.
16+
- Integration tests live in `crates/lambda-rs/tests/`.
17+
18+
Run `scripts/setup.sh` once to install git hooks and `git-lfs`.
19+
Use `cargo build --workspace` for a full Rust build and
20+
`cargo test --workspace` to exercise unit and integration suites.
21+
Example binaries can be launched with `cargo run --example minimal`
22+
while iterating.
23+
24+
## Project Architecture & Structure
25+
26+
### General Architecture Rules
27+
28+
- `lambda-rs` is the primary API exposed to end users and MUST NOT leak
29+
internal platform or dependency details.
30+
- `lambda-rs-platform` contains lower-level abstractions and dependency
31+
wrappers and SHOULD be designed to support the needs of the higher-level
32+
framework.
33+
- Use the builder pattern where appropriate to expose resources provided by
34+
the APIs, such as windows, GPUs, shaders, and audio streams.
35+
- In libraries exposed by this repository, avoid panics unless absolutely
36+
necessary and allow the caller to handle errors whenever possible.
37+
- Errors SHOULD be actionable and descriptive, including context about the
38+
cause of the failure.
39+
40+
### `lambda-rs`
41+
42+
`lambda-rs`, located in `crates/lambda-rs`, is the primary API offered by
43+
this repository. It is a high-level framework for building desktop
44+
applications, games, and other GPU-backed software.
45+
46+
- Do not expose dependency code to end users unless absolutely necessary.
47+
Lower-level dependency or vendor code SHOULD be abstracted in
48+
`lambda-rs-platform` and consumed from there.
49+
50+
### `lambda-rs-platform`
51+
52+
`lambda-rs-platform`, located in `crates/lambda-rs-platform`, is the
53+
platform and dependency abstraction layer. This library provides wrappers
54+
around dependency code used by `lambda-rs`, allowing the primary API to stay
55+
focused on higher-level abstractions.
56+
57+
- APIs in this crate SHOULD aim for stable interfaces for `lambda-rs`, but
58+
this crate is still treated as an internal support layer.
59+
Non-backward-compatible changes are acceptable when they are required to
60+
support the primary framework.
61+
62+
## Coding Practices, Style, & Naming Conventions
63+
64+
- Follow Rust 2021 idioms with 2-space indentation and `max_width = 80`,
65+
as enforced by `rustfmt.toml`.
66+
- Always run `cargo +nightly fmt --all` and
67+
`cargo clippy --workspace --all-targets -- -D warnings` before sending
68+
changes.
69+
- Module and file names MUST remain `snake_case`.
70+
- Public types MUST use `UpperCamelCase`.
71+
- Constants MUST use `SCREAMING_SNAKE_CASE`.
72+
- Use explicit return statements.
73+
- Do not use abbreviations or acronyms for variable names.
74+
- Maintain readable spacing in new statements: keep spaces after keywords,
75+
around operators, and after commas and semicolons instead of tightly packed
76+
tokens.
77+
- Add comprehensive documentation to all code and tests.
78+
- Add documentation to code that is complex or not immediately clear.
79+
80+
### Rustdoc Requirements
81+
82+
- All public functions, methods, and types MUST have Rustdoc comments.
83+
- Non-trivial private helper functions SHOULD have Rustdoc comments.
84+
- Rustdoc for new or changed APIs MUST follow this structure:
85+
- One-line summary sentence describing behavior.
86+
- Optional paragraph describing nuances, constraints, or invariants.
87+
- `# Arguments` section documenting each parameter.
88+
- `# Returns` section describing the return value.
89+
- `# Errors` section for `Result`-returning APIs describing failure cases.
90+
- `# Panics` section only if the implementation can panic. Prefer avoiding
91+
panics in library code.
92+
- `# Safety` section for `unsafe` APIs describing required invariants.
93+
94+
- Do not add comments explaining why code was removed where that code used to
95+
be.
96+
97+
### Feature Flags & Documentation
98+
99+
- Non-essential code with production runtime cost, such as validation or
100+
extra logging, MUST be disabled by default in release builds and guarded
101+
behind explicit Cargo features. Debug builds MAY enable such checks via
102+
`debug_assertions`.
103+
- Add features in the crate that owns the behavior. For example, rendering
104+
validation features belong in `lambda-rs`.
105+
- Prefer narrowly scoped feature flags over broad umbrella flags. Umbrella
106+
bundles MAY exist for convenience but MUST NOT be enabled by default.
107+
- Umbrella Cargo features, such as `render-validation`,
108+
`render-validation-strict`, and `render-validation-all`, MUST only compose
109+
granular feature flags.
110+
- Code and documentation MUST gate behavior using granular feature names, such
111+
as `render-validation-encoder` and `render-validation-instancing`, together
112+
with `debug_assertions`, never umbrella names.
113+
- Every granular feature that toggles behavior MUST be included in at least
114+
one umbrella feature for discoverability and consistency.
115+
- Public `lambda-rs` features MUST NOT leak platform or vendor details. Map
116+
high-level features to `lambda-rs-platform` internals as needed.
117+
- Specifications that add or change behavior MUST list the exact Cargo
118+
features they introduce or rely on. The same change MUST also update
119+
`docs/features.md` with the feature name, owning crate, default state
120+
(debug or release), summary, and expected runtime cost.
121+
- Do not include performance-impacting features in a crate's `default`
122+
feature set.
123+
124+
## Testing Guidelines
125+
126+
Unit tests live alongside the code. Integration test coverage lives under
127+
`crates/lambda-rs/tests/`, with runnable scenarios defined in
128+
`crates/lambda-rs/tests/runnables.rs`.
129+
130+
- Add focused tests for new render paths or platform shims, grouped by
131+
feature.
132+
- Run `cargo test -p lambda-rs -- --nocapture` when debugging rendering
133+
output.
134+
- Maintain coverage by updating or extending runnable scenarios and examples.
135+
- Document non-trivial manual verification steps in the pull request body.
136+
137+
## Commit & Pull Request Guidelines
138+
139+
Commit messages follow the `[scope] message` style used in `git log`, such as
140+
`[add] logging crate to packages.` Each commit SHOULD remain narrowly scoped
141+
and buildable.
142+
143+
Pull requests MUST:
144+
145+
- Describe the intent of the change.
146+
- List the test commands that were run.
147+
- Link any tracking issues.
148+
- Include screenshots or clips for visual changes.
149+
- Note any required platform checks so reviewers can reproduce the change.
150+
151+
## Setup & Tooling Tips
152+
153+
- Run `scripts/setup.sh`, then enable the bundled hooks with
154+
`pre-commit install`.
155+
- When working with the C++ engine archive, respect the `lambda_args_*`
156+
options exposed by `lambda-sh/lambda.sh` for consistent builds.
157+
- Store large assets through `git-lfs` to keep history lean.
158+
159+
## Documentation Skills
160+
161+
Use the repo-local Codex skills for detailed documentation workflows.
162+
163+
- Use `.codex/skills/long-lived-docs-authoring/SKILL.md` for specs, roadmaps,
164+
guides, plans, and other long-lived Markdown documents.
165+
- Use `.codex/skills/tutorial-authoring/SKILL.md` for step-by-step tutorials
166+
in `docs/tutorials/`.
167+
- Keep repo-wide policy in this file and keep detailed documentation authoring
168+
workflow in those skills.
169+
170+
## Documentation Requirements
171+
172+
- Long-lived docs MUST include YAML front matter with `title`,
173+
`document_id`, `status`, `created`, `last_updated`, `version`,
174+
`engine_workspace_version`, `wgpu_version`, `shader_backend_default`,
175+
`winit_version`, `repo_commit`, `owners`, `reviewers`, and `tags`.
176+
- New specifications MUST be created from `docs/specs/_spec-template.md`.
177+
- Specifications and tutorials MUST include a table of contents.
178+
- Substantive documentation edits MUST update `last_updated`, `version`,
179+
`repo_commit`, and the `Changelog`.
180+
- Long-lived docs MUST use a professional, precise tone with active voice,
181+
consistent terminology, American English spelling, and RFC-2119 keywords
182+
where appropriate.
183+
- Tutorials MUST live in `docs/tutorials/`, use kebab-case filenames, include
184+
the `tutorial` tag, and include `Goals`, `Overview`, `Prerequisites`,
185+
`Implementation Steps`, `Validation`, `Notes`, `Conclusion`, `Exercises`,
186+
and `Changelog`.

0 commit comments

Comments
 (0)